dss/admin-ui/COMPONENT-USAGE.md

# Component Usage Guide

How to use design system components in the DSS Admin UI and other projects.

## Navigation Components

### Navigation Sections

Group related navigation items with section headers.

```html
<div class="nav-section">
  <h3 class="nav-section__title">Main</h3>
  <a href="#dashboard" class="nav-item" data-page="dashboard">
    <svg class="nav-item__icon"><!-- icon --></svg>
    Dashboard
  </a>
  <a href="#analytics" class="nav-item" data-page="analytics">
    <svg class="nav-item__icon"><!-- icon --></svg>
    Analytics
  </a>
</div>
```

**Classes**:
- `.nav-section`: Container for related items
- `.nav-section__title`: Section header (uppercase, muted)
- `.nav-item`: Individual navigation item
- `.nav-item__icon`: Icon within navigation item
- `.nav-item.active`: Active/current page state
- `.nav-item--indent-1`: Indentation level 1
- `.nav-item--indent-2`: Indentation level 2

**States**:
- `:hover`: Light background, darker text
- `:focus-visible`: Ring outline at 2px offset
- `.active`: Primary background, lighter text

## Buttons

### Button Variants

```html
<!-- Primary button -->
<button class="btn-primary">Save Changes</button>

<!-- Secondary button -->
<button class="btn-secondary">Cancel</button>

<!-- Ghost button -->
<button class="btn-ghost">Learn More</button>

<!-- Destructive button -->
<button class="btn-destructive">Delete</button>
```

**Variants**:
- `.btn-primary`: Main call-to-action
- `.btn-secondary`: Secondary action
- `.btn-ghost`: Tertiary action
- `.btn-destructive`: Dangerous action (delete, remove)

**Sizes**:
- `.btn-sm`: Small button (compact UI)
- (default): Standard button
- `.btn-lg`: Large button (primary CTA)

**States**:
- `:hover`: Darker background
- `:active`: Darkest background
- `:disabled`: Reduced opacity, cursor not-allowed
- `:focus-visible`: Ring outline

## Form Controls

### Input Fields

```html
<div class="form-group">
  <label for="project-name">Project Name</label>
  <input type="text" id="project-name" placeholder="Enter name...">
  <div class="form-group__help">Used in URLs and API calls</div>
</div>

<div class="form-group">
  <label for="description">Description</label>
  <textarea id="description" placeholder="Describe your project..."></textarea>
</div>

<div class="form-group">
  <label for="team">Team</label>
  <select id="team">
    <option>Select a team...</option>
    <option>Design</option>
    <option>Engineering</option>
  </select>
</div>
```

**Classes**:
- `.form-group`: Container for input + label
- `.form-group__help`: Helper text (muted)
- `.form-group__error`: Error message (destructive color)

**Input Types**:
- `input[type="text"]`
- `input[type="email"]`
- `input[type="password"]`
- `textarea`
- `select`

**States**:
- `:focus`: Border to ring color
- `:disabled`: Muted background
- `.form-group__error`: Display error below input

## Cards & Panels

### Basic Card

```html
<div class="card">
  <h3>Card Title</h3>
  <p>Card content goes here.</p>
</div>
```

### Card Variants

```html
<!-- Elevated card -->
<div class="card card--elevated">
  Content with shadow
</div>

<!-- Outlined card -->
<div class="card card--outlined">
  Content with border only
</div>
```

### Panel with Structure

```html
<div class="panel">
  <div class="panel__header">
    <h3 class="panel__title">Panel Title</h3>
    <button class="btn-ghost">Close</button>
  </div>
  <div class="panel__body">
    Panel content goes here
  </div>
  <div class="panel__footer">
    <button class="btn-secondary">Cancel</button>
    <button class="btn-primary">Save</button>
  </div>
</div>
```

**Classes**:
- `.card`: Basic card container
- `.card--elevated`: Card with shadow
- `.card--outlined`: Card with border
- `.panel`: Structured container
- `.panel__header`: Header section with title
- `.panel__title`: Panel heading
- `.panel__body`: Main content area
- `.panel__footer`: Footer with actions

## Help Panel (Collapsible)

```html
<details class="help-panel">
  <summary class="help-panel__toggle">
    <svg><!-- help icon --></svg>
    Need Help?
  </summary>
  <div class="help-panel__content">
    <div class="help-section">
      <strong>Getting Started</strong>
      <ul>
        <li>Create a new project</li>
        <li>Import design tokens</li>
        <li>Apply to your UI</li>
      </ul>
    </div>
    <div class="help-section">
      <strong>Keyboard Shortcuts</strong>
      <ul>
        <li><code>Cmd+K</code>: Search</li>
        <li><code>Cmd+/</code>: Toggle sidebar</li>
      </ul>
    </div>
  </div>
</details>
```

