Specgen React Mui

React SPA Specification Generator

This skill generates a comprehensive specification document (Markdown) that serves as a blueprint for building a React Single Page Application. The spec is intended to be followed by a developer or a coding agent to produce a fully functional project scaffold.

The specification does NOT generate code. It produces a detailed, opinionated technical document describing every layer of the application — from Vite configuration to MUI theme to React Query patterns — so that implementation becomes a mechanical exercise.

Technology Stack

Core Stack (Always Included)

These are the fixed versions the spec targets. Do not deviate unless the user explicitly requests different versions.

| Component | Version | |----------------------|-----------| | React | 19.x | | TypeScript | 5.x | | Vite | 6.x | | Material UI (MUI) | 6.x | | MUI Icons | 6.x | | MUI System | 6.x | | React Router | 7.x | | TanStack Query | 5.x | | Zustand | 5.x | | React Hook Form | 7.x | | Zod | 3.x | | Axios | 1.x | | Node.js | 22.x LTS |

Optional Integration Versions

Include in the version table only when the corresponding integration is selected.

| Component | Version | When Selected | |----------------------|-----------|------------------------| | Keycloak | 26.x | Auth = Keycloak | | oidc-client-ts | 3.x | Auth = Keycloak or OIDC| | react-oidc-context | 3.x | Auth = Keycloak or OIDC| | MUI X Data Grid | 7.x | DataGrid = yes | | MUI X Charts | 7.x | Charts = yes | | MUI X Date Pickers | 7.x | DatePickers = yes | | Socket.io Client | 4.x | WebSocket = yes | | react-i18next | 15.x | i18n = yes | | i18next | 24.x | i18n = yes | | React Quill (or similar rich text editor) | latest | RichText = yes |

Core Dependencies (package.json)

The spec must include these in the npm configuration section (always):

Production dependencies:

• react + react-dom — Core React
• @mui/material + @mui/icons-material — MUI component library and icons
• @emotion/react + @emotion/styled — MUI v6 styling engine
• react-router-dom — Client-side routing
• @tanstack/react-query — Server state and data fetching
• zustand — Global client state management
• react-hook-form — Form state management
• @hookform/resolvers — Zod integration for React Hook Form
• zod — Schema validation
• axios — HTTP client

Development dependencies:

• typescript — Type checking
• @types/react + @types/react-dom — React type definitions
• vite + @vitejs/plugin-react — Build tooling
• eslint + @typescript-eslint/* — Linting

Conditional Dependencies

If Auth = Keycloak or OIDC:

• oidc-client-ts — OAuth2/OIDC PKCE client
• react-oidc-context — React context wrapper for oidc-client-ts

If DataGrid = yes:

• @mui/x-data-grid — Advanced data grid component

If Charts = yes:

• @mui/x-charts — Chart components

If DatePickers = yes:

• @mui/x-date-pickers — Date/time picker components
• date-fns — Date manipulation library

If WebSocket = yes:

• socket.io-client — WebSocket client

If i18n = yes:

• react-i18next + i18next — Internationalization
• i18next-browser-languagedetector — Auto language detection
• i18next-http-backend — Lazy translation loading

If RichText = yes:

• react-quill-new — Rich text editor (Quill-based, React 19 compatible)
• dompurify + @types/dompurify — HTML sanitization for rich text content

If Reporting = yes:

• xlsx — Client-side XLSX file generation
• papaparse + @types/papaparse — Client-side CSV generation
• Report service (Node.js companion): puppeteer, express, cors — server-side HTML-to-PDF via headless Chrome

When the Skill Triggers

Generate the spec when the user provides an application name and version that corresponds to one of the custom applications defined in CLAUDE.md. The skill reads all required inputs from the project's context files — no interactive Q&A is needed for the core inputs.

The user invokes this skill by specifying the target application and version, for example:

• /specgen-react-mui admin v1.0.4
• /specgen-react-mui admin v1.0.4 module:Hero Section
• /specgen-react-mui "Admin Portal" v1.0.4

The skill then locates the matching context folder and reads all input files automatically.

Version Gate

Before starting any work, resolve the application folder first (see Input Resolution below), then check CHANGELOG.md in the application folder (/CHANGELOG.md):

1. If /CHANGELOG.md does not exist, skip this check (first-ever execution for this application).
2. If /CHANGELOG.md exists, scan all ## vX.Y.Z headings and determine the highest version using semantic versioning comparison.
3. Compare the requested version against the highest version:

• If requested version >= highest version: proceed normally.
• If requested version **/CHANGELOG.md. Execution rejected."` Do NOT proceed with any work.

