Brand guidelines to shadcn theme: map decisions to tokens and DESIGN.md

Brand guidelines often mix approved rules, examples, suggestions, old material, and unanswered questions. A theme file can't distinguish those categories. Before mapping anything, identify the source by name and version, record who approved it, and state which products, surfaces, modes, locales, and platforms it governs.

Generated CSS variables are downstream output. Component compatibility doesn't make them authoritative. If a generated value conflicts with the current approved guideline, the conflict remains open until an authorized owner resolves it.

• Source identity and version: the exact guideline, kit, asset release, or decision record.
• Approval state: approved, conditional, superseded, or unresolved.
• Scope: covered products, surfaces, modes, locales, and platforms.
• Decision owner: the role allowed to approve or change the brand decision.
• Implementation owner: the role responsible for the shadcn mapping.
• Acceptance owner: the role that can accept, revise, or block the result.
• Exclusions: behaviors and surfaces the source does not govern.
• Proof limit: what the source establishes and what still requires project evidence.

Shadcn themes describe roles, not loose palettes. Components consume names such as background, foreground, primary, muted, border, input, and ring. Surface roles commonly have corresponding foreground roles. The theme also covers chart and sidebar roles, while radius contributes to the wider visual system.

Instead of asking which brand swatch should replace each default swatch, ask what relationship the source intends for each interface role. A primary action needs a surface and readable content. A muted region needs a background treatment and a foreground hierarchy. A focus ring must remain visible against the components and neighboring colors where it appears.

• Base surfaces: background and foreground.
• Contained surfaces: card with card foreground, and popover with popover foreground.
• Actions and supporting treatments: primary, secondary, muted, and accent with their required foreground relationships.
• Consequential actions: destructive treatment and readable content.
• Structure and controls: border, input, and ring.
• Data visualization: chart roles used by the project's real charts.
• Navigation shells: sidebar surface, foreground, actions, accents, borders, and focus treatment.
• Shape and type: radius and the project's typography mappings.
• Modes: an explicit light and dark value, or a documented decision that a role is outside the accepted scope.

Use one row per governing decision, rather than one row per hex value. Keep the source wording, semantic interpretation, mode inputs, destination artifact, conflicts, owner, and consumer check. Uncertainty then becomes visible before implementation begins.

source_version,source_decision,semantic_role,light_input,dark_input,shadcn_destination,non_token_destination,conflict,status,owner,verification_case
"Brand guide 4.2","Primary action uses approved brand yellow","primary / primary-foreground","approved value","unresolved","theme variables","button contract","Dark foreground pair missing","blocked","Brand owner","Primary button in light and dark"
"Brand guide 4.2","Technical strings use mono","technical text","n/a","n/a","font mapping if supported","DESIGN.md + code component contract","None","mapped","Design-system owner","Code sample and identifier cell"
"Brand guide 4.2","Avoid decorative shadows","elevation policy","n/a","n/a","none","DESIGN.md + component contracts","Existing card shadow conflicts","revise","Component owner","Card and popover"
"Brand guide 4.2","Charts use approved sequence","chart roles","roles supplied","roles supplied","chart-1 through chart-5","chart usage guidance","Series-to-role policy missing","unresolved","Data-viz owner","Five-series chart in both modes"

A blocked row is useful. It explains why the conversion can't proceed without turning an assumption into a shared decision. Keep blocked and unresolved rows beside completed mappings so they don't disappear during export.

Start with relationships that recur across components. Background and foreground define the base reading surface. Card and popover define contained layers. Primary and secondary express action hierarchy. Muted and accent support lower-emphasis content, selection, or emphasis according to the approved system. Border, input, and ring handle structure and interaction.

1. 1

   Name the intended role

   Describe what the color does in the interface. Avoid labels such as green or brand yellow when the decision is really success, primary action, muted text, or focus.

2. 2

   Record the light pair

   Map the surface and intended foreground together. Check them in the consumers that will use them rather than approving either value alone.

