Brand guidelines as code: structure authority, outputs, and verification

A conventional brand guide explains how a brand should appear and communicate. Storing it in a repository adds history, review, and distribution, but doesn't make every statement precise enough for software or coding agents. A rule such as "use the accent sparingly" still needs a scope, semantic role, and intended consumer before an implementation can apply it consistently.

A token file solves a different problem. It can hold exact values, but it can't explain every compositional rule, prohibited treatment, asset restriction, or product behavior. A valid export proves that structured data exists. It doesn't prove that the current application loads it, maps it to the intended component property, or renders it correctly.

For every important decision, an operational brand-as-code system can answer five questions: What approved source established it? Which artifact carries it? Which project maps it? Which component or surface consumes it? What observation would show that it worked?

A workable system keeps four layers separate. They may live in one repository and share the same small maintenance team, but they answer different questions. One layer shouldn't inherit authority from another without an explicit rule.

This separation tells you where to fix a mismatch. If an approved accent role is wrong, change the portable decision. If the source is right but the Tailwind output is stale, regenerate the output. If the project maps the right token to the wrong property, fix the mapping. When everything is correct until one component applies a local override, correct the component or record a bounded exception.

Start with the decisions the system must preserve, not the files you want to generate. Record provenance and approval alongside the visual content. Otherwise, an obsolete deck, a current kit, and an experimental screenshot can look equally authoritative to an agent.

• Source identity, revision, approval state, decision owner, implementation owner, scope, and exclusions.
• Semantic light and dark roles, including foreground relationships and interaction roles.
• Typography roles, approved families, available weights, fallbacks, and unresolved loading policy.
• Spacing foundations, layout rules, responsive conditions, density decisions, motifs, and deliberate exceptions.
• Logos, imagery, icons, asset identities, usage restrictions, and replacement rules.
• Component-specific states, application-owned behavior, open conflicts, missing decisions, and retest triggers.

Don't fill a field merely because a framework expects a value. A missing dark-mode decision differs from a dark-mode value intentionally matching light mode. The first is unresolved. Recording that distinction stops a developer, generator, or agent from turning personal preference into apparent brand policy.

This manifest is a control record, not another design-token format. It identifies authority, generated outputs, intended consumers, precedence, and verification. Keep exact reusable values in the appropriate token source instead of duplicating them throughout the record.

manifest_id: brand-system-main
manifest_revision: 1
status: approved

sources:
  strategy:
    id: brand-strategy
    revision: 3
    owner: brand-lead
    governs: [positioning, voice, verbal-exclusions]
  visual_system:
    id: product-visual-system
    revision: 7
    owner: design-system-lead
    governs:
      - semantic-color-roles
      - typography-roles
      - spacing-foundations
      - motifs
      - asset-usage

scope:
  products: [customer-web-app]
  modes: [light, dark]
  locales: [en]
  excluded_surfaces: [transactional-email]

outputs:
  - id: design-guidance
    format: DESIGN.md
    derived_from: [brand-strategy@3, product-visual-system@7]
    identity: pending-build-hash
  - id: portable-tokens
    format: DTCG
    derived_from: [product-visual-system@7]
    identity: pending-build-hash
  - id: web-theme
    format: framework-mapping
    derived_from: [portable-tokens]
    identity: pending-build-hash

consumers:
  - id: customer-web-app
    owner: web-product-team
    expected_outputs: [design-guidance, web-theme]
    representative_cases:
      - primary-action-default-light
      - primary-action-focus-dark
      - data-table-dense-light

precedence:
  - current-approved-source-over-generated-output
  - approved-scoped-exception-within-named-scope
  - unresolved-when-approved-sources-conflict

unresolved:
  - decision: font-loading-policy
    owner: web-platform
    blocks: [typography-acceptance]

verification:
  status: not-run
  first_divergence: unknown
  acceptance_owner: product-design
  retest_triggers:
    - source-revision-change
    - output-identity-change
    - consumer-mapping-change
    - component-contract-change

The output entries need identities because a filename isn't enough. Contents can change while the path stays fixed. Use a version, immutable package identifier, content hash, or another reproducible identity, and record the source revisions that produced it.

An application may consume a generated token export without making that export the place where a person approves the original decision. If a team authors canonical values directly in a token file, place that file under sources with an owner, revision, scope, and approval state.

Don't make every format repeat every fact. A consumer may require duplication, but the direction should be declared. One representation governs the decision; the others are generated, mapped, or reviewed against it.

Consider a primary action. Brand or product strategy may establish its strategic importance. The semantic color relationship belongs in the portable visual system, and DTCG can carry the reusable role. Tailwind or shadcn maps that role into a project. The button contract owns hover, focus, disabled, and loading states, while the application decides whether the action is permitted. A rendered check records what happened in a named state.

Files will drift. Someone will edit generated CSS, a project will retain an old package, or a component will gain an urgent override. Decide what happens before the first conflict. Otherwise, the newest timestamp or loudest stakeholder can become the accidental rule.

1. 1

   Prefer the current approved source

   When an approved decision conflicts with generated output, the source wins. Regenerate or correct the output unless an authorized owner changes the decision.

2. 2

   Honor an approved exception only within its scope

   Name the consumer, decision, reason, owner, and review trigger. The exception must not silently become a portable rule.

3. 3

   Mark conflicts between approved sources unresolved

   If two current approved sources disagree and no precedence exists, stop that mapping and route the conflict to the decision owner.

4. 4

   Reject unsupported inference as authority

   A screenshot, existing component, agent output, or local override reveals behavior. It doesn't settle what the brand requires without owner approval.

5. 5

   Retest when a relevant identity changes

   A source revision, output identity, framework mapping, component contract, or consumer exception can invalidate earlier evidence.

