Shain Dls

Shain Design Language System (DLS)

A token-based design system for product UI work. Components use semantic tokens only — no hardcoded colors, spacing, or typography. Figma is the source of truth; code is generated or guided by Figma exports.

For the full Figma best practices reference, read references/figma-best-practices.md. For guidance on evolving the token system, read references/token-improvements.md.

1. Architecture

Three-tier token hierarchy

Copy code
Primitive → Semantic → Component-specific (optional)

colors/blue/500          → #0097DB
action/primary/default   → {colors/blue/500}
button/bg/primary        → {action/primary/default}

• Primitive — raw palette values (colors/blue/500, spacing/4, radius/md). Never referenced directly from components.
• Semantic — purpose-named aliases (action/primary/default, text/primary, bg/surface). Components reference these.
• Component-specific — optional per-component tokens when a component needs its own tuning knob (button/bg/primary). Use sparingly.

Sync flow

Copy code
Figma Variables → figma-tokens.json → tokens/build.ts → tokens/dist/
                                                         ├── tokens.css
                                                         └── tokens.ts

Project structure

Copy code
├── docs/           Documentation
├── tokens/         figma-tokens.json → CSS vars + TS
└── src/
    ├── components/ React components
    └── icons/      Figma → lucide-react catalog

2. Design principles

1. Token-first — All visual values come from design tokens. No hardcoded colors, spacing, or typography in components.
2. Semantic over raw — Semantic token names describe purpose, not appearance. Components reference destructive/default, not red/500.
3. Figma as source of truth — Tokens and component specs live in Figma. Code is generated or guided by Figma exports.
4. Mode-ready — All semantic tokens resolve through modes (Light/Dark, density, brand) so a single component definition adapts to any theme.

3. Token naming

Pattern

Copy code
{category}/{purpose}/{state}

• category — action, destructive, success, warning, info, text, bg, border, icon, overlay
• purpose — primary, secondary, subtle, inverse, link, disabled
• state — default, hover, pressed, focus, disabled, selected

Examples

Rules

• Use lowercase, slashes in Figma, kebab-case as CSS vars.
• Do not encode appearance in the name (red-hover is wrong; destructive-hover is right).
• Stateful tokens always live at the third level (.../hover, .../pressed).
• A token that exists on one category should exist on comparable categories (if action/primary/hover exists, so should destructive/hover).

4. Modes

Built-in modes

• Theme: Light (default), Dark
• Optional: Density (Comfortable, Compact), Brand (if multi-brand)

Rules

• Every semantic token defines a value for every mode. No mode may be empty.
• Components never branch on theme — they reference semantic tokens only.
• Primitive collections do not need modes; modes live on the semantic layer.

Required dark-mode pairs (minimum)

5. Component guidelines

File layout

Copy code
src/components/[ComponentName]/
├── [ComponentName].tsx
├── [ComponentName].css
└── index.ts

CSS class naming (BEM-like)

• Block: shain-[component] (e.g. shain-btn, shain-input)
• Element: shain-[component]__[element] (e.g. shain-btn__label)
• Modifier: shain-[component]--[modifier] (e.g. shain-btn--primary, shain-btn--sm)

Multiple modifiers combine: shain-btn shain-btn--primary shain-btn--md shain-btn--destructive.

Token usage in code

Theme config pattern (variant styling)

For components with variants and states, use a config object instead of variant-specific CSS:

tsCopy code
enum ButtonVariant {
  Primary = "primary",
  Secondary = "secondary",
}

const theme = {
  [ButtonVariant.Primary]: {
    base:     ["--action-primary-default",  "--action-primary-default",  "--text-inverse"],
    hover:    ["--action-primary-hover",    "--action-primary-hover",    "--text-inverse"],
    pressed:  ["--action-primary-pressed",  "--action-primary-pressed",  "--text-inverse"],
    disabled: ["--action-disabled",         "--border-default",          "--text-disabled"],
  },
  [ButtonVariant.Secondary]: {
    base:     ["--bg-surface",              "--border-default",          "--action-primary-default"],
    hover:    ["--bg-surface-hover",        "--border-default",          "--action-primary-hover"],
    pressed:  ["--bg-surface-pressed",      "--border-default",          "--action-primary-pressed"],
    disabled: ["--bg-surface",              "--border-default",          "--text-disabled"],
  },
};
// Apply via CSS variables: --cmp-bg, --cmp-border, --cmp-color

