tinted-ui-tokens-skills

Tinted UI Design Principles

Distilled from the essay 《你的UI廉价，错在颜色》. These are the rules the generator enforces. Read this when you need to explain why a token looks the way it does, or when hand-tuning a system the script produced.

The one decision

Cheap-looking UIs use pure neutral colors: #FFFFFF, #000000, #808080. Expensive-looking UIs never do. Every neutral surface carries a few percent of the brand hue. Brand color does not sit on top of the design — it flows through it.

Where the temperature lives (3 core places)

1. Backgrounds & surfaces — mix the brand color into the gray ramp. The background leans toward the brand; cards, borders and muted text lean too. The shift is tiny (2–3%) but it is what separates “designed” from “assembled”.
2. Shadows — never rgba(0,0,0,0.1). A shadow is light absence; it takes the temperature of the surrounding light. Blue brand → blue-violet shadow; warm brand → amber shadow. Keep alpha very low. The 0 0 0 1px hairline border is part of the same shadow system and inherits its temperature.
3. Text hierarchy — primary text is near-black with a hue lean, not #000. Muted text follows the brand’s warm/cool direction, not flat gray. Values still pass WCAG AA at body sizes — temperature is added inside the existing contrast budget, never at the cost of readability. The generator now enforces this automatically: every text-on-surface pair is measured with the WCAG 2.1 relative-luminance formula and, if it falls below AA (4.5:1 normal / 3:1 muted), the text is nudged along its HSL lightness axis until it passes — so readability always wins, and the brand hue-lean is kept wherever lightness does not hit an extreme.

Three extensions (where systems usually break)

1. Semantic colors — error/warning/success must also be nudged toward the brand temperature (about 6–10° on the hue wheel). A red error in a blue product is “correct signal, wrong temperature” — like a fire alarm in a library. Keep it red, just lean it a few degrees. Their subtle backgrounds must lean toward the brand field, not default pink/amber/green.
2. Gradients — both stops must be tinted; never let one end drift to pure white. Direction should match natural light on a surface of that temperature (cool: deep-blue corner → light blue-white center; warm: deep amber bottom → cream top). Mesh gradients: every radial point carries brand hue, base is the tinted --color-bg, never #FFFFFF.
3. Icons & illustration — icon stroke color IS the text token (same stack, not an approximation). Icon container background IS --color-brand-subtle. Illustration shadows are derived from the same token family as UI shadows, so illustration and chrome look lit by one source.

The test

Desaturate the whole interface to grayscale. If hierarchy still holds, the temperature work is correct and invisible. If it collapses, the hue was doing too much structural work — fix the gray ramp first, then re-add temperature.

Three rules, no exceptions

• Never use pure neutral colors. Every neutral gets a hue, even 2%.
• Shadow color matches brand temperature. Pure black shadows belong to no system.
• Every interactive state (hover/focus/active) is tinted with --color-brand-subtle or a slightly more saturated surface — never a flat gray overlay.

Pre-delivery checklist · 交付前验收清单

Run this before you ship a system the generator produced. The generator enforces most of it automatically, but the checklist catches the human steps (wiring, review, edge brands).

• No pure neutrals — grep the output for #FFFFFF, #000000, #808080. None should appear (degenerate black/white/gray brands are the only exception, and even then the generator keeps a brand-lean where a hue exists).
• Contrast — body text vs its surface is ≥ 4.5:1; muted text vs surface is ≥ 3:1; --color-on-brand (text on the brand button) is ≥ 4.5:1 on the brand hue. The generator guarantees this, but re-check after any hand-tune.
• Dark mode — open preview.html, toggle dark, and confirm the topbar title + body text stay legible. Tinting must not wash out in dark.
• Grayscale test — desaturate the rendered UI; hierarchy (background → surface → text → muted) must still read. If it collapses, fix the gray ramp first, then re-add temperature.
• Semantic signal preserved — error stays red, warning amber, success green; the generator only leans them a few degrees toward the brand, never swaps the hue.
• Interactive states tinted — hover/focus/active use --color-brand-subtle or a more saturated surface, not a gray overlay.
• Drop-in sanity — tokens.css :root variables override the framework defaults without a specificity war; no !important needed.
• Format parity — if you emitted --format all, tokens.css, tokens.json (DTCG), tailwind.config.js, and _tokens.scss all exist and carry the same values.

Common mistakes / anti-patterns · 常见错误与反模式

• Pure neutrals “for safety.” Designers sometimes reset a value to #FFF to “be sure it’s clean.” That is exactly the cheap look. Keep the 2–3% hue-lean.
• Over-tinting. tint-strength: strong on an already-saturated brand reads as “themed,” not “designed.” Default normal is right for most products; reserve strong for brand-forward marketing surfaces.
• Trusting the hue for structure. Temperature is a finish, not a hierarchy system. Never let the brand hue carry the contrast budget — lightness does.
• Forgetting dark mode in review. Tinted light themes often look great and then wash out in dark. Always toggle before sign-off.
• Swapping semantic hues “to match brand.” A blue error in a blue product is a wrong signal. Lean, don’t swap.
• Hand-editing a token then skipping the contrast re-check. One nudge can drop a pair below AA. Re-run the generator or re-measure after any manual change.
• Mixing token sources. Don’t patch half the set from one brand color and half from another — pick one brand and regenerate the whole set.

Why this skill exists

The cheap-vs-premium gap is almost never the layout or the font. It is the neutrals. Flat #FFF/#000/#808080 read as “template”; a 2–3% brand hue-lean reads as “someone designed this.” This skill automates that single, high-leverage move — and keeps it accessible while it does.

This site is open source. Improve this page.