MCP, a CLI, a registry, and direct files determine how a consumer obtains an artifact. They don't decide which brand source is correct. Each route should return or install an identified output derived from an identified source revision.

Hybrid delivery works only when both routes resolve to the same recorded authority and compatible output identities. If a CLI installs revision 7 while an agent retrieves revision 8 through MCP, that convenience has created a precedence problem. Align the versions or declare which route governs the installation.

Ambient Sage is a public Identity Forge kit with a recorded v1 revision. Its published page identifies Plus Jakarta Sans for heading and body roles, JetBrains Mono for the mono role, and semantic color roles across light and dark modes. It also exposes DESIGN.md and installation routes. These published facts make it useful as upstream intake for this method.

source:
  id: identityforge-kit-ambient-sage
  revision: 1
  approval_state: published
  evidence_scope:
    - typography-roles
    - semantic-light-and-dark-structure
    - design-guidance-availability
    - delivery-route-availability

verified_public_facts:
  heading_role: Plus Jakarta Sans
  body_role: Plus Jakarta Sans
  mono_role: JetBrains Mono
  semantic_modes: [light, dark]

outputs_or_routes:
  design_md: available
  cli: available
  registry: available
  mcp: available

consumer:
  id: example-product
  delivery_status: not-checked
  mapping_status: not-checked
  adoption_status: not-checked
  rendered_observation: not-run
  disposition: open

The record doesn't copy protected token values, generated CSS, or private kit content. Nor does it turn available routes into an implementation claim. The consumer fields remain open because no named external product was inspected for this example.

A single status such as "installed" hides the part of the chain most likely to fail. Track available, delivered, mapped, adopted, and observed separately. Each state answers a narrower question and needs different evidence.

Write the expected result before you observe it. Otherwise, a plausible interface can pass merely because it looks polished. Name the consumer, component, variant, state, mode, viewport, content condition, environment, expected role, expected behavior, and observation method.

record_id: customer-web-primary-action-focus-dark
source:
  id: product-visual-system
  revision: 7
  decision: action-primary-focus

artifact:
  expected_id: web-theme
  expected_identity: release-2026-11-05
  delivered_status: pass

project_mapping:
  consumer: customer-web-app
  role: action.primary.focus
  destination: button-focus-style
  mapping_status: pass

adoption:
  component: PrimaryButton
  variant: default
  state: keyboard-focus
  mode: dark
  viewport: desktop
  adoption_status: pending

observation:
  expected: Uses the approved focus role and remains visibly distinct on the button surface.
  method: computed-style-and-rendered-inspection
  result: not-run

first_divergence: unknown
owner: web-product-team
disposition: open
retest_on:
  - source-change
  - theme-output-change
  - button-contract-change
  - dark-mode-policy-change

When a check fails, inspect the chain in order: source decision, artifact identity, project mapping, component contract, approved exceptions, consumer use, and rendered result. The first point where the evidence no longer matches the expectation identifies the layer that owns the correction.

Don't begin by validating every decision across every product. Choose one decision that crosses the important layers, such as a semantic action role, typography role, or spacing rule used by a representative component. Record its source, output, mapping, consumer, and expected observation.

1. 1

   Freeze one source revision

   Identify the approved source, owner, scope, modes, exclusions, and unresolved questions. Don't mix material from several revisions.

2. 2

   Select identified outputs

   Record which DESIGN.md, token package, framework mapping, assets, or agent resource derive from that source.

3. 3

   Map one representative consumer

   Choose a real project and component state that exercises the decision, including the difficult mode or interaction where relevant.

4. 4

   Write the expected result

   State what should happen and how it will be inspected before running the check.

5. 5

   Observe and classify the first divergence

   Record pass, revise, block, or approved exception, and assign the first mismatch to its owning layer.

6. 6

   Expand only after resolving the divergence

   Reuse the working chain for more roles and consumers. Fix authority or precedence problems before generating more outputs.

This method doesn't replace broader brand strategy, generate an identity by itself, rank coding agents, or guarantee adoption. It gives you a reviewable path from an approved decision to a real interface, with a place to preserve uncertainty when evidence is missing.

• AI Brand Suite Brand Code | Upland Strategy: Upland presents brand strategy as identified, versioned documents with dependencies, decision rules, exclusions, and governance, providing a baseline for the strategy authority layer.
• brand-guidelines - Claude Code Skills - BuildWithClaude: The captured skill combines colors, typography, fallbacks, and application instructions in an agent resource, illustrating both the value and limits of an agent-facing artifact.
• Brand Guidelines Generator | Claude Code Skill - MCP Market: The captured workflow moves from source ingestion and guided discovery to a persistent SKILL.md, showing how several inputs can feed an agent-facing output.
• Ambient Sage Design Kit: The public Ambient Sage v1 page identifies its revision, semantic light and dark structure, typography roles, available outputs, and delivery routes used in the bounded example.
• DESIGN.md vs design tokens: choose authority and prevent drift: Identity Forge distinguishes written intent from reusable exact values and component behavior, and recommends assigning authority decision by decision.
• Brand guidelines to Tailwind CSS: map rules into code without losing context: The guide supports routing framework values, runtime CSS, assets, component behavior, guidance, exceptions, and unresolved decisions into separate layers.
• Brand guidelines to shadcn theme: map decisions to tokens and DESIGN.md: The guide supports source-first semantic mapping, explicit precedence, separate treatment of non-color rules, and verification in named consumers.
• Design system MCP server vs CLI: choose the right delivery route: The guide distinguishes design-system authority from MCP and CLI delivery routes and requires downstream artifact, mapping, adoption, and rendered checks.