---
title: Button
description: A clickable UI element to trigger actions and user interactions
path: /elements/button
icon: i-ph-hand-pointing-duotone
to: /elements/button
date: 2025-01-15
badge:
  label: Stable
category: element
status: stable
version: 2.1.0
figma_url: https://figma.com/design/button-component
storybook_url: https://storybook.company.com/button
usage_guidelines: Use buttons for primary actions. Avoid using more than one primary button per section.

# Element-specific fields
html_tag: button
css_classes:
  - btn
  - btn-primary
  - btn-secondary
design_tokens:
  - color-primary
  - spacing-md
  - border-radius-sm

# Component properties
props:
  - name: variant
    type: string
    required: false
    default: primary
    description: Visual style variant of the button
  - name: size
    type: string
    required: false
    default: md
    description: Size of the button (xs, sm, md, lg, xl)
  - name: disabled
    type: boolean
    required: false
    default: false
    description: Whether the button is disabled
  - name: loading
    type: boolean
    required: false
    default: false
    description: Shows loading state with spinner

# Variants
variants:
  - name: Primary
    description: Main call-to-action button
    preview_url: /previews/button-primary
  - name: Secondary
    description: Secondary action button
    preview_url: /previews/button-secondary
  - name: Ghost
    description: Subtle button with minimal styling
    preview_url: /previews/button-ghost

# Accessibility
accessibility:
  wcag_level: AA
  aria_roles:
    - button
  keyboard_support: true
  screen_reader_support: true
  notes: Ensure button text is descriptive and actionable

seo:
  title: Button Element - Design System
  description: Documentation for the button element including usage, variants, and accessibility guidelines
---

## Overview

The Button element is a fundamental interactive component used to trigger actions and guide user interactions throughout the interface.

## Usage Guidelines

### When to Use
- Primary actions (submit, save, continue)
- Secondary actions (cancel, back, reset)
- Call-to-action elements

### When Not to Use
- Navigation links (use Link element instead)
- Toggling states (use Toggle element instead)

## Code Examples

### Basic Usage
```html
<button class="btn btn-primary">
  Click me
</button>

<button class="btn btn-primary">
  <i class="icon-save"></i>
  Save Changes
</button>

---

# Components Template

## File: `content/components/callout.md`

```markdown
---
title: Callout
description: Highlights important information, alerts, or promotional content to draw user attention
path: /components/callout
icon: i-ph-megaphone-simple-duotone
to: /components/callout
date: 2025-01-15
badge:
  label: Stable
category: component
status: stable
version: 1.8.0
figma_url: https://figma.com/design/callout-component
storybook_url: https://storybook.company.com/callout
usage_guidelines: Use callouts sparingly to highlight critical information. Overuse reduces their effectiveness.

# Component-specific fields
dependencies:
  - button
  - icon
composed_of:
  - text
  - icon
  - button
use_cases:
  - Important announcements
  - Warning messages
  - Tips and helpful information
  - Promotional content
best_practices:
  - Keep content concise
  - Use appropriate color coding
  - Include clear action items when needed
avoid:
  - Using multiple callouts on one page
  - Overly long content
  - Generic or unclear messaging

# Component properties
props:
  - name: type
    type: string
    required: true
    default: info
    description: Type of callout (info, warning, error, success)
  - name: title
    type: string
    required: false
    description: Optional title for the callout
  - name: dismissible
    type: boolean
    required: false
    default: false
    description: Whether the callout can be dismissed
  - name: icon
    type: string
    required: false
    description: Icon to display (uses design system icons)

# Variants
variants:
  - name: Info
    description: General information callout
    preview_url: /previews/callout-info
  - name: Warning
    description: Warning or caution message
    preview_url: /previews/callout-warning
  - name: Error
    description: Error or critical issue
    preview_url: /previews/callout-error
  - name: Success
    description: Success or completion message
    preview_url: /previews/callout-success

# Accessibility
accessibility:
  wcag_level: AA
  aria_roles:
    - alert
    - status
  keyboard_support: true
  screen_reader_support: true
  notes: Use appropriate ARIA roles based on callout type. Critical messages should use role="alert"

seo:
  title: Callout Component - Design System
  description: Documentation for the callout component including variants, usage patterns, and accessibility guidelines
---

## Overview

The Callout component is used to highlight important information, alerts, or promotional content that requires user attention.

## Usage Guidelines

### When to Use
- Important system announcements
- Form validation messages
- Helpful tips or guidance
- Warning about potential issues

### When Not to Use
- Regular content display
- Navigation elements
- Decorative purposes only

## Code Examples

