spec-ui-component

When to use this skill

• User asks to design a new UI component or create a component spec.
• User asks to document a component's API, state machine, or behavior.
• User needs a bridge between product requirements and frontend implementation.
• User wants to define strict contracts before implementing a component.

This skill is ideal for:

• Designing complex interactive components (forms, modals, data tables).
• Establishing clear API contracts between parent and child components.
• Documenting edge cases and error states before implementation.
• Creating testable behavioral specifications.

Input Schema

When invoking this skill, provide:

component:
  name: string           # PascalCase component name
  type: "atom" | "molecule" | "organism" | "page"
  responsibility: string # One-sentence description of what it does
context:
  product_area: string   # Where this component lives (e.g., "Settings Page")
  user_role: string      # Target user (e.g., "Admin", "End User")
constraints:
  tech_stack: string     # (optional) e.g., "React + Zustand"
  performance: string    # (optional) e.g., "High latency network"
  permissions: string    # (optional) e.g., "Role-based access"

Execution Rules

1. Define Contract (The Interface)

• Use TypeScript syntax strictly.
• Define Props (Inputs) and Events (Outputs).
• Explicitly annotate State Ownership in comments:
  • [Controlled]: Owned by parent/server.
  • [Local]: Internal UI state.
  • [Computed]: Derived from props/state.
• Do NOT implement the logic, only the type signature.

2. Define Logic (The Machine)

• Use Mermaid.js (stateDiagram-v2).
• Focus on the Finite State Machine (FSM):
  • Valid States (e.g., Idle, Loading, Error, Success).
  • Transitions (Triggered by User or System).
  • Guard conditions (e.g., if data > 0).
• Do NOT use Flowcharts; use State Diagrams.

3. Define Scenarios (The Tests)

• Use Gherkin-lite syntax (Given / When / Then).
• Focus strictly on Edge Cases identified in constraints:
  • Network failures / Latency.
  • Permission denials.
  • Empty states / Partial data.
  • Concurrent user actions.

Output Format (Strict)

Output must be a single Markdown document containing exactly these three sections:

Section 1: Component Contract

interface {ComponentName}Props {
  // [Controlled] Description
  propName: Type;
}

interface {ComponentName}State {
  // [Local] Description
  stateName: Type;
}

interface {ComponentName}Events {
  // Event callbacks
  onEvent: (payload: Type) => void;
}

Section 2: State Logic

stateDiagram-v2
    [*] --> InitialState
    InitialState --> NextState: Trigger
    NextState --> FinalState: Condition

Section 3: Behavioral Scenarios

• Scenario: [Name]
  • Given initial condition
  • When user action or system event
  • Then expected outcome

Example

Input:

component:
  name: "SmartSaveButton"
  type: "molecule"
  responsibility: "Debounce user input and save to server with optimistic updates."
context:
  product_area: "Settings Page"
  user_role: "End User"
constraints:
  performance: "High latency network"

Output:

1. Component Contract

interface SmartSaveButtonProps {
  // [Controlled] The actual value to save
  value: any;
  // [Computed] Dirty state (value !== initialValue)
  isDirty: boolean;
  // [Controlled] External save handler
  onSave: (val: any) => Promise<void>;
}

interface SmartSaveButtonState {
  // [Local] Optimistic UI state
  optimisticStatus: 'idle' | 'saving' | 'saved' | 'error';
}

2. State Logic

stateDiagram-v2
    [*] --> Idle
    Idle --> Saving: User Click (Debounced)
    state Saving {
        [*] --> OptimisticUpdate
        OptimisticUpdate --> AwaitServer
    }
    AwaitServer --> Saved: 200 OK
    AwaitServer --> Error: 500 / Timeout
    Saved --> Idle: After 3s
    Error --> Idle: User Retry

3. Behavioral Scenarios

• Scenario: Rapid Clicking

  • Given the button is in 'Saving' state
  • When user clicks again immediately
  • Then the click should be ignored (disabled) to prevent race conditions.

• Scenario: Network Timeout

  • Given server takes > 10s to respond
  • When timeout threshold is reached
  • Then revert optimistic UI AND show toast error.

Output Location

Save generated specs to: doc/specs/{component-name}-spec.md

Requirements

• TypeScript knowledge for contract definitions.
• Mermaid.js for state diagram rendering.
• Understanding of component state ownership patterns.