1---
2name: ckm:design-system
3description: Token architecture, component specifications, and slide generation. Three-layer tokens (primitive→semantic→component), CSS variables, spacing/typography scales, component specs, strategic slide creation. Use for design tokens, systematic design, brand-compliant presentations.
4argument-hint: "[component or token]"
5license: MIT
6metadata:
7  author: claudekit
8  version: "1.0.0"
9---
10 
11# Design System
12 
13Token architecture, component specifications, systematic design, slide generation.
14 
15## When to Use
16 
17- Design token creation
18- Component state definitions
19- CSS variable systems
20- Spacing/typography scales
21- Design-to-code handoff
22- Tailwind theme configuration
23- **Slide/presentation generation**
24 
25## Token Architecture
26 
27Load: `references/token-architecture.md`
28 
29### Three-Layer Structure
30 
31```
32Primitive (raw values)
33       ↓
34Semantic (purpose aliases)
35       ↓
36Component (component-specific)
37```
38 
39**Example:**
40```css
41/* Primitive */
42--color-blue-600: #2563EB;
43 
44/* Semantic */
45--color-primary: var(--color-blue-600);
46 
47/* Component */
48--button-bg: var(--color-primary);
49```
50 
51## Quick Start
52 
53**Generate tokens:**
54```bash
55node scripts/generate-tokens.cjs --config tokens.json -o tokens.css
56```
57 
58**Validate usage:**
59```bash
60node scripts/validate-tokens.cjs --dir src/
61```
62 
63## References
64 
65| Topic | File |
66|-------|------|
67| Token Architecture | `references/token-architecture.md` |
68| Primitive Tokens | `references/primitive-tokens.md` |
69| Semantic Tokens | `references/semantic-tokens.md` |
70| Component Tokens | `references/component-tokens.md` |
71| Component Specs | `references/component-specs.md` |
72| States & Variants | `references/states-and-variants.md` |
73| Tailwind Integration | `references/tailwind-integration.md` |
74 
75## Component Spec Pattern
76 
77| Property | Default | Hover | Active | Disabled |
78|----------|---------|-------|--------|----------|
79| Background | primary | primary-dark | primary-darker | muted |
80| Text | white | white | white | muted-fg |
81| Border | none | none | none | muted-border |
82| Shadow | sm | md | none | none |
83 
84## Scripts
85 
86| Script | Purpose |
87|--------|---------|
88| `generate-tokens.cjs` | Generate CSS from JSON token config |
89| `validate-tokens.cjs` | Check for hardcoded values in code |
90| `search-slides.py` | BM25 search + contextual recommendations |
91| `slide-token-validator.py` | Validate slide HTML for token compliance |
92| `fetch-background.py` | Fetch images from Pexels/Unsplash |
93 
94## Templates
95 
96| Template | Purpose |
97|----------|---------|
98| `design-tokens-starter.json` | Starter JSON with three-layer structure |
99 
100## Integration
101 
102**With brand:** Extract primitives from brand colors/typography
103**With ui-styling:** Component tokens → Tailwind config
104 
105**Skill Dependencies:** brand, ui-styling
106**Primary Agents:** ui-ux-designer, frontend-developer
107 
108## Slide System
109 
110Brand-compliant presentations using design tokens + Chart.js + contextual decision system.
111 
112### Source of Truth
113 
114| File | Purpose |
115|------|---------|
116| `docs/brand-guidelines.md` | Brand identity, voice, colors |
117| `assets/design-tokens.json` | Token definitions (primitive→semantic→component) |
118| `assets/design-tokens.css` | CSS variables (import in slides) |
119| `assets/css/slide-animations.css` | CSS animation library |
120 
121### Slide Search (BM25)
122 
123```bash
124# Basic search (auto-detect domain)
125python scripts/search-slides.py "investor pitch"
126 
127# Domain-specific search
128python scripts/search-slides.py "problem agitation" -d copy
129python scripts/search-slides.py "revenue growth" -d chart
130 
131# Contextual search (Premium System)
132python scripts/search-slides.py "problem slide" --context --position 2 --total 9
133python scripts/search-slides.py "cta" --context --position 9 --prev-emotion frustration
134```
135 
136### Decision System CSVs
137 
138| File | Purpose |
139|------|---------|
140| `data/slide-strategies.csv` | 15 deck structures + emotion arcs + sparkline beats |
141| `data/slide-layouts.csv` | 25 layouts + component variants + animations |
142| `data/slide-layout-logic.csv` | Goal → Layout + break_pattern flag |
143| `data/slide-typography.csv` | Content type → Typography scale |
144| `data/slide-color-logic.csv` | Emotion → Color treatment |
145| `data/slide-backgrounds.csv` | Slide type → Image category (Pexels/Unsplash) |
146| `data/slide-copy.csv` | 25 copywriting formulas (PAS, AIDA, FAB) |
147| `data/slide-charts.csv` | 25 chart types with Chart.js config |
148 
149### Contextual Decision Flow
150 
151```
1521. Parse goal/context
153        ↓
1542. Search slide-strategies.csv → Get strategy + emotion beats
155        ↓
1563. For each slide:
157   a. Query slide-layout-logic.csv → layout + break_pattern
158   b. Query slide-typography.csv → type scale
159   c. Query slide-color-logic.csv → color treatment
160   d. Query slide-backgrounds.csv → image if needed
161   e. Apply animation class from slide-animations.css
162        ↓
1634. Generate HTML with design tokens
164        ↓
1655. Validate with slide-token-validator.py
166```
167 
168### Pattern Breaking (Duarte Sparkline)
169 
170Premium decks alternate between emotions for engagement:
171```
172"What Is" (frustration) ↔ "What Could Be" (hope)
173```
174 
175System calculates pattern breaks at 1/3 and 2/3 positions.
176 
177### Slide Requirements
178 
179**ALL slides MUST:**
1801. Import `assets/design-tokens.css` - single source of truth
1812. Use CSS variables: `var(--color-primary)`, `var(--slide-bg)`, etc.
1823. Use Chart.js for charts (NOT CSS-only bars)
1834. Include navigation (keyboard arrows, click, progress bar)
1845. Center align content
1856. Focus on persuasion/conversion
186 
187### Chart.js Integration
188 
189```html
190<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.umd.min.js"></script>
191 
192<canvas id="revenueChart"></canvas>
193<script>
194new Chart(document.getElementById('revenueChart'), {
195    type: 'line',
196    data: {
197        labels: ['Sep', 'Oct', 'Nov', 'Dec'],
198        datasets: [{
199            data: [5, 12, 28, 45],
200            borderColor: '#FF6B6B',  // Use brand coral
201            backgroundColor: 'rgba(255, 107, 107, 0.1)',
202            fill: true,
203            tension: 0.4
204        }]
205    }
206});
207</script>
208```
209 
210### Token Compliance
211 
212```css
213/* CORRECT - uses token */
214background: var(--slide-bg);
215color: var(--color-primary);
216font-family: var(--typography-font-heading);
217 
218/* WRONG - hardcoded */
219background: #0D0D0D;
220color: #FF6B6B;
221font-family: 'Space Grotesk';
222```
223 
224### Reference Implementation
225 
226Working example with all features:
227```
228assets/designs/slides/claudekit-pitch-251223.html
229```
230 
231### Command
232 
233```bash
234/slides:create "10-slide investor pitch for ClaudeKit Marketing"
235```
236 
237## Best Practices
238 
2391. Never use raw hex in components - always reference tokens
2402. Semantic layer enables theme switching (light/dark)
2413. Component tokens enable per-component customization
2424. Use HSL format for opacity control
2435. Document every token's purpose
2446. **Slides must import design-tokens.css and use var() exclusively**
245