| name | create-component |
|---|---|
| model | standard |
| description | Scaffold a UI component with variants, props, accessibility, and documentation |
| usage | /create-component <name> [--variant] [--interactive] [--with-tests] [--with-story] |
Scaffold a production-ready UI component with variants, typed props, accessibility, and optional tests and stories.
/create-component <name> [--variant] [--interactive] [--with-tests] [--with-story]
Arguments:
name— Component name in PascalCase (e.g.,Button,UserCard,SearchInput)--variant— Include visual variants (primary, secondary, outline, ghost, etc.)--interactive— Add event handlers, state management, and controlled/uncontrolled modes--with-tests— Generate a co-located test file with unit tests for props, variants, and accessibility--with-story— Generate a Storybook story file with variant showcases and controls
/create-component Button --variant --interactive --with-tests --with-story
/create-component UserCard --variant --with-story
/create-component SearchInput --interactive --with-tests
/create-component Modal --variant --interactive --with-tests --with-story
/create-component Avatar --variant
- Starting a new UI component from scratch
- Adding a component to an existing design system or component library
- Replacing an ad-hoc element with a properly typed, accessible component
- Prototyping a component that needs variant support from day one
- When you need consistent file structure across a component library
- Parses the component name and flags from the input
- Detects the project's framework and styling approach automatically
- Generates the component file with typed props and sensible defaults
- Adds visual variants and prop-driven styling when
--variantis set - Adds accessibility attributes, keyboard navigation, and ARIA roles
- Generates test and story files when
--with-testsor--with-storyare set - Creates a barrel export and reports all generated files
Use TodoWrite to track progress through each phase.
- Extract the component
namefrom the first argument. - Validate that the name is PascalCase. If not, convert it and warn:
"Converted
user-cardtoUserCard." - Parse boolean flags:
--variant,--interactive,--with-tests,--with-story. - Derive the kebab-case directory name from the PascalCase name (e.g.,
UserCard->user-card).
Use Glob and Grep to scan the project root and src/ for configuration files and import patterns.
Framework detection:
| Indicator | Framework | File Extension |
|---|---|---|
tsconfig.json + .tsx files |
React (TypeScript) | .tsx |
.jsx files, react in package.json |
React (JavaScript) | .jsx |
*.vue files, vue in package.json |
Vue (SFC) | .vue |
*.svelte files, svelte in package.json |
Svelte | .svelte |
@angular/core in package.json |
Angular | .component.ts |
react-native in package.json |
React Native | .tsx |
solid-js in package.json |
Solid | .tsx |
If multiple indicators match, prefer the one with the most file hits. If none match, default to React with TypeScript and inform the user.
Styling detection:
| Indicator | Approach | Usage |
|---|---|---|
tailwind.config.* or @tailwind in CSS |
Tailwind CSS | Utility classes in className |
*.module.css or *.module.scss files |
CSS Modules | Import as styles, use styles.className |
styled-components in package.json |
Styled Components | Tagged template literals |
@emotion/react or @emotion/styled in package.json |
Emotion | css prop or styled API |
*.css files co-located with components |
Vanilla CSS | Plain class names |
| None of the above | Inline styles | style prop as fallback |
Component directory detection:
Use Glob to find the existing component directory. Check in order:
src/components/components/app/components/lib/components/src/ui/
If no component directory exists, create src/components/ and inform the user.
Create the component file based on detected framework. Place it at [component-dir]/[kebab-name]/[Name].[ext].
Component structure by framework:
| Framework | Props Definition | Component Pattern | Export Style |
|---|---|---|---|
| React (TS) | interface [Name]Props |
forwardRef function component |
Named export |
| React (JS) | JSDoc + propTypes |
forwardRef function component |
Named export |
| Vue | defineProps<{}>() |
<script setup lang="ts"> SFC |
Default export |
| Svelte | export let prop declarations |
Svelte component | Default export |
| Angular | @Input() decorators |
@Component class |
Class export |
| React Native | interface [Name]Props |
forwardRef function component |
Named export |
| Solid | interface [Name]Props |
Function component with splitProps |
Named export |
Every generated component must include:
- A
Propstype or interface with JSDoc comments on each prop - A
displayName(React) or equivalent identifier - A
refforwarding mechanism when the framework supports it - Default prop values where sensible
- A
classNameorclassprop for style overriding
Skip this phase if --variant was not set.
- Define a
variantprop with a union type:'default' | 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive'. - Define a
sizeprop with a union type:'sm' | 'md' | 'lg'. - Map each variant and size to styling using the detected styling approach.
- For Tailwind: use a variant mapping object with
cvaor a plain record. - For CSS Modules: generate a
.module.cssfile with classes for each variant. - For Styled Components / Emotion: use a
variantsprop pattern. - For vanilla CSS: generate a
.cssfile with BEM-style variant classes. - Export the variant and size types so consumers can reference them.
Apply the following checklist to the generated component. Every item must be addressed:
| Requirement | Implementation |
|---|---|
| ARIA role | Set the semantic role (button, dialog, alert, etc.) or use the correct HTML element |
| Keyboard navigation | Handle Enter, Space, Escape, Tab, and arrow keys as appropriate for the role |
| Focus management | Ensure focusable elements have visible focus indicators; manage focus traps for modals/dialogs |
| Screen reader labels | Add aria-label, aria-labelledby, or aria-describedby when visual label is absent |
| Color contrast | Add a code comment noting WCAG AA contrast requirement (4.5:1 for text, 3:1 for large text) |
| Disabled state | Support disabled prop with aria-disabled and prevent interaction when disabled |
| Loading state | Support loading prop with aria-busy="true" and a visually-hidden status message |
| Reduced motion | Wrap animations in prefers-reduced-motion media query or equivalent |
For interactive components (--interactive), also add:
roleandaria-expandedfor collapsible elementsaria-haspopupfor menu triggersaria-pressedfor toggle buttons- Keyboard event handlers that mirror click behavior
Tests (when --with-tests is set):
Detect the test runner:
| Indicator | Runner | Import |
|---|---|---|
vitest in package.json |
Vitest | import { describe, it, expect } from 'vitest' |
jest in package.json |
Jest | import { describe, it, expect } from '@jest/globals' |
@testing-library/react |
React Testing Library | import { render, screen } from '@testing-library/react' |
@testing-library/vue |
Vue Testing Library | import { render } from '@testing-library/vue' |
@testing-library/svelte |
Svelte Testing Library | import { render } from '@testing-library/svelte' |
Generate a test file at [component-dir]/[kebab-name]/[Name].test.[ext] with:
- Renders without crashing
- Renders with default props
- Renders each variant (if
--variant) - Renders each size (if
--variant) - Handles click events (if
--interactive) - Supports disabled state
- Meets accessibility baseline (
toHaveNoViolationsifjest-axeorvitest-axeis available) - Forwards ref correctly
Stories (when --with-story is set):
Generate a story file at [component-dir]/[kebab-name]/[Name].stories.[ext] with:
- Default story
- One story per variant (if
--variant) - One story per size (if
--variant) - Interactive story with actions (if
--interactive) - A "Playground" story with all controls exposed via
argTypes
- Create or update
[component-dir]/[kebab-name]/index.[ext]to re-export the component and its types. - If a top-level barrel file exists at
[component-dir]/index.[ext], append the new export. - Use
Bashto verify no syntax errors: runnpx tsc --noEmit(TypeScript) or the framework's equivalent. - Report all generated files and their paths.
Output a summary:
Component Scaffolded
====================
Name: [Name]
Framework: [detected framework]
Styling: [detected approach]
Directory: [full path]
Files created:
[component-dir]/[kebab-name]/[Name].tsx
[component-dir]/[kebab-name]/[Name].types.ts
[component-dir]/[kebab-name]/[Name].test.tsx (--with-tests)
[component-dir]/[kebab-name]/[Name].stories.tsx (--with-story)
[component-dir]/[kebab-name]/index.ts
Props: [list of props with types]
Variants: [list of variants, if applicable]
Sizes: [list of sizes, if applicable]
A11y: [checklist items addressed]
| Rule | Reason |
|---|---|
| NEVER generate a component without typed props | Untyped props erode maintainability and break IDE autocompletion |
| NEVER skip accessibility attributes | Components without ARIA roles, keyboard support, and focus management exclude users |
| NEVER hardcode colors or spacing values | Always use design tokens, theme variables, or Tailwind classes for consistency |
NEVER use any or untyped event handlers |
Every handler and prop must have an explicit type signature |
| NEVER create a default export for React components | Named exports enable better tree-shaking, refactoring, and import autocompletion |
| NEVER put business logic inside the component | Components handle presentation only; logic belongs in hooks, stores, or services |
| NEVER ignore the existing project conventions | Match the naming, file structure, and patterns already used in the codebase |
| NEVER generate files outside the detected component directory | Respect the project layout; never scatter files across unrelated directories |
| Situation | Action |
|---|---|
| Component name is not PascalCase | Auto-convert and warn the user (e.g., user-card becomes UserCard) |
| No framework detected | Default to React with TypeScript. Inform the user and ask to confirm. |
| No component directory found | Create src/components/ and inform the user of the new directory. |
| Component with the same name already exists | Stop and warn. Ask the user whether to overwrite or choose a different name. |
| Styling approach cannot be determined | Default to vanilla CSS with a plain .css file. Inform the user. |
| Test runner not found | Skip test generation even if --with-tests was set. Warn the user to install a test runner. |
| Storybook not installed | Skip story generation even if --with-story was set. Warn the user to install Storybook. |
| TypeScript check fails after generation | Display the errors and offer to fix them before finishing. |
- Component file —
[Name].tsx(or framework-appropriate extension) - Types/props file —
[Name].types.ts(or co-located in the component for Vue/Svelte) - Test file (optional) —
[Name].test.tsxwhen--with-testsis set - Story file (optional) —
[Name].stories.tsxwhen--with-storyis set - Barrel export —
index.tsre-exporting the component and its types
- Skill:
shadcn-ui(for installing pre-built accessible components) - Skill:
ui-ux-pro-max(for design guidance, palettes, and layout patterns) - Skill:
ui-design(UI design fundamentals) - Skill:
react-composition(composition patterns for scalable components) - Skill:
responsive-design(responsive layout strategies) - Command:
/new-feature(for full feature workflows that include component creation)