# Component Usage Guide

## Design Token Reference

All visual properties are controlled via CSS custom properties in `styles/tokens.css`. Override them in `styles/theme.css` or inline.

### Color Tokens

```css
/* Brand */
var(--color-brand)          /* Primary action color */
var(--color-brand-hover)    /* Hover state */
var(--color-brand-active)   /* Active/pressed state */
var(--color-brand-subtle)   /* Light background tint */
var(--color-brand-border)   /* Border color */
var(--color-on-brand)       /* Text on brand background */

/* Accent */
var(--color-accent)         /* Secondary action color */
var(--color-accent-hover)
var(--color-accent-subtle)
var(--color-on-accent)

/* Neutrals */
var(--color-bg)             /* Page background */
var(--color-bg-subtle)      /* Slightly off-white */
var(--color-bg-muted)       /* Muted background */
var(--color-surface)        /* Card/panel background */
var(--color-border)         /* Default border */
var(--color-border-strong)  /* Stronger border */

/* Text */
var(--color-text)           /* Primary text */
var(--color-text-muted)     /* Secondary text */
var(--color-text-subtle)    /* Placeholder/disabled */
var(--color-text-inverse)   /* Text on dark backgrounds */

/* Status */
var(--color-success)        /* #16a34a */
var(--color-warning)        /* #d97706 */
var(--color-error)          /* #dc2626 */
var(--color-info)           /* #0284c7 */
```

### Spacing Tokens

```css
var(--space-1)   /* 4px  */
var(--space-2)   /* 8px  */
var(--space-3)   /* 12px */
var(--space-4)   /* 16px */
var(--space-5)   /* 20px */
var(--space-6)   /* 24px */
var(--space-8)   /* 32px */
var(--space-10)  /* 40px */
var(--space-12)  /* 48px */
var(--space-16)  /* 64px */
var(--space-20)  /* 80px */
var(--space-24)  /* 96px */
```

### Typography Tokens

```css
var(--font-size-xs)    /* ~12px */
var(--font-size-sm)    /* ~14px */
var(--font-size-base)  /* 16px  */
var(--font-size-lg)    /* ~18px */
var(--font-size-xl)    /* ~20px */
var(--font-size-2xl)   /* ~24px */
var(--font-size-3xl)   /* ~30px */
var(--font-size-4xl)   /* ~36px */
var(--font-size-5xl)   /* ~48px */
```

---

## Layout Components

### Container

```html
<div class="container">          <!-- Max 1280px, centered, padded -->
<div class="container-sm">       <!-- Max 640px -->
<div class="container-md">       <!-- Max 768px -->
<div class="container-lg">       <!-- Max 1024px -->
<div class="container-2xl">      <!-- Max 1536px -->
```

### Section Wrappers

```html
<section class="section">        <!-- Standard vertical padding -->
<section class="section-sm">     <!-- Compact padding -->
<section class="section-lg">     <!-- Generous padding -->
<section class="section-bg">     <!-- Subtle background -->
<section class="section-dark">   <!-- Dark background -->
<section class="section-brand">  <!-- Brand color background -->
```

### Grid System

```html
<!-- Auto-fit responsive grids (recommended) -->
<div class="d-grid grid-auto-sm">   <!-- Min 200px per column -->
<div class="d-grid grid-auto-md">   <!-- Min 280px per column -->
<div class="d-grid grid-auto-lg">   <!-- Min 320px per column -->

<!-- Fixed column grids -->
<div class="d-grid grid-cols-2 gap-6">
<div class="d-grid grid-cols-3 gap-6">
<div class="d-grid grid-cols-4 gap-6">

<!-- Flex layouts -->
<div class="d-flex items-center justify-between gap-4">
<div class="d-flex flex-col gap-3">
```

### Sidebar Layout

```html
<div class="sidebar-layout">
  <aside class="sidebar" aria-label="Navigation">
    <div class="sidebar-section-title">Section</div>
    <ul class="sidebar-nav">
      <li class="sidebar-nav-item">
        <a href="#" aria-current="page">Active Link</a>
      </li>
      <li class="sidebar-nav-item">
        <a href="#">Other Link</a>
      </li>
    </ul>
  </aside>
  <main>
    <!-- Main content -->
  </main>
</div>
```

---

## UI Components

### Badges

```html
<span class="badge badge-primary">New</span>
<span class="badge badge-secondary">Beta</span>
<span class="badge badge-success">Active</span>
<span class="badge badge-warning">Pending</span>
<span class="badge badge-error">Error</span>
<span class="badge badge-neutral">Draft</span>
```

