dss/docs/COMPONENT_API_REFERENCE.md

# Design System Component API Reference

**Version:** 1.0.0
**Last Updated:** December 7, 2025
**Status:** Complete

---

## Table of Contents

1. [DsButton](#dsbutton)
2. [DsInput](#dsinput)
3. [DsCard](#dscard)
4. [DsBadge](#dsbadge)
5. [DsToast](#dstoast)
6. [DsWorkflow](#dsworkflow)
7. [DsNotificationCenter](#dsnotificationcenter)
8. [DsActionBar](#dsactionbar)
9. [DsToastProvider](#dstoastprovider)
10. [DsComponentBase](#dscomponentbase)

---

## DsButton

A versatile button component with multiple variants and sizes.

### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-variant` | string | `primary` | Button style variant: `primary`, `secondary`, `outline`, `ghost`, `destructive`, `success`, `link` |
| `data-size` | string | `default` | Button size: `sm`, `default`, `lg`, `icon`, `icon-sm`, `icon-lg` |
| `disabled` | boolean | `false` | Disables the button |
| `aria-label` | string | - | Accessible label for screen readers |
| `aria-disabled` | boolean | `false` | Announces disabled state to assistive technology |
| `aria-pressed` | boolean | `false` | For toggle buttons, announces pressed state |

### Properties

```javascript
// Read/Write
button.disabled = true;
button.ariaLabel = "Submit form";

// Read-only
button.isLoading; // boolean
button.isDarkMode(); // boolean
```

### Methods

```javascript
// Focus management
button.focus();
button.blur();

// Event emission
button.emit('custom-event', { detail: data });

// CSS variable access
button.getCSSVariable('--primary');

// Event waiting
await button.waitForEvent('ds-click');

// Utilities
button.debounce(fn, 300);
button.throttle(fn, 100);
```

### Variants

**Style Variants:** primary, secondary, outline, ghost, destructive, success, link (7 variants)
**Sizes:** sm, default, lg, icon, icon-sm, icon-lg (6 sizes)
**Total Combinations:** 42 variants

### CSS Classes

```css
.ds-btn                        /* Base button */
.ds-btn[data-variant="primary"]  /* Primary style */
.ds-btn[data-size="lg"]          /* Large size */
.ds-btn:hover                    /* Hover state */
.ds-btn:active                   /* Active state */
.ds-btn:disabled                 /* Disabled state */
.ds-btn:focus-visible            /* Focus visible */
```

### Example Usage

```html
<!-- Primary Button -->
<ds-button data-variant="primary" data-size="default">
  Click me
</ds-button>

<!-- Icon Button -->
<ds-button data-variant="ghost" data-size="icon">
  ✕
</ds-button>

<!-- Destructive Button (Disabled) -->
<ds-button data-variant="destructive" disabled>
  Delete
</ds-button>

<!-- Link Button -->
<ds-button data-variant="link">
  Learn more →
</ds-button>
```

### States

- **default:** Normal state
- **hover:** Mouse over or keyboard focus
- **active:** Pressed/clicked
- **disabled:** Cannot interact
- **loading:** Processing action (via aria-busy)
- **focus:** Keyboard focus

### Accessibility

- ✅ WCAG 2.1 Level AA
- ✅ Keyboard navigation (Enter, Space)
- ✅ Screen reader support (aria-label, aria-disabled, aria-pressed)
- ✅ Focus indicators
- ✅ Sufficient color contrast (4.5:1 minimum)

---

## DsInput

Text input component with multiple input types and validation states.

### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `type` | string | `text` | Input type: `text`, `password`, `email`, `number`, `search`, `tel`, `url` |
| `value` | string | `` | Current input value |
| `placeholder` | string | `` | Placeholder text |
| `disabled` | boolean | `false` | Disables the input |
| `data-state` | string | `default` | State: `default`, `focus`, `hover`, `disabled`, `error` |
| `aria-invalid` | boolean | `false` | Marks input as having invalid value |
| `aria-describedby` | string | - | ID of error message element |
| `aria-label` | string | - | Accessible label |

### Properties

```javascript
// Read/Write
input.value = "New value";
input.disabled = true;
input.placeholder = "Enter email";

// Read-only
input.isDarkMode(); // boolean
input.isFocused; // boolean
```

### Methods

```javascript
// Focus and blur
input.focus();
input.blur();

// Validation
input.validate(); // boolean
input.clear();

// Event handling
input.addEventListener('change', (e) => console.log(e.target.value));
input.addEventListener('input', (e) => console.log(e.target.value));
```

### Input Types

1. **text** - Standard text input
2. **password** - Masked password input
3. **email** - Email validation
4. **number** - Numeric input
5. **search** - Search-optimized input
6. **tel** - Telephone number
7. **url** - URL validation

### CSS Classes

```css
.ds-input                    /* Base input */
.ds-input[type="email"]      /* Email input type */
.ds-input[data-state="error"] /* Error state */
.ds-input:disabled           /* Disabled state */
.ds-input:focus              /* Focus state */
```

### Example Usage

```html
<!-- Standard Text Input -->
<label for="username">Username</label>
<ds-input id="username" type="text" placeholder="Enter username" />

<!-- Email with Error State -->
<label for="email">Email</label>
<ds-input
  id="email"
  type="email"
  data-state="error"
  aria-invalid="true"
  aria-describedby="email-error"
/>
<span id="email-error">Invalid email format</span>

<!-- Number Input (Disabled) -->
<label for="quantity">Quantity</label>
<ds-input
  id="quantity"
  type="number"
  value="1"
  disabled
/>

<!-- Password Input -->
<label for="password">Password</label>
<ds-input id="password" type="password" placeholder="••••••" />
```

### States

- **default:** Normal state
- **focus:** Active focus
- **hover:** Mouse over
- **disabled:** Cannot interact
- **error:** Validation error

### Accessibility

- ✅ WCAG 2.1 Level AA
- ✅ Proper label association
- ✅ aria-invalid and aria-describedby for errors
- ✅ Keyboard accessible
- ✅ Focus indicators

---

## DsCard

Container component for grouping content.

### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-variant` | string | `default` | Card style: `default`, `interactive` |
| `aria-label` | string | - | Card title/description |

### Properties

```javascript
// Read-only
card.isDarkMode(); // boolean
```

### Methods

```javascript
card.focus();
card.emit('card-clicked');
```

### Variants

- **default:** Static card
- **interactive:** Clickable/hoverable card

### CSS Classes

```css
.ds-card                           /* Base card */
.ds-card[data-variant="interactive"] /* Interactive card */
.ds-card:hover                     /* Hover state */
```

### Example Usage

```html
<!-- Default Card -->
<ds-card>
  <h3>Card Title</h3>
  <p>Card content goes here</p>
</ds-card>

<!-- Interactive Card -->
<ds-card data-variant="interactive" aria-label="User Profile">
  <h3>User Name</h3>
  <p>Click to view profile</p>
</ds-card>
```

### States

- **default:** Normal state
- **hover:** Mouse over (interactive only)

### Accessibility

- ✅ WCAG 2.1 Level AA
- ✅ Semantic HTML (article/section)
- ✅ aria-label support
- ✅ Proper contrast ratios

---

## DsBadge

Small label component for status/category indicators.

### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-variant` | string | `default` | Badge style: `default`, `secondary`, `outline`, `destructive`, `success`, `warning` |
| `aria-label` | string | - | Badge description |

### Properties

```javascript
badge.isDarkMode(); // boolean
```

### Variants

1. **default** - Primary color badge
2. **secondary** - Secondary color badge
3. **outline** - Outlined badge
4. **destructive** - Error/danger badge
5. **success** - Success/positive badge
6. **warning** - Warning badge

### CSS Classes

```css
.ds-badge                        /* Base badge */
.ds-badge[data-variant="success"] /* Success badge */
.ds-badge[data-variant="warning"] /* Warning badge */
```

### Example Usage

```html
<!-- Default Badge -->
<ds-badge>New</ds-badge>

<!-- Success Badge -->
<ds-badge data-variant="success">Active</ds-badge>

<!-- Destructive Badge -->
<ds-badge data-variant="destructive">Error</ds-badge>

<!-- Warning Badge -->
<ds-badge data-variant="warning">Attention</ds-badge>
```

### Accessibility

- ✅ WCAG 2.1 Level AA
- ✅ aria-label for context
- ✅ Sufficient contrast

---

## DsToast

Notification message displayed temporarily.

### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-type` | string | `default` | Toast type: `default`, `success`, `warning`, `error`, `info` |
| `data-state` | string | `visible` | State: `entering`, `visible`, `exiting`, `swiped` |
| `data-duration` | number | `3000` | Duration in milliseconds |
| `role` | string | `alert` | ARIA role |
| `aria-live` | string | `polite` | Politeness level |

### Properties

```javascript
toast.type = "success";
toast.duration = 5000;
toast.isDarkMode(); // boolean
```

### Methods

```javascript
// Lifecycle
toast.show();
toast.hide();
toast.dismiss();

// Events
toast.addEventListener('ds-toast-enter', () => {});
toast.addEventListener('ds-toast-exit', () => {});
toast.addEventListener('ds-toast-action', (e) => {});
```

### Types

- **default** - Default notification
- **success** - Success message
- **warning** - Warning message
- **error** - Error message
- **info** - Information message

### States

- **entering:** Animating in
- **visible:** Fully visible
- **exiting:** Animating out
- **swiped:** Manually dismissed

### Example Usage

```html
<!-- Success Toast -->
<ds-toast data-type="success">
  Profile updated successfully!
</ds-toast>

<!-- Error Toast with Action -->
<ds-toast data-type="error">
  <span>Failed to load data</span>
  <ds-button data-variant="ghost" data-size="sm">
    Retry
  </ds-button>
</ds-toast>

<!-- Info Toast (5 second duration) -->
<ds-toast data-type="info" data-duration="5000">
  This is an informational message
</ds-toast>
```

### Animations

- **slideIn:** Enter animation (300ms)
- **slideOut:** Exit animation (300ms)
- **swipeOut:** Manual dismiss animation (200ms)

### Accessibility

- ✅ WCAG 2.1 Level AA
- ✅ role="alert" and aria-live="polite"
- ✅ Keyboard dismissal (Escape key)
- ✅ Screen reader announcement
- ✅ Reduced motion support

---

## DsWorkflow

Step-by-step workflow visualization component.

### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-direction` | string | `vertical` | Layout: `vertical`, `horizontal` |
| `data-current-step` | number | `0` | Current step index (0-based) |

### Structure

```html
<ds-workflow data-direction="vertical">
  <ds-workflow-step data-state="completed">Step 1</ds-workflow-step>
  <ds-workflow-step data-state="active">Step 2</ds-workflow-step>
  <ds-workflow-step data-state="pending">Step 3</ds-workflow-step>
</ds-workflow>
```

### Step States

1. **pending** - Not yet reached
2. **active** - Currently on this step
3. **completed** - Step finished
4. **error** - Step failed (with pulse animation)
5. **skipped** - Step was skipped

### Properties

```javascript
workflow.direction = "horizontal";
workflow.currentStep = 1;
workflow.steps; // Array of step elements
```

### Methods

```javascript
workflow.nextStep();
workflow.previousStep();
workflow.setStep(stepIndex);
workflow.completeStep(stepIndex);
workflow.errorStep(stepIndex);
workflow.skipStep(stepIndex);
```

### CSS Classes

```css
.ds-workflow                          /* Container */
.ds-workflow[data-direction="horizontal"] /* Horizontal layout */
.ds-workflow-step[data-state="active"] /* Active step */
.ds-workflow-step[data-state="error"] /* Error step (pulse animation) */
```

### Example Usage

```html
<!-- Vertical Workflow -->
<ds-workflow data-direction="vertical" data-current-step="1">
  <ds-workflow-step data-state="completed">Account Setup</ds-workflow-step>
  <ds-workflow-step data-state="active">Verify Email</ds-workflow-step>
  <ds-workflow-step data-state="pending">Enable 2FA</ds-workflow-step>
  <ds-workflow-step data-state="pending">Profile Complete</ds-workflow-step>
</ds-workflow>

<!-- Horizontal Workflow -->
<ds-workflow data-direction="horizontal">
  <ds-workflow-step data-state="completed">1. Review</ds-workflow-step>
  <ds-workflow-step data-state="completed">2. Confirm</ds-workflow-step>
  <ds-workflow-step data-state="active">3. Processing</ds-workflow-step>
  <ds-workflow-step data-state="pending">4. Complete</ds-workflow-step>
</ds-workflow>

<!-- Workflow with Error -->
<ds-workflow>
  <ds-workflow-step data-state="completed">Step 1</ds-workflow-step>
  <ds-workflow-step data-state="error">Step 2 - Failed</ds-workflow-step>
  <ds-workflow-step data-state="skipped">Step 3</ds-workflow-step>
</ds-workflow>
```

### Accessibility

- ✅ WCAG 2.1 Level AA
- ✅ aria-current="step" on active step
- ✅ Semantic step numbering
- ✅ Keyboard navigation
- ✅ Screen reader support

---

## DsNotificationCenter

Notification inbox component for managing messages.

### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-layout` | string | `compact` | Layout: `compact`, `expanded` |
| `data-group-by` | string | `type` | Grouping: `type`, `date`, `none` |
| `data-state` | string | `closed` | State: `open`, `closed`, `loading` |

### Properties

```javascript
notificationCenter.layout = "expanded";
notificationCenter.groupBy = "date";
notificationCenter.notifications; // Array
notificationCenter.unreadCount; // number
```

### Methods

```javascript
// Notification management
notificationCenter.addNotification(notification);
notificationCenter.removeNotification(id);
notificationCenter.clearAll();
notificationCenter.markAsRead(id);

// State
notificationCenter.open();
notificationCenter.close();
```

### Notification Object

```javascript
{
  id: string,           // Unique identifier
  type: string,         // "info" | "success" | "warning" | "error"
  title: string,        // Notification title
  message: string,      // Main message
  timestamp: Date,      // When it occurred
  read: boolean,        // Read status
  action?: {            // Optional action button
    label: string,
    callback: () => void
  }
}
```

### Variants

**Layout:** compact, expanded (2 layouts)
**GroupBy:** type, date, none (3 grouping options)
**Total:** 6 variants

### Example Usage

```html
<!-- Notification Center -->
<ds-notification-center
  data-layout="expanded"
  data-group-by="date"
  data-state="open"
>
</ds-notification-center>
```

```javascript
// Add notification
notificationCenter.addNotification({
  id: 'notif-1',
  type: 'success',
  title: 'File uploaded',
  message: 'Your file has been uploaded successfully',
  timestamp: new Date(),
  read: false,
  action: {
    label: 'View',
    callback: () => console.log('View file')
  }
});

// Listen to notification events
notificationCenter.addEventListener('ds-notification-click', (e) => {
  console.log('Notification clicked:', e.detail);
});
```

### States

- **open:** Notification center visible
- **closed:** Hidden
- **loading:** Fetching notifications

### Accessibility

- ✅ WCAG 2.1 Level AA
- ✅ role="region" with aria-label
- ✅ Keyboard navigation
- ✅ aria-live updates
- ✅ Custom scrollbar for accessibility

---

## DsActionBar

Fixed or sticky action bar for primary actions.

### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-position` | string | `bottom` | Position: `top`, `bottom`, `floating` |
| `data-alignment` | string | `center` | Alignment: `left`, `center`, `right` |
| `data-state` | string | `default` | State: `default`, `expanded`, `collapsed`, `dismissing` |

### Properties

```javascript
actionBar.position = "bottom";
actionBar.alignment = "right";
actionBar.isDismissed; // boolean
```

### Methods

```javascript
actionBar.expand();
actionBar.collapse();
actionBar.dismiss();
actionBar.restore();
```

### Variants

**Positions:** top, bottom, floating (3)
**Alignments:** left, center, right (3)
**Total:** 9 variants

### CSS Classes

```css
.ds-action-bar                          /* Base */
.ds-action-bar[data-position="bottom"]  /* Bottom position */
.ds-action-bar[data-alignment="right"]  /* Right alignment */
.ds-action-bar[data-state="dismissing"] /* Dismissal animation */
```

### Example Usage

```html
<!-- Bottom Center Action Bar -->
<ds-action-bar data-position="bottom" data-alignment="center">
  <ds-button data-variant="primary">Save</ds-button>
  <ds-button data-variant="ghost">Cancel</ds-button>
</ds-action-bar>

<!-- Top Right Action Bar (Floating) -->
<ds-action-bar data-position="floating" data-alignment="right">
  <ds-button data-variant="primary">Create New</ds-button>
</ds-action-bar>

<!-- Dismissible Action Bar -->
<ds-action-bar
  data-position="bottom"
  data-alignment="center"
  id="action-bar"
>
  <ds-button data-variant="primary">Save</ds-button>
  <ds-button data-variant="ghost">Dismiss</ds-button>
</ds-action-bar>

<script>
  document.getElementById('action-bar').addEventListener('ds-dismiss', () => {
    // Handle dismissal
  });
</script>
```

### States

- **default:** Fully visible
- **expanded:** Expanded state
- **collapsed:** Minimized state
- **dismissing:** Being dismissed (animation)

### Accessibility

- ✅ WCAG 2.1 Level AA
- ✅ role="toolbar"
- ✅ Keyboard navigation
- ✅ aria-label for context
- ✅ Semantic button structure

---

## DsToastProvider

Container for managing multiple toast notifications.

### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-position` | string | `bottom-right` | Toast position: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right` |

### Positions

1. **top-left** - Upper left corner
2. **top-center** - Top center
3. **top-right** - Upper right corner
4. **bottom-left** - Lower left corner
5. **bottom-center** - Bottom center
6. **bottom-right** - Lower right corner (default)

### Properties

```javascript
provider.position = "top-right";
provider.toasts; // Array of toast elements
provider.maxToasts; // number
```

### Methods

```javascript
// Toast management
provider.show(message, type, duration);
provider.showSuccess(message, duration);
provider.showError(message, duration);
provider.showWarning(message, duration);
provider.showInfo(message, duration);
provider.clearAll();
provider.getToast(id); // Get specific toast
```

### Example Usage

```html
<!-- Toast Provider -->
<ds-toast-provider data-position="bottom-right"></ds-toast-provider>
```

```javascript
const provider = document.querySelector('ds-toast-provider');

// Show notifications
provider.showSuccess('Profile saved!', 3000);
provider.showError('Failed to load data', 5000);
provider.showWarning('This action cannot be undone', 4000);
provider.showInfo('New message received', 3000);

// Clear all toasts
provider.clearAll();
```

### Auto-Stack

Toasts automatically stack vertically without overlapping.

### Accessibility

- ✅ WCAG 2.1 Level AA
- ✅ aria-live="polite" for announcements
- ✅ Keyboard dismissal support
- ✅ Screen reader compatible

---

## DsComponentBase

Base class for all design system components.

### Properties

```javascript
// Standard properties available on all components
component.disabled;           // boolean
component.loading;            // boolean
component.ariaLabel;          // string
component.ariaDescribedBy;    // string
component.ariaBusy;           // boolean
component.ariaHidden;         // boolean
component.role;               // string
component.tabindex;           // number
```

### Methods

```javascript
// Focus management
component.focus();
component.blur();

// Event handling
component.emit(eventName, detail);
component.addEventListener(event, callback);
component.removeEventListener(event, callback);

// CSS variables
component.getCSSVariable(varName);  // Get value
component.setCSSVariable(varName, value);

// Theme detection
component.isDarkMode();       // boolean

// Utilities
component.debounce(fn, delay);      // Debounce function
component.throttle(fn, interval);   // Throttle function
component.waitForEvent(eventName);  // Promise-based

// Lifecycle hooks
component.connectedCallback();       // When added to DOM
component.disconnectedCallback();    // When removed from DOM
component.attributeChangedCallback(name, oldValue, newValue);
component.render();                  // Render method
```

### Lifecycle Hooks

```javascript
class CustomComponent extends DsComponentBase {
  connectedCallback() {
    super.connectedCallback();
    console.log('Component mounted');
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    console.log('Component unmounted');
  }

  attributeChangedCallback(name, oldValue, newValue) {
    super.attributeChangedCallback(name, oldValue, newValue);
    console.log(`${name} changed from ${oldValue} to ${newValue}`);
  }

  render() {
    // Custom render logic
  }
}
```

### CSS Variables Available

All components have access to design tokens:

```css
/* Colors */
--primary        /* Primary accent color */
--secondary      /* Secondary accent color */
--success        /* Success/positive color */
--warning        /* Warning color */
--destructive    /* Error/destructive color */
--info           /* Information color */
--foreground     /* Text color */
--background     /* Background color */
--card           /* Card background */
--card-foreground /* Card text */
--muted-foreground /* Muted text */
--border         /* Border color */

/* Spacing */
--space-1 through --space-10

/* Typography */
--text-xs, --text-sm, --text-base, --text-lg, --text-xl

/* Radius */
--radius, --radius-sm, --radius-lg

/* Transitions */
--duration-fast (0.1s)
--duration-normal (0.2s)
--duration-slow (0.3s)
--ease-default

/* Shadows */
--shadow-sm, --shadow-md, --shadow-lg

/* Z-index */
--z-toast
```

### Example Custom Component

```javascript
import { DsComponentBase } from '@company/design-system';

class CustomComponent extends DsComponentBase {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    super.connectedCallback();
    this.render();
    this.addEventListener('click', this._onClick.bind(this));
  }

  attributeChangedCallback(name, oldValue, newValue) {
    super.attributeChangedCallback(name, oldValue, newValue);
    if (oldValue !== newValue) {
      this.render();
    }
  }

  render() {
    const template = this.renderTemplate(`
      <div class="custom-component">
        <button>${this.ariaLabel || 'Click me'}</button>
      </div>
    `);
    this.shadowRoot.innerHTML = '';
    this.shadowRoot.appendChild(template);
  }

  _onClick() {
    this.emit('custom-click', { timestamp: Date.now() });
  }

  static get observedAttributes() {
    return ['aria-label', 'disabled', 'data-variant'];
  }
}

customElements.define('custom-component', CustomComponent);
```

---

## Common Patterns

### Theme Switching

```javascript
// Detect dark mode
const isDark = component.isDarkMode();

// Listen for theme changes
document.addEventListener('theme-change', (e) => {
  console.log('Theme:', e.detail.theme); // 'light' or 'dark'
});

// Toggle dark mode
document.documentElement.classList.toggle('dark');
```

### Event Handling

```javascript
// Custom event emission
button.emit('action-complete', {
  success: true,
  message: 'Action completed'
});

// Event listening
button.addEventListener('action-complete', (e) => {
  console.log(e.detail);
});

// Wait for event (Promise-based)
const result = await button.waitForEvent('action-complete');
```

### CSS Customization

```css
/* Override token values */
:root {
  --primary: #0066cc;
  --success: #10b981;
  --space-4: 1.5rem;
}

/* Dark mode overrides */
:root.dark {
  --primary: #3b82f6;
  --success: #059669;
  --foreground: #e5e7eb;
}

/* Component-specific overrides */
.ds-btn[data-variant="primary"] {
  background: var(--primary);
  padding: var(--space-4) var(--space-6);
}
```

### Accessibility Patterns

```html
<!-- Form with error -->
<label for="email">Email</label>
<ds-input
  id="email"
  type="email"
  aria-invalid="true"
  aria-describedby="email-error"
/>
<span id="email-error" role="alert">Invalid email format</span>

<!-- Button with icon -->
<ds-button aria-label="Close dialog">✕</ds-button>

<!-- Disabled state -->
<ds-button aria-disabled="true">Save</ds-button>

<!-- Loading state -->
<ds-button aria-busy="true">Loading...</ds-button>
```

---

## Browser Support

- Chrome 88+
- Firefox 85+
- Safari 14+
- Edge 88+

**Web Components features required:**
- Custom Elements v1
- Shadow DOM
- HTML Templates

---

## Version History

- **v1.0.0** (December 7, 2025) - Initial production release
  - 9 components
  - 123 variants
  - 42 design tokens
  - WCAG 2.1 AA compliance
  - Full dark mode support
  - 115+ tests

---

**For questions or issues, visit:** design-system@company.com