Input Resolution

This skill uses standardized input resolution. Provide:

| Argument | Required | Example | Description | |----------|----------|---------|-------------| | ` | Yes | admin | Application name to locate the context folder | | | Yes | v1.0.4 | Version to scope processing | | module: | No | module:Hero Section` | Limit generation to a single module |

Application Folder Resolution

The application name is matched against root-level application folders:

1. Strip any leading _ prefix from folder names (e.g., 1_admin → admin)
2. Match case-insensitively against the provided application name
3. Accept snake_case, kebab-case, or title-case input (all match the same folder)
4. If no match found, list available applications and stop

Auto-Resolved Paths

| File | Resolved Path | |------|---------------| | PRD.md | /context/PRD.md | | Module Models | /context/model/ | | HTML Mockups | /context/mockup/ | | Output (specification) | /context/specification/ |

Version Filtering

When a version is provided, only include user stories, NFRs, and constraints from versions ` is provided:

• Only generate the SPEC.md for that specific module
• Other existing module spec files remain untouched
• SPECIFICATION.md (root) gets a partial update — only that module's entry in the TOC

is added or updated; all other TOC entries are preserved as-is

Gathering Input

The specification is driven by six input sources read from the project's context files. The skill does NOT ask the user for auth, API backend URL, or optional component choices — it determines these automatically from the context.

Input 1: Application Name (from CLAUDE.md)

From CLAUDE.md (already loaded in context), locate the target application under the Custom Applications section. Extract:

• Application name: The section heading (e.g., "Admin Portal", "Landing Page")
• Application description: The description paragraph below the heading
• Dependencies: The "Depends on" list — primary source for determining backend API

base URL, authentication provider, and optional components

The application name is used to derive:

• Project slug: Kebab-case of the application name (e.g., admin-portal)
• Vite env prefix: VITE_ (standard Vite convention)
• App title: Title-case of application name (e.g., "Admin Portal")

Input 2: User Stories (from PRD.md)

Read /context/PRD.md. This file contains all user stories organized by module. Extract:

• System modules: Modules under # System Module heading (e.g., Authentication,

User Management). These become system-level features.

• Business modules: Modules under # Business Module heading (e.g., Hero Section,

Product and Service). These become business-level features.

• User stories per module: Each ### User Story section contains tagged items.

These define the functional requirements for each feature's API hooks, form schemas, and page components.

The user stories directly inform:

• Which API calls each feature's hooks must expose
• Which pages and routes are needed
• Which form fields and validation schemas apply
• Which MUI components best match the described UI

Important: Items with strikethrough (~~text~~) are deprecated — do NOT include them as active requirements. List them in the "Removed / Replaced" subsection of the traceability table.

• Version tags per item: Each ### User Story, ### Non Functional Requirement,

and ### Constraint section contains one or more version blocks formatted as [v1.0.x]. The skill must track the version tag for each item and carry it through to the generated specification's traceability section.

Input 3: Non-Functional Requirements (from PRD.md)

Within the same PRD.md, each module has a ### Non Functional Requirement section. These inform:

• UI layout choices (grid columns, card sizes, image dimensions)
• Data fetching strategies (pagination, filtering, real-time)
• Validation rules (character limits, format requirements)
• Performance constraints (lazy loading, caching)

NFRs should be mapped to specific technical decisions in the spec — for example, an NFR stating "paginated with 10 items per page" confirms which React Query pagination pattern to use, while "must support filtering" confirms which Zustand slice manages filter state.

Input 4: Constraints (from PRD.md)

Within the same PRD.md, each module has a ### Constraint section. These define hard boundaries that the spec must enforce:

• Status enum values (e.g., "DRAFT, ACTIVE, EXPIRED")
• Business rules (e.g., "category must exist before creating content")
• Access control (e.g., "only ADMIN role can access user management")

Constraints are embedded directly into the relevant module blueprint — they inform Zod validation schemas, API call parameters, and route guard configurations.

Input 5: Module Model (from model/ folder)

Read /context/model/MODEL.md first as the index, then read the individual module model files in each module subfolder.

MODEL.md provides:

• Summary table of all modules with table/collection counts and design decisions
• Links to each module's detailed model files

Per-module files (e.g., model/hero-section/model.md):

• Complete field definitions with types and constraints
• Relationships and references
• Table/collection names

Per-module schema (e.g., model/hero-section/schemas.json):

• JSON schemas defining exact field types, required fields, and validation rules

The module model directly maps to:

• TypeScript interface/type definitions (field-for-field, not placeholder)
• Zod validation schemas
• React Hook Form field configurations
• TanStack Query response type annotations
• API request/response DTOs

Input 6: HTML Mockup Screens (from mockup/ folder)

Read /context/mockup/MOCKUP.html first as the index page, then read the HTML files organized by role in subfolders.

MOCKUP.html provides:

• Application identity (name, version, short name)
• Design tokens: fonts, colors from Tailwind/CSS config or inline styles
• List of user roles and their screen sets

Role-specific subfolders (e.g., mockup/admin/content/):

• Individual HTML screens for each page in the application
• Screen layout: which components are used (tables, forms, cards, modals, grids)
• Navigation structure from sidebar/header HTML files
• Data display patterns (list pages, detail pages, create/edit forms)

IMPORTANT — Role folders inform access control, NOT URL paths. The role-specific folder structure (e.g., mockup/admin/content/hero-section.html) determines:

1. Which role can access the page → ``
2. Which navigation items appear for each role

It does NOT determine the URL path. The URL path is always module-based:

• ` — NOT `

The mockup screens directly map to:

• React page components (one per HTML screen)
• React Router route definitions
• MUI component selections (DataGrid vs Table, Dialog vs Drawer, etc.)
• Form field layouts
• Navigation items per role
• MUI theme color tokens (extract from mockup CSS/styles)

PRD.md Extended Sections

Before determining optional components, check PRD.md for the following extended sections:

Architecture Principle Extraction

If PRD.md contains an # Architecture Principle section, extract patterns that affect frontend decisions:

| Pattern to Extract | How It Influences the Specification | |---|---| | "Stateless REST API" | Confirms Axios + TanStack Query pattern for API calls | | "Event-driven" / "WebSocket" / "real-time" | Include Socket.io client integration and real-time notification component | | "API gateway" | Configure base URL to point to gateway rather than individual services | | Backend framework mention | Validate API response format assumptions |

If the section is absent, proceed with existing CLAUDE.md-only detection.

Design System Extraction

If PRD.md contains a # Design System section with a file reference:

1. Resolve and read the referenced file
2. Map design tokens to MUI createTheme() configuration: palette, typography variants, component style overrides
3. Include a complete MUI theme configuration in SPECIFICATION.md derived from the design system tokens

If the section is absent, use default MUI theme (existing behavior).

High Level Process Flow Extraction

If PRD.md contains a # High Level Process Flow section:

1. Process flows with user-visible states inform which status values appear in MUI DataGrid filter dropdowns
2. Process flows with real-time updates inform WebSocket subscription patterns
3. Multi-step user flows inform React Router nested route design

If the section is absent, derive UI flow from user stories only (existing behavior).

---

Determining Optional Components

Instead of asking the user, the skill determines optional components by analyzing the dependencies listed in CLAUDE.md, the # Architecture Principle section in PRD.md (if present), and cross-referencing with PRD.md NFRs and constraints.

Backend API Detection

Examine the "Depends on" list in CLAUDE.md for the target application:

| Dependency Pattern | API Configuration | |---|---| | References another application's REST API | VITE_API_BASE_URL set to that app's base URL | | References a Spring Boot backend | Include Spring Boot CORS headers note | | No explicit backend | Include mock API / json-server note for development |

Authentication Detection

| Dependency / PRD Pattern | Auth Selection | |---|---| | References "Single Sign On" or "Keycloak" in CLAUDE.md dependencies | Auth = Keycloak | | PRD.md has login user stories with email/password | Auth = Local (local JWT from API) | | PRD.md constraint says "public access, no auth required" | Auth = none | | PRD.md has only public-facing content (landing page) | Auth = none |

If Auth = Keycloak, also extract from CLAUDE.md:

• Keycloak version
• Keycloak realm: Default derived from project name
• Keycloak client ID: Default -spa
• Keycloak issuer URI: Default http://localhost:8180/realms/
• Keycloak roles: Infer from mockup role folders (e.g., admin → ADMIN, editor → EDITOR)

If Auth = Local (API-managed JWT):

• Login/logout handled by API calls to the backend
• JWT stored in memory (not localStorage) for XSS protection
• Axios interceptor attaches Authorization header
• Zustand auth store manages token and user info

Optional Component Detection

| PRD.md Pattern | Component Selection | |---|---| |

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rashidee
• Source: rashidee/co2-skills
• License: MIT
• Homepage: https://compound-context.com/

Install and usage instructions live in the source repository linked above.