Design System Skill

Design System Skill

Core Rule

NEVER use hardcoded Tailwind colors. ALWAYS use semantic CSS variables.

// ❌ WRONG
<div className="bg-slate-900 text-slate-300 border-slate-700">

// ✅ CORRECT
<div className="bg-card text-foreground border-border">

---

Full Documentation

MUST READ: docs/​THEME_SYSTEM.md

This skill is a quick reference. The full theme documentation contains:

• Complete CSS variable reference
• Light/​dark mode implementation
• Accessibility requirements
• Common pitfalls and solutions

---

Quick Reference: CSS Variables

Backgrounds

Text

Status Colors

// Use HSL syntax for status colors
className="text-[hsl(var(--success))]"  // Green
className="text-[hsl(var(--warning))]"  // Amber
className="text-[hsl(var(--info))]"     // Blue
className="text-destructive"             // Red

With Opacity

className="bg-primary/​90"                    // 90% opacity
className="bg-[hsl(var(--success)/​0.1)]"     // 10% opacity

---

Badge Components

Two Distinct Systems

shadcn Badge

import { Badge } from "@/​components/​ui/​badge";

<Badge variant="default">Default</​Badge>
<Badge variant="secondary">Secondary</​Badge>
<Badge variant="destructive">Error</​Badge>
<Badge variant="outline">Outline</​Badge>

SystemBadge

import { SystemBadge } from "@/​components/​ui/​SystemBadge";

<SystemBadge category="status" value="verified" />
<SystemBadge category="type" value="bug" size="sm" />
<SystemBadge category="release" value="now" />

Central Badge Configuration

All badge colors are in src/​lib/​badges.ts:

import { getBadgeClass, getBadgeConfig } from '@/​lib/​badges';

const statusClass = getBadgeClass('status', 'verified');
const badgeConfig = getBadgeConfig('type', 'bug');

---

Critical Patterns

Text Truncation

CRITICAL: truncate won't work without min-w-0!

// ✅ CORRECT
<div className="flex items-center gap-3">
  <Icon className="flex-shrink-0" />        // Prevent icon shrinking
  <div className="flex-1 min-w-0">          // Enable truncation
    <div className="truncate">Long text...</​div>
  </​div>
</​div>

// ❌ WRONG - truncate won't work
<div className="flex-1">
  <div className="truncate">Long text...</​div>
</​div>

Hover States

className="hover:bg-secondary"
className="hover:border-primary/​50"
className="hover:bg-[hsl(var(--success)/​0.1)]"

Focus States

className="focus:outline-none focus:ring-1 focus:ring-primary"

---

⚠️ Light/​Dark Mode (CRITICAL)

The Rule

Every color MUST work in BOTH light AND dark mode. No exceptions.

How It Works

CSS Variable Pattern

ALWAYS define BOTH variants:

/​* In globals.css */
:root {
  /​* Dark mode (default) */
  --custom-color: 200 50% 50%;
}

[data-theme="light"] {
  /​* Light mode - MUST be defined! */
  --custom-color: 200 60% 30%;  /​* Darker for light bg */
}

Common Mistakes

// ❌ WRONG - Hardcoded, breaks in one theme
<div className="bg-slate-900 text-white">

// ❌ WRONG - Only works in dark mode
<div className="bg-gray-800">

// ❌ WRONG - Custom inline color
<div style={{ backgroundColor: '#1e293b' }}>

// ✅ CORRECT - Uses semantic variables
<div className="bg-card text-foreground">

// ✅ CORRECT - With opacity
<div className="bg-muted/​50">

Testing Requirement

ALWAYS test in BOTH themes before considering work complete. Toggle to light mode via user settings or browser dev tools.

---

⚠️ Contrast Requirements (CRITICAL)

WCAG 2.1 AA Standard

How to Check

1. Use browser DevTools color picker
2. Or use WebAIM Contrast Checker

Common Problem: Muted Text

// ❌ RISKY - muted-foreground may have low contrast
<p className="text-muted-foreground text-sm">Small muted text</​p>

// ✅ SAFER - use for secondary info only, not critical content
<p className="text-muted-foreground">Secondary description</​p>
<p className="text-foreground">Important content here</​p>

Status Colors Must Have Contrast

// ✅ Status on dark background - use appropriate contrast
<span className="text-[hsl(var(--success))]">Verified</​span>
<span className="text-destructive">Error occurred</​span>

// ✅ Status as background - ensure text contrast
<Badge variant="success">Verified</​Badge>  // Uses pre-defined contrast

---

Hardcoded Colors = FORBIDDEN

Zero Tolerance Policy

Allowed Patterns

Finding Violations

Search for hardcoded colors in codebase:

# Find Tailwind color classes (potential violations)
grep -r "bg-slate\|bg-gray\|text-slate\|text-gray" src/
grep -r "border-zinc\|bg-zinc" src/

---

Accessibility

Screen Reader Support

<button aria-label="Close modal">
  <X className="h-5 w-5" />
</​button>

// Always add aria-label for icon-only buttons
<button aria-label="Delete item" className="text-destructive">
  <Trash2 className="h-4 w-4" />
</​button>

Focus Indicators

All interactive elements must have visible focus:

className="focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2"

---

shadcn/​ui Components

Installed Components

Usage

// Toasts
import { toast } from "@/​hooks/​use-toast";
toast({ title: "Success!", description: "Saved" });
toast({ title: "Error", variant: "destructive" });

// Confirmation
import { ConfirmDialog } from "@/​components/​ui/​confirm-dialog";
<ConfirmDialog
  open={showDelete}
  onOpenChange={setShowDelete}
  title="Delete?"
  variant="destructive"
  onConfirm={handleDelete}
/>

---

Reference Files

---

Checklist

Before completing any UI work:

• Using semantic CSS variables (not hardcoded colors)
• Tested in BOTH light and dark themes
• Used min-w-0 for flex containers needing truncation
• Used flex-shrink-0 on icons in flex layouts
• Added focus indicators to interactive elements
• Text contrast meets 4.5:1 ratio
• Updated design system page if adding new patterns

---

Related Skills

• form-components - Form field styling
• architecture-philosophy - Use shadcn over custom components