Component anatomy

Interactive components support: variants (primary, secondary, outline, ghost, link), sizes (sm, md, lg, icon), states (default, hover, focus, pressed, disabled, loading).

Non-interactive components (e.g. Badge): no hover states or transitions, cursor: default.

Variant properties in Figma

Keep variant properties to 2–3 maximum. In exceptional cases 4 is acceptable with justification. Use boolean properties for optional elements (icons, badges) and instance swap for swappable elements.

Copy code
Good — 9 variants + flexible toggles:
  Variant: Size (sm, md, lg) × Type (primary, secondary, outline)
  Boolean: Show Leading Icon, Show Trailing Icon
  Instance swap: Icon

Bad — 864 variants:
  Size (4) × Color (6) × Icon Position (3) × State (4) × Alignment (3)

Props convention

• TypeScript interfaces with explicit types
• Support className and spread remaining HTML attributes
• forwardRef for form elements and focusable components
• Default values match the most common use case

Icons

• Use lucide-react
• Accept LucideIcon type for icon props
• Icon size: 16px inline with text; use tokens if a size scale exists
• Catalog: src/icons/iconCatalog.ts maps Figma names → Lucide components

6. Accessibility

1. Focus — :focus-visible for keyboard focus; avoid focus ring on mouse click.
2. Disabled — disabled on interactive elements; aria-disabled only as fallback.
3. Loading — aria-busy="true" when appropriate.
4. Labels — All form controls have associated labels (visible or aria-label).
5. Keyboard — Tab, Enter, Space, Escape for dropdowns/modals.
6. Touch targets — Minimum 44×44px.
7. Contrast — 4.5:1 for text, 3:1 for UI elements, verified in both Light and Dark.

7. Typography

• Font family: sans-serif (configurable per brand)
• Weights: 400 (normal), 600 (medium), 700 (bold)
• Sizes: text/xs (12px) through text/3xl (32px)
• Line heights: leading/1 (16px) through leading/6 (40px)

8. Spacing & Radius

Spacing scale:

Radius scale:

9. Anti-patterns

1. Absolute positioning instead of auto layout — Always use auto layout with spacing tokens.
2. Too many variants — 100+ variants means booleans and instance swaps are underused.
3. Hardcoded values — Any raw hex, px value, or magic number should be a token reference.
4. Appearance-based names — red-hover, blue-bg leak visuals into purpose names.
5. Components referencing primitives — Primitives are internal; components reference semantic tokens.
6. Unnamed layers — "Frame 123" is unacceptable. Name every layer by purpose.
7. No component docs — Every component needs a doc from the template.
8. Mixing presentation and content — Separate structural layers from content layers.
9. Componentizing everything — Only reusable, consistent, interactive, or coded elements.
10. Ignoring accessibility in Figma — 44×44px targets, contrast ratios, focus states.
11. Deep nesting — Maximum 3 levels (e.g., Card → Button → Icon).
12. Detached instances — Always use main component references inside other components.

10. Checklists

Figma-side (before handoff)

Structure: auto layout, descriptive layer names, ≤3 nesting levels, main component refs, proper constraints.

Properties: 2–3 variant props, booleans for optional elements, text props for content, instance swap for icons, sensible defaults.

Tokens: all fills use semantic variables (no hex), spacing variables, text styles, effect styles, no magic numbers. No primitive references from component layers.

States: default, hover, pressed/active, disabled, focus (keyboard).

Testing: works at different sizes, short/long content, no overflow, Light and Dark mode both pass contrast checks.

Code-side (new components)

• All colors: var(--semantic-token-name) — never primitives
• Variant colors via theme config
• All spacing: var(--spacing-N)
• All typography: var(--text-*) / var(--leading-*)
• Border radius: var(--radius-*)
• CSS classes: shain-[component] naming
• TypeScript typed props
• forwardRef for focusable elements
• :focus-visible styles
• Component doc from template

11. AI workflow for component generation

When generating components from Figma:

1. Read component spec — Variants, sizes, states from Figma.
2. Map to semantic tokens — Every fill, stroke, text, padding, radius, gap maps to a semantic token (never a primitive).
3. Use the theme config pattern for variants with multiple states.
4. Follow component guidelines — BEM naming (shain-*), forwardRef, accessibility.
5. Verify both modes — Component must pass contrast in Light and Dark.
6. Add changelog entry to the component doc.

Reference files

Read these when you need deeper context: