# Component Specification Template

> **Copy this template for new component documentation**
>
> Location: `src/docs/ui/components/[component-name]-spec.md`

## 📦 Component: [Component Name]

**Path**: `src/features/[feature]/components/[component-name]/`

**Purpose**: [What does this component do? One-line description]

**Category**: [Form Input | Button | Layout | Navigation | Data Display | Feedback]

---

## 🎨 Visual Design

### Desktop View
![Desktop Screenshot](path/to/screenshot-desktop.png)

### Mobile View
![Mobile Screenshot](path/to/screenshot-mobile.png)

### Figma Link
[Link to Figma component]

---

## 🔧 Component API

### Props

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `variant` | `'primary' \| 'secondary'` | `'primary'` | No | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | No | Size of the component |
| `disabled` | `boolean` | `false` | No | Disable interaction |
| `children` | `ReactNode` | - | Yes | Content to display |
| `className` | `string` | - | No | Additional CSS classes |
| `onClick` | `() => void` | - | No | Click handler |

### Variants

#### Primary Variant
- **Use when**: [When to use this variant]
- **Visual**: [Description of appearance]
- **Example**:
```tsx
<Component variant="primary">Primary</Component>
```

#### Secondary Variant
- **Use when**: [When to use this variant]
- **Visual**: [Description of appearance]
- **Example**:
```tsx
<Component variant="secondary">Secondary</Component>
```

### Sizes

#### Small (`sm`)
- Height: [px/rem]
- Padding: [px/rem]
- Font size: [px/rem]
- Use case: [When to use]

#### Medium (`md`)
- Height: [px/rem]
- Padding: [px/rem]
- Font size: [px/rem]
- Use case: [When to use]

#### Large (`lg`)
- Height: [px/rem]
- Padding: [px/rem]
- Font size: [px/rem]
- Use case: [When to use]

---

## 📱 States

### Default State
**Description**: Normal, inactive state

**Visual**:
- Background: [color/variable]
- Border: [color/variable]
- Text: [color/variable]

**Code**:
```tsx
<Component>Default</Component>
```

---

### Hover State
**Description**: Mouse over the component

**Visual**:
- Background: [color/variable]
- Border: [color/variable]
- Text: [color/variable]
- Transform: [scale/translate if any]

**Code**:
```tsx
<Component className="hover:...">Hover me</Component>
```

---

### Active State
**Description**: Component is being clicked/pressed

**Visual**:
- Background: [color/variable]
- Border: [color/variable]
- Text: [color/variable]

---

### Focus State
**Description**: Component is focused (keyboard navigation)

**Visual**:
- Outline/Ring: [color/variable]
- Background: [color/variable]

**Accessibility**: Must be clearly visible for keyboard users

---

### Disabled State
**Description**: Component cannot be interacted with

**Visual**:
- Opacity: [value]
- Cursor: not-allowed
- Background: [color/variable]

**Code**:
```tsx
<Component disabled>Disabled</Component>
```

---

### Loading State (if applicable)
**Description**: Component is processing an action

**Visual**:
- Spinner/loading indicator
- Disabled interaction
- Optional text change

**Code**:
```tsx
<Component loading>Loading...</Component>
```

---

### Error State (if applicable)
**Description**: Component has validation error

**Visual**:
- Border: error color
- Background: error color with low opacity
- Error icon (optional)
- Error message below

**Code**:
```tsx
<Component error="Error message">Value</Component>
```

---

## 💡 Usage Examples

### Basic Usage
```tsx
import { Component } from '@/features/shared/components/ui/component'

function Example() {
  return (
    <Component>
      Basic example
    </Component>
  )
}
```

---

### With All Props
```tsx
<Component
  variant="primary"
  size="lg"
  disabled={false}
  onClick={handleClick}
  className="custom-class"
>
  Full example
</Component>
```

---

