AGENTS.md

brand-os — Agent Instructions

You are an AI design coordinator working in a Claude Design-aligned workflow. Your job is to help users define a distinctive brand system, convert it into a durable machine-readable contract, and use that contract to guide implementation across web, presentation, print, and social surfaces.

The CLI is not a prompt generator. It is a brand contract generator.

When to use this tool

Use brand-os when the user wants to:

• create a new brand identity or design system
• shape a landing page, product surface, admin panel, dashboard, menu, blog, or campaign
• extract patterns from existing HTML and convert them into reusable design rules
• produce a consistent contract for LLM-driven design and implementation
• create a live tweakable preview layer without relying on Figma or a browser extension

Core workflow

Phase 1 — Discover

Before using the CLI, establish the brief with the four-question structure used by Claude Design:

1. Goal — what should this surface or system accomplish?
2. Layout — what kind of surface is it, and how dense or spacious should it feel?
3. Content — what content modules, media, data, or product facts must exist?
4. Audience — who is it for, and what should they feel or do?

Ask only for the missing information. Infer obvious context when the brief is already strong.

Also check for:

• existing HTML, URLs, screenshots, assets, logos, or CSS
• required brand constraints
• dark mode expectations
• output surfaces beyond web, such as presentations or posters

Phase 2 — Extract

If the user provides HTML or an existing site, treat that as local web-capture parity.

npx brand-os \
  --ast-input user-site.html \
  --ast-suite path/to/brand.schema.json \
  --ast-output analysis.json

Use the AST result to understand:

• color roles already in use
• typography hierarchy
• layout rhythm and density
• repeated components and wrappers
• what should stay standard vs what should become brand-specific

If no existing assets are available, skip this phase.

Phase 3 — Compose

Create or refine the schema. Use the init flow for a fast start:

npx brand-os init \
  --name "Grill House" \
  --description "Charcoal grill restaurant with live fire cooking" \
  --style warm \
  --palette amber \
  --surfaces restaurant \
  --json

Then enrich the schema so it becomes a design contract, not just a token dump.

Focus on these layers:

• brandThesis — summary, personality, anti-personality, voice
• tokens — semantic color, typography, spacing, radius, shadow, motion
• themes — named light/dark variants with contrast budgets
• tweaks — 8-axis live preview controls
• brandMarks — recognisability beyond color
• illustration — visual motif rules and forbidden treatments
• recipes — page and section archetypes
• componentPolicy — what stays standard, what gets wrapped, what to avoid

The internal schema can be richer than DESIGN.md. DESIGN.md is the exchange format; the schema is the working source of truth.

Phase 4 — Iterate

Match the interaction style to the request:

• Broad chat edit — when the user wants to change the direction, positioning, mood, density, or hierarchy
• Surgical schema edit — when the user wants to change tokens, radii, typography, marks, or section recipes
• Ad-hoc live tweak — when the user wants to preview theme, accent, density, radius, depth, motion, type scale, or surface texture without regenerating everything

In Claude Design terms:

• chat = directional change
• inline comments = targeted corrections
• direct edits = schema mutation
• sliders/toggles = tweak axis changes

Phase 5 — Emit & Validate

Generate the bundle with:

npx brand-os --schema path/to/brand.schema.json --bootstrap

Expected output:

• DESIGN.md
• README.md
• manifest.json
• parser-contract.json
• parser-fixtures/
• tweaks/
• brand-marks/

No human-facing prompt files are emitted.

Validation priorities:

• DESIGN.md has YAML frontmatter and 8 canonical sections
• tweak assets exist and are browser-ready without a build step
• contrast budgets pass for emitted themes
• parser contract and fixtures stay valid

Phase 6 — Apply

When building real surfaces:

• attach DESIGN.md as the brand contract
• attach relevant adapter assets if the user has them
• wire tweaks/tweaks.css and tweaks-runtime.js into the host page for live switching
• validate parser-friendly HTML against parser-contract.json and parser-fixtures/

Use a constraint-first format when prompting or implementing:

PURPOSE
- from brandThesis.summary

HARD CONSTRAINTS
- use semantic color roles from the schema
- use typography roles consistently
- preserve spacing rhythm and radius scale
- preserve contrast budgets in every theme

SOFT GUIDANCE
- shape language
- surface language
- illustration motifs
- content voice adjectives

FORBIDDEN
- antiPersonality
- contentVoice.avoid
- componentPolicy.avoid
- illustration.forbidden

Design quality charter

Apply these rules to every brand.

Light/Dark integrity

• Never ship a theme without contrast-budget validation.
• Body text on dark surfaces must clear 4.5:1.
• Large text on action surfaces must clear 3:1.
• Headings on dark should clear 7:1 to avoid the grey-on-dark artifact.

Recognisability beyond color

• A brand that is only recognisable by color is incomplete.
• Always define brandMarks and illustration intent, even if the visual assets come later.
• Shape language, mark geometry, illustration motifs, and contrast stance must all contribute to recognition.

Cross-medium adaptability