### Basic Info Callout
```html
<div class="callout callout-info">
  <div class="callout-content">
    <h4>Did you know?</h4>
    <p>You can save time by using keyboard shortcuts.</p>
  </div>
</div>

<div class="callout callout-warning">
  <div class="callout-content">
    <h4>Account Expiring Soon</h4>
    <p>Your account will expire in 7 days.</p>
    <button class="btn btn-primary">Renew Now</button>
  </div>
</div>

---

# Patterns Template

## File: `content/patterns/vertical-navigation.md`

```markdown
---
title: Vertical Navigation
description: A sidebar-style navigation pattern that provides hierarchical menu structure for complex applications
path: /patterns/vertical-navigation
icon: i-ph-list-duotone
to: /patterns/vertical-navigation
date: 2025-01-15
badge:
  label: Stable
category: pattern
status: stable
version: 3.2.0
figma_url: https://figma.com/design/vertical-nav-pattern
storybook_url: https://storybook.company.com/vertical-navigation
usage_guidelines: Use for applications with complex hierarchical navigation. Ensure mobile responsiveness.

# Pattern-specific fields
components_used:
  - navigation-item
  - icon
  - button
  - collapse-container
layout_type: sidebar
responsive_behavior: Collapses to hamburger menu on mobile devices
interaction_states:
  - default
  - hover
  - active
  - expanded
  - collapsed
user_flows:
  - Main navigation
  - Section browsing
  - Deep linking

# Component properties
props:
  - name: collapsed
    type: boolean
    required: false
    default: false
    description: Whether the navigation is in collapsed state
  - name: items
    type: array
    required: true
    description: Array of navigation items with hierarchy
  - name: activeItem
    type: string
    required: false
    description: Currently active navigation item ID
  - name: collapsible
    type: boolean
    required: false
    default: true
    description: Whether the navigation can be collapsed

# Variants
variants:
  - name: Standard
    description: Full-width sidebar with icons and labels
    preview_url: /previews/vertical-nav-standard
  - name: Collapsed
    description: Narrow sidebar showing only icons
    preview_url: /previews/vertical-nav-collapsed
  - name: Mobile
    description: Hamburger menu for mobile devices
    preview_url: /previews/vertical-nav-mobile

# Accessibility
accessibility:
  wcag_level: AA
  aria_roles:
    - navigation
    - menubar
    - menuitem
  keyboard_support: true
  screen_reader_support: true
  notes: Implements full keyboard navigation with arrow keys, Enter, and Escape. Announces current location and hierarchy.

seo:
  title: Vertical Navigation Pattern - Design System
  description: Documentation for the vertical navigation pattern including responsive behavior and accessibility features
---

## Overview

The Vertical Navigation pattern provides a sidebar-style navigation solution for complex applications requiring hierarchical menu structures.

## Usage Guidelines

### When to Use
- Applications with multiple sections
- Complex site hierarchies
- Admin dashboards
- Multi-level navigation needs

### When Not to Use
- Simple websites with few pages
- Mobile-first experiences
- Linear user flows

## Behavior

### Desktop
- Fixed sidebar positioned on the left
- Expandable/collapsible sections
- Persistent active state indication
- Smooth transitions between states

### Mobile
- Converts to hamburger menu
- Full-screen overlay when open
- Touch-friendly interaction targets
- Swipe gestures for closing

## Code Examples

### Basic Implementation
```html
<nav class="vertical-nav" role="navigation" aria-label="Main navigation">
  <ul class="nav-list">
    <li class="nav-item">
      <a href="/dashboard" class="nav-link active">
        <i class="nav-icon icon-dashboard"></i>
        <span class="nav-label">Dashboard</span>
      </a>
    </li>
    <li class="nav-item has-children">
      <button class="nav-link" aria-expanded="true">
        <i class="nav-icon icon-users"></i>
        <span class="nav-label">Users</span>
        <i class="nav-chevron icon-chevron-down"></i>
      </button>
      <ul class="nav-submenu">
        <li><a href="/users/list">All Users</a></li>
        <li><a href="/users/add">Add User</a></li>
      </ul>
    </li>
  </ul>
</nav>

---

# Layouts Template

## File: `content/layouts/container.md`

```markdown
---
title: Container
description: A foundational layout component that wraps content to maintain consistent spacing and maximum widths across devices
path: /layouts/container
icon: i-ph-square-duotone
to: /layouts/container
date: 2025-01-15
badge:
  label: Stable
category: layout
status: stable
version: 4.0.0
figma_url: https://figma.com/design/container-layout
storybook_url: https://storybook.company.com/container
usage_guidelines: Use containers to wrap page sections and maintain consistent content width across devices.

# Layout-specific fields
grid_system: 12-column responsive grid
breakpoints:
  - name: xs
    min_width: 0px
    max_width: 575px
  - name: sm
    min_width: 576px
    max_width: 767px
  - name: md
    min_width: 768px
    max_width: 991px
  - name: lg
    min_width: 992px
    max_width: 1199px
  - name: xl
    min_width: 1200px
spacing_scale:
  - spacing-xs
  - spacing-sm
  - spacing-md
  - spacing-lg
  - spacing-xl