### Tags / Filters

```html
<a href="#" class="tag">Engineering</a>
<a href="#" class="tag" aria-current="page">Selected</a>
```

### Alerts

```html
<div class="alert alert-info" role="status">
  <span class="alert-icon" aria-hidden="true">ℹ️</span>
  <div class="alert-content">
    <div class="alert-title">Information</div>
    This is an informational message.
  </div>
  <button class="alert-close" aria-label="Dismiss">✕</button>
</div>

<!-- Types: alert-info | alert-success | alert-warning | alert-error -->
```

### Skeleton Loading

```html
<div class="skeleton skeleton-title"></div>
<div class="skeleton skeleton-text"></div>
<div class="skeleton skeleton-text" style="width:80%"></div>
<div class="skeleton skeleton-image"></div>
<div class="skeleton skeleton-avatar"></div>
```

### Empty State

```html
<div class="empty-state">
  <div class="empty-state-icon" aria-hidden="true">📭</div>
  <h3>No results found</h3>
  <p>Try adjusting your search or filters to find what you're looking for.</p>
  <a href="#" class="btn btn-primary">Clear filters</a>
</div>
```

### Timeline

```html
<div class="timeline">
  <div class="timeline-item">
    <div class="timeline-dot" aria-hidden="true"></div>
    <div class="timeline-date">January 2024</div>
    <div class="timeline-title">Company founded</div>
    <div class="timeline-body">Alex and Jordan started Acme in a San Francisco garage.</div>
  </div>
  <div class="timeline-item">
    <div class="timeline-dot" aria-hidden="true"></div>
    <div class="timeline-date">June 2024</div>
    <div class="timeline-title">Series A — $8M raised</div>
    <div class="timeline-body">Closed our Series A to accelerate product development.</div>
  </div>
</div>
```

### Stats / Counters

```html
<div class="stats-grid">
  <div class="stat-item">
    <div class="stat-value">10K+</div>
    <div class="stat-label">Active Teams</div>
    <div class="stat-description">Across 80+ countries</div>
  </div>
</div>
```

### Logo Cloud

```html
<div class="logo-cloud" aria-label="Trusted by">
  <div class="logo-cloud-item">
    <img src="logos/stripe.svg" alt="Stripe" height="32" />
  </div>
  <div class="logo-cloud-item">
    <img src="logos/notion.svg" alt="Notion" height="32" />
  </div>
</div>
```

### Breadcrumbs

```html
<nav aria-label="Breadcrumb">
  <ol class="breadcrumb">
    <li><a href="/">Home</a></li>
    <li><a href="/blog">Blog</a></li>
    <li aria-current="page">Article Title</li>
  </ol>
</nav>
```

### Pagination

```html
<nav aria-label="Blog pagination">
  <ul class="pagination">
    <li><a href="#" aria-label="Previous page">«</a></li>
    <li><a href="#">1</a></li>
    <li><a href="#" aria-current="page">2</a></li>
    <li><a href="#">3</a></li>
    <li><span class="ellipsis">…</span></li>
    <li><a href="#">12</a></li>
    <li><a href="#" aria-label="Next page">»</a></li>
  </ul>
</nav>
```

### Search Bar

```html
<div class="search-bar">
  <span class="search-icon" aria-hidden="true">🔍</span>
  <input type="search"
         placeholder="Search..."
         aria-label="Search articles" />
  <button class="search-btn">Search</button>
</div>
```

### Data Table

```html
<div class="table-wrapper">
  <table class="data-table" aria-label="Team members">
    <thead>
      <tr>
        <th scope="col">Name</th>
        <th scope="col">Role</th>
        <th scope="col">Status</th>
        <th scope="col">Actions</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Alex Rivera</td>
        <td>CEO</td>
        <td><span class="badge badge-success">Active</span></td>
        <td><a href="#" class="btn btn-ghost btn-sm">Edit</a></td>
      </tr>
    </tbody>
  </table>
</div>
```

---

## Card Variants

### Feature Card

```html
<article class="feature-card">
  <div class="feature-icon" aria-hidden="true">⚡</div>
  <h3>Lightning Fast</h3>
  <p>Built on a modern stack optimized for speed.</p>
</article>
```

### Blog Card

