front-component-generator

name	front-component-generator
description	Generate a React or Vue component from a natural language description, including TypeScript types, styles, and basic tests.
when_to_use	- The user asks to create a new UI component (e.g., "Create a button with loading state", "Generate a modal component"). - The user provides a natural language description of a component and wants production-ready code (TypeScript, styles, tests). - The user mentions specific frameworks like React or Vue, or the project already uses them. - The user needs to scaffold a component following existing project conventions (styling, testing, type definitions). - The user wants to avoid manual setup for component files, types, and basic error/loading states.
tools	read, write, glob, bash
args	[{"name":"description","description":"Natural language description of the desired component","required":true},{"name":"framework","description":"Target framework, choose react or vue","required":false,"default":"react"}]

GUIDANCE SKILL — INSTRUCTIONS ONLY Frontend component generation follows a convention-first approach: inspect the existing project's tech stack, align with its conventions, and produce a complete, type-safe component with styles, types, and tests — all from a natural language description. This skill provides patterns, conventions, and constraints. It contains no executable code — apply the guidance to your context, adapting specifics as needed per C2-B.

CRITICAL: Guidance Principles

The instructions below define the REQUIRED APPROACH — you MUST follow the prescribed patterns, conventions, and constraints.

Mandatory adherence:

• Follow all stated conventions and naming patterns
• Respect all constraints and boundaries
• Apply the recommended patterns to your implementation
• Do NOT deviate from prescribed architectural decisions
• Never install new dependencies unless explicitly requested by the user and truly necessary
• Never overwrite an existing file without warning the user first
• Always present the file list and component API overview, then wait for user confirmation before creating any files
• Every component MUST handle loading, empty, and error states where applicable
• Every component MUST include necessary accessibility attributes (e.g., aria-label, role)

Correct Application Pattern

1. Read and absorb all guidance sections below
2. Map the prescribed patterns to your current context
3. Implement following the stated conventions — adapt specifics to fit, but preserve the intent
4. Validate against the C3 checklist at the end

Argument Details

Arg	Type	Required	Default	Description
description	string	Yes	—	Natural language description of the desired component
framework	string	No	react	Target framework; valid values: react or vue

Design Patterns & Conventions

Architectural Pattern

Convention-first generation pipeline: every component MUST be produced by first inspecting the host project's existing tech stack and conventions, then aligning all generated code to those conventions. The pipeline proceeds as: Inspect → Analyze → Design API → Present → Confirm → Generate. This ensures generated components integrate seamlessly rather than introducing foreign patterns.

Naming Conventions

Files and identifiers follow these rules:

Element	Convention	Example
Component file	PascalCase matching component name	Button.tsx, Modal.vue
Style file	Co-located, matching component name	Button.module.css, Modal.scss
Test file	Co-located, .test or .spec suffix	Button.test.tsx, Modal.spec.ts
Type file	Co-located types.ts or inline	types.ts or within component file
Component name	PascalCase	UserProfile, SearchInput
Props interface	{ComponentName}Props	ButtonProps, ModalProps
Event handlers	on{Event} or handle{Event}	onClick, handleSubmit

File / Module Organization

All generated files for a component are co-located in a single directory:

ComponentName/
├── ComponentName.tsx          # Main component (React) or .vue (Vue)
├── ComponentName.module.css   # Scoped styles (or .scss/.less per project)
├── ComponentName.test.tsx     # Unit tests (or .spec.ts)
└── types.ts                   # Type definitions (may be inlined for simple components)

For very simple components (single element, 1-2 props), types may be inlined in the component file and the directory may be omitted in favor of a single file.

Data Flow

User provides {{description}} + {{framework}}
  → Inspect project: read package.json, existing components, config files
    → Analyze requirement: determine props, state, events, sub-components
      → Design component API and file list
        → Present API overview + file list to user
          → Wait for explicit user confirmation
            → Generate files: component → styles → types → tests

Constraints & Boundaries

Hard Constraints (non-negotiable)

