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:

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:

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

   <link rel="stylesheet" href="/src/styles/index.css">
   

3. Use tokens in custom 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:

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

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