aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/build-component.md

@@ -1,478 +1,478 @@
-# Build Production-Ready Component
-
-> Task ID: atlas-build-component
-> Agent: Atlas (Design System Builder)
-> Version: 1.0.0
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: buildComponent()
-responsável: Uma (Empathizer)
-responsavel_type: Agente
-atomic_layer: Molecule
-
-**Entrada:**
-- campo: name
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Must be non-empty, lowercase, kebab-case
-
-- campo: options
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Valid JSON object with allowed keys
-
-- campo: force
-  tipo: boolean
-  origem: User Input
-  obrigatório: false
-  validação: Default: false
-
-**Saída:**
-- campo: created_file
-  tipo: string
-  destino: File system
-  persistido: true
-
-- campo: validation_report
-  tipo: object
-  destino: Memory
-  persistido: false
-
-- campo: success
-  tipo: boolean
-  destino: Return value
-  persistido: false
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Target does not already exist; required inputs provided; permissions granted
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check target does not already exist; required inputs provided; permissions granted
-    error_message: "Pre-condition failed: Target does not already exist; required inputs provided; permissions granted"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Resource created successfully; validation passed; no errors logged
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify resource created successfully; validation passed; no errors logged
-    error_message: "Post-condition failed: Resource created successfully; validation passed; no errors logged"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Resource exists and is valid; no duplicate resources created
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert resource exists and is valid; no duplicate resources created
-    error_message: "Acceptance criterion not met: Resource exists and is valid; no duplicate resources created"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** component-generator
-  - **Purpose:** Generate new components from templates
-  - **Source:** .aios-core/scripts/component-generator.js
-
-- **Tool:** file-system
-  - **Purpose:** File creation and validation
-  - **Source:** Node.js fs module
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** create-component.js
-  - **Purpose:** Component creation workflow
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/create-component.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Resource Already Exists
-   - **Cause:** Target file/resource already exists in system
-   - **Resolution:** Use force flag or choose different name
-   - **Recovery:** Prompt user for alternative name or force overwrite
-
-2. **Error:** Invalid Input
-   - **Cause:** Input name contains invalid characters or format
-   - **Resolution:** Validate input against naming rules (kebab-case, lowercase, no special chars)
-   - **Recovery:** Sanitize input or reject with clear error message
-
-3. **Error:** Permission Denied
-   - **Cause:** Insufficient permissions to create resource
-   - **Resolution:** Check file system permissions, run with elevated privileges if needed
-   - **Recovery:** Log error, notify user, suggest permission fix
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 2-5 min (estimated)
-cost_estimated: $0.001-0.003
-token_usage: ~1,000-3,000 tokens
-```
-
-**Optimization Notes:**
-- Parallelize independent operations; reuse atom results; implement early exits
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - automation
-  - workflow
-updated_at: 2025-11-17
-```
-
----
-
-
-## Description
-
-Generate production-ready React TypeScript component from design tokens. Output follows Shadcn-style Tailwind utility patterns with `cva` variants, optional Radix composition, tests, Storybook stories, and documentation. All styling uses tokens/variables (zero hardcoded values) and supports loading/accessibility states out of the box.
-
-## Prerequisites
-
-- Setup completed (*setup command run successfully)
-- Tokens loaded and accessible
-- React and TypeScript configured
-
-## Workflow
-
-### Interactive Elicitation
-
-This task uses interactive elicitation to configure component.
-
-1. **Select Component Type**
-   - Atomic level (atom, molecule, organism)
-   - Component name (Button, Input, Card, etc)
-   - Confirm token availability for this component
-
-2. **Configure Component Features**
-   - Variants needed (primary, secondary, destructive)
-   - Sizes needed (sm, md, lg)
-   - States needed (hover, disabled, loading, error)
-   - Additional props
-
-3. **Review Generation Plan**
-   - Show files to be generated
-   - Confirm test coverage requirements
-   - Ask for Storybook stories (if enabled)
-
-### Steps
-
-1. **Validate Prerequisites**
-   - Check tokens are loaded
-   - Verify component doesn't already exist (or confirm overwrite)
-   - Validate component name (PascalCase)
-   - Validation: Ready to generate
-
-2. **Load Token References**
-   - Identify which tokens this component needs
-   - Validate token availability
-   - Generate token import statements
-   - Validation: All required tokens exist
-
-3. **Generate Component File**
-   - Create React component using `React.forwardRef` + `Slot` (Radix pattern)
-   - Import `cva` + `cn` helpers (`class-variance-authority`, `tailwind-merge`)
-   - Implement variants, sizes, density, and loading states
-   - Wire ARIA attributes, keyboard handling, dark mode parity
-   - Validation: Valid TypeScript (strict), lint clean, no hardcoded CSS values
-
-4. **Author Variant Catalogue**
-   - Define `cva` config (base classes, variants, compound variants, defaults)
-   - Map variant classes to tokens (Tailwind utilities referencing design tokens)
-   - Generate story-friendly helper types (VariantProps)
-   - Validation: Variants align with consolidated tokens and atomic level
-
-5. **Generate Unit Tests**
-   - Create test file ({Component}.test.tsx) with RTL + jest-axe
-   - Snapshot default render, variant permutations, responsive classes
-   - Test loading/disabled state interactions and event handlers
-   - Aim for >85% coverage including accessibility assertions
-   - Validation: Tests pass locally (npm test) with coverage gated
-
-6. **Generate Storybook Stories (Optional)**
-   - If Storybook enabled, create {Component}.stories.tsx (Storybook 8 syntax)
-   - Provide CSF stories for each variant/size & loading state
-   - Configure controls, play functions, a11y addon
-   - Validation: `npm run storybook` renders without warnings
-
-7. **Run Accessibility Checks**
-   - Validate ARIA attributes + keyboard flows (Tab/Shift+Tab/Space/Enter)
-   - Check WCAG 2.2 AA + APCA contrast, including dark mode tokens
-   - Ensure focus-visible styles present and themable
-   - Validation: jest-axe passes, manual keyboard traversal verified
-
-8. **Generate Component Documentation**
-   - Create {Component}.md in docs/ with overview + variant tables
-   - Document props, TypeScript types, default variants, composition notes
-   - Include usage for light/dark themes, loading state, accessibility guidance
-   - Validation: Docs align with generated code and tokens
-
-9. **Update Component Index**
-   - Add to design-system/index.ts
-   - Export component for easy import
-   - Update barrel exports
-   - Validation: Component importable
-
-10. **Update State File**
-    - Add component to patterns_built in .state.yaml
-    - Record atomic level, variants, test coverage
-    - Increment component count
-    - Validation: State tracking updated
-
-## Output
-
-- **{Component}.tsx**: React TypeScript component (forwardRef + cva)
-- **{Component}.test.tsx**: Unit + accessibility tests
-- **{Component}.stories.tsx**: Storybook stories (optional)
-- **{Component}.md**: Component reference documentation
-- **ui/index.ts**: Barrel export updated
-- **.state.yaml**: Updated with component metadata + variant catalog
-
-### Output Format
-
-```typescript
-// button.tsx
-import * as React from 'react';
-import { Slot } from '@radix-ui/react-slot';
-import { cva, type VariantProps } from 'class-variance-authority';
-import { cn } from '@/lib/utils';
-import { Spinner } from '@/components/ui/spinner';
-
-export const buttonVariants = cva(
-  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-70',
-  {
-    variants: {
-      variant: {
-        primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
-        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/90',
-        outline: 'border border-border bg-transparent hover:bg-muted'
-      },
-      size: {
-        sm: 'h-9 px-3',
-        md: 'h-10 px-4',
-        lg: 'h-12 px-6 text-base',
-        icon: 'h-10 w-10'
-      }
-    },
-    defaultVariants: {
-      variant: 'primary',
-      size: 'md'
-    }
-  }
-);
-
-export interface ButtonProps
-  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
-    VariantProps<typeof buttonVariants> {
-  asChild?: boolean;
-  isLoading?: boolean;
-  loadingIcon?: React.ReactNode;
-}
-
-const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  (
-    { className, variant, size, asChild = false, isLoading = false, loadingIcon, children, ...props },
-    ref
-  ) => {
-    const Comp = asChild ? Slot : 'button';
-
-    return (
-      <Comp
-        ref={ref}
-        className={cn(buttonVariants({ variant, size }), className, isLoading && 'pointer-events-none')}
-        data-state={isLoading ? 'loading' : props['data-state']}
-        aria-busy={isLoading}
-        {...props}
-      >
-        {isLoading && (loadingIcon ?? <Spinner className="mr-2 h-4 w-4 animate-spin" />)}
-        <span className="inline-flex items-center gap-1">{children}</span>
-      </Comp>
-    );
-  }
-);
-Button.displayName = 'Button';
-
-export { Button };
-```
-
-## Success Criteria
-
-- [ ] Component compiles without TypeScript errors (strict) and passes lint
-- [ ] Variants implemented via `cva` with token-backed Tailwind utilities
-- [ ] Props fully typed (VariantProps + custom props) with TSDoc
-- [ ] Loading/disabled states, accessibility attributes, and dark mode supported
-- [ ] Unit + jest-axe tests pass with ≥85% coverage
-- [ ] Storybook stories render (if enabled) with controls + docs tab
-- [ ] Component documentation published with variant/density tables
-- [ ] .state.yaml updated with variant catalogue + QA status
-
-## Error Handling
-
-- **Token not found**: Report which token is missing, suggest alternatives
-- **Component exists**: Ask to overwrite or use different name
-- **TypeScript errors**: Display errors, suggest fixes
-- **Test failures**: Show failing tests, don't complete until fixed
-- **Accessibility violations**: Warn and suggest improvements
-
-## Security Considerations
-
-- Sanitize component name (prevent injection)
-- Validate token references
-- Escape user content in examples
-- No eval() or dynamic code execution
-
-## Examples
-
-### Example 1: Build Button Component
-
-```bash
-*build button
-```
-
-Output:
-```
-🏗️ Atlas: Building Button component...
-
-📋 Configuration:
-  - Type: Atom
-  - Variants: primary, secondary, outline
-  - Sizes: sm, md, lg, icon
-  - Loading state: enabled (spinner)
-  - Tests: RTL + jest-axe (>85% coverage)
-  - Storybook: Yes
-
-✓ Generated button.tsx (Shadcn-style, cva variants)
-✓ Generated button.test.tsx (22 tests, jest-axe assertions)
-✓ Generated button.stories.tsx (8 stories, controls + docs)
-✓ Generated button.md (usage + theming guidance)
-
-🧪 Running tests...
-  ✓ renders default button (matches snapshot)
-  ✓ applies variant classes via cva
-  ✓ shows spinner + disables interactions when loading
-  ✓ passes accessibility audit (jest-axe)
-  ✓ supports asChild slot rendering
-  Coverage: 96.4%
-
-♿ Accessibility check:
-  ✓ ARIA attributes present
-  ✓ Color contrast: 4.8:1 (WCAG AA ✓)
-  ✓ Keyboard navigable
-  ✓ Focus indicators visible
-
-✅ Button component ready!
-
-Import: `import { Button } from '@/components/ui/button';`
-Usage: `<Button variant="primary" isLoading>Saving</Button>`
-
-Atlas says: "Built right. Built once."
-```
-
-### Example 2: Build Input Component
-
-```bash
-*build input
-```
-
-Output includes additional features:
-- Validation states (error, success)
-- Helper text prop
-- Label integration
-- Icon slots
-
-## Notes
-
-- All components strictly typed with TypeScript
-- Zero hardcoded values enforced (tokens only)
-- Accessibility is non-negotiable (WCAG AA minimum)
-- Test coverage >80% required
-- Tailwind utilities + tokens ensure zero hardcoded values
-- Variants and sizes extend via `cva` without editing component body
-- Components are tree-shakeable and server-component friendly
-- Storybook stories enable visual + interaction testing
-- Documentation mirrors props/types for instant onboarding
-- Components follow Atomic Design principles
-- Atlas ensures quality at every step
+# Build Production-Ready Component
+
+> Task ID: atlas-build-component
+> Agent: Atlas (Design System Builder)
+> Version: 1.0.0
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: buildComponent()
+responsável: Uma (Empathizer)
+responsavel_type: Agente
+atomic_layer: Molecule
+
+**Entrada:**
+- campo: name
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be non-empty, lowercase, kebab-case
+
+- campo: options
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid JSON object with allowed keys
+
+- campo: force
+  tipo: boolean
+  origem: User Input
+  obrigatório: false
+  validação: Default: false
+
+**Saída:**
+- campo: created_file
+  tipo: string
+  destino: File system
+  persistido: true
+
+- campo: validation_report
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: success
+  tipo: boolean
+  destino: Return value
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target does not already exist; required inputs provided; permissions granted
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target does not already exist; required inputs provided; permissions granted
+    error_message: "Pre-condition failed: Target does not already exist; required inputs provided; permissions granted"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Resource created successfully; validation passed; no errors logged
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify resource created successfully; validation passed; no errors logged
+    error_message: "Post-condition failed: Resource created successfully; validation passed; no errors logged"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Resource exists and is valid; no duplicate resources created
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert resource exists and is valid; no duplicate resources created
+    error_message: "Acceptance criterion not met: Resource exists and is valid; no duplicate resources created"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** component-generator
+  - **Purpose:** Generate new components from templates
+  - **Source:** .aios-core/scripts/component-generator.js
+
+- **Tool:** file-system
+  - **Purpose:** File creation and validation
+  - **Source:** Node.js fs module
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** create-component.js
+  - **Purpose:** Component creation workflow
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/create-component.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Resource Already Exists
+   - **Cause:** Target file/resource already exists in system
+   - **Resolution:** Use force flag or choose different name
+   - **Recovery:** Prompt user for alternative name or force overwrite
+
+2. **Error:** Invalid Input
+   - **Cause:** Input name contains invalid characters or format
+   - **Resolution:** Validate input against naming rules (kebab-case, lowercase, no special chars)
+   - **Recovery:** Sanitize input or reject with clear error message
+
+3. **Error:** Permission Denied
+   - **Cause:** Insufficient permissions to create resource
+   - **Resolution:** Check file system permissions, run with elevated privileges if needed
+   - **Recovery:** Log error, notify user, suggest permission fix
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 2-5 min (estimated)
+cost_estimated: $0.001-0.003
+token_usage: ~1,000-3,000 tokens
+```
+
+**Optimization Notes:**
+- Parallelize independent operations; reuse atom results; implement early exits
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Description
+
+Generate production-ready React TypeScript component from design tokens. Output follows Shadcn-style Tailwind utility patterns with `cva` variants, optional Radix composition, tests, Storybook stories, and documentation. All styling uses tokens/variables (zero hardcoded values) and supports loading/accessibility states out of the box.
+
+## Prerequisites
+
+- Setup completed (*setup command run successfully)
+- Tokens loaded and accessible
+- React and TypeScript configured
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to configure component.
+
+1. **Select Component Type**
+   - Atomic level (atom, molecule, organism)
+   - Component name (Button, Input, Card, etc)
+   - Confirm token availability for this component
+
+2. **Configure Component Features**
+   - Variants needed (primary, secondary, destructive)
+   - Sizes needed (sm, md, lg)
+   - States needed (hover, disabled, loading, error)
+   - Additional props
+
+3. **Review Generation Plan**
+   - Show files to be generated
+   - Confirm test coverage requirements
+   - Ask for Storybook stories (if enabled)
+
+### Steps
+
+1. **Validate Prerequisites**
+   - Check tokens are loaded
+   - Verify component doesn't already exist (or confirm overwrite)
+   - Validate component name (PascalCase)
+   - Validation: Ready to generate
+
+2. **Load Token References**
+   - Identify which tokens this component needs
+   - Validate token availability
+   - Generate token import statements
+   - Validation: All required tokens exist
+
+3. **Generate Component File**
+   - Create React component using `React.forwardRef` + `Slot` (Radix pattern)
+   - Import `cva` + `cn` helpers (`class-variance-authority`, `tailwind-merge`)
+   - Implement variants, sizes, density, and loading states
+   - Wire ARIA attributes, keyboard handling, dark mode parity
+   - Validation: Valid TypeScript (strict), lint clean, no hardcoded CSS values
+
+4. **Author Variant Catalogue**
+   - Define `cva` config (base classes, variants, compound variants, defaults)
+   - Map variant classes to tokens (Tailwind utilities referencing design tokens)
+   - Generate story-friendly helper types (VariantProps)
+   - Validation: Variants align with consolidated tokens and atomic level
+
+5. **Generate Unit Tests**
+   - Create test file ({Component}.test.tsx) with RTL + jest-axe
+   - Snapshot default render, variant permutations, responsive classes
+   - Test loading/disabled state interactions and event handlers
+   - Aim for >85% coverage including accessibility assertions
+   - Validation: Tests pass locally (npm test) with coverage gated
+
+6. **Generate Storybook Stories (Optional)**
+   - If Storybook enabled, create {Component}.stories.tsx (Storybook 8 syntax)
+   - Provide CSF stories for each variant/size & loading state
+   - Configure controls, play functions, a11y addon
+   - Validation: `npm run storybook` renders without warnings
+
+7. **Run Accessibility Checks**
+   - Validate ARIA attributes + keyboard flows (Tab/Shift+Tab/Space/Enter)
+   - Check WCAG 2.2 AA + APCA contrast, including dark mode tokens
+   - Ensure focus-visible styles present and themable
+   - Validation: jest-axe passes, manual keyboard traversal verified
+
+8. **Generate Component Documentation**
+   - Create {Component}.md in docs/ with overview + variant tables
+   - Document props, TypeScript types, default variants, composition notes
+   - Include usage for light/dark themes, loading state, accessibility guidance
+   - Validation: Docs align with generated code and tokens
+
+9. **Update Component Index**
+   - Add to design-system/index.ts
+   - Export component for easy import
+   - Update barrel exports
+   - Validation: Component importable
+
+10. **Update State File**
+    - Add component to patterns_built in .state.yaml
+    - Record atomic level, variants, test coverage
+    - Increment component count
+    - Validation: State tracking updated
+
+## Output
+
+- **{Component}.tsx**: React TypeScript component (forwardRef + cva)
+- **{Component}.test.tsx**: Unit + accessibility tests
+- **{Component}.stories.tsx**: Storybook stories (optional)
+- **{Component}.md**: Component reference documentation
+- **ui/index.ts**: Barrel export updated
+- **.state.yaml**: Updated with component metadata + variant catalog
+
+### Output Format
+
+```typescript
+// button.tsx
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+import { Spinner } from '@/components/ui/spinner';
+
+export const buttonVariants = cva(
+  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-70',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/90',
+        outline: 'border border-border bg-transparent hover:bg-muted'
+      },
+      size: {
+        sm: 'h-9 px-3',
+        md: 'h-10 px-4',
+        lg: 'h-12 px-6 text-base',
+        icon: 'h-10 w-10'
+      }
+    },
+    defaultVariants: {
+      variant: 'primary',
+      size: 'md'
+    }
+  }
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+  isLoading?: boolean;
+  loadingIcon?: React.ReactNode;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    { className, variant, size, asChild = false, isLoading = false, loadingIcon, children, ...props },
+    ref
+  ) => {
+    const Comp = asChild ? Slot : 'button';
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(buttonVariants({ variant, size }), className, isLoading && 'pointer-events-none')}
+        data-state={isLoading ? 'loading' : props['data-state']}
+        aria-busy={isLoading}
+        {...props}
+      >
+        {isLoading && (loadingIcon ?? <Spinner className="mr-2 h-4 w-4 animate-spin" />)}
+        <span className="inline-flex items-center gap-1">{children}</span>
+      </Comp>
+    );
+  }
+);
+Button.displayName = 'Button';
+
+export { Button };
+```
+
+## Success Criteria
+
+- [ ] Component compiles without TypeScript errors (strict) and passes lint
+- [ ] Variants implemented via `cva` with token-backed Tailwind utilities
+- [ ] Props fully typed (VariantProps + custom props) with TSDoc
+- [ ] Loading/disabled states, accessibility attributes, and dark mode supported
+- [ ] Unit + jest-axe tests pass with ≥85% coverage
+- [ ] Storybook stories render (if enabled) with controls + docs tab
+- [ ] Component documentation published with variant/density tables
+- [ ] .state.yaml updated with variant catalogue + QA status
+
+## Error Handling
+
+- **Token not found**: Report which token is missing, suggest alternatives
+- **Component exists**: Ask to overwrite or use different name
+- **TypeScript errors**: Display errors, suggest fixes
+- **Test failures**: Show failing tests, don't complete until fixed
+- **Accessibility violations**: Warn and suggest improvements
+
+## Security Considerations
+
+- Sanitize component name (prevent injection)
+- Validate token references
+- Escape user content in examples
+- No eval() or dynamic code execution
+
+## Examples
+
+### Example 1: Build Button Component
+
+```bash
+*build button
+```
+
+Output:
+```
+🏗️ Atlas: Building Button component...
+
+📋 Configuration:
+  - Type: Atom
+  - Variants: primary, secondary, outline
+  - Sizes: sm, md, lg, icon
+  - Loading state: enabled (spinner)
+  - Tests: RTL + jest-axe (>85% coverage)
+  - Storybook: Yes
+
+✓ Generated button.tsx (Shadcn-style, cva variants)
+✓ Generated button.test.tsx (22 tests, jest-axe assertions)
+✓ Generated button.stories.tsx (8 stories, controls + docs)
+✓ Generated button.md (usage + theming guidance)
+
+🧪 Running tests...
+  ✓ renders default button (matches snapshot)
+  ✓ applies variant classes via cva
+  ✓ shows spinner + disables interactions when loading
+  ✓ passes accessibility audit (jest-axe)
+  ✓ supports asChild slot rendering
+  Coverage: 96.4%
+
+♿ Accessibility check:
+  ✓ ARIA attributes present
+  ✓ Color contrast: 4.8:1 (WCAG AA ✓)
+  ✓ Keyboard navigable
+  ✓ Focus indicators visible
+
+✅ Button component ready!
+
+Import: `import { Button } from '@/components/ui/button';`
+Usage: `<Button variant="primary" isLoading>Saving</Button>`
+
+Atlas says: "Built right. Built once."
+```
+
+### Example 2: Build Input Component
+
+```bash
+*build input
+```
+
+Output includes additional features:
+- Validation states (error, success)
+- Helper text prop
+- Label integration
+- Icon slots
+
+## Notes
+
+- All components strictly typed with TypeScript
+- Zero hardcoded values enforced (tokens only)
+- Accessibility is non-negotiable (WCAG AA minimum)
+- Test coverage >80% required
+- Tailwind utilities + tokens ensure zero hardcoded values
+- Variants and sizes extend via `cva` without editing component body
+- Components are tree-shakeable and server-component friendly
+- Storybook stories enable visual + interaction testing
+- Documentation mirrors props/types for instant onboarding
+- Components follow Atomic Design principles
+- Atlas ensures quality at every step