• Confirmation gate: MUST present the file list and component API overview to the user and wait for explicit confirmation before creating any files.
• No implicit dependency installation: Never install new packages unless the user explicitly requests it and the dependency is truly necessary for the component.
• No silent overwrites: Never overwrite an existing file without warning the user and receiving confirmation.
• State handling: Every component MUST handle loading, empty, and error states where applicable. A component with async data that lacks an error boundary or loading indicator is incomplete.
• Accessibility: Every component MUST include necessary accessibility attributes (aria-label, role, aria-expanded, etc.) appropriate to its function.
• No build or dev server: Do not run npm run dev, npm start, or any build/watch commands.

Soft Guidelines (preferred but flexible)

• Default to TypeScript when the project supports it; fall back to JavaScript with JSDoc only if the project is explicitly JS-only.
• Match the project's existing styling approach: CSS Modules, SCSS, styled-components, or Tailwind — do not introduce a different styling system.
• Comment briefly on non-obvious logic: state machines, async boundaries, side effects, and performance optimizations.
• Combine files when the component is simple enough (e.g., inline types for 1-2 prop components).
• Prefer functional components with hooks (React) or Composition API (Vue) over class-based components unless the project convention demands otherwise.

Implementation Guidance

Step-by-step Approach

1. Inspect the host project: Read package.json to determine dependencies (React/Vue version, TypeScript, testing library, CSS preprocessors). Read 1-2 existing components to understand project conventions (file structure, export style, styling approach, test patterns).
2. Analyze the requirement: From {{description}}, extract:
   • Props: name, type, required/optional, default values
   • State: local state, derived state, async data sources
   • Events: callbacks emitted to parent (onClick, onChange, onSubmit)
   • Sub-components: logical breakdown if the component is complex (e.g., Modal → Modal.Header, Modal.Body, Modal.Footer)
   • States to handle: loading (initial fetch), empty (no data), error (fetch failure), edge cases (invalid props)
3. Determine the file set: Based on complexity, decide which files are needed. Simple components (1-2 props, no async) may need only a component file. Complex components need all four: component, styles, types, tests.
4. Present the plan: Output a Markdown summary with:
   • Component API table: Prop name, type, required, default, description
   • File list: paths relative to the component directory
   • State handling plan: how loading/empty/error states are rendered
   • Accessibility plan: which aria- attributes and roles are needed
5. Wait for confirmation: Do NOT proceed to Step 6 until the user explicitly approves. If the user requests changes, return to Step 2.
6. Generate the files: Write each file following the project's conventions. Ensure:
   • TypeScript types are exported for reuse
   • Styles are scoped (CSS Modules, scoped styles, or BEM)
   • Tests cover: renders correctly, prop variations, event handlers, state transitions
   • Accessibility attributes are present on interactive elements

Key Decisions

Decision	Rationale	Trade-offs
Confirm-before-write gate	Prevents unwanted file creation; allows user to adjust API design before code exists	Adds a round-trip; slows down power users who trust the output
Inspect before generate	Aligns output with project conventions, avoiding style/setup mismatches	Requires readable project files; fails gracefully if package.json is absent
All three states mandatory	Incomplete state handling is the #1 source of production UI bugs	Adds boilerplate; may feel excessive for truly static components
Co-located files	Keeps component concerns together; easy to find, move, or delete	Deviates from projects that separate styles/tests into different directories
TypeScript by default	Catches prop mismatches at compile time; aligns with industry standards	Requires project to support TypeScript; adds type boilerplate for simple components

Usage Notes

Input / Output

Input:

• {{description}}: A natural language description of the desired component (required). Examples: "A button with loading, disabled, and variant states", "A modal with header, body, footer slots and escape-to-close".
• {{framework}}: Target framework — react (default) or vue.

Output (presented for confirmation before writing):

1. Component API table: Props, their types, defaults, and descriptions.
2. File list: The set of files to be created with their paths.
3. State handling plan: How loading, empty, error states are rendered.
4. Accessibility plan: Which ARIA attributes and roles are applied.