**Classes**:
- `.help-panel`: Details element wrapper
- `.help-panel__toggle`: Summary (clickable title)
- `.help-panel__content`: Content container (hidden by default)
- `.help-section`: Section within content
- `<strong>`: Section header

**States**:
- `.help-panel[open]`: Content visible

## Notification Indicator

```html
<button class="notification-toggle-container">
  <svg><!-- bell icon --></svg>
  <span class="status-dot"></span>
</button>
```

**Classes**:
- `.notification-toggle-container`: Container for relative positioning
- `.status-dot`: Small indicator dot

## Utility Classes

### Flexbox

```html
<!-- Flex container -->
<div class="flex gap-4">
  <div>Left</div>
  <div>Right</div>
</div>

<!-- Column layout -->
<div class="flex flex-col gap-2">
  <div>Top</div>
  <div>Middle</div>
  <div>Bottom</div>
</div>

<!-- Centering -->
<div class="flex items-center justify-center">
  Centered content
</div>
```

**Flex Utilities**:
- `.flex`: Display flex
- `.flex-col`: Flex direction column
- `.flex-row`: Flex direction row (default)
- `.justify-start`, `.justify-center`, `.justify-end`, `.justify-between`, `.justify-around`
- `.items-start`, `.items-center`, `.items-end`

### Gaps & Spacing

```html
<div class="gap-4 p-4 m-3">
  Content with gap, padding, margin
</div>
```

**Gap Utilities**: `.gap-1` through `.gap-6`
**Padding**: `.p-1`, `.p-2`, `.p-3`, `.p-4`, `.p-6`
**Margin**: `.m-1`, `.m-2`, `.m-3`, `.m-4`, `.m-6`

### Text & Typography

```html
<p class="text-sm text-muted">Small muted text</p>
<h2 class="text-xl font-600">Heading</h2>
<p class="text-primary">Colored text</p>
```

**Text Size**: `.text-xs` through `.text-2xl`
**Font Weight**: `.font-400` through `.font-700`
**Text Color**: `.text-foreground`, `.text-muted`, `.text-primary`, `.text-destructive`, `.text-success`, `.text-warning`

### Background & Borders

```html
<div class="bg-surface border rounded p-4">
  Styled container
</div>
```

**Background**: `.bg-surface`, `.bg-muted`, `.bg-primary`, `.bg-destructive`
**Border**: `.border`, `.border-none`, `.border-top`, `.border-bottom`
**Border Radius**: `.rounded`, `.rounded-sm`, `.rounded-md`, `.rounded-lg`, `.rounded-full`

### Display & Visibility

```html
<div class="hidden">Not visible</div>
<div class="block">Block element</div>
<div class="inline-block">Inline-block element</div>
```

**Display**: `.hidden`, `.block`, `.inline-block`, `.inline`
**Overflow**: `.overflow-hidden`, `.overflow-auto`, `.overflow-x-auto`, `.overflow-y-auto`
**Opacity**: `.opacity-50`, `.opacity-75`, `.opacity-100`

## Responsive Design

Media queries are handled in Layer 5 (`_responsive.css`):

```css
/* Tablets and below */
@media (max-width: 1023px) {
  .sidebar {
    display: none;
  }
}

/* Mobile only */
@media (max-width: 639px) {
  button {
    width: 100%;
  }
}
```

**Breakpoints**:
- `1024px`: Tablet/desktop boundary
- `640px`: Mobile/tablet boundary

## Accessible Components

All components are built with accessibility in mind:

### Focus Management
```html
<!-- Input gets focus ring -->
<input type="text" />

<!-- Button gets focus ring -->
<button>Action</button>
```

### Labels for Inputs
```html
<!-- Always pair label with input -->
<label for="email">Email Address</label>
<input type="email" id="email" />
```

### Navigation Semantics
```html
<nav class="sidebar__nav">
  <div class="nav-section">
    <!-- Items get proper keyboard nav -->
  </div>
</nav>
```

### Color Contrast
- All text meets WCAG AA or AAA standards
- Never rely on color alone to convey information

### Motion Preferences
Consider user preferences:
```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

## Dark Mode

All components automatically respond to dark mode:

```css
@media (prefers-color-scheme: dark) {
  /* Dark theme colors applied automatically */
}
```

Users can also set theme explicitly:
```html
<html data-theme="dark">
```

## Best Practices

1. **Use semantic HTML**: `<button>`, `<input>`, `<label>`, `<nav>`
2. **Combine utilities**: Mix classes for flexibility
3. **Maintain spacing consistency**: Always use spacing scale
4. **Test contrast**: Especially for custom colors
5. **Keyboard test**: Ensure all interactive elements are keyboard accessible
6. **Mobile first**: Design for mobile, enhance for larger screens
7. **Respect motion preferences**: Reduce animations for users who prefer it