tmj-90/brand

Establish or audit the brand

A factory that ships UI without a brand ships templates. This skill gives the product a specific visual and verbal identity — or audits and extends the one it has — and writes it down in a form delivery agents can consume: BRAND.md plus tokens. It owns identity (direction, palette, type pairing, voice). The token structure belongs to the design-system skill; surface execution to the frontend-design skill.

Depth	Reference
Palette tiers, oklch tokens, contrast, type pairing and fluid scale	references/color-and-typography.md
Voice spectrums, traits, messaging hierarchy, consistency checklist	references/voice-and-messaging.md

Steps

1. Detect. Call search_lore for brand, positioning, voice and design ADRs. In the repo look for BRAND.md, DESIGN.md, token files (*.tokens.json, tokens.css, theme.ts), a :root block of custom properties, logo assets, and marketing copy. Read the product's README and the ticket for audience and purpose. Decide: does a brand exist?

2. Brand exists → audit and extend in its idiom. Do not replace it with your taste.

   • Score it against the required qualities (step 4) and the banned list below; name each gap with the file and value.
   • Measure every text/background pair the brand uses, in every theme, against WCAG contrast (4.5:1 body, 3:1 large text and UI) — compute the ratio; oklch lightness is not a contrast ratio. A brand colour that fails as text gets a darker text-safe variant, not a waiver.
   • Fill gaps in the existing direction: hover/active steps, a missing surface tier, a dark variant, a text-safe accent, missing semantic roles.

3. No brand → commit to one direction and write why it fits this product and audience: editorial/magazine, Swiss/International, neo-brutalism, bento, glassmorphism with real depth, light or dark luxury, retro-futurism. "Clean minimal" is not a direction; dark mode is chosen for the users, not by habit. Then define:

   • Palette as oklch tokens with a stated job per colour: surfaces (at least two tiers), text (primary, muted), accent, and the semantic roles success / warning / danger / info — each with a text-safe variant where the fill colour fails as text.
   • Type pairing — display + text families with a reason (and mono if the product shows code or data), a clamp() fluid scale, and a loading plan: self-hosted, subset, one critical weight preloaded, metric-matched fallback.
   • Voice — audience, the one-line promise, 3–5 voice traits each with a "we say / we don't say" pair, and how voice shifts in errors and empty states.

4. Check the required qualities. The brand must let delivered UI show at least four of the ten qualities listed in the frontend-design skill (scale hierarchy, spacing rhythm, depth, typographic character, semantic colour, designed states, composition, atmosphere, clarifying motion, data-viz in the system). Name the four-plus in BRAND.md.

5. Write the artifacts. BRAND.md: direction and rationale, palette table (token, value, job, contrast result), type pairing and scale, voice, qualities delivered, open questions. When the work is visual, a token file in the repo's format (DTCG JSON or CSS custom properties — see the design-system skill), for example:

   :root {
     --color-surface: oklch(98% 0.01 95);
     --color-text: oklch(22% 0.02 265);
     --color-accent: oklch(64% 0.19 28); /* fill only; text uses --color-accent-text */
     --color-accent-text: oklch(50% 0.19 28);
     --text-display: clamp(2.5rem, 1rem + 6vw, 6rem);
     --text-base: clamp(1rem, 0.94rem + 0.3vw, 1.125rem);
     --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
   }
   

6. Flag, don't invent, unknown strategy. If positioning or audience is genuinely undecided and the ticket does not settle it, do not fabricate one. As a delivery skill, mark_ticket_blocked with the specific question; as a lore seed, suggest_lore the brand with the open questions named.

7. Land it. As a delivery skill (you are on the ticket's worktree branch — verify with git branch --show-current), commit, record per-AC evidence with the record-evidence skill (the BRAND.md diff, contrast table, qualities list), then stop; the runner submits for review. As a lore seed, suggest_lore the brand; it stays a suggestion until a human ratifies it.

Banned (an audit must catch these)

• Default card grids with uniform spacing and no hierarchy.
• The centred headline + gradient-blob hero with a generic CTA.
• Unmodified library/Tailwind/shadcn defaults passed off as finished design.
• Identical radius, spacing and shadow on every component.
• Grey-on-white with one decorative accent colour.
• Default font stacks with no stated reason; more than two families without a reason.
• An accent colour used for body-size text when it fails 4.5:1.
• Reflexive dark mode chosen by habit rather than fit.

Done when

BRAND.md states one direction with its rationale; every palette pair has a measured contrast result that passes in every theme; the type pairing, scale and loading plan are defined; voice has traits with examples; four or more required qualities are named; open strategic questions are listed rather than guessed; tokens exist in the repo's format.

Rules

• Commit to a direction and state why; never "clean minimal".
• Tokens, not literals, so delivery agents reuse them.
• Extend an existing brand in its idiom; never overwrite it with preference.
• Motion tokens are for transform/opacity; never bake layout-bound animation into the system.
• Unknown strategy is a named open question, never an invented answer.