3. 3

   Record the dark pair separately

   Don't derive dark mode by mechanically inverting the palette unless the approved source authorizes that transformation.

4. 4

   Add structural and interaction roles

   Map borders, inputs, and focus rings deliberately. A page can look branded while forms and keyboard focus retain unrelated defaults.

5. 5

   Map charts and sidebars only with policy

   Chart colors don't decide series order, overlap, or status meaning. Sidebar colors don't define navigation states. Route those rules to their owners.

Brand guidelines rarely stop at color. They may define typography, density, rounding, layout rhythm, imagery, motifs, shadows, and prohibitions. Forcing everything into theme variables either loses the rule or creates variables that no component reliably consumes.

Typography often spans several destinations. The approved family and role belong in the source record. Reusable family mappings may enter the theme or Tailwind layer, while weight, size, tracking, and hierarchy guidance can belong in DESIGN.md. A data table may need a component rule for numeric treatment. Font delivery remains an implementation concern.

Spacing follows the same rule. A shared scale can be reusable, while page gutters, dense table rows, responsive transitions, and section pacing may belong in layout or component contracts. Keep shadows and motifs in guidance or components when their correct use depends on context.

The approved guideline may disagree with an old theme, a component default, a screenshot, or a local override. Set the precedence before editing so the nearest piece of code doesn't win by convenience.

1. The current approved source contract governs the brand decision within its stated scope.
2. A documented, approved exception may override that decision only for its named consumer, condition, and review period.
3. The mapped shadcn theme and DESIGN.md implement the source; they do not outrank it.
4. Component defaults apply where the source and component contract permit them.
5. Local overrides are evidence of project behavior, not automatic authority.
6. If approved sources conflict and no precedence exists, block the affected mapping and assign an owner.

Ambient Sage v1 is a public example of the inputs a conversion can start from. Its page lists 28 semantic tokens across light and dark modes, Plus Jakarta Sans for body and heading roles, JetBrains Mono for technical strings, a compact product-oriented type scale, spacing and visual guidance, DESIGN.md, and shadcn delivery. Those facts establish the available upstream kit.

For a real conversion, several fields remain open until someone inspects the consuming repository: installed artifact version, CSS destination, theme selector, font delivery, component variants, local overrides, rendered light mode, rendered dark mode, keyboard focus, charts, and accessibility findings. Mark them unexecuted, not passed.

Keep the source record, mapped output, and project mapping identifiable after installation. Record the source version, exported artifact identity, destination files, application route, and transformations. A later reviewer should be able to tell whether the project is current without reverse-engineering its CSS.

1. 1

   Approve the crosswalk

   Review mappings and unresolved rows before changing the project. A valid export can still encode an unauthorized decision.

2. 2

   Apply the theme through the project's supported route

   Use the route appropriate to the current project and shadcn setup. Record what was added, changed, or generated. Consult the official shadcn documentation for current mechanics.

3. 3

   Place DESIGN.md where the intended agent can read it

   State which file is authoritative for design guidance and how it relates to tokens and component contracts.

4. 4

   Record component and application mappings

   Identify wrappers, aliases, theme selectors, chart configuration, font loading, and other project-specific connections.

5. 5

   List local exceptions

   Give every deliberate override a consumer, rationale, owner, and review condition. An unexplained override remains a mismatch.

Installation proves that the artifacts were delivered. It doesn't prove that components resolve them, that local styles leave them visible, or that users receive the intended result. Write the expected behavior before observing the interface, then record what actually happened.

