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.

<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

<!-- 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

<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

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

Card Variants

<!-- 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

<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)

<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

<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

<!-- 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

<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

<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

<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

<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):

/* 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

<!-- Input gets focus ring -->
<input type="text" />

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

Labels for Inputs

<!-- Always pair label with input -->
<label for="email">Email Address</label>
<input type="email" id="email" />

Navigation Semantics

<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:

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Dark Mode

All components automatically respond to dark mode:

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

Users can also set theme explicitly:

<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