### Complex Example
```tsx
function ComplexExample() {
  const [loading, setLoading] = useState(false)

  const handleClick = async () => {
    setLoading(true)
    await someAction()
    setLoading(false)
  }

  return (
    <Component
      variant="primary"
      size="lg"
      loading={loading}
      onClick={handleClick}
    >
      {loading ? 'Processing...' : 'Click me'}
    </Component>
  )
}
```

---

## 🎨 Design Tokens Used

### Colors
- `--accent-primary`: Primary action color
- `--bg-secondary`: Background color
- `--text-primary`: Text color
- `--border-primary`: Border color

### Typography
- Font: `var(--font-sans)`
- Size: `var(--text-base)`
- Weight: `var(--font-medium)`

### Spacing
- Padding: `var(--spacing-4)`
- Margin: `var(--spacing-2)`

### Borders
- Radius: `var(--radius-md)`
- Width: `1px`

### Shadows
- Default: `var(--shadow-sm)`
- Hover: `var(--shadow-md)`

---

## ♿ Accessibility

### ARIA Attributes
```tsx
<Component
  role="button"
  aria-label="Descriptive label"
  aria-disabled={disabled}
>
  Content
</Component>
```

### Keyboard Navigation
- **Tab**: Focus the component
- **Enter/Space**: Activate the component
- **Escape**: Cancel (if applicable)

### Screen Reader Support
- Component announces its purpose
- State changes are announced
- Error messages are announced with `role="alert"`

### Focus Management
- Visible focus indicator (X.ai blue ring)
- Focus trap (if modal/dialog)
- Focus returns to trigger element after close

### Color Contrast
- Text to background: ≥ 4.5:1 (WCAG AA)
- Focus indicator: ≥ 3:1 (WCAG AA)

---

## 📱 Responsive Behavior

### Mobile (< 640px)
- [How does it adapt?]
- [Touch target size: min 44x44px]
- [Full width or stacked?]

### Tablet (640-1024px)
- [How does it adapt?]

### Desktop (> 1024px)
- [How does it adapt?]

---

## 🧪 Testing

### Unit Tests
```tsx
describe('Component', () => {
  it('renders correctly', () => {
    // Test case
  })

  it('handles click events', () => {
    // Test case
  })

  it('shows disabled state', () => {
    // Test case
  })
})
```

### Visual Regression Tests
- Default state
- All variants
- All sizes
- All states (hover, active, focus, disabled)
- Dark + Light theme

### Accessibility Tests
- axe-core tests pass
- Keyboard navigation works
- Screen reader announces correctly

---

## 🐛 Known Issues

### Issue 1: [Issue Description]
**Browsers affected**: [Chrome, Firefox, Safari, etc.]
**Workaround**: [How to work around it]
**Tracking**: [Link to GitHub issue]

---

## 📝 Development Notes

### Dependencies
- `react`: ^18.2.0
- `react-aria`: ^3.45.0 (if applicable)
- [Other dependencies]

### File Structure
```
component-name/
├── index.ts              # Barrel export
├── component-name.tsx    # Main component
├── component-name.test.tsx
├── component-name.stories.tsx
└── component-name.module.css (if needed)
```

### CSS Classes
```tsx
// Tailwind classes used
className="
  bg-accent-primary
  text-white
  px-4 py-2
  rounded-md
  hover:bg-accent-primary-hover
  focus:ring-2 focus:ring-accent-primary/30
  disabled:opacity-50
  transition-colors duration-150
"
```

---

## 🔄 Changelog

### v2.0.0 (2026-01-04)
- Updated to X.ai blue accent color
- Removed gradient, now solid color
- Updated focus states

### v1.0.0 (2025-12-01)
- Initial release

---

## 📚 Related Components

- [Related Component 1](./related-component-1-spec.md)
- [Related Component 2](./related-component-2-spec.md)

---

## 🔗 Links

- [Storybook](http://localhost:6006/?path=/story/component)
- [Figma Design](#)
- [GitHub Source](path/to/component)

---

**Maintained by**: [Team Name]
**Last Updated**: [Date]
**Version**: [Version Number]
