---
watermark: ORIRO
name: uipm-design-system
provider: ORIRO.ai
copyright: Copyright (c) 2026 ORIRO.ai
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: ORIRO.ai
  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/ORIRO.ai-pitch-251223.html
```

### Command

```bash
/slides:create "10-slide investor pitch for ORIRO.ai"
```

## 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**