Output (written after confirmation):

• Main component file (.tsx or .vue)
• Scoped style file (matching project convention)
• Type definitions (types.ts or inlined)
• Unit test file (.test.tsx / .spec.ts)

Feature Support

Feature	Input	Output
React component	framework: react	.tsx file with hooks, CSS Modules/styles
Vue component	framework: vue	.vue SFC with Composition API
TypeScript types	Project uses TS	types.ts or inlined interface
Scoped styles	Project convention	Co-located style file
Unit tests	Project has test config	Test file with render + interaction tests
Accessibility	All components	aria- attributes and roles

Edge Cases

• No package.json found: Default to React + TypeScript + CSS Modules. Note in the plan that conventions were assumed and ask the user to confirm.
• No TypeScript in project: Generate .jsx / .js files with JSDoc type annotations. Skip types.ts.
• No testing framework configured: Skip test file generation. Note in the plan that tests were omitted due to missing test configuration.
• Component name conflict: If a file with the proposed component name already exists, warn the user and suggest an alternative name or ask for confirmation to overwrite.
• Mixed or unrecognized styling approach: If the project uses an unusual or mixed styling setup, default to CSS Modules and note the assumption.
• Ambiguous description: If {{description}} is too vague (e.g., "a card"), ask clarifying questions about props, states, and interactions before proceeding to Step 2.
• Complex sub-component tree: If the component naturally breaks into 3+ sub-components, present the tree structure in the plan and confirm the breakdown before generating.

Self-Check Before C3

Before running the formal C3 verification, confirm:

• The API overview was presented and user confirmation was received before any files were created.
• Loading, empty, and error states are handled (or explicitly noted as not applicable with reasoning).
• Accessibility attributes are present on all interactive elements.
• Generated code follows the project's existing conventions (file structure, export style, styling, testing).
• No new dependencies were installed and no existing files were silently overwritten.

Common Pitfalls

Over-adaptation: "Adapt specifics to fit" does not mean rewrite the core patterns. When in doubt, preserve the prescribed approach over local convenience — the patterns exist for a reason.

Pattern drift: As implementation progresses, it's easy to gradually deviate from conventions. Regularly re-read the Design Patterns section to catch drift early.

Skipping project inspection: Generating a component without reading package.json and existing components leads to style mismatches, incorrect imports, and broken conventions. Always inspect first — even if the user seems impatient.

Generating before confirmation: Writing files before the user approves the API design is the most common and costly mistake. The confirmation gate exists to catch misunderstandings about props, states, and file structure before code is committed.

Ignoring existing patterns: If the project uses styled-components and you generate CSS Modules, or if it exports with export default and you use named exports — the component will not integrate. Let the existing codebase dictate conventions.

Missing accessibility: Forgetting aria-label on icon-only buttons, role on custom interactive elements, or aria-expanded on toggles. Accessibility is not optional — it is a hard constraint.

C3 Verification

Check Item	Constraint	Common Omission	Method
Pattern adherence	Prescribed patterns followed	Divergent implementation	Compare against Design Patterns section
Naming conventions	Conventions applied consistently	Inconsistent naming	Grep / code review
Hard constraints	All non-negotiable constraints met	Constraint violation	Manual checklist verification
File organization	Modules/files structured as prescribed	Misplaced or missing files	Directory structure review
Confirmation gate	API overview presented; user confirmed before writes	Files written without approval	Verify conversation flow: plan → confirmation → writes
State handling	Loading, empty, error states handled or explicitly waived	Async component with no error/loading UI	Inspect generated component for state conditionals
Accessibility	aria- attributes and roles on interactive elements	Icon-only button missing aria-label	Scan generated JSX/template for ARIA attributes
Convention alignment	Generated code matches project conventions	Divergent styling or export pattern	Compare generated files against existing project components
No side effects	No dependencies installed, no dev server started, no overwrites without warning	Silent npm install or file overwrite	Confirm no bash/install commands were issued