consumer,condition,expected_source,expected_behavior,observed,disposition,owner
"Primary navigation","light and dark","background, foreground, accent, ring","Current item and keyboard focus remain distinguishable","UNEXECUTED","open","UI owner"
"Sign-up form","default, focus, error, disabled","input, border, ring plus input contract","Boundaries and states remain distinguishable","UNEXECUTED","open","Forms owner"
"Delete dialog","light and dark","destructive roles plus application policy","Action is clear and confirmation follows policy","UNEXECUTED","open","Workflow owner"
"Five-series chart","light and dark","chart roles plus chart policy","Series remain distinguishable under recorded content","UNEXECUTED","open","Data-viz owner"
"Settings table","desktop and narrow viewport","type roles, spacing, border","Labels, values, and technical strings use their assigned roles","UNEXECUTED","open","Settings owner"

• Navigation: default, current, hover, and keyboard-focus states.
• Form: label, placeholder, entered text, focus, validation error, and disabled control.
• Consequential action: trigger, confirmation surface, destructive action, cancellation, and resulting message.
• Chart: the maximum representative series count, labels, grid or axes, tooltip, and both modes.
• Sidebar: base surface, selected item, accent treatment, separator, and focus.
• Typography: heading, body, label, technical string, numeric data, and a narrow layout.
• Mode transition: base page, elevated surface, overlay, form, chart, and navigation shell after switching themes.

When a component looks wrong, resist patching the visible element first. Trace the decision from its authority to the rendered result, then stop at the earliest layer where expected and observed evidence disagree.

1. 1

   Source ambiguity

   The approved guide doesn't define the role, mode, state, or precedence. Return the decision to the authorized brand owner.

2. 2

   Transformation failure

   The mapped or generated artifact doesn't preserve the approved decision. Correct the mapping or generation step and regenerate affected output.

3. 3

   Project mapping failure

   The project points to a stale file, wrong selector, wrong alias, missing font, or unintended theme source. Correct the project connection.

4. 4

   Component-contract failure

   The component lacks the required variant or state, or owns an independent decision the shared theme cannot express. Fix or clarify the component contract.

5. 5

   Local override

   A page, wrapper, utility, or inline value masks the shared mapping. Remove it only if unauthorized, or record it as a bounded approved exception.

6. 6

   Rendered-observation failure

   The intended artifacts and mappings are present, but the named condition still fails. Investigate the actual browser, content, interaction, mode, and environment.

This order protects shared decisions from symptom fixes. Changing primary because one button has a local override could repaint unrelated actions and leave the original override in place. Finding the first divergence sends the correction to the owner who can fix it at the right scope.

Don't approve the whole theme because one page looks right. Complete one important row from approved source to rendered consumer, including both modes and the states that matter. If it passes, apply the method to the next shared role. If it fails, revise the first divergent layer before adding more mappings.

• Theming - shadcn/ui: The official documentation defines shadcn's semantic token convention, theme roles, paired background and foreground values, radius scale, custom-token route, and light and dark theme structure.
• DESIGN.md for shadcn/ui Themes: Brand Guidelines AI Agents Can Follow: This article distinguishes CSS variables that style components from DESIGN.md guidance covering typography, layout, spacing, taste, and agent composition.
• How to use this kit - Documentation - Obra shadcn/ui Figma kit: The guide treats a shadcn kit as the start of a system and identifies color, theme, typography, border radius, spacing, and shadow collections as customization surfaces.
• Docs - Shadcn Theme Generator: The documentation separates theme editing and preview from exporting or applying a theme to a new or existing project.
• Shadcn UI Best Practices for 2026: The article recommends an early token layer, product-specific abstractions, accessible component behavior, and documentation of component decisions.
• Ambient Sage Design Kit: The public Ambient Sage v1 page documents a free kit with 28 semantic light and dark tokens, Plus Jakarta Sans, JetBrains Mono, DESIGN.md, and shadcn delivery routes.
• Brand guidelines to Tailwind CSS: map rules into code without losing context: This related guide distinguishes approved sources, generated artifacts, project mappings, local exceptions, and rendered evidence.
• Brand guidelines for SaaS product UI: map brand rules into states and components: This related guide assigns portable identity intent to brand guidance, reusable roles and behavior to the design system, and mappings, exceptions, and observations to the product.