The-Utopia-Studio/ckm:design-system

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:

1. Import assets/design-tokens.css - single source of truth
2. Use CSS variables: var(--color-primary), var(--slide-bg), etc.
3. Use Chart.js for charts (NOT CSS-only bars)
4. Include navigation (keyboard arrows, click, progress bar)
5. Center align content
6. Focus on persuasion/conversion

Chart.js Integration

<script src="https://cdn.jsdelivr.net/npm/[email protected]/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

1. Never use raw hex in components - always reference tokens
2. Semantic layer enables theme switching (light/dark)
3. Component tokens enable per-component customization
4. Use HSL format for opacity control
5. Document every token's purpose
6. Slides must import design-tokens.css and use var() exclusively