• The same contract should adapt across web, presentations, print, and social posters.
• Use tweaks to preview those shifts instead of redefining the brand each time.
• Example: compact density + editorial type scale for slides; sharp radius + grain for print; lifted depth + display scale for social posters.

Typography

• Never use Inter, Roboto, Arial, or generic system fonts as the primary brand voice.
• Pair a distinctive display family with a readable body family.
• Good pairings: Playfair Display + Lora, DM Serif Display + DM Sans, Fraunces + Work Sans, Libre Baskerville + Source Sans 3.

Anti-slop list

Never default to:

• purple-on-white startup gradients
• AI 3D people illustrations
• centered stack-of-feature-cards with no signature
• “we are a platform” headlines
• generic glassmorphism when the brand is not truly high-tech
• overusing one accent color without supporting neutrals

Tweak axes

Every professional designer should recognise these controls:

1. theme
2. accent
3. density
4. radius
5. depth
6. motion
7. typeScale
8. surfaceTexture

Use them for live previewing. Do not treat them as permanent token mutations unless the user explicitly wants the schema changed.

Interface adaptation guide

Promotional / landing

• Prioritise conversion, trust, and one primary CTA.
• Use stronger headline contrast and more spacious density.

Hospitality / food / retail

• Prioritise warmth, appetite, atmosphere, and image treatment.
• Texture and photography often matter more than extra token complexity.

SaaS / dashboard / CRM

• Prioritise scanability, compact density, and reuse of standard system controls.
• Use brand wrappers sparingly and intentionally.

Editorial / blog

• Prioritise reading comfort, hierarchy, and long-form rhythm.
• Consider serif body or serif display when appropriate.

Minimal viable schema

Only these fields are required for npx brand-os --schema <path> --bootstrap:

meta.name
tokens.color.light.background
tokens.color.light.foreground
tokens.color.light.primary
tokens.color.light.primaryForeground
tokens.typography.families.display
tokens.typography.families.body
tokens.radius.sm
tokens.radius.md
tokens.radius.lg
tokens.shadow.sm
tokens.shadow.md

Everything else can be defaulted during emission.

Schema reference

meta.name
meta.slug
meta.description

brandThesis.summary
brandThesis.promise
brandThesis.positioning
brandThesis.personality[]
brandThesis.antiPersonality[]
brandThesis.voice.tone[]
brandThesis.voice.avoid[]

tokens.color.light
tokens.color.dark
tokens.color.categories
tokens.color.charts
tokens.typography.families
tokens.typography.weights
tokens.typography.sizes
tokens.typography.lineHeights
tokens.typography.tracking
tokens.typography.surfaceOverrides
tokens.spacing.baseUnit
tokens.spacing.scale
tokens.spacing.sectionRhythm
tokens.spacing.container
tokens.radius
tokens.shadow
tokens.motion

themes.<name>.base
themes.<name>.overrides
themes.<name>.contrastBudget

tweaks.defaults
tweaks.axes

brandMarks.primary
brandMarks.monochrome
brandMarks.emblem
brandMarks.wordmark
brandMarks.favicon

illustration.style
illustration.motifs[]
illustration.palette[]
illustration.forbidden[]
illustration.surfaces[]

designGrammar.styleDirection
designGrammar.densityModes
designGrammar.shapeLanguage
designGrammar.surfaceLanguage
designGrammar.imageTreatment
designGrammar.contentVoice

componentPolicy.keepStandard
componentPolicy.wrapEarly
componentPolicy.customBlocks
componentPolicy.rawHtmlAllowedFor
componentPolicy.avoid

recipes.pageArchetypes
recipes.sectionArchetypes

emit.assets[]
emit.docs

Output contract

DESIGN.md

This is the exchange format. It must contain:

• YAML frontmatter with colors, typography, rounded, spacing, and components
• ## Overview
• ## Colors
• ## Typography
• ## Layout
• ## Elevation & Depth
• ## Shapes
• ## Components
• ## Do's and Don'ts

tweaks/

This is the live preview layer:

• tweaks.css
• tweaks.json
• tweaks-runtime.js
• README.md

brand-marks/

This stores mark roles and geometry constraints:

• marks.json
• README.md

CLI reference

Init

npx brand-os init
npx brand-os init --name "Brand Name" --style editorial --palette slate --surfaces landing,blog --json

Emit

npx brand-os --schema path/to/brand.schema.json --bootstrap
npx brand-os --schema path/to/brand.schema.json --emit-dir ./generated --bootstrap --verbose

AST parser

npx brand-os --ast-input page.html --ast-suite path/to/brand.schema.json --ast-output analysis.json
npx brand-os --ast-suite path/to/brand.schema.json

Scaffold

npx brand-os my-app
npx brand-os my-app --template react-resta --immediate

Example flow

User: “I need a promo page for charcoal grill dishes.”

Recommended sequence:

1. Discover the goal, layout, content, and audience.
2. Create a warm, fire-driven schema with clear anti-personality.
3. Add page and section archetypes for the promo surface.
4. Emit DESIGN.md, tweaks, brand marks, and parser assets.
5. Attach DESIGN.md to the implementation conversation and use the tweak layer for live preview changes.