Brand Theme Design

Turn a brand into a theme that satisfies the token contract — and say plainly when the brand cannot do what is being asked of it.

The job is not filling in blanks. A brand guide is a superset with different intent: five to eight colors chosen to work on a logo, a billboard, and a product UI. The contract needs a value-structured neutral ramp and exactly one accent. Most of the work is deciding what to leave out.

The other half of the job is arithmetic nobody does by eye. Brand colors routinely fail contrast for body text, because body text is not what they were picked for. Finding that out before shipping is most of this skill's value.

Workflow

1. Ask what exists

Do not guess the input. Ask which of these they have, and take the best one available:

references/extraction.md covers each path, including what to pull beyond color.

2. Extract with provenance

Record where every value came from — "primary #0B5FFF ← brand guide p.4", "body ink #1A1A1A ← computed color on body". The user needs to correct your reading, and they cannot correct what they cannot trace.

Capture typography and border character too. A theme that changes only color is not a theme.

3. Map to roles — the judgment step

This is where the skill earns its keep, and it is mostly subtraction. The rules, in full, are in references/mapping.md. The four that decide most outcomes:

• The brand's primary is usually not --accent. It is more often the ink, or a heading color. --accent marks the one or two things a reader should look at first; a color that appears on every surface cannot do that job.
• Neutrals must stay close in value. --paper, --surface, --surface-muted sit within a narrow luminance band. That value structure is what makes a document read as a document rather than as a UI.
• The leftover brand colors become nothing. Not a categorical chart palette — chart-design rejects exactly that.
• Brand success/error map to the status tokens, but re-tuned. Values chosen against a white app background usually fail on this system's surfaces.

4. Audit — do not skip and do not eyeball

python3 scripts/audit_theme.py path/to/theme.css

It checks token completeness, every contrast pair at its correct threshold, the one-accent rule, the accent's hue distance from the status colors and from the other themes, and the dark-theme print rule. Non-zero exit on failure.

When contrast fails, do not quietly darken the brand color and move on. Say what failed and offer the choice — references/mapping.md has the three honest remedies in preference order. A brand color that cannot carry body text is a fact about the brand, and the user is entitled to know it.

5. Preview it beside the others

Add the theme as a panel in templates/themes.html, build, and show them the result:

python3 scripts/build_document.py templates/themes.html --theme <brand> --out /tmp/themes.html

Seeing it next to editorial-coral, executive-navy, field-notes, and console-violet answers "does this look like a member of the system" faster than any description.

Then print one real document with it, per references/verification.md. If the theme is dark, the print step is not optional — see below.

6. Ship it

Where the file goes depends on where you are:

• Working inside the document-design-system repo → core/themes/<brand>.css, then run scripts/validate_repository.py and the test suite.
• The plugin is installed and you are in someone else's project → write it into their project. The plugin directory is read-only and is replaced on update, so a theme written there is silently lost.

Check which situation you are in before writing. If unsure, ask.

Non-negotiables

Everything in core/tokens.md applies. The ones a brand most often pushes against:

• One accent. A brand with six colors still gets one. This is the rule most likely to be argued with, and the one that most determines whether documents read clearly.
• All 22 tokens defined. A partially themed document looks like a bug.
• Status colors are semantic, not a palette to fill with brand secondaries.
• A dark brand needs its own @media print block. core/print.css flattens surfaces to white but deliberately leaves the ink ramp alone, so a dark theme without this prints near-white on white. console-violet is the worked example.
• Font fallbacks are mandatory. Brand fonts are frequently licensed for web use, unavailable, or both.

When the brand does not fit

Sometimes the honest answer is that the brand cannot be applied as-is. Say so, and name the specific conflict:

• "Your brand blue is 3.1:1 on white. It can be the accent and carry headings at 24px and up, but it cannot be body text. Three options…"
• "The guide specifies six colors of equal weight. This system gives one of them the accent role and treats the rest as neutrals — which one should lead?"
• "Your brand font is not licensed for web embedding. The nearest metric-compatible fallback is X, which will shift line lengths by about 2%."

That is more useful than a theme that technically renders and quietly fails its readers.

Before delivering

• Every value traceable to a source the user can check.
• audit_theme.py passes with no errors.
• Any warnings shown to the user, not silently accepted.
• One accent; leftover brand colors are not wired in anywhere.
• Typography and border character differ, not just color.
• Previewed beside the shipped themes.
• Printed a real document; dark themes have a print block.
• Written to the right place for the context.

Paths in this skill

core/…, scripts/… and templates/… are relative to this skill's directory — the folder that contains this SKILL.md — not to your working directory. Each skill carries its own copy, so it works however it was installed. Prefix them with that directory:

python3 "<skill-dir>/scripts/audit_theme.py" theme.css

scripts/validate_repository.py exists only in the document-design-system repository and is not part of the skill.

Reference files

• references/extraction.md — per-input extraction, and what to capture beyond color.
• references/mapping.md — brand palette to semantic roles, the contrast remedies, and a worked example.
• references/verification.md — the audit, grayscale, print, and preview steps in order.