Quick start
For AI Agents
Machine-readable guide for AI agents building Ontopix-branded UIs
Production
AI Agent Consumption Guide
This page helps AI agents (via MCP or direct brand.json access) make consistent design decisions.
brand.json Structure
The complete brand data is available at output/brand.json and via the Ontopix Docs MCP (stylebook collection).
Top-Level Shape
brand/ # Identity, description, pronunciation, version
identity/ # Mission, vision, tagline, values, messaging (taglines, positioning, pitches)
audience/ # Primary, secondary, geographic, languages
market/ # Category, description, differentiators
products/ # Product list
channels/ # Channel reference data
color/ # Palette + semantic tokens + accessibility
logo/ # Variants, groups, rasterization
typography/ # Fonts, scales, contexts
theme/ # Components, color modes, motion, icons
voice/ # Character, speech, tones, writing-style, writing-contexts, terminology
layout/ # Spacing, grid, breakpoints
avatars/ # Avatar generation config
Key Paths
| Data | Path in brand.json |
|---|---|
| Brand identity | brand.identity |
| Taglines | brand.identity.messaging.taglines |
| Positioning | brand.identity.messaging.positioning |
| Semantic color tokens | brand.color.config.semantic.tokens |
| Color palette (all colors) | brand.color.data.palette.colors |
| Accessibility (WCAG) | brand.color.config.accessibility |
| Font definitions | brand.typography.config.fonts |
| Typography scales | brand.typography.config.scales |
| Typography contexts | brand.typography.config.contexts |
| Logo variants | brand.logo.data.variants |
| Logo groups | brand.logo.config.groups |
| Motion tokens | brand.theme.config.motion |
| Voice character | brand.voice.config.character |
| Voice tones | brand.voice.config.tones |
| Writing style | brand.voice.config.writing-style |
| Writing contexts | brand.voice.config.writing-contexts |
| Terminology | brand.voice.config.terminology |
Decision Algorithms
Selecting a Logo Variant
INPUT: background_type (light|dark), needs_transparency (bool), format (full|square|spinner)
1. format → determines group: full=logo, square=avatar, spinner=spinner
2. background_type → determines arrow: light=black_arrow, dark=white_arrow
3. needs_transparency → determines bg: yes=onlight/ondark, no=onwhite/onblack
4. LOOKUP: brand.logo.data.variants[{group}{bg_variant}].save-as
Selecting a Color Token
INPUT: element_purpose (brand|navigation|action|status)
1. brand decoration → token: brand
2. navigation link → token: navigation
3. primary action (save, submit) → token: primary
4. secondary action (cancel, back) → token: secondary
5. hero CTA → token: prominent
6. success/error/warning/info → matching status token
7. text, borders, backgrounds → token: neutral
Selecting Typography
INPUT: context (web|ui|docs|print|internal|commercial)
1. LOOKUP: brand.typography.config.contexts[context]
2. GET fonts: context.fonts.headings, context.fonts.body, context.fonts.code
3. GET scale: brand.typography.config.scales[context.scale]
4. APPLY rules: context.rules (min sizes, line heights, max widths)
Selecting a Voice Tone
INPUT: context (marketing|docs|ui|error|internal)
1. LOOKUP: brand.voice.config.tones[context]
2. GET adjectives, examples, avoid lists
3. APPLY writing-style rules from brand.voice.config.writing-style
4. CHECK terminology in brand.voice.config.terminology before naming things
Picking a Channel Template
INPUT: deliverable_type
1. one-pager, poster, flyer → channels/printed-media
2. whitepaper, report, RFP, proposal → channels/document
3. pitch deck, conference talk → channels/slide-deck
4. standalone HTML, micro-site → channels/html-artifact
MCP Query Patterns
When consuming via ontopix-docs MCP:
| Decision | Query |
|---|---|
| Which logo to use? | get-page /stylebook/logos/decision-guide |
| Which color token? | get-page /stylebook/colors/usage-guide |
| Contrast requirements? | get-page /stylebook/colors/accessibility |
| Font for context? | get-page /stylebook/typography/fonts |
| Font role mapping? | get-page /stylebook/typography/role-mapping |
| Voice/tone? | get-page /stylebook/voice/tones |
| Writing rules? | get-page /stylebook/voice/writing-style |
| Channel-specific context? | get-page /stylebook/voice/contexts |
| Approved terminology? | get-page /stylebook/voice/terminology |
| Motion/timing tokens? | get-page /stylebook/theme/motion |
| Which channel template? | get-page /stylebook/channels |