Stylebook CLI

Outputs & Build

Understanding the output folder and build process

Production

Outputs & Build Process

The Stylebook generates assets through a two-stage pipeline: generate produces intermediate outputs, and build assembles final packages.

Output Directory

The output/ directory contains all generated intermediates. It is gitignored and must be regenerated from source.

output/
├── brand.json           # Complete brand data context
├── data/                # Domain data exports
│   ├── logo.json
│   ├── color.json
│   └── ...
├── logo/                # Logo domain outputs
│   ├── variants/        # Generated SVG variants
│   ├── png/             # Rasterized PNG files
│   ├── webp/            # Rasterized WebP files
│   ├── jpg/             # Rasterized JPG files
│   └── ico/             # ICO favicon files
├── color/               # Color domain outputs
│   ├── palette.json     # All colors with computed values
│   └── by_palette.json  # Colors grouped by palette
└── avatars/             # Avatar domain outputs
    ├── humans/          # Generated human avatars
    │   └── {subject}/   # Per-subject directory
    └── agents/          # Generated agent avatars
        └── {agent}/     # Per-agent directory

Why Gitignore Output?

  1. Reproducibility: All outputs can be regenerated from brand/
  2. Size: Rasterized images would bloat the repository
  3. Source of truth: brand/ is canonical; output/ is derived
  4. CI/CD: Build pipelines should generate fresh outputs

Generate Commands

The generate command processes brand data into outputs:

# Generate specific domain
stylebook generate logo            # Logo variants + rasterization
stylebook generate color           # Color palettes
stylebook generate avatars humans  # Human avatars
stylebook generate avatars agents  # Agent avatars

Logo Generation

Transforms the master SVG into variants and rasterizes them:

  1. Parse variants.yaml for variant definitions
  2. Apply transforms to master SVG (delete, set, replace)
  3. Save SVG variants to output/logo/variants/
  4. Rasterize according to rasterize.yaml specs
  5. Export PNG, WebP, JPG, ICO formats

Color Generation

Computes full palettes from OKLCH primitives:

  1. Parse base.yaml for color primitives
  2. Generate shades (50-950) for each hue step
  3. Compute OKLCH, sRGB, hex values
  4. Apply semantic tokens from semantic.yaml
  5. Export to output/color/palette.json

Avatar Generation

Creates AI-stylized avatars from source photos:

  1. Scan originals/ for subject photos
  2. Group by subject (name.surname pattern)
  3. Load prompt template for style
  4. Call AI model (OpenAI or Gemini)
  5. Save to output/avatars/{type}/{subject}/

Build Commands

The build command assembles final packages:

# Build brand.json only
stylebook build data

# Build packages only (assumes generate was run)
stylebook build packages

# Preview changes without executing
stylebook build packages --dry-run

# Verbose output showing each operation
stylebook build packages --verbose

Build Pipeline Order

The build process executes in a strict order:

1. File operations (files.yaml)
   ├── clean: Remove stale files from packages/
   ├── copy: Copy assets from output/ to packages/
   └── rename: Rename files in packages/

2. Template rendering
   └── Render *.j2 templates to packages/

3. Static file copy
   └── Copy non-template files from templates/

brand.json

The build data command generates output/brand.json, a complete snapshot of all brand data used as template context:

{
  "brand": {
    "name": "Ontopix",
    "version": "1.2.0"
  },
  "logo": { ... },
  "color": { ... },
  "typography": { ... },
  "principles": { ... },
  "avatars": { ... }
}

Templates receive this as the brand context variable.

File Operations

The templates/files.yaml configuration controls file operations during build. Three phases execute in order: clean → copy → rename.

Phase 1: Clean

Remove stale files before copying fresh ones:

clean:
  - path: "layers/nuxt-assets-logos/public/logo"
  - path: "content"

Phase 2: Copy

Copy files from output/ to packages/:

copy:
  - source: "data/*.json"
    target: "content/data"
  - source: "logo/**"
    target: "layers/nuxt-assets-logos/public/logo"
    recursive: true
  - source: "logo/ico/favicon-grey-favicon.ico"
    target: "layers/nuxt-layer-ui/public"
    as: "favicon.ico"  # Rename on copy

Phase 3: Rename

Rename files in packages/ after copying:

rename:
  - in: "layers/nuxt-assets-logos/public/logo"
    pattern: "logo-(.+)\\.svg"
    to: "$1.svg"  # Capture groups supported

Taskfile Integration

Common operations are exposed through Taskfile:

task build           # Full pipeline
task build:data      # Generate brand.json
task build:packages  # Export to packages/
task generate        # Generate all domains
task generate:logo   # Generate logo assets
task generate:color  # Generate color palette
task clean           # Remove output/ and packages/
task info            # Show domain information

Domains

Understanding the domain-based brand data structure

Packages

Generated artifacts and Nuxt layers