245 lines
6.7 KiB
Markdown
245 lines
6.7 KiB
Markdown
---
|
|
name: ckm:design-system
|
|
description: 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.
|
|
argument-hint: "[component or token]"
|
|
license: MIT
|
|
metadata:
|
|
author: claudekit
|
|
version: "1.0.0"
|
|
---
|
|
|
|
# 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:**
|
|
```css
|
|
/* Primitive */
|
|
--color-blue-600: #2563EB;
|
|
|
|
/* Semantic */
|
|
--color-primary: var(--color-blue-600);
|
|
|
|
/* Component */
|
|
--button-bg: var(--color-primary);
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
**Generate tokens:**
|
|
```bash
|
|
node scripts/generate-tokens.cjs --config tokens.json -o tokens.css
|
|
```
|
|
|
|
**Validate usage:**
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```html
|
|
<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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```bash
|
|
/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**
|