Gmira Palette

Palette

Color is decided at page scale, from a named material, and verified in measured numbers.

Load ../gmira/references/DOCTRINE.md first. Section 3.2 is the floor this skill enforces; Law 1 is the reason the last section exists.

The premise

Color commits at page scale: fields that own whole regions, not accents scattered over a neutral ground. The single most common failure is not an ugly hue, it is a palette that was never committed to: one saturated color assigned to --primary, spent on a button and a link underline, with everything else neutral. That page is Restrained pretending to be Committed, and it reads as a default because it is one.

The second most common failure is deriving the hue from the category. Automotive gets red, finance gets blue, sustainability gets green, AI gets violet. Hue comes from the material world named in the direction contract, never from a category association.

Step 1: pick a strategy, then pick colors

Mode gates which are open:

Committed is a measurement, not an intention

Screenshot the built page full height, then count.

// node, sharp. share of the rendered surface owned by the committed color.
import sharp from "sharp"
const ACCENT = [0xc1, 0x46, 0x2a]                     // sampled from the built page, not from the token
const { data, info } = await sharp("full.png").removeAlpha()
  .raw().toBuffer({ resolveWithObject: true })
let hit = 0
for (let i = 0; i < data.length; i += 3) {
  const d = Math.max(Math.abs(data[i] - ACCENT[0]),
                     Math.abs(data[i + 1] - ACCENT[1]),
                     Math.abs(data[i + 2] - ACCENT[2]))
  if (d < 48) hit++
}
console.log((100 * hit / (info.width * info.height)).toFixed(1) + "%")

Under 30% with a Committed strategy declared means the strategy was declared and not executed. Fix it by giving the color a region (a full-bleed band, the footer, the entire spec column, every alternating row, the whole first viewport), not by adding more small accents.

INCORRECT   --primary: the brand color, used on buttons, links, and one icon. 4% coverage.
CORRECT     the plate color owns the section bands, the part-number column, the active
            filter chips, and the full-bleed footer. 38% coverage, measured from a screenshot.

Step 2: dark or light comes from the scene, never the category

Write one sentence of physical scene from the brief's SCENE block and let it force the answer. Do not pick dark because the product is technical. Do not pick light because the product is retail.

INCORRECT   dark, because the product is a developer tool and developer tools are dark.
CORRECT     the scene says a workshop foreman reads it from three metres under
            fluorescent tubes at 07:00. Light, with the figures at 7:1. The category
            never entered the decision.

If both themes ship, design the dark surface explicitly. Do not invert the light theme mechanically. Elevation in dark comes from lighter surfaces, not from shadows, and the accent usually needs its chroma reduced and its lightness raised to hold the same perceived weight.

A world may legitimately have no dark mode. A paper world inverted is not a dark mode, it is a broken paper world. If the answer is "this world has one light state", ship one and say so in the brief.

Step 3: derive the palette from the material world

Five steps. The check at the end is the one that matters.

1. Read OWN-WORLD from the direction contract. No contract means no palette. Stop and run gmira-direction.
2. List six actual materials from that world, each written as what it physically is, not as a color name. "Uncoated newsprint, aged, warm" not "off-white".
3. Sample each into OKLCH. Physical materials are duller than screen colors. A 1970s spot-plate red lands near chroma 0.185, not 0.28. Keeping screen chroma is how a material world turns back into a default palette.
4. Assign roles from the world's own logic. Ground from the substrate. Ink from the mark. Accent from the second plate or the signal element. Rules and separators from the accent, tinted, never from gray.
5. Delete anything that did not come from step 2.

The trace check: every token names the material it came from, in a comment. A token that cannot be traced came from the default palette and has to go.

INCORRECT   the vertical is automotive, so red: --primary: oklch(0.58 0.24 27)
CORRECT     the world is a 1970s parts catalogue and its second ink is a spot vermilion
            printed on uncoated stock: oklch(0.552 0.185 34). Duller and warmer than any
            screen red, because ink on absorbent paper is. The token comment names it.

Worked example: a 1970s Porsche parts catalogue

The direction contract says: monospace part numbers, hairline rules, photographs on a neutral card, no rounded corners anywhere. The materials, in order:

Strategy: Committed. The plate owns the section bands, the part-number column, active states, and the full-bleed footer. Measured coverage on the built page: 38%.

Rules are derived, not invented:

