Stylebook CLI

Tools

Interactive applications for brand development

Production

Stylebook includes interactive applications for brand development and refinement. These tools help visualize changes before committing to the brand configuration.

Playground

Path: apps/playground/

The playground is a Nuxt 4 dev environment that serves as the primary development tool. It includes:

Showroom — Browse all Nuxt UI components with the Ontopix theme applied
Stylebook — Preview documentation content from packages/content/
Palette Editor — Edit OKLCH color palettes with real-time preview and auto-regeneration
Theme Editor — Edit Nuxt UI component defaults, slot classes, and color mode mappings

Running the Playground

# Via Taskfile
task app:playground

# Or directly
cd apps/playground && pnpm dev

Palette Editor

The palette editor is integrated into the playground at /palette-editor. It provides a full OKLCH color editing experience with automatic pipeline regeneration.

Features

Live preview of all shades across all hue steps
OKLCH controls for lightness, chroma, and hue
Fine-tuning with per-shade, per-step, and per-cell overrides
Hue step management — add, remove, rename, reorder
Auto-regeneration — saving triggers generate color + filtered build pipeline
Vite HMR — color changes reflect in the showroom automatically

How It Works

The editor operates on OKLCH color parameters:

┌─────────────────────────────────────────────────────────┐
│  Base Color (per palette)                               │
│  ├── Lightness (L): 0-100  →  Perceptual brightness     │
│  ├── Chroma (C): 0-0.4     →  Color saturation          │
│  └── Hue (H): 0-360        →  Color angle               │
├─────────────────────────────────────────────────────────┤
│  Shade Deltas (global)                                  │
│  └── Per shade: L and C offsets from base               │
├─────────────────────────────────────────────────────────┤
│  Fine Tuning (per palette)                              │
│  ├── Shade overrides: per-shade L/C adjustments         │
│  ├── Step overrides: per-hue-step H/L/C adjustments     │
│  └── Cell overrides: specific cell adjustments          │
└─────────────────────────────────────────────────────────┘

Editor Workflow

Set base color for each palette (brand, neutral, etc.)
Adjust global shade deltas for consistent progression
Fine-tune individual shades or steps as needed
Click Save — writes to brand/color/base.yaml and triggers pipeline
Vite HMR reflects the updated tokens in the showroom

Interface Components

Component	Purpose
Overview Tab	Full palette preview with all palettes side-by-side
Base Editor	Adjust base OKLCH values per palette
Shades Editor	Modify global shade delta progression
Steps Editor	Add, remove, rename, reorder hue steps
Fine Tuning	Base hue offset, spread, and color wheel
Palette Preview	Color grid with override indicators
Edit Modal	Per-shade, per-step, and per-cell override editing

Architecture

Browser → /palette-editor (Nuxt page)
           │
           ├── useColorConfig() composable (reactive state + palette generation)
           ├── color-math.ts (OKLCH → hex via culori)
           │
           └── Nitro server routes:
               ├── GET  /api/color-config     → reads brand/color/base.yaml
               ├── POST /api/color-config     → writes YAML + triggers pipeline
               └── GET  /api/pipeline-status  → pipeline execution state
                                                  │
                                                  ▼
                               uv run stylebook generate color &&
                               uv run stylebook build data &&
                               uv run stylebook build packages --filter "layers/nuxt-layer-ui/*"
                                                  │
                                                  ▼
                               packages/layers/nuxt-layer-ui/ (Vite detects change → HMR)

Theme Editor

The theme editor is integrated into the playground at /theme-editor. It provides editing of Nuxt UI component defaults, slot classes, and color mode mappings.

Features

Global defaults — Set default color and size for all components (renders to nuxt.config.ts)
Per-component editing — Modify defaultVariants and slots classes (renders to app.config.ts)
Color mode mappings — Configure light/dark shade mappings for semantic colors and UI tokens (renders to ontopix.css)
Auto-regeneration — saving triggers a filtered build pipeline (no generate needed)
Vite HMR — theme changes reflect in the showroom automatically

Editor Workflow

Components tab — Edit global defaults and per-component variants/slots
Color Modes tab — Adjust semantic color shades and UI token overrides
Click Save — writes to brand/theme/components.yaml and brand/theme/color_modes.yaml
Filtered build — only rebuilds nuxt-layer-ui templates (fast)
Vite HMR reflects the updated theme in the showroom

Architecture

Browser → /theme-editor (Nuxt page)
           │
           ├── useThemeConfig() composable (reactive state + dirty tracking)
           │
           └── Nitro server routes:
               ├── GET  /api/theme-components  → reads brand/theme/components.yaml
               ├── POST /api/theme-components  → writes YAML + triggers pipeline
               ├── GET  /api/theme-colormodes  → reads brand/theme/color_modes.yaml
               ├── POST /api/theme-colormodes  → writes YAML + triggers pipeline
               └── GET  /api/pipeline-status   → pipeline execution state
                                                  │
                                                  ▼
                               uv run stylebook build data &&
                               uv run stylebook build packages --filter "layers/nuxt-layer-ui/*"
                                                  │
                                                  ▼
                               packages/layers/nuxt-layer-ui/ (Vite detects change → HMR)

Available Apps

List available applications:

stylebook app list

Running Apps

# Run specific app (starts a dev server)
stylebook app run <app-name>

# Playground (recommended)
task app:playground

Development Tips

Color Design

When working with the palette editor:

Start with the 500 shade as your base—it's the reference point
Ensure sufficient contrast between adjacent shades
Test accessibility with the built-in contrast checker
Compare across palettes using the Overview tab
Save frequently to trigger pipeline and verify in the showroom

OKLCH Guidelines

Property	Typical Range	Notes
Lightness	20-95	50-70 for primary colors
Chroma	0.05-0.35	Higher = more saturated
Hue	0-360	Red=0, Green=120, Blue=240

Surface vs Brand Colors

Brand colors: Higher chroma (0.2-0.35) for vibrancy
Surface colors: Lower chroma (0.05-0.1) for neutrality

Packages

Generated artifacts and Nuxt layers

Data Validation

Schema validation for brand data