Elementary Design System

Elementary is a design system comprised of three independent, orthogonal layers:

Layer 1: Token Naming System

• Standardized names (--c-primary, --s-4, ...)
• The unchanging contract
• Used across ALL themes

Layer 2: Theme Implementations

• Different VALUES for the same names
• Currently: polished, sketch
• Future: custom themes, brand themes

Layer 3: Component Classes

• Optional pre-built patterns
• Uses Layer 1 token names
• Works with ANY Layer 2 theme

Key Insight: Token NAMES stay constant across themes; only token VALUES change. This allows switching visual fidelity by changing a single CSS import without touching Layer 1 (token names) or Layer 3 (component code).

When to Use This Skill

Token-Based Styling:

• Design system approach with reusable tokens
• Consistent spacing, colors, and typography across projects
• Themeable interfaces (light/dark mode, fidelity levels)

Visual Fidelity Control:

• High-fidelity prototypes (polished, production-ready)
• Low-fidelity wireframes (structural mockups)
• Switch between fidelity levels without code changes

Component Consistency:

• Pre-built component patterns for rapid prototyping
• Design system compliance

Keywords: Elementary, design tokens, CSS variables, light/dark mode, themeable, high-fidelity, sketch, component classes (wf-btn, wf-card), design system

Not a Fit For: Utility-first styling (use Tailwind), quick prototypes without design system constraints, fully custom styling without reusable patterns

Quick Start

Import a Theme

/* Polished (production-ready with light/dark mode) */
@import './assets/elementary/tokens/polished.css';
@import './assets/elementary/components.css';  /* optional */

See: references/themes.md for complete theme documentation

Installing Elementary Assets

To use Elementary in your own project, install the assets locally:

# From your project directory
/path/to/elementary/scripts/elementary.mjs install .

This creates assets/elementary/ in your project with the same structure as this skill.

Component Classes First, Tokens for Custom Components

Primary Approach: Use Component Classes

<article className="wf-card">
  <h3 className="title">Card Title</h3>
  <p className="description">Card content</p>
</article>

Tiny Tweaks: Inline Style Overrides (1-2 properties only):

<article className="wf-card" style={{
  backgroundColor: 'var(--c-slate-100)'  /* Single override OK */
}}>
  <h3 className="title">Card with custom background</h3>
  <p className="description">Override theme for quick escape</p>
</article>

Custom Components: Use Tokens in CSS (when no component class exists):

/* Import Elementary tokens first */
@import './assets/elementary/tokens/polished.css';

/* Create your own class when `components.css` doesn't have what you need */
.custom-alert {
  padding: var(--s-4);
  border-radius: var(--r-card);
  background-color: var(--bg-surface);
  border-left: 4px solid var(--c-primary);
  color: var(--c-text);
  & .title {
    font: var(--t-heading);
  }
}

<article className="custom-alert">
  <h3 className="title">Custom Alert</h3> 
  <p>This component doesn't exist in components.css, 
  so we created a CSS class using Elementary tokens.
  </p>
</article>

Rule: Component classes → Tiny inline tweaks (1-2 properties) → Custom CSS classes with tokens. Never extensive inline styles.

See: references/components.md for all available component classes

Core Concepts

Layer 1: Token Naming System (The Contract)

Standardized names used across ALL themes:

• --c-primary, --c-secondary (colors)
• --bg-surface, --bg-overlay (backgrounds)
• --s-4, --s-6 (spacing: 16px, 24px)
• --r-btn, --r-card (radius)

Token Hierarchy:

• Primitives: Raw scales (--s-4, --c-slate-500) - use in theme files
• Semantics: Intent-based (--c-primary, --bg-surface) - use in CSS classes for custom components

When to Use Design Tokens:

• Creating custom CSS classes for components not in component-library.css
• Building your own design system on top of Elementary
• Tiny inline overrides (1-2 properties max)

When NOT to Use Design Tokens:

• Component classes already exist (use wf-btn, wf-card, etc.)
• Would result in >2 inline style properties (create a CSS class instead)

See: references/token-system.md for complete token taxonomy

Layer 2: Theme Implementations (The Values)

Different VALUE assignments to the same token NAMES:

Polished:

• Semantic colors with light/dark mode
• Professional typography
• Refined shadows
• Production-ready

Sketch:

• Grayscale palette
• Monospace typography
• Minimal shadows
• Structural focus

Theme Switching: Change import path only - all code remains unchanged.

See: references/themes.md for theme characteristics and usage

Layer 3: Component Classes (Optional Patterns)

Pre-built patterns in assets/components.css:

• .wf-btn, .wf-card, .wf-hero (UI components)
• .title, .description, .actions (semantic children)
• Works with ANY Layer 2 theme

See: references/components.md for all available components

Critical Rules

✅ DO

Use Component Classes First:

<div className="wf-card">
<button className="wf-btn primary">

Use Tokens in CSS Classes (for custom components):

.my-custom-alert {
  color: var(--c-primary);
  background-color: var(--bg-surface);
  padding: var(--s-4);
}

Inline Overrides for Tiny Tweaks (1-2 properties max):

<div className="wf-card" style={{ backgroundColor: 'var(--c-accent)' }}>

Change Themes via Import:

/* Switch from polished to sketch */
@import './assets/elementary/tokens/sketch.css';

❌ DON'T

Mix Tailwind with Elementary:

{/* WRONG */}
<div className="wf-card p-4 flex gap-2">

Invent Component Classes:

{/* WRONG - .wf-dashboard-card doesn't exist */}
<div className="wf-dashboard-card">

Use Primitive Tokens in Component Code:

/* WRONG - use semantics instead */
color: var(--c-slate-700);

Hardcode Values:

/* WRONG - defeats the token system */
padding: 16px;
color: #333333;

Excessive Inline Styles (>2 properties):

{/* WRONG - code smell, create a CSS class instead */}
<div style={{
  padding: 'var(--s-6)',
  borderRadius: 'var(--r-card)',
  backgroundColor: 'var(--bg-surface)',
  border: '1px solid var(--c-border)'
}}>

Light/Dark Mode (Polished Theme Only)

Polished theme uses light-dark() CSS function for automatic theming:

User Control:

// Toggle theme
document.documentElement.style.colorScheme = 'dark';  // or 'light'

System Preference (Automatic):

/* Already set in polished.css */
:root { color-scheme: light dark; }

Note: Sketch theme does not support light/dark mode (intentionally grayscale).

See: references/themes.md for browser compatibility and fallbacks

Cross-Skill Composition

Elementary works standalone OR composed with other skills:

With reactive-md:

/* From reactive-md document */
@import './assets/elementary/tokens/polished.css';
@import './assets/elementary/components.css';

With React frameworks:

/* Next.js, Remix, Vite - adjust relative path as needed */
@import './assets/elementary/tokens/polished.css';

Discovering Resources

Token Names (Layer 1):

• Read references/token-system.md - Complete token taxonomy
• Semantic vs primitive hierarchy
• "Ink & Paper" metaphor

Theme Values (Layer 2):

• Read references/themes.md - All available themes
• Polished vs sketch characteristics
• Light/dark mode implementation

Component Classes (Layer 3):

• Read references/components.md - All available classes
• Semantic child elements
• Component-level token patterns

Usage Examples:

• references/recipes/ - Common patterns (buttons, cards, dashboards, landing pages, settings pages)

Installation Tool:

# Install Elementary assets to current directory
/path/to/elementary/scripts/elementary.mjs install .

Discovery Tool (if available):

// Discover component classes and tokens
list_design_classes({
  css_file: "assets/elementary/components.css",
  include_tokens: true,
  theme: "polished"
})