--rule: color-mix(in oklch, var(--plate) 24%, var(--stock));   /* the plate at a 24% tint */
--line: color-mix(in oklab, var(--rule) 64%, var(--stock));    /* softer than the border, see gmira-typeset */

Contrast, measured on the built page, not calculated from the token:

That last row is the rule in doctrine 3.2 made concrete: on colored surfaces, secondary text is tinted from that hue or from the foreground. It is never gray, and the mix ratio is measured, not guessed.

INCORRECT   <div class="bg-plate"><p class="text-muted-foreground">Bestellnummer</p></div>
CORRECT     <div class="bg-plate"><p class="text-plate-ink/[0.84]">Bestellnummer</p></div>
            then measure it, because opacity over a saturated ground rarely lands where you expect.

Step 4: wire it

Two blocks. Primitives carry values and comments. The semantic block carries only assignments. No new color value ever appears in the semantic block.

/* app/globals.css */
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

:root {
  /* --- the material world, sampled. every line names its material. --- */
  --stock:      oklch(0.962 0.010 88);   /* uncoated newsprint, aged */
  --stock-2:    oklch(0.928 0.014 86);   /* the same stock under a 6% screen tint */
  --ink:        oklch(0.235 0.014 62);   /* press black on uncoated, with dot gain */
  --ink-2:      oklch(0.470 0.018 66);   /* press black at a 60% tint */
  --plate:      oklch(0.552 0.185 34);   /* the second ink: signal vermilion */
  --plate-ink:  oklch(0.978 0.012 60);   /* stock knocked out of the plate */
  --diagram:    oklch(0.470 0.075 205);  /* exploded-view callout ink */
  --rule:       color-mix(in oklch, var(--plate) 24%, var(--stock));
  --line:       color-mix(in oklab, var(--rule) 64%, var(--stock));

  /* --- shadcn roles. assignments only. --- */
  --background: var(--stock);
  --foreground: var(--ink);
  --card: var(--stock);
  --card-foreground: var(--ink);
  --popover: var(--stock-2);
  --popover-foreground: var(--ink);
  --primary: var(--plate);
  --primary-foreground: var(--plate-ink);
  --secondary: var(--stock-2);
  --secondary-foreground: var(--ink);
  --muted: var(--stock-2);
  --muted-foreground: var(--ink-2);
  --accent: var(--diagram);
  --accent-foreground: var(--plate-ink);
  --destructive: oklch(0.505 0.192 27);  /* the plate hue pushed to a warning register */
  --border: var(--rule);
  --input: var(--rule);
  --ring: var(--plate);
  --radius: 0rem;                        /* the contract says no rounded corners anywhere */
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-border: var(--border);
  --color-ring: var(--ring);
  --color-line: var(--line);             /* gives bg-line, border-line, text-line */
  --color-plate: var(--plate);
  --color-plate-ink: var(--plate-ink);
}

@theme inline is what makes the roles available as utilities while keeping the runtime values in :root, so a .dark block can remap them without regenerating classes.

Three technique rules that stop palettes from drifting:

• Prefer explicit colors over chains of translucent overlays. bg-black/5 over bg-muted over an image makes contrast context-dependent and unmeasurable. Two stacked alphas is the limit.
• When building an OKLCH ramp, vary lightness and reduce chroma near white and black. Holding high chroma at extreme lightness to keep the math uniform produces the neon step that everyone can see is wrong and nobody can name.
• Theme changes remap semantic roles, they never rewrite primitives. That is the reason for the two-block split.

Step 5: measure contrast from computed styles

Eyeballing fails on exactly the pairs that matter: mid-tone on mid-tone, and anything on a saturated ground. Run this in the console at each of the five verify viewports, or through page.evaluate in Playwright.

const ctxLum = (c) => { const [r, g, b] = c.map(v => { v /= 255
  return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 })
  return 0.2126 * r + 0.7152 * g + 0.0722 * b }
const parse = (s) => (s.match(/[\d.]+/g) || []).slice(0, 3).map(Number)
const bgOf = (el) => { for (let n = el; n; n = n.parentElement) {
    const c = getComputedStyle(n).backgroundColor
    if (c && !/rgba?\(0,\s*0,\s*0,\s*0\)|transparent/.test(c)) return parse(c) }
  return [255, 255, 255] }