```html
<article class="blog-card">
  <img class="blog-card-image"
       src="post-image.jpg"
       alt="Descriptive alt text" loading="lazy" />
  <div class="blog-card-body">
    <div class="blog-card-meta">
      <span>June 10, 2025</span>
      <span>5 min read</span>
    </div>
    <h3 class="blog-card-title">
      <a href="blog-article.html">Article Title</a>
    </h3>
    <p class="blog-card-excerpt">Brief excerpt of the article content.</p>
    <div class="blog-card-footer">
      <span class="tag">Engineering</span>
      <a href="blog-article.html" class="btn btn-ghost btn-sm">Read →</a>
    </div>
  </div>
</article>
```

### Pricing Card

```html
<div class="pricing-card featured">
  <div class="pricing-badge">Most Popular</div>
  <h3>Pro</h3>
  <p class="text-muted text-sm mb-4">For growing teams.</p>
  <div class="price">
    <sup>$</sup>49<span class="price-period">/month</span>
  </div>
  <ul class="pricing-features">
    <li>
      <span class="check" aria-hidden="true">✓</span>
      Unlimited projects
    </li>
    <li>
      <span class="cross" aria-hidden="true">✕</span>
      <span class="text-muted">SSO / SAML</span>
    </li>
  </ul>
  <a href="signup.html" class="btn btn-primary btn-full">Start free trial</a>
</div>
```

### Testimonial Card

```html
<article class="testimonial-card">
  <div class="stars" aria-label="5 out of 5 stars">★★★★★</div>
  <div class="quote-mark" aria-hidden="true">"</div>
  <p class="quote-text">"This product changed how our team works."</p>
  <div class="author">
    <img class="author-avatar"
         src="https://i.pravatar.cc/48?img=5"
         alt="" />
    <div>
      <div class="author-name">Sarah Chen</div>
      <div class="author-role">VP Engineering, Stripe</div>
    </div>
  </div>
</article>
```

### Team Card

```html
<article class="team-card">
  <img class="avatar"
       src="https://i.pravatar.cc/96?img=20"
       alt="Portrait of Alex Rivera" />
  <div class="name">Alex Rivera</div>
  <div class="role">CEO & Co-founder</div>
  <p class="bio">Previously VP Product at Stripe.</p>
  <div class="social-links">
    <a href="#" class="social-link" aria-label="Alex Rivera on LinkedIn">in</a>
    <a href="#" class="social-link" aria-label="Alex Rivera on Twitter">𝕏</a>
  </div>
</article>
```

---

## Utility Classes Quick Reference

### Display
```
d-block  d-flex  d-inline-flex  d-grid  d-none
```

### Flexbox
```
flex-row  flex-col  flex-wrap
items-start  items-center  items-end  items-stretch
justify-start  justify-center  justify-end  justify-between
gap-1  gap-2  gap-3  gap-4  gap-6  gap-8
```

### Typography
```
text-xs  text-sm  text-base  text-lg  text-xl  text-2xl  text-3xl  text-4xl  text-5xl
font-normal  font-medium  font-semibold  font-bold  font-extrabold
text-left  text-center  text-right
leading-tight  leading-normal  leading-relaxed
tracking-tight  tracking-wide  tracking-wider  tracking-widest
uppercase  lowercase  capitalize
truncate  line-clamp-2  line-clamp-3
```

### Colors
```
text-primary  text-secondary  text-muted  text-subtle  text-inverse
text-success  text-warning  text-error  text-info
bg-primary  bg-secondary  bg-subtle  bg-muted  bg-surface  bg-dark
```

### Spacing
```
mt-0  mt-2  mt-4  mt-6  mt-8  mt-12
mb-0  mb-2  mb-4  mb-6  mb-8  mb-12
p-0  p-2  p-4  p-6  p-8
px-4  px-6  px-8
py-2  py-4  py-6  py-8
mx-auto
```

### Borders & Radius
```
border  border-strong  border-brand  border-t  border-b  border-none
rounded-sm  rounded-md  rounded-lg  rounded-xl  rounded-2xl  rounded-full
```

### Shadows
```
shadow-xs  shadow-sm  shadow-md  shadow-lg  shadow-xl  shadow-none
```

### Accessibility
```
sr-only          /* Visually hidden, screen reader accessible */
not-sr-only      /* Undo sr-only */
skip-link        /* Skip to main content link */
eyebrow          /* Section label above heading */
gradient-text    /* Brand gradient text effect */
```

### Hover Effects
```
hover-lift       /* Subtle lift on hover (translateY + shadow) */
transition-fast  transition-base  transition-slow  transition-colors
```

### Aspect Ratios
```
aspect-square  aspect-video  aspect-4-3  aspect-3-2
```

### Object Fit
```
object-cover  object-contain  object-center
```