React Component Architect

When to use this skill

• User asks to create a new React component
• User wants component scaffolding with tests and stories
• User mentions Next.js component creation
• User asks for TypeScript interfaces for props
• User wants CSS modules or styled components setup

Workflow

• [ ] Determine component name and location
• [ ] Detect project conventions (file structure, styling approach)
• [ ] Generate component file with TypeScript props
• [ ] Create CSS module with design tokens
• [ ] Generate test file
• [ ] Create Storybook story
• [ ] Export from index if barrel pattern used

Instructions

Step 1: Determine Component Details

Gather from user:

• Component name (PascalCase)
• Location: src/components/, app/components/, or feature folder
• Type: presentational, container, layout, or page component

Derive file paths:

src/components/Button/
├── Button.tsx
├── Button.module.css
├── Button.test.tsx
├── Button.stories.tsx
└── index.ts

Step 2: Detect Project Conventions

Styling approach:

ls src/**/*.module.css src/**/*.module.scss 2>/dev/null | head -1 && echo "CSS Modules"
ls src/**/*.styled.ts src/**/*.styles.ts 2>/dev/null | head -1 && echo "Styled Components"
npm ls tailwindcss 2>/dev/null && echo "Tailwind CSS"

Test framework:

npm ls jest vitest @testing-library/react 2>/dev/null

Storybook:

ls .storybook/main.* 2>/dev/null && echo "Storybook configured"

Barrel exports:

ls src/components/index.ts 2>/dev/null && echo "Uses barrel exports"

Step 3: Generate Component File

Use the standard FC structure with TypeScript:

• Export interface for props with JSDoc comments
• Use FC<Props> or forwardRef for DOM access
• Destructure props with defaults
• Apply CSS module classes

See component-templates.md for full templates including:

• Standard FC component
• forwardRef pattern
• Hooks pattern
• Next.js Server/Client components

Step 4: Create CSS Module

Use design tokens for consistency:

.root {
  padding: var(--spacing-md, 1rem);
  border-radius: var(--radius-md, 0.5rem);
  background-color: var(--color-primary, #3b82f6);
}

[data-disabled="true"] {
  opacity: 0.5;
  cursor: not-allowed;
}

Step 5: Generate Test File

Use Testing Library with Vitest/Jest:

import { render, screen, fireEvent } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";
import { ComponentName } from "./ComponentName";

describe("ComponentName", () => {
  it("renders children", () => {
    render(<ComponentName>Hello</ComponentName>);
    expect(screen.getByText("Hello")).toBeInTheDocument();
  });

  it("handles click when not disabled", () => {
    const onClick = vi.fn();
    render(<ComponentName onClick={onClick}>Click me</ComponentName>);
    fireEvent.click(screen.getByText("Click me"));
    expect(onClick).toHaveBeenCalledOnce();
  });
});

See testing.md for user events, async testing, context, and hooks testing.

Step 6: Create Storybook Story

Use CSF3 format for Storybook 7+:

import type { Meta, StoryObj } from "@storybook/react";
import { ComponentName } from "./ComponentName";

const meta: Meta<typeof ComponentName> = {
  title: "Components/ComponentName",
  component: ComponentName,
  tags: ["autodocs"],
  argTypes: {
    variant: { control: "select", options: ["primary", "secondary"] },
  },
};

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: { children: "Primary Button", variant: "primary" },
};

See storybook.md for decorators, play functions, and MDX docs.

Step 7: Create Barrel Export

index.ts:

export { ComponentName } from "./ComponentName";
export type { ComponentNameProps } from "./ComponentName";

Update parent barrel (if exists):

// src/components/index.ts
export * from "./ComponentName";

Common Patterns

Compound components:

export const Card = Object.assign(CardRoot, {
  Header: CardHeader,
  Body: CardBody,
});

Polymorphic component:

interface BoxProps<T extends React.ElementType = "div"> {
  as?: T;
}

Context provider:

const Context = createContext<Value | null>(null);
export const useContext = () => {
  const ctx = useContext(Context);
  if (!ctx) throw new Error("Must be used within Provider");
  return ctx;
};

See advanced-patterns.md for compound components, HOCs, render props, and error boundaries.

Validation

Before completing:

• [ ] Component renders without errors
• [ ] TypeScript has no errors
• [ ] Props interface is exported
• [ ] CSS module imports correctly
• [ ] Tests pass
• [ ] Story renders in Storybook
• [ ] Barrel export updated

Error Handling

• Module not found: Check import paths use correct relative paths.
• CSS module types: Add declare module '*.module.css' to global types if needed.
• Test setup missing: Ensure @testing-library/react and @testing-library/jest-dom are installed.
• Storybook not rendering: Check .storybook/main.js includes correct story glob pattern.
• Unsure about conventions: Check existing components in project for patterns.

Resources

• React TypeScript Cheatsheet
• Testing Library Documentation
• Storybook Documentation

Examples

• Component Templates — FC, forwardRef, hooks, Next.js patterns
• Testing — User events, async, context, hooks testing
• Storybook — Decorators, play functions, MDX docs
• Advanced Patterns — Compound components, HOCs, error boundaries