container_types:
  - fluid
  - fixed
  - content-width

# Component properties
props:
  - name: type
    type: string
    required: false
    default: fixed
    description: Container type (fixed, fluid, content-width)
  - name: padding
    type: string
    required: false
    default: md
    description: Internal padding size
  - name: centered
    type: boolean
    required: false
    default: true
    description: Whether content should be centered
  - name: maxWidth
    type: string
    required: false
    description: Custom maximum width override

# Variants
variants:
  - name: Fixed
    description: Standard container with max-width constraints
    preview_url: /previews/container-fixed
  - name: Fluid
    description: Full-width container that spans entire viewport
    preview_url: /previews/container-fluid
  - name: Content Width
    description: Narrow container optimized for reading content
    preview_url: /previews/container-content

# Accessibility
accessibility:
  wcag_level: AA
  keyboard_support: true
  screen_reader_support: true
  notes: Container provides semantic structure but doesn't interfere with accessibility. Ensure proper heading hierarchy within.

seo:
  title: Container Layout - Design System
  description: Documentation for the container layout component including responsive behavior and spacing guidelines
---

## Overview

The Container layout component provides consistent content wrapping and spacing across all device sizes, serving as the foundation for page layouts.

## Usage Guidelines

### When to Use
- Wrapping page sections
- Maintaining consistent content width
- Creating responsive layouts
- Providing consistent spacing

### When Not to Use
- Full-width hero sections (use fluid variant)
- Components that need edge-to-edge display
- Already within another container

## Responsive Behavior

### Breakpoint Specifications

| Breakpoint | Min Width | Max Width | Container Width | Padding |
| ---------- | --------- | --------- | --------------- | ------- |
| xs         | 0px       | 575px     | 100%            | 16px    |
| sm         | 576px     | 767px     | 540px           | 16px    |
| md         | 768px     | 991px     | 720px           | 24px    |
| lg         | 992px     | 1199px    | 960px           | 24px    |
| xl         | 1200px+   | -         | 1140px          | 32px    |

## Code Examples

### Standard Fixed Container
```html
<div class="container">
  <h1>Page Title</h1>
  <p>Your content here...</p>
</div>

<div class="container-fluid">
  <div class="hero-section">
    <!-- Full-width hero content -->
  </div>
</div>

<div class="container container-content-width">
  <article>
    <!-- Article content with optimal reading width -->
  </article>
</div>

<div class="container">
  <div class="row">
    <div class="col-md-8">Main content</div>
    <div class="col-md-4">Sidebar</div>
  </div>
</div>

---

# Tokens Template

## File: `content/tokens/color-primary.md`

```markdown
---
title: Primary Color
description: The main brand color used for primary actions, links, and key interface elements
path: /tokens/color-primary
icon: i-ph-palette-duotone
to: /tokens/color-primary
date: 2025-01-15
badge:
  label: Core
token_type: color
value: "#0066cc"
css_variable: "--color-primary"
sass_variable: "$color-primary"
usage_examples:
  - Primary buttons
  - Active navigation items
  - Links and interactive elements
  - Progress indicators
related_tokens:
  - color-primary-hover
  - color-primary-light
  - color-primary-dark

seo:
  title: Primary Color Token - Design System
  description: Documentation for the primary color design token including usage guidelines and accessibility considerations
---

## Overview

The Primary Color token defines the main brand color used throughout the interface for primary actions and key interactive elements.

## Token Details

- **Value**: `#0066cc`
- **CSS Variable**: `var(--color-primary)`
- **Sass Variable**: `$color-primary`
- **HSL**: `hsl(210, 100%, 40%)`
- **RGB**: `rgb(0, 102, 204)`

## Usage Guidelines

### Recommended Use
- Primary call-to-action buttons
- Active states for navigation
- Links and interactive text
- Progress bars and loading states
- Selected items and focus states

### Avoid Using For
- Large background areas
- Text on colored backgrounds without proper contrast
- Decorative elements that don't require interaction

## Accessibility

- **Contrast Ratio**: 4.5:1 against white background
- **WCAG Compliance**: AA level for normal text
- **Color Blindness**: Tested with deuteranopia and protanopia

## Color Variations

| Token                   | Value     | Usage               |
| ----------------------- | --------- | ------------------- |
| `--color-primary`       | `#0066cc` | Default state       |
| `--color-primary-hover` | `#0052a3` | Hover interactions  |
| `--color-primary-light` | `#cce6ff` | Light backgrounds   |
| `--color-primary-dark`  | `#004080` | High contrast needs |

## Code Examples

### CSS
```css
.btn-primary {
  background-color: var(--color-primary);
  border-color: var(--color-primary);
}

.btn-primary:hover {
  background-color: var(--color-primary-hover);
}

.link {
  color: $color-primary;

  &:hover {
    color: darken($color-primary, 10%);
  }
}