When to use which
colour, on what.
Colour chapter names the tokens. This chapter names where they go. The Polaris bridge translates Shopify's colour roles into ours; the decision tree resolves the three questions that drift most; the by-element lookup is the table designers and Claude both reach for first.
Polaris speaks role. The brand speaks colour. The translation goes one way.
The admin app inherits Polaris semantics (Critical, Warning, Success, Highlight, Subdued) but renders them in BetterReviews tokens. The mapping is one-way: Polaris role → brand token, never the reverse. Shopify green, Shopify red, and Shopify blue do not appear in the brand under any circumstances, including in error states.
| Polaris role | Polaris colour | BetterReviews token | Why |
|---|---|---|---|
| Primary action | #008060 green | bg-clay · paper text · pill | Primary = go. Clay fill (#CC6633), paper text, 999px pill. The only brand element that uses a saturated clay-family fill. If it’s a fill, it’s the positive primary. |
| Critical (errors) | #D72C0D red | paper · 1.5px burnt-clay border · filled octagon icon | Critical = stop. Never a fill · a fill is reserved for the positive primary action. Critical reads as paper ground + a heavier 1.5px burnt-clay (#7A3216) outline + a filled warning-octagon-fill icon. The fill lives in the icon, never the chrome. |
| Warning | #FFC453 yellow | paper · 1px clay hairline · outline triangle icon | Warning = review. Paper ground, 1px clay hairline (lighter than Critical), burnt-clay text, outline warning-triangle icon. Reads as a quiet note. |
| Success (state) | #00A881 green | moss chip | The reserved-moss rule: moss for product success only, never marketing. Never the Shopify green. |
| Highlight (info) | #0095F2 blue | peacock soft chip | Peacock is the cool accent slot. Bordered, not filled, when used outside its drenched band. |
| Subdued text | #6D7175 cool grey | paper-text-3 · stone | The no-cold-neutral rule. The brand's muted text trends warm-earth, not cool-grey. |
| Page background | #F6F6F7 cool | paper · Cloud Dancer | Cloud Dancer is the canonical paper. The Polaris cool-grey ground belongs to a different brand. |
| Body text | #202223 near-black | ink · Midnight | Midnight is the canonical ink. Black is banned; Polaris's near-black has the wrong undertone. |
| AI-generated content | none (Polaris has no AI role) | viola hairline + text | Viola is the brand's AI accent. Reserved for evidence (cited sentences, generated summaries), never for affordances (sparkle buttons, AI badges). See § VII. |
Implementation note. Polaris's React components accept colour roles by name, not by hex. The admin prototype overrides the role tokens in tailwind.config.js so semantic Polaris classes (`bg-critical`, `text-success`) resolve to BetterReviews colours. Never reach for Polaris hex literally.
Midnight (#0B1018) is deliberately not pure #000. On OLED panels, true black causes adjacent-pixel smearing on motion and crushes faint borders. Our ink stays at ~3% lift to keep the hairline scale legible while still reading as black on every other surface.
When the admin embeds in Shopify's Polaris chrome, keep Paper + Ink + Clay but adopt Polaris spacing and shape tokens. Inside Slack OAuth, partner connectors, or third-party iframes: dial back to a hairline mark + Clay accent only.
Three questions, resolved.
These three drift the most. Memorise the answers; the rest follows.
text-clay (#CC6633) · the canonical Terracotta
text-gold (#9E4615) · the AA-safe clayDeep variant. Same brand colour, different L\* for fine text.
bg-clay with paper text. Never bg-gold; clayDeep on a fill loses the warm-peach feel.
border: 1px solid peacock with bg-peacock-bg (the soft tint) and text-peacock. Used for "Cited" status only.
Thirty-four elements, named.
Sorted by surface (Page · Type · Buttons · Fields · Cards · Chips · Tables · Nav · Feedback). Find the row, read the token.
| Element | Token | Note |
|---|---|---|
| PAGE | ||
| Page background | bg-paper · #F0EEE6 | Cloud Dancer. The default ground for every product surface. |
| Hero / anchor section | bg-ink · #0B1018 | Midnight. Marketing only; admin keeps paper. |
| Drenched band | bg-peacock · #1E6B73 | Edge-to-edge only. The Refusals strip. |
| TYPE | ||
| Display headline · h1 | text-ink | Solid Midnight. Never clay at display size. |
| Section head · h2 / h3 | text-ink | Same. Hierarchy from size, not colour. |
| Body | text-paper-text-2 (88% ink) | A notch off pure ink for reading comfort. |
| Meta / caption | text-paper-text-3 (72% ink) | Smallcaps chrome, tabular numerals, datestamps. |
| Inactive / breadcrumb | text-paper-text-4 (56% ink) | Lowest legal opacity on body type. |
| Inline accent (display) | text-clay | ≥ 18px or ≥ 14px bold only. ≤10% per screen. |
| Inline accent (body / link) | text-gold (#9E4615) | The AA-safe clayDeep variant for small text. |
| BUTTONS | ||
| Primary CTA | bg-clay text-paper | The only primary fill. Pill, 999px radius. |
| Primary hover | bg-clay-warm (#D87543) | The single legal use of clay-warm. |
| Secondary CTA | bg-paper text-ink border-ink | Hairline pill. Same shape, different weight. |
| Tertiary / text-only | text-ink + underline-on-hover (clay) | No background. Hover paints clay underline. |
| Destructive | bg-paper text-clay border-clay | Clay border, clay text, paper ground. Warning icon required. |
| FIELDS | ||
| Resting underline | border-paper-line (#C8C0AE) | No box. Hairline under the input. |
| Focus underline + ring | border-clay + 2px clay outline at 3px offset | The brand's only sharp colour ring. |
| Placeholder text | text-paper-text-3 | Never the same colour as the typed value. |
| Error underline + message | border-clay + clay text + warning icon | Colour alone is not enough; icon disambiguates. |
| CARDS | ||
| Default card ground | bg-paper-2 + border-rule | Hairline first; reach for shadow only when truly floating. |
| Hover | + shadow-lift | No transform. Just-perceptible elevation. |
| Selected / active | bg-paper-3 + clay 1px border | The border, not the fill, communicates selection. |
| CHIPS | ||
| Approved | bg-moss-soft text-moss | Reserved-moss rule. Product only. |
| Needs attention | bg-clay-soft text-clay | Inherits primary accent; reads as soft warning. |
| Cited | bg-peacock-bg text-peacock border-peacock | Bordered, not filled. The only peacock-outside-band exception. |
| Pending | bg-paper-2 text-paper-text-3 | Inert. No status colour. |
| TABLES | ||
| Row separator | border-rule · 1px hairline | No zebra striping. Hairline is enough. |
| Header | bg-paper-2 text-paper-text-3 | Smallcaps, tracked, sticky on scroll. |
| Selected row | bg-paper-3 + clay 1px left edge | The only legal use of a coloured left edge. |
| NAV | ||
| Side-link resting | text-paper-text-2 | Ink at 88%. Reads as available, not loud. |
| Side-link active | text-ink + clay 1px left edge | Selected uses the same affordance as table rows. |
| FEEDBACK | ||
| Toast · success | moss icon + ink text | Icon carries the colour; copy stays ink. |
| Toast · attention | clay icon + ink text | Same pattern. Severity is in the copy. |
| Toast · progress | peacock icon + ink text | Single peacock-outside-band exception, paired with an icon. |
| Empty state | paper-text-3 icon + ink h3 + body | No colour required. Empty is information. |
| AI | ||
| AI suggestion (draft reply, keyword prompt) | bg-clay-soft + sparkle icon | Action-shaped. The user accepts or rewrites. Lives next to clay because it’s an invitation to act. |
| AI evidence (cited quote, generated summary) | border-viola text-viola bg-paper | Evidence-shaped. The user reads, doesn’t act. Viola hairline + viola text on paper; never viola fill. |
| Citation source label | text-viola smallcaps | “CITED BY CHATGPT · PERPLEXITY” · the engine that quoted the sentence. |
| Background AI work (indexing, scoring) | no colour | The engine is invisible by default. Surface only when the user needs to act on it. |
The matrix. Seven states. Six elements.
paper text
ink text
paper text
The cells marked "·" mean the state does not apply to that element. Every interactive element must implement every applicable state. Missing a state is a defect, not an omission.
Six application failures the audit script catches.
text-clay on small text.
text-clay on a 13px caption fails AA (3.6:1). Use text-gold. The audit script greps for the pattern text-(sm|xs|\[1[0-3]px\]) alongside text-clay and flags every hit.
Hard-coded clay hex.
Literal #CC6633 outside tailwind.config.js or the token file. When the brand updates a shade, hard-coded hex strands the component on the old colour. Always reach for the Tailwind utility.
Polaris green leaking through.
Anywhere a Polaris primary-action component renders without the token override. #008060 shows up in screenshots when Tailwind's --p-color-bg-fill-brand override is missing. The audit catches it at the CSS layer.
Gradient text.
Any bg-clip-text text-transparent with a gradient fill. The brand uses solid colour. The .text-gradient-gold class is kept for back-compat but resolves to a solid clayDeep fill.
Side-stripes.
border-l-2 or larger on a card with a coloured border is banned (with the single exception of the 1px clay edge on selected rows). Use a full hairline border or none.
#fff / #000 literals.
Pure white and pure black are banned everywhere. The audit greps for #fff, #000, bg-white, text-white, bg-black, text-black. Always Paper or Ink.
Viola is for evidence, not affordances.
Viola (#515299) is reserved for AI-generated content the user reads as evidence: cited sentences, model-generated summaries, engine attribution. It is not the colour of buttons, badges, or sparkle prompts. Those use clay-soft because they ask the user to act. The rule is action vs. evidence; the colours follow.
Thank you, Eleanor. Yes · we formulated the sensitive-skin cleanser exactly for this. The rosemary you noticed is from our own farm in Provence…
Action-shaped. The user decides whether to send. Clay-soft + sparkle invites a choice; it never claims to be the user’s own voice.
“doesn’t strip everything, smells like rosemary not perfume”
Evidence-shaped. The user reads; an engine quoted this customer. Viola hairline + viola attribution names the AI without colouring the customer’s voice itself.
- Citation source labels (“CITED BY CHATGPT”)
- Hairline frame around quoted customer language
- Generated summary block in dashboards
- “Answered for you” evidence cards in the engine view
- Buttons, CTAs, primary actions (those are clay)
- Sparkle icons on suggestions (those are clay-soft)
- Page-level grounds or drenched bands
- Text body, headlines, links
- Decorative chips that don’t name an engine
The principle behind the colour. Generative engines are now the brand’s shelf. Naming them in viola gives the user (the merchant) a clear visual cue when they are looking at an AI’s claim versus their own customer’s words. Conflating the two would be the worst kind of trust failure.
Drop in a screenshot. Read the percentages.
The One Voice rule says clay covers ≤10% of any screen. This widget measures it. Drop a PNG or JPG of any BetterReviews surface into the well below; the page samples its pixels and reports clay coverage, ink coverage, paper coverage, plus any banned hex literals found.
All processing is local. Your image is never uploaded.
Squint at the screen. Count clay pixels.
The One Voice Rule is the simplest application check. If clay covers more than ten percent of the screen, the design is wrong. Squint at it. If the clay area looks like a paragraph, it is too much; if it looks like a punctuation mark, it is right.
The Polaris-bridge, the decision tree, the by-element table, the state matrix, the anti-patterns: all five exist to keep that single test passable without thinking about it. When a screen passes the squint, it has almost certainly satisfied the other four chapters automatically.