Stylebook CLI

Stylebook is a Python CLI tool that transforms structured brand data into production-ready artifacts. It maintains a single source of truth in the brand/ directory and generates consumable outputs for multiple platforms.

Concept

The Stylebook CLI follows a data-driven generation philosophy:

1. Brand data is maintained as structured YAML files in brand/
2. Processors transform this data into intermediate outputs in output/
3. Templates render final artifacts to packages/ for consumption

This separation ensures:

• Brand definitions remain human-readable and version-controlled
• Generated assets are always reproducible from source
• Multiple output formats share the same source of truth

Lifecycle

The complete workflow follows four stages:

┌─────────┐    ┌──────────┐    ┌─────────┐    ┌─────────┐
│  EDIT   │ →  │ GENERATE │ →  │  BUILD  │ →  │  SHIP   │
└─────────┘    └──────────┘    └─────────┘    └─────────┘
   brand/         output/        packages/      publish

1. Edit

Modify brand definitions in brand/:

• Update color primitives in brand/color/base.yaml
• Add logo variants in brand/logo/variants.yaml
• Define typography scales in brand/typography/typography.yaml
• Configure avatar generation in brand/avatars/config.yaml

2. Generate

Process brand data into intermediate outputs:

stylebook generate logo            # Generate logo variants + rasterize
stylebook generate color           # Generate color palettes
stylebook generate avatars humans  # Generate human avatars
stylebook generate avatars agents  # Generate AI agent avatars

Generated files land in output/ with domain-specific structure.

3. Build

Assemble packages from templates and generated data:

stylebook build data         # Generate brand.json only
stylebook build packages     # Render templates to packages/
stylebook build packages -v  # Verbose output showing each operation
stylebook build packages -n  # Preview changes without executing

This renders Jinja2 templates using brand.json as context.

4. Ship

Deploy packages to consumers:

• Nuxt layers → consumed via extends in Nuxt apps
• Content → consumed by docs.ontopix.dev
• Brand JSON → consumed by tooling and automation

Quick Reference

Configuration

Stylebook uses standard Python tooling:

• uv for dependency management
• Taskfile for task orchestration
• pyproject.toml for project configuration

# Install dependencies
uv sync

# Use via uv
uv run stylebook --help

# Or activate virtualenv
source .venv/bin/activate
stylebook --help