dss/admin-ui/CUSTOMIZATION-GUIDE.md

Design System Customization Guide

How to customize the design system for your project while maintaining its integrity.

Customization Hierarchy

The design system is organized into customization layers:

1. Token Overrides (safest): Modify design-tokens.json and regenerate CSS
2. Theme Customization (safe): Override colors in 2-theme/
3. Component Extension (consider carefully): Add new variants in 4-components/
4. Admin Overrides (last resort): Use 5-admin/ for project-specific changes

Token Customization

Modifying Tokens

Edit design-tokens.json to change design decisions:

{
  "colors": {
    "primary": {
      "value": "oklch(0.65 0.18 250)",
      "description": "Brand color - MODIFY THIS"
    }
  }
}

After editing, regenerate the CSS variable files:

npm run generate-tokens
# or manually update src/styles/1-tokens/_colors.css

Adding New Tokens

{
  "colors": {
    "brand-blue": {
      "value": "oklch(0.55 0.20 230)",
      "description": "Custom brand blue",
      "category": "custom"
    }
  },
  "spacing": {
    "custom-large": {
      "value": "3rem",
      "description": "Custom large spacing"
    }
  }
}

Then add CSS variables:

:root {
  --color-brand-blue: oklch(0.55 0.20 230);
  --space-custom-large: 3rem;
}

Theme Customization

Creating a Light/Dark Theme

Edit 2-theme/_palette.css:

:root {
  --primary: var(--color-primary);
  --primary-hover: var(--color-primary-hover);
  /* ... map tokens to semantic roles ... */
}

Override colors for light mode:

@media (prefers-color-scheme: light) {
  :root {
    --foreground: oklch(0.15 0.02 280);
    --background: oklch(0.98 0.01 280);
    /* ... */
  }
}

Brand-Specific Theme

Create a new theme file in 2-theme/:

/* src/styles/2-theme/_brand-acme.css */
:root[data-brand="acme"] {
  --primary: oklch(0.70 0.15 25);  /* Acme red */
  --secondary: oklch(0.65 0.18 45); /* Acme orange */
  --accent: oklch(0.75 0.12 210);  /* Acme blue */
}

Import in index.css:

@import url('./2-theme/_palette.css');
@import url('./2-theme/_brand-acme.css');
@import url('./2-theme/_theme-dark.css');

Component Customization

Creating a New Component Variant

Add to the appropriate component file in 4-components/:

/* In _buttons.css */
button.btn-outline {
  background: transparent;
  border: 2px solid var(--primary);
  color: var(--primary);
}

button.btn-outline:hover {
  background: var(--primary);
  color: var(--primary-foreground);
}

Extending Panels

/* In _panels.css */
.panel--highlighted {
  border-left: 4px solid var(--primary);
  background: var(--primary-light, oklch(0.65 0.18 250 / 0.05));
}

.panel--compact {
  padding: var(--space-2);
}

Custom Navigation

/* In _navigation.css */
.nav-item--large {
  padding: var(--space-4) var(--space-3);
  min-height: 48px;
}

.nav-item--small {
  padding: var(--space-1) var(--space-3);
  font-size: var(--text-xs);
}

Admin-Level Customization

Project-Specific Styles

For changes that only apply to your project, use Layer 5:

/* src/styles/5-admin/_custom-ui.css */

/* Custom layout for admin pages */
.admin-layout {
  display: grid;
  grid-template-columns: 200px 1fr;
  gap: var(--space-6);
}

