Foundation
Semantic color tokens and CSS custom properties for consistent theming
Semantic Naming
Use semantic tokens (like --color-primary-solid) instead of raw color values. This ensures consistency and enables automatic theme switching.
Background colors for the design system
Primary brand colors for backgrounds
Semantic action colors for buttons and states
Text colors organized by importance and hierarchy
Semantic text colors for different states and purposes
Standard border colors for default states
Semantic border colors for different states
Semantic icon colors for different purposes
{
--sidebar: var(--color-bg); /* Sidebar background */
--sidebar-foreground: var(--color-ink); /* Sidebar text */
--sidebar-primary: var(--color-ink-dark); /* Sidebar primary */
--sidebar-primary-foreground: var(--color-bg); /* Sidebar primary text */
--sidebar-accent: var(--color-secondary); /* Sidebar accent */
--sidebar-accent-foreground: var(--color-ink-dark); /* Sidebar accent text */
--sidebar-border: var(--color-border); /* Sidebar borders */
--sidebar-ring: var(--color-gray-500); /* Sidebar focus ring */
}Spacing tokens provide consistent spacing throughout the design system. All spacing values are in pixels.
Consistent spacing values for margins, padding, and gaps
All tokens automatically adapt to dark mode. Key differences:
.dark {
/* Backgrounds */
--color-panel: oklch(0.21 0.02 256); /* Dark panels */
--color-bg: var(--color-gray-950); /* Very dark background */
/* Text */
--color-ink-dark: oklch(0.98 0 0); /* White text */
--color-ink: oklch(0.95 0 248); /* Light text */
--color-ink-light: oklch(0.71 0.02 259); /* Muted light */
--color-ink-muted: oklch(0.6 0.05 258); /* Dark muted */
/* Primary colors */
--color-primary-solid: var(--color-primary-400);
--color-primary-solid-hover: var(--color-primary-600);
/* Semantic colors */
--color-ink-destructive: var(--color-red-400);
--color-ink-success: var(--color-green-400);
--color-ink-warning: var(--color-yellow-400);
}.my-component {
background-color: var(--color-panel);
color: var(--color-ink);
border: 1px solid var(--color-border);
}
.my-component:hover {
border-color: var(--color-border-hover);
}
.my-component:focus {
border-color: var(--color-border-focus);
outline: 2px solid var(--color-primary-solid);
}<div class="bg-panel text-ink border border-border">
<h2 class="text-ink-dark font-semibold">Heading</h2>
<p class="text-ink-light">Secondary text</p>
</div><Card className="bg-panel border-border">
<CardHeader>
<CardTitle className="text-ink-dark">Title</CardTitle>
<CardDescription className="text-ink-light">Description</CardDescription>
</CardHeader>
<CardContent className="text-ink">
Content with semantic colors
</CardContent>
</Card>/* Using CSS custom properties */
.my-component {
padding: var(--spacing-space-md);
margin-bottom: var(--spacing-space-lg);
gap: var(--spacing-space-sm);
}// Using Tailwind classes (when configured)
<div className="p-md mb-lg gap-sm">
Content with spacing tokens
</div>// In React components with inline styles
<div style={{
padding: 'var(--spacing-space-md)',
marginBottom: 'var(--spacing-space-xl)'
}}>
Content
</div>Use semantic color tokens instead of hard-coded values. This ensures consistency and theme compatibility.
Always test your components in both light and dark modes to ensure proper contrast and readability.
Choose tokens based on semantic meaning (e.g., --color-destructive-solid for delete buttons).
Don't create new color tokens without consulting the design team. Use existing tokens.
Avoid using hex, RGB, or HSL values directly. Always reference design tokens.
Don't override token values in your components. If a token doesn't work, discuss with the design team.
Contrast Requirements
All color token combinations meet WCAG 2.1 AA standards. Ensure you maintain these standards when using tokens.