Specgen React Tailwind

React SPA Specification Generator (Tailwind CSS)

This skill generates a comprehensive specification document (Markdown) that serves as a blueprint for building a React Single Page Application styled with Tailwind CSS. 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 the Tailwind design-token theme to React Query patterns — so that implementation becomes a mechanical exercise.

This skill is the Tailwind-CSS sibling of specgen-react-mui. It keeps the same React data stack (React Router, TanStack Query, Zustand, React Hook Form, Zod, Axios) but replaces the Material UI component framework with a utility-first Tailwind layer: components are hand-built with Tailwind classes and made accessible with Headless UI primitives (Dialog, Menu, Listbox, Combobox, Switch, Tabs, Popover, Transition) and Heroicons.

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 | | Tailwind CSS | 3.x | | PostCSS | 8.x | | Autoprefixer | 10.x | | @tailwindcss/forms | 0.5.x | | Headless UI (@headlessui/react) | 2.x | | Heroicons (@heroicons/react) | 2.x | | clsx | 2.x | | tailwind-merge | 2.x | | class-variance-authority | 0.7.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| | @tanstack/react-table| 8.x | DataGrid = yes | | recharts | 2.x | Charts = yes | | react-day-picker | 9.x | DatePickers = yes | | date-fns | 4.x | DatePickers = yes | | Socket.io Client | 4.x | WebSocket = yes | | react-i18next | 15.x | i18n = yes | | i18next | 24.x | i18n = yes | | @tiptap/react + @tiptap/starter-kit | 2.x | RichText = yes | | @tailwindcss/typography | 0.5.x | RichText = yes |

Core Dependencies (package.json)

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

Production dependencies:

• react + react-dom — Core React
• 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
• @headlessui/react — Accessible, unstyled interactive primitives (Dialog, Menu, Listbox, Combobox, Switch, Tabs, Popover, Transition)
• @heroicons/react — Icon set (outline + solid)
• clsx — Conditional className composition
• tailwind-merge — Resolve conflicting Tailwind classes (powers the cn() helper)
• class-variance-authority — Type-safe component style variants (Button, Badge, etc.)

Development dependencies:

• typescript — Type checking
• @types/react + @types/react-dom — React type definitions
• vite + @vitejs/plugin-react — Build tooling
• tailwindcss + postcss + autoprefixer — Tailwind CSS build pipeline
• @tailwindcss/forms — Sensible form-control reset that pairs well with Headless UI inputs
• @tanstack/react-query-devtools — Query devtools (dev only)
• 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:

• @tanstack/react-table — Headless table/data-grid (sorting, filtering, pagination, row selection) styled with Tailwind

If Charts = yes:

• recharts — Composable SVG chart components

If DatePickers = yes:

• react-day-picker — Accessible date/range picker rendered inside a Headless UI Popover
• date-fns — Date manipulation and formatting

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:

• @tiptap/react + @tiptap/starter-kit — Headless, extensible WYSIWYG editor (React 19 compatible)
• @tiptap/extension-link + @tiptap/extension-placeholder — Common editor extensions
• @tailwindcss/typography — prose classes to style rendered rich-text HTML
• dompurify + @types/dompurify — HTML sanitization when rendering stored 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-tailwind admin v1.0.4
• /specgen-react-tailwind admin v1.0.4 module:Hero Section
• /specgen-react-tailwind "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 Tailwind/Headless UI 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
• Tailwind/Headless UI component selections (TanStack Table vs simple table, Headless UI

Dialog vs slide-over panel, etc.)

• Form field layouts
• Navigation items per role
• Tailwind design tokens (extract colors, font, radius, spacing from the mockup CSS/config)

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 the Tailwind theme: extend colors, fontFamily, borderRadius,

spacing, and boxShadow in tailwind.config.js, and seed CSS custom properties in src/index.css for light/dark token values

1. Include a complete tailwind.config.js in SPECIFICATION.md derived from the design system tokens

If the section is absent, derive tokens from the mockup CSS (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 list/table filter dropdowns
2. Process flows with real-time updates inform WebSocket subscription patterns
3. Multi-step user flows inform React Router nested ro

…

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.