/* Custom admin card styles */
.admin-card {
  padding: var(--space-6);
  background: var(--card);
  border: 2px solid var(--primary);
  border-radius: var(--radius-lg);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

Import in index.css:

@import url('./5-admin/_custom-ui.css');

Responsive Overrides

For project-specific responsive changes:

/* src/styles/5-admin/_responsive-custom.css */

@media (max-width: 768px) {
  .admin-layout {
    grid-template-columns: 1fr;
  }
  
  .sidebar {
    height: auto;
    flex-direction: row;
    border-right: none;
    border-bottom: 1px solid var(--border);
  }
}

Dangerous Customizations (Avoid!)

Don't Override Tokens Locally

❌ Bad: Hardcoding values

button {
  background: #5B21B6;  /* ❌ No! Use tokens */
  padding: 12px;        /* ❌ No! Use spacing scale */
}

✅ Good: Using tokens

button {
  background: var(--primary);        /* ✓ Use token */
  padding: var(--space-3);           /* ✓ Use spacing */
}

Don't Break the Cascade

❌ Bad: Adding high-specificity rules

div.page-content button.nav-item.active {  /* ❌ Too specific */
  color: var(--primary);
}

✅ Good: Working with cascade

button.nav-item.active {  /* ✓ Appropriate specificity */
  color: var(--primary);
}

Don't Duplicate Components

❌ Bad: Creating similar but separate components

.card { /* ... */ }
.panel { /* ... */ }
.container { /* ... */ }

✅ Good: Extending existing components

.card { /* base styles */ }
.card--highlighted { /* variant */ }
.card--compact { /* variant */ }

Migration Path

When updating the design system:

1. Update tokens: Change design-tokens.json
2. Regenerate CSS: Run token generation script
3. Test components: Check all component variants
4. Iterate themes: Update color overrides
5. Test responsive: Verify mobile/tablet views
6. Update docs: Document any new tokens or patterns

Accessibility Considerations

When customizing:

• Color Contrast: Test contrast ratios for text/background
• Focus States: Ensure focus indicators are visible
• Motion: Respect prefers-reduced-motion
• Sizing: Use spacing scale for consistent padding/margin
• Typography: Maintain readable font sizes and line heights

WCAG Compliance

Test customizations against WCAG 2.1 AA:

/* Good: High contrast */
.dark-text {
  color: oklch(0.20 0.02 280);      /* ✓ WCAG AAA on light bg */
  background: oklch(0.98 0.01 280);
}

/* Bad: Low contrast */
.muted-text {
  color: oklch(0.85 0.01 280);       /* ❌ Fails WCAG on light bg */
  background: oklch(0.98 0.01 280);
}

Performance Considerations

CSS File Size

• Keep Layer 5 minimal (only project-specific styles)
• Reuse utility classes instead of creating new ones
• Import only needed theme variations

CSS Specificity

• Avoid !important (breaks cascade)
• Use lowest specificity possible
• Let the cascade work for you

Exporting Customizations

To share customizations with other projects:

1. Extract tokens: Export design-tokens.json with your changes
2. Export theme: Create exportable theme file in 2-theme/
3. Document changes: Update TOKEN-REFERENCE.md
4. Version: Tag the release (e.g., v1.0.0)

Sharing Format

my-design-system/
├── design-tokens.json
├── src/styles/
│   ├── 1-tokens/
│   ├── 2-theme/
│   │   └── _custom-brand.css
│   └── index.css
├── TOKEN-REFERENCE.md
└── CUSTOMIZATION-GUIDE.md

Troubleshooting

Colors Look Wrong

1. Check browser supports OKLCH (modern browsers do)
2. Verify 2-theme/_palette.css mappings
3. Check dark mode detection (prefers-color-scheme)
4. Compare against design-tokens.json values

Spacing Is Inconsistent

1. Verify all custom styles use token variables
2. Check Layer 5 for hardcoded values
3. Ensure no margins/padding in Layer 4 conflict
4. Use spacing scale consistently

Components Not Styled

1. Verify CSS link in HTML: <link rel="stylesheet" href="/src/styles/index.css">
2. Check browser network tab (file loading?)
3. Verify HTML class names match CSS selectors
4. Check browser dev tools for CSS overrides

Focus Indicators Not Visible

1. Ensure --ring token is defined
2. Check focus styles in Layer 4 components
3. Verify outline isn't removed elsewhere
4. Test with keyboard navigation (Tab)