const fails = []
document.querySelectorAll("body *").forEach(el => {
  if (![...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim())) return
  const cs = getComputedStyle(el)
  const px = parseFloat(cs.fontSize), w = parseInt(cs.fontWeight) || 400
  const large = px >= 24 || (px >= 18.66 && w >= 700)
  const L1 = ctxLum(parse(cs.color)), L2 = ctxLum(bgOf(el))
  const ratio = (Math.max(L1, L2) + 0.05) / (Math.min(L1, L2) + 0.05)
  const floor = large ? 3 : 4.5
  if (ratio < floor) fails.push({ ratio: +ratio.toFixed(2), floor, px,
    text: el.textContent.trim().slice(0, 40) })
})
console.table(fails)

// placeholders do not appear above: they live in a pseudo-element
document.querySelectorAll("input, textarea").forEach(el =>
  console.log(el.name || el.type, getComputedStyle(el, "::placeholder").color))

Floors: body and placeholder 4.5:1, large text 3:1, controls, icons, and focus indicators 3:1. Placeholder text is the one that fails most often, because the default text-muted-foreground on a tinted input rarely survives the second surface.

Also simulate protanopia and deuteranopia once. For data, encode with lightness, shape, label, or pattern as well, so color is never the only code.

Step 6: verify the palette survived the effect layer

Doctrine Law 1. A registry shader sets the palette at layer 2 and then adds prism, iridescence, and a glow at roughly +1.84 per channel before clamp. Prop names say the palette is honored. The pixels say it is white. Verify from rendered pixels, never from props.

// playwright: capture only the effect region, after it settles
await page.waitForTimeout(1200)
await page.screenshot({ path: "hero.png", clip: await page.locator("canvas").boundingBox() })

// node: does the render still live inside the palette?
const { data } = await sharp("hero.png").resize(48, 48, { fit: "fill" })
  .removeAlpha().raw().toBuffer({ resolveWithObject: true })
const lum = (r, g, b) => 0.2126 * r + 0.7152 * g + 0.0722 * b
const chroma = (r, g, b) => Math.max(r, g, b) - Math.min(r, g, b)
let maxL = 0, maxC = 0, sumL = 0, n = 0
for (let i = 0; i < data.length; i += 3) {
  maxL = Math.max(maxL, lum(data[i], data[i + 1], data[i + 2]))
  maxC = Math.max(maxC, chroma(data[i], data[i + 1], data[i + 2]))
  sumL += lum(data[i], data[i + 1], data[i + 2]); n++
}
console.log({ meanL: +(sumL / n).toFixed(1), maxL: +maxL.toFixed(1), maxC: +maxC.toFixed(1) })

Compute the same three numbers for the source hexes you passed the component. Then:

Full repair procedure in gmira-arsenal, step 3a and 3b. A blown-out effect is not a color problem you can fix in the palette; it is a welded constant in the shader.

The bans, and how to grep for them

rg -n "bg-clip-text|text-transparent" src app          # gradient text. emphasis is weight or size.
rg -n "border-l-[2-9]|border-l-\[" src app             # colored left borders above 1px on cards, alerts, callouts
rg -n "text-gray-|text-zinc-|text-neutral-" src app    # check every hit that sits on a colored surface
rg -n "backdrop-blur" src app                          # glass as decoration rather than a specific effect

• No gradient text. Emphasis comes from weight or size.
• Declare elevation once: border or shadow, not both. A 1px border under a wide soft shadow is the ghost card.
• Shadows carry an offset and a soft blur. A zero-offset colored halo is decoration.
• Never gray on a colored surface. Tint from the hue or from the foreground.
• A single accent applied everywhere stops meaning anything. Give it a region and a job.

Checks before this skill is done

• A strategy was named before any color was picked, and the mode allows it
• Committed coverage measured from a full-page screenshot, between 30 and 60%
• Dark versus light traced to the written scene sentence, not to the category
• Every primitive token carries a comment naming the material it came from
• The semantic block contains assignments only, zero new color values
• Contrast run from computed styles at all five viewports, zero rows in the fail table
• ::placeholder colors checked separately and passing 4.5:1
• Secondary text on every colored surface is tinted from that hue, and the ratio was measured
• Zero bg-clip-text hits, zero colored left borders above 1px
• Canvas surfaces sampled from rendered pixels and compared against the source hexes
• Dark theme designed explicitly, or the world declared to have only one state