Stylebook CLI
Domains
Understanding the domain-based brand data structure
Production
The brand system is organized into domains—logical groupings of related brand assets.
Each domain has its own directory in brand/, dedicated processors, and structured outputs.
Domain Overview
| Domain | Directory | Purpose |
|---|---|---|
| Logo | brand/logo/ | Logo variants, transforms, rasterization |
| Color | brand/color/ | Color primitives, palettes, semantic tokens |
| Typography | brand/typography/ | Font families, scales, line heights |
| Principles | brand/principles/ | Voice, tone, writing guidelines |
| Theme | brand/theme/ | Component defaults, color mode overrides |
| Avatars | brand/avatars/ | AI-generated avatars for team and agents |
Brand Data Structure
Each domain follows a consistent directory pattern:
brand/
├── metadata.yaml # Root brand metadata
├── {domain}/
│ ├── metadata.yaml # Domain metadata and documentation
│ ├── {config}.yaml # Domain-specific configuration
│ └── {assets}/ # Source assets (if applicable)
Root Metadata
The brand/metadata.yaml file defines top-level brand information:
brand:
name: Ontopix
description: AI that understands your business before transforming your customer service
website: https://ontopix.ai
version: 1.2.0
Domain Metadata
Each domain's metadata.yaml contains:
- title: Human-readable domain name
- icon: Icon identifier for documentation
- version: Domain-specific version
- description: Brief purpose description
- doc: Rich documentation content for generated pages
Logo Domain
Manages logo variants through composable transforms applied to a master SVG.
brand/logo/
├── metadata.yaml # Logo system documentation
├── master/logo.svg # The single source SVG
├── variants.yaml # Variant definitions with transforms
├── rasterize.yaml # Output size and format specs
├── backgrounds.yaml # Background color definitions
└── groups.yaml # Variant groupings for documentation
Key concepts:
- Variants define transformations (delete elements, change colors)
- Extends allows composing transforms from multiple variants
- Rasterize specifies output sizes and formats per variant
- Variants marked
internal: trueare building blocks, not outputs
Color Domain
Generates perceptually uniform color palettes from OKLCH primitives.
brand/color/
├── metadata.yaml # Color system documentation
├── base.yaml # Color primitives and palettes
├── semantic.yaml # Semantic token mappings
└── reference/ # Reference palettes (Tailwind, etc.)
Key concepts:
- OKLCH color space ensures perceptual uniformity
- Palettes define hue families (brand, surface)
- Hue steps are named colors within each palette
- Shades are lightness variations (50-950)
- Semantic tokens map purpose to colors (primary, secondary)
Typography Domain
Defines font families, scales, and typographic properties.
brand/typography/
├── metadata.yaml # Typography documentation
├── fonts.yaml # Font family definitions
└── typography.yaml # Scales, line heights, spacing
Key concepts:
- Font families define stacks with fallbacks
- Scales map named sizes to pixel values
- Line heights and letter spacing for readability
Principles Domain
Documents brand voice, tone, and writing guidelines.
brand/principles/
├── metadata.yaml # Principles documentation
├── voice.yaml # Brand voice characteristics
└── writing.yaml # Writing style guidelines
Key concepts:
- Voice defines personality traits and communication style
- Writing guidelines provide practical authoring rules
Avatars Domain
Generates AI-powered stylized avatars from source photos.
brand/avatars/
├── metadata.yaml # Avatars documentation
├── config.yaml # Generation configuration
├── agents.yaml # AI agent definitions
├── originals/ # Source photos
└── prompts/ # AI prompt templates
├── humans/ # Human avatar prompts
└── agents/ # Agent avatar prompts
Key concepts:
- Subjects are identified by filename pattern (
name.surname.N.ext) - Multi-reference uses multiple photos for accuracy
- Prompts define the artistic style for generation
- Supports OpenAI and Google Gemini models
Domain Processing
All domains follow a standardized processing pipeline:
1. Load metadata → metadata.yaml
2. Load config → all YAML files (except metadata)
3. Process config → generate computed data
4. Generate outputs → create files in output/{domain}/
5. Parse outputs → build file tree structure
6. Join to JSON → include in brand.json
The result is a unified brand.json containing all domain data:
{
"brand": { ... }, // Root metadata
"logo": {
"metadata": { ... }, // From metadata.yaml
"config": { ... }, // Merged from all config files
"data": { ... }, // Processed/computed data
"generated": { ... }, // Generation results
"outputs": { ... } // File tree of generated assets
},
"color": { ... },
"typography": { ... },
"principles": { ... },
"avatars": { ... }
}
Viewing Domain Info
Use the info command to inspect domain state:
stylebook info # All domains summary
stylebook info logo # Logo variants and outputs
stylebook info color # Color palettes and tokens
stylebook info avatars # Avatar subjects and status