Design System

Token architecture, component specifications, systematic design, slide generation.

When to Use

• Design token creation

• Component state definitions

• CSS variable systems

• Spacing/typography scales

• Design-to-code handoff

• Tailwind theme configuration

• Slide/presentation generation

Token Architecture

Load: references/token-architecture.md

Three-Layer Structure

Primitive (raw values)

       ↓

Semantic (purpose aliases)

       ↓

Component (component-specific)

Example:

/* Primitive */

--color-blue-600: #2563EB;

/* Semantic */

--color-primary: var(--color-blue-600);

/* Component */

--button-bg: var(--color-primary);

Quick Start

Generate tokens:

node scripts/generate-tokens.cjs --config tokens.json -o tokens.css

Validate usage:

node scripts/validate-tokens.cjs --dir src/

References

Topic

File

Token Architecture

references/token-architecture.md

Primitive Tokens

references/primitive-tokens.md

Semantic Tokens

references/semantic-tokens.md

Component Tokens

references/component-tokens.md

Component Specs

references/component-specs.md

States & Variants

references/states-and-variants.md

Tailwind Integration

references/tailwind-integration.md

Component Spec Pattern

Property

Default

Hover

Active

Disabled

Background

primary

primary-dark

primary-darker

muted

Text

white

white

white

muted-fg

Border

none

none

none

muted-border

Shadow

sm

md

none

none

Scripts

Script

Purpose

generate-tokens.cjs

Generate CSS from JSON token config

validate-tokens.cjs

Check for hardcoded values in code

search-slides.py

BM25 search + contextual recommendations

slide-token-validator.py

Validate slide HTML for token compliance

fetch-background.py

Fetch images from Pexels/Unsplash

Templates

Template

Purpose

design-tokens-starter.json

Starter JSON with three-layer structure

Integration

With brand: Extract primitives from brand colors/typography

With ui-styling: Component tokens → Tailwind config

Skill Dependencies: brand, ui-styling

Primary Agents: ui-ux-designer, frontend-developer

Slide System

Brand-compliant presentations using design tokens + Chart.js + contextual decision system.

Source of Truth

File

Purpose

docs/brand-guidelines.md

Brand identity, voice, colors

assets/design-tokens.json

Token definitions (primitive→semantic→component)

assets/design-tokens.css

CSS variables (import in slides)

assets/css/slide-animations.css

CSS animation library

Slide Search (BM25)

# Basic search (auto-detect domain)

python scripts/search-slides.py "investor pitch"

# Domain-specific search

python scripts/search-slides.py "problem agitation" -d copy

python scripts/search-slides.py "revenue growth" -d chart

# Contextual search (Premium System)

python scripts/search-slides.py "problem slide" --context --position 2 --total 9

python scripts/search-slides.py "cta" --context --position 9 --prev-emotion frustration

Decision System CSVs

File

Purpose

data/slide-strategies.csv

15 deck structures + emotion arcs + sparkline beats

data/slide-layouts.csv

25 layouts + component variants + animations

data/slide-layout-logic.csv

Goal → Layout + break_pattern flag

data/slide-typography.csv

Content type → Typography scale

data/slide-color-logic.csv

Emotion → Color treatment

data/slide-backgrounds.csv

Slide type → Image category (Pexels/Unsplash)

data/slide-copy.csv

25 copywriting formulas (PAS, AIDA, FAB)

data/slide-charts.csv

25 chart types with Chart.js config

Contextual Decision Flow

1. Parse goal/context

        ↓

2. Search slide-strategies.csv → Get strategy + emotion beats

        ↓

3. For each slide:

   a. Query slide-layout-logic.csv → layout + break_pattern

   b. Query slide-typography.csv → type scale

   c. Query slide-color-logic.csv → color treatment

   d. Query slide-backgrounds.csv → image if needed

   e. Apply animation class from slide-animations.css

        ↓

4. Generate HTML with design tokens

        ↓

5. Validate with slide-token-validator.py

Pattern Breaking (Duarte Sparkline)

Premium decks alternate between emotions for engagement:

"What Is" (frustration) ↔ "What Could Be" (hope)

System calculates pattern breaks at 1/3 and 2/3 positions.

Slide Requirements

ALL slides MUST:

• Import assets/design-tokens.css - single source of truth

• Use CSS variables: var(--color-primary), var(--slide-bg), etc.

• Use Chart.js for charts (NOT CSS-only bars)

• Include navigation (keyboard arrows, click, progress bar)

• Center align content

• Focus on persuasion/conversion

Chart.js Integration

<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script>

<canvas id="revenueChart"></canvas>

<script>

new Chart(document.getElementById('revenueChart'), {

    type: 'line',

    data: {

        labels: ['Sep', 'Oct', 'Nov', 'Dec'],

        datasets: [{

            data: [5, 12, 28, 45],

            borderColor: '#FF6B6B',  // Use brand coral

            backgroundColor: 'rgba(255, 107, 107, 0.1)',

            fill: true,

            tension: 0.4

        }]

    }

});

</script>

Token Compliance

/* CORRECT - uses token */

background: var(--slide-bg);

color: var(--color-primary);

font-family: var(--typography-font-heading);

/* WRONG - hardcoded */

background: #0D0D0D;

color: #FF6B6B;

font-family: 'Space Grotesk';

Reference Implementation

Working example with all features:

assets/designs/slides/claudekit-pitch-251223.html

Command

/slides:create "10-slide investor pitch for ClaudeKit Marketing"

Best Practices

• Never use raw hex in components - always reference tokens

• Semantic layer enables theme switching (light/dark)

• Component tokens enable per-component customization

• Use HSL format for opacity control

• Document every token's purpose

• Slides must import design-tokens.css and use var() exclusively