dss/admin-ui/DESIGN-SYSTEM.md

# Design System Implementation

## Overview

The DSS Admin UI is built using a layered CSS architecture that consumes the Design System as the source of truth. This document explains how the design system is implemented and how other projects can replicate this pattern.

## Architecture

The design system is organized into **5 distinct layers**, each with a specific responsibility:

### Layer 0: Reset
**Location**: `/src/styles/0-reset/`

Establishes a consistent baseline across all browsers by normalizing default styles and setting sensible defaults for all HTML elements.

- Removes margins and padding
- Sets box-sizing to border-box
- Normalizes form elements
- Improves font smoothing

### Layer 1: Design Tokens
**Location**: `/src/styles/1-tokens/`

Defines all base design decisions as CSS custom properties (variables). These tokens are the single source of truth and are derived from `design-tokens.json`.

**Token Categories**:
- **Colors**: Primary, secondary, accent, semantic (success, warning, error), and neutral colors
- **Spacing**: Scale from 0-8 using a 4px base unit
- **Typography**: Font families, sizes, weights, and line heights
- **Radius**: Border radius values for different element sizes
- **Shadows**: Shadow system for depth and elevation
- **Durations**: Animation timing values
- **Easing**: Animation easing functions

**Example Token Usage**:
```css
button {
  background: var(--primary);
  color: var(--primary-foreground);
  padding: var(--space-3) var(--space-4);
  border-radius: var(--radius);
  transition: background var(--duration-fast) var(--ease-default);
}
```

### Layer 2: Theme
**Location**: `/src/styles/2-theme/`

Applies semantic meaning to tokens by mapping them to functional roles. This layer enables theme switching (light/dark mode) without changing component code.

**Files**:
- `_palette.css`: Maps tokens to semantic roles (primary, secondary, destructive, success, etc.)
- `_theme-dark.css`: Dark mode color overrides

### Layer 3: Layout
**Location**: `/src/styles/3-layout/`

Defines the application structure and major layout components:

- **_grid.css**: Main app grid (sidebar + content)
- **_sidebar.css**: Sidebar structure
- **_header.css**: Page header and action bars
- **_main.css**: Main content area and sections

### Layer 4: Components
**Location**: `/src/styles/4-components/`

Reusable component styles built from tokens and layout primitives:

- **_navigation.css**: Navigation items and sections
- **_buttons.css**: Button variants (primary, secondary, ghost, destructive)
- **_inputs.css**: Form controls and inputs
- **_panels.css**: Cards, panels, help elements
- **_utilities.css**: Utility classes for common patterns

### Layer 5: Admin
**Location**: `/src/styles/5-admin/`

Admin-specific customizations and overrides:

- **_sidebar-custom.css**: Admin UI sidebar styling
- **_responsive.css**: Media queries for responsive behavior
- **_overrides.css**: Emergency overrides (should be minimal)

## Import Order

The CSS files are imported in strict order via `/src/styles/index.css`:

1. Reset (establishes baseline)
2. Tokens (defines all design values)
3. Theme (applies semantic mapping)
4. Layout (defines structure)
5. Components (builds on top)
6. Admin (project-specific)

This order ensures proper CSS cascade and prevents specificity conflicts.

## Design Tokens JSON

The source of truth is `design-tokens.json` in the root directory:

```json
{
  "colors": {
    "primary": {
      "value": "oklch(0.65 0.18 250)",
      "description": "Primary brand color",
      "category": "semantic",
      "usage": "Links, buttons, active states"
    }
  },
  "spacing": { ... },
  "typography": { ... }
}
```

## Using the Design System

### Replicating This Pattern

To use this design system in another project:

1. **Copy the token definitions**:
   ```
   design-tokens.json
   src/styles/
   ```

2. **Link the stylesheet**:
   ```html
   <link rel="stylesheet" href="/src/styles/index.css">
   ```

3. **Use tokens in custom CSS**:
   ```css
   .custom-element {
     background: var(--primary);
     padding: var(--space-4);
   }
   ```

4. **Customize tokens as needed**:
   - Edit `design-tokens.json`
   - Regenerate CSS variable files from the tokens
   - Your entire project updates automatically

### Theme Switching

Implement light/dark mode:

```js
// Switch to dark mode
document.documentElement.style.setProperty('--color-foreground', 'oklch(0.92 0.02 280)');
// or use media query
@media (prefers-color-scheme: dark) { ... }
```

### Extending Components

Create project-specific components:

```css
/* layers/5-admin/_custom-components.css */
.custom-card {
  padding: var(--space-4);
  background: var(--card);
  border: 1px solid var(--border);
  border-radius: var(--radius);
}
```

## CSS Variable Reference

### Colors
- `--color-primary`, `--primary`
- `--color-secondary`, `--secondary`
- `--color-accent`, `--accent`
- `--color-destructive`, `--destructive`
- `--color-success`, `--success`
- `--color-warning`, `--warning`
- `--color-info`, `--info`
- `--color-foreground`, `--muted-foreground`
- `--color-background`, `--surface`, `--card`, `--input`, `--muted`
- `--color-border`, `--ring`

### Spacing
- `--space-0` through `--space-8` (4px base unit)

### Typography
- `--font-sans`, `--font-mono`
- `--text-xs` through `--text-2xl`
- `--font-400` through `--font-700`
- `--line-height-tight` through `--line-height-loose`

### Other
- `--radius-none`, `--radius-sm`, `--radius`, `--radius-md`, `--radius-lg`, `--radius-full`
- `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`
- `--duration-fast`, `--duration-normal`, `--duration-slow`
- `--ease-default`, `--ease-in`, `--ease-out`, `--ease-in-out`

## Best Practices

1. **Always use tokens**: Never hardcode colors, spacing, or sizing
2. **Respect the cascade**: Each layer builds on previous ones
3. **Keep overrides minimal**: Layer 5 should be small and well-documented
4. **Semantic naming**: Use semantic tokens (--primary) over base tokens (--color-primary)
5. **Component consistency**: Use the same tokens across all components
6. **Responsive first**: Layer 5 handles responsive adjustments
7. **Document changes**: Update TOKEN-REFERENCE.md when adding new tokens

## Maintenance

When updating the design system:

1. Update `design-tokens.json`
2. Regenerate token CSS files (Layers 1-2)
3. Test all components
4. Update documentation
5. Deploy changes

All projects using the design system will automatically inherit the updates.