@greenharness/greenrack-cli 0.0.0-stage → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/README.md +335 -2
  2. package/agents/design-system-lookup.md +59 -0
  3. package/dist/bin.d.ts +3 -0
  4. package/dist/bin.d.ts.map +1 -0
  5. package/dist/bin.js +145 -0
  6. package/dist/bin.js.map +1 -0
  7. package/dist/catalog.d.ts +13 -0
  8. package/dist/catalog.d.ts.map +1 -0
  9. package/dist/catalog.js +67 -0
  10. package/dist/catalog.js.map +1 -0
  11. package/dist/commands/context.d.ts +17 -0
  12. package/dist/commands/context.d.ts.map +1 -0
  13. package/dist/commands/context.js +110 -0
  14. package/dist/commands/context.js.map +1 -0
  15. package/dist/commands/doctor.d.ts +75 -0
  16. package/dist/commands/doctor.d.ts.map +1 -0
  17. package/dist/commands/doctor.js +1008 -0
  18. package/dist/commands/doctor.js.map +1 -0
  19. package/dist/commands/hook.d.ts +10 -0
  20. package/dist/commands/hook.d.ts.map +1 -0
  21. package/dist/commands/hook.js +323 -0
  22. package/dist/commands/hook.js.map +1 -0
  23. package/dist/commands/list.d.ts +4 -0
  24. package/dist/commands/list.d.ts.map +1 -0
  25. package/dist/commands/list.js +59 -0
  26. package/dist/commands/list.js.map +1 -0
  27. package/dist/commands/lookup.d.ts +13 -0
  28. package/dist/commands/lookup.d.ts.map +1 -0
  29. package/dist/commands/lookup.js +66 -0
  30. package/dist/commands/lookup.js.map +1 -0
  31. package/dist/commands/manifest.d.ts +5 -0
  32. package/dist/commands/manifest.d.ts.map +1 -0
  33. package/dist/commands/manifest.js +33 -0
  34. package/dist/commands/manifest.js.map +1 -0
  35. package/dist/commands/mcp.d.ts +159 -0
  36. package/dist/commands/mcp.d.ts.map +1 -0
  37. package/dist/commands/mcp.js +235 -0
  38. package/dist/commands/mcp.js.map +1 -0
  39. package/dist/commands/mockup.d.ts +80 -0
  40. package/dist/commands/mockup.d.ts.map +1 -0
  41. package/dist/commands/mockup.js +714 -0
  42. package/dist/commands/mockup.js.map +1 -0
  43. package/dist/commands/skill.d.ts +15 -0
  44. package/dist/commands/skill.d.ts.map +1 -0
  45. package/dist/commands/skill.js +398 -0
  46. package/dist/commands/skill.js.map +1 -0
  47. package/dist/disambiguation.d.ts +24 -0
  48. package/dist/disambiguation.d.ts.map +1 -0
  49. package/dist/disambiguation.js +56 -0
  50. package/dist/disambiguation.js.map +1 -0
  51. package/dist/extension-pointer.d.ts +7 -0
  52. package/dist/extension-pointer.d.ts.map +1 -0
  53. package/dist/extension-pointer.js +30 -0
  54. package/dist/extension-pointer.js.map +1 -0
  55. package/dist/format.d.ts +19 -0
  56. package/dist/format.d.ts.map +1 -0
  57. package/dist/format.js +213 -0
  58. package/dist/format.js.map +1 -0
  59. package/dist/hook-script.d.ts +73 -0
  60. package/dist/hook-script.d.ts.map +1 -0
  61. package/dist/hook-script.js +165 -0
  62. package/dist/hook-script.js.map +1 -0
  63. package/dist/index.d.ts +7 -0
  64. package/dist/index.d.ts.map +1 -0
  65. package/dist/index.js +6 -0
  66. package/dist/index.js.map +1 -0
  67. package/dist/legacy-names.d.ts +26 -0
  68. package/dist/legacy-names.d.ts.map +1 -0
  69. package/dist/legacy-names.js +26 -0
  70. package/dist/legacy-names.js.map +1 -0
  71. package/dist/manifest.d.ts +51 -0
  72. package/dist/manifest.d.ts.map +1 -0
  73. package/dist/manifest.js +229 -0
  74. package/dist/manifest.js.map +1 -0
  75. package/dist/registry-types.d.ts +106 -0
  76. package/dist/registry-types.d.ts.map +1 -0
  77. package/dist/registry-types.js +2 -0
  78. package/dist/registry-types.js.map +1 -0
  79. package/dist/registry.d.ts +52 -0
  80. package/dist/registry.d.ts.map +1 -0
  81. package/dist/registry.js +95 -0
  82. package/dist/registry.js.map +1 -0
  83. package/dist/scan.d.ts +19 -0
  84. package/dist/scan.d.ts.map +1 -0
  85. package/dist/scan.js +29 -0
  86. package/dist/scan.js.map +1 -0
  87. package/dist/search.d.ts +16 -0
  88. package/dist/search.d.ts.map +1 -0
  89. package/dist/search.js +75 -0
  90. package/dist/search.js.map +1 -0
  91. package/dist/skill-template.d.ts +24 -0
  92. package/dist/skill-template.d.ts.map +1 -0
  93. package/dist/skill-template.js +140 -0
  94. package/dist/skill-template.js.map +1 -0
  95. package/greenharness.toml +38 -0
  96. package/package.json +76 -3
  97. package/registry.json +12893 -0
  98. package/skills/colors/LICENSE +21 -0
  99. package/skills/colors/NOTICE.md +36 -0
  100. package/skills/colors/SKILL.md +101 -0
  101. package/skills/colors/color-formats.md +90 -0
  102. package/skills/colors/color-usage.md +109 -0
  103. package/skills/colors/contrast.md +70 -0
  104. package/skills/colors/palette-generation.md +108 -0
  105. package/skills/colors/palette-structure.md +72 -0
  106. package/skills/colors/token-naming.md +99 -0
  107. package/skills/greenrack-mockup/SKILL.md +115 -0
  108. package/skills/typography/LICENSE +21 -0
  109. package/skills/typography/NOTICE.md +36 -0
  110. package/skills/typography/SKILL.md +171 -0
  111. package/skills/typography/choosing-fonts.md +53 -0
  112. package/skills/typography/css-cheat-sheet.md +67 -0
  113. package/skills/typography/details-and-accessibility.md +84 -0
  114. package/skills/typography/spacing-and-sizing.md +87 -0
  115. package/skills/typography/variable-fonts-and-opentype.md +100 -0
  116. package/skills/typography/wrapping-and-punctuation.md +23 -0
  117. package/skills/ui/LICENSE +21 -0
  118. package/skills/ui/NOTICE.md +38 -0
  119. package/skills/ui/SKILL.md +141 -0
  120. package/skills/ui/animations.md +170 -0
  121. package/skills/ui/enter-exit.md +157 -0
  122. package/skills/ui/icon-transitions.md +72 -0
  123. package/skills/ui/icons.md +105 -0
  124. package/skills/ui/performance.md +63 -0
  125. package/skills/ui/surfaces.md +166 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jakub Krehel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,36 @@
1
+ # Notice
2
+
3
+ This skill is a fork of `better-colors/` from the repository `jakubkrehel/skills`, at commit `4c66b1fa86e9ab70187b43d7da9b6fdb29f2ef63`, fetched 2026-10-16.
4
+
5
+ Local edits:
6
+
7
+ - Renamed by `scripts/fork-interface-skills.sh` at dotfiles commit `5fbdc4b` (`better-colors` to `colors`).
8
+ - Dropped `agents/openai.yaml`.
9
+ - Added the precedence block after the introduction of `SKILL.md`.
10
+ - Reconciled the clause in `ui/SKILL.md` that limited project tokens, so a project token always wins.
11
+
12
+ Updating: diff upstream from the pinned commit, have a frontier model port the changes over the local edits, then bump the pin.
13
+
14
+ The upstream license (MIT) applies; the text is in `LICENSE`:
15
+
16
+ > MIT License
17
+ >
18
+ > Copyright (c) 2026 Jakub Krehel
19
+ >
20
+ > Permission is hereby granted, free of charge, to any person obtaining a copy
21
+ > of this software and associated documentation files (the "Software"), to deal
22
+ > in the Software without restriction, including without limitation the rights
23
+ > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
24
+ > copies of the Software, and to permit persons to whom the Software is
25
+ > furnished to do so, subject to the following conditions:
26
+ >
27
+ > The above copyright notice and this permission notice shall be included in all
28
+ > copies or substantial portions of the Software.
29
+ >
30
+ > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
31
+ > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
32
+ > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
33
+ > AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
34
+ > LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
35
+ > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
36
+ > SOFTWARE.
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: colors
3
+ description: Helps you build and check a color system for your project. It generates palettes, names semantic tokens, converts between formats and measures contrast.
4
+ ---
5
+
6
+ **Gate.** This skill applies only in a repository whose `package.json` depends on `@greenharness/greenrack-ui`, or on the old `@duro-app/ui` it replaces (a `workspace:` dependency counts). Anywhere else, stop: do not apply it.
7
+
8
+ # Colors
9
+
10
+ This skill builds and audits color systems. It generates ramps, maps their steps to roles and token names, converts notation and measures rendered contrast pairs.
11
+
12
+ A decision of this repository (resolved at its applicable scope with `aval resolve`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal.
13
+
14
+ Where greenrack defines the value, these win: the CLAUDE.md "Color Semantics" table, `packages/tokens/src/tokens/colors.css.ts` and the themes.
15
+
16
+ Never report a contrast value you did not measure, and never estimate a color you could compute. Notation, a tinted neutral and a gradient's interpolation space are project choices, not findings. A broken role mapping, a failing pair and an out-of-gamut step are findings. Perceived lightness throughout means OKLCH `L`, from `0` to `1`.
17
+
18
+ Whether a pair is required to pass belongs to `accessibility`. Surfaces, shadows and icon color belong to `ui`.
19
+
20
+ ## Match the project's color system
21
+
22
+ Reuse the project's tokens and notation. A consistent hex system beats hex with `oklch()` scattered through it.
23
+
24
+ For a new system, `oklch()` is the best default, because its numbers behave the way the ramp rules below describe. Everywhere else, a color library produces the same ramp in the project's own notation ([color-formats.md](color-formats.md)).
25
+
26
+ ## A system is ramps, not colors
27
+
28
+ One neutral ramp, one accent ramp and only the status ramps the product actually renders. A `warning` ramp nothing imports is maintenance for zero pixels. A second accent hue earns its place only when two things must be distinguishable at a glance. Otherwise use more steps of the one accent ramp.
29
+
30
+ ## Every step has a job
31
+
32
+ A ramp is not a gradient to pick from by eye. Each step exists because a role needs it: page background, component hover, border, solid fill, body text. Do not generate a step no role consumes. Both the Tailwind `50`–`950` and Radix `1`–`12` conventions map to those roles ([palette-structure.md](palette-structure.md)).
33
+
34
+ ## Name primitives by hue, semantics by role
35
+
36
+ Primitives name a value (`--blue-600`) and are never applied in a component. Semantic tokens name a job (`--color-text-secondary`), point at a primitive and are the only tier components reference. That seam is what lets a theme repoint colors without touching components ([token-naming.md](token-naming.md)).
37
+
38
+ ## Use a token only in its role
39
+
40
+ Never borrow a token because its value is right today. A separator used as a text color works until borders get lighter, and then the text goes with them. If a role has no token, add the token.
41
+
42
+ ## Hold the hue across the ramp
43
+
44
+ A ramp holds one hue end to end, peaks in vividness mid-ramp and steps more finely at the light end. Build it with a color library, never by eye ([palette-generation.md](palette-generation.md)).
45
+
46
+ ## One color, one meaning
47
+
48
+ Use a color for one purpose across the whole interface, treating anything within `15°` of OKLCH hue as the same color ([color-usage.md](color-usage.md)). Never let color be the only carrier of meaning. Pair it with an icon or a label, a requirement `accessibility` owns.
49
+
50
+ ## Fill exactly one action per view
51
+
52
+ When filled color encodes primary emphasis, one primary action gets it and peers stay neutral. Put the color on the background, not the label. A filled button reads as primary across the room; accent-colored text on a neutral button reads as a link.
53
+
54
+ Keep an established hierarchy that already signals emphasis another way. Several colored backgrounds are fine when they encode distinct states or categories rather than competing as peers.
55
+
56
+ ## Measure the rendered pair, then report
57
+
58
+ Measure a foreground against the background it actually renders on, not the page background. When a pair fails, report the pair, its measured value and the threshold it misses, then leave the colors alone. They are a design decision. Change them only when asked, and remeasure after ([contrast.md](contrast.md)).
59
+
60
+ ## Pick a gradient's interpolation space
61
+
62
+ The space is a look, not a correctness setting. Default to `in oklab`, and reach for `in oklch` when a two-hue gradient goes gray in the middle ([color-usage.md](color-usage.md)).
63
+
64
+ ## Before you finish
65
+
66
+ | Pattern | Fix |
67
+ | --- | --- |
68
+ | A hex, `rgb(` or `oklch(` literal in a component file where a token exists | Reuse or add the role token, in the project's notation |
69
+ | One `oklch(` value in a codebase otherwise written in hex | Write it in the established notation unless a migration is in scope |
70
+ | `var(--blue-600)` or `bg-blue-600` in a component file | Point a semantic token at the primitive and use that |
71
+ | A semantic name containing a hue or a component, as in `--color-blue-button` or `--color-sidebar-gray` | Rename it for its role: `--color-accent-solid`, `--color-bg-surface` |
72
+ | `--color-primary` and `--color-text-primary` both defined | Rename the brand token `accent` |
73
+ | A `border` or `separator` token inside `color:`, or a `text` token inside `background:` | Add a token for the missing role |
74
+ | `hsl(` ramp values that differ only in lightness | Rebuild in OKLCH with a constant hue |
75
+ | `50`–`200` stepping as far apart in OKLCH `L` as mid-ramp steps do | Tighten the light end to about `0.04`–`0.05` per step |
76
+ | One chroma or saturation number copied across every hue's ramp | Use the same proportion of each hue's own maximum |
77
+ | A status hue within `15°` of the accent hue | Move it at least `15°` away, or give the destructive action a distinct treatment |
78
+ | Dark tokens equal to the light ramp in reverse step order | Lower the accent's chroma, widen the dark end and remeasure every pair |
79
+ | Color tokens set under both `prefers-color-scheme` and a `.dark` class | Pick one switching mechanism and use it throughout |
80
+ | A contrast fix that changes hue and leaves lightness | Change lightness, the channel contrast responds to |
81
+ | `prefers-contrast: more` overriding a color for both appearances in one block | Give each appearance its own increased-contrast value |
82
+ | Text on a color with alpha, such as `/50`, `rgba(` or `color-mix(` with `transparent` | Measure the rendered result, or use a solid token |
83
+ | `text-white` on a Tailwind `500` fill | Measure it; white on most `500` hues fails 4.5:1, so move the fill to `600` |
84
+ | `oklch()` chroma beyond sRGB with no sRGB value declared before it | Declare the sRGB value first, then the vivid one inside `@media (color-gamut: p3)` |
85
+
86
+ ## Reporting
87
+
88
+ **Severity.** `HIGH` makes content unreadable or assigns a misleading semantic color. `MEDIUM` is a noticeable theme, token or gamut failure. `LOW` is isolated polish.
89
+
90
+ Three symptoms are `HIGH` on sight whatever the surface, matching `interface`'s escalation triggers. They are body or control text whose rendered pair fails its required ratio, state or meaning carried by color alone and a semantic color used against its meaning.
91
+
92
+ **Verification.** Without a browser: token values, the gamut of every declared color, both theme blocks present and contrast computed from the declared token pair. With one: the background actually rendered behind the text, including opacity and any image beneath it, measured in both light and dark. Report every check you could not run as `Not verified`.
93
+
94
+ **Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
95
+
96
+ | Severity | Location | Before | After | Why |
97
+ | --- | --- | --- | --- | --- |
98
+
99
+ `Location` is `path/to/file:line`. `Why` names the principle and the user impact.
100
+
101
+ End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable color findings" and report verification.
@@ -0,0 +1,90 @@
1
+ # Color formats
2
+
3
+ Which notation to write colors in, how to convert between them and what happens at the edges of a display's gamut. Every other rule in this skill is stated perceptually and holds whatever notation you write.
4
+
5
+ ## Choosing a notation
6
+
7
+ | Notation | Good for | Weakness |
8
+ | --- | --- | --- |
9
+ | Hex | Universal support, compact, what design tools hand you | Opaque. No channel is readable or editable by hand |
10
+ | `rgb()` | Same reach as hex, readable alpha | Channels do not correspond to anything a designer thinks about |
11
+ | `hsl()` | Channels look like design controls | Its lightness is not perceptual and its hue drifts; a ramp built by varying lightness bunches at one end and shifts hue |
12
+ | `oklch()` | Perceptually uniform lightness, stable hue, predictable ramps | Baseline 2023, so very old browser matrices need a fallback |
13
+
14
+ **Match whatever the project already uses.** Notation is not a defect: a project on hex is not doing it wrong.
15
+
16
+ **For a genuinely new color system, `oklch()` is the best default.** Even lightness steps stay even, and a fixed hue stays fixed. See [palette-generation.md](palette-generation.md).
17
+
18
+ ```css
19
+ oklch(L C H) /* lightness 0–1, chroma 0–~0.4, hue 0–360 */
20
+ oklch(L C H / alpha) /* alpha uses a slash, never a comma */
21
+ ```
22
+
23
+ ## Converting
24
+
25
+ Convert when the user asks, when an agreed migration is in scope or when the project is standardizing on a notation and this value is the straggler. Never convert an isolated value in a project that deliberately uses something else and never because this skill happened to load.
26
+
27
+ When conversion is in scope, change the values and nothing else:
28
+
29
+ - Leave CSS keywords alone: `currentColor`, `inherit`, `transparent`, `initial`, `unset`.
30
+ - Leave gradient functions alone. Convert the color stops inside them; do not touch the interpolation method.
31
+ - Leave colors in third-party configs that expect a specific format.
32
+ - Preserve comments and formatting.
33
+
34
+ ```css
35
+ /* Before */
36
+ color: #3b82f6;
37
+ border: 1px solid rgba(0, 0, 0, 0.1);
38
+
39
+ /* After */
40
+ color: oklch(0.623 0.188 259.815);
41
+ border: 1px solid oklch(0 0 0 / 0.1);
42
+ ```
43
+
44
+ Bulk conversion is a migration, not cleanup. It shifts every rendered color by a rounding margin and touches files nobody asked about, so it has to be the task rather than a side effect.
45
+
46
+ ## Gamut
47
+
48
+ Every sRGB color exists in Display P3, but not the reverse. The extra room is only at high chroma and varies by hue. At OKLCH `L` `0.65`, green gains about `0.07` of chroma while blue gains about `0.015`.
49
+
50
+ A color more vivid than its display can render gets gamut-mapped, which in current browsers mostly means clipped. It flattens neighbouring steps into one rendered color, so the top of a ramp can lose its distinctions on an sRGB screen. Maximum vividness varies by hue and lightness. Cyans top out far lower than reds and purples, so a clipping ramp clips at some steps and not others.
51
+
52
+ The fix is to reduce vividness while holding hue and lightness. Generate ramps against sRGB unless the product is display-restricted, and add P3 as an enhancement:
53
+
54
+ ```css
55
+ .success {
56
+ background: #11ad32; /* oklch(0.65 0.2 145), inside sRGB */
57
+ }
58
+
59
+ @media (color-gamut: p3) {
60
+ .success {
61
+ background: oklch(0.65 0.27 145);
62
+ }
63
+ }
64
+ ```
65
+
66
+ Order matters. The sRGB value comes first, so an sRGB screen shows a color you chose rather than one the browser clipped. The P3 rule overrides only where it will render.
67
+
68
+ For browser matrices predating `oklch()` support, the same layering works with `@supports`:
69
+
70
+ ```css
71
+ .accent {
72
+ background: #3b82f6;
73
+ }
74
+
75
+ @supports (color: oklch(0 0 0)) {
76
+ .accent {
77
+ background: oklch(0.62 0.19 259);
78
+ }
79
+ }
80
+ ```
81
+
82
+ Check the project's actual browser matrix before adding this. On a modern baseline it is dead weight.
83
+
84
+ ## Modern CSS worth knowing
85
+
86
+ - **`color-mix()`** derives one color from another, as in `color-mix(in oklab, var(--color-accent-solid) 15%, white)` for a tinted background. Useful for states, but keep generated values out of the token layer, since a mixed color cannot be inspected in a design tool.
87
+ - **Relative color syntax** adjusts one channel of an existing color. `oklch(from var(--color-accent-solid) calc(l - 0.1) c h)` darkens the accent by hand. Powerful and easy to overuse, since a token defined by three chained derivations is unreadable.
88
+ - **`light-dark()`** puts both appearances in one declaration. See [palette-generation.md](palette-generation.md).
89
+
90
+ All three resolve at render time. Compute the resolved value with a color library, or measure the rendered result, before reporting contrast.
@@ -0,0 +1,109 @@
1
+ # Color usage
2
+
3
+ Deploying color once the system exists: meaning, emphasis, gradients and appearance variants. For picking values see [palette-generation.md](palette-generation.md), for naming them [token-naming.md](token-naming.md), for checking pairs [contrast.md](contrast.md).
4
+
5
+ ## One color, one meaning
6
+
7
+ Users read a near-miss in hue as a slightly different shade, not as a different color.
8
+
9
+ ```css
10
+ /* Bad: the accent means both "link" and "decorative heading" */
11
+ a { color: #3b82f6; }
12
+ .section-title { color: #4f8ef7; }
13
+
14
+ /* Good: interactive elements own the accent; headings stay neutral */
15
+ a { color: var(--color-accent-text); }
16
+ .section-title { color: var(--color-text-primary); }
17
+ ```
18
+
19
+ The rule runs both ways. A color must not be *absent* where its meaning occurs. If the accent means interactive, an interactive element rendered neutral is just as misleading.
20
+
21
+ ## Use tokens in their role
22
+
23
+ A value that happens to work in two roles stops working in both at the next theme change.
24
+
25
+ ```css
26
+ /* Bad: separator token repurposed as a text color because it looked right */
27
+ .caption { color: var(--color-border); }
28
+
29
+ /* Bad: text token repurposed as a background */
30
+ .tag { background: var(--color-text-secondary); }
31
+ ```
32
+
33
+ The role inventory in [token-naming.md](token-naming.md) is the list of roles a system needs.
34
+
35
+ ## One colored action per view
36
+
37
+ ```html
38
+ <!-- Good: one filled primary action, neutral secondaries -->
39
+ <button class="bg-accent-solid text-text-on-accent">Save</button>
40
+ <button class="text-text-secondary">Cancel</button>
41
+
42
+ <!-- Bad: every action colored, so nothing is primary -->
43
+ <button class="bg-accent-solid text-text-on-accent">Save</button>
44
+ <button class="bg-accent-solid text-text-on-accent">Duplicate</button>
45
+ <button class="bg-accent-solid text-text-on-accent">Export</button>
46
+ ```
47
+
48
+ Selected states may use the accent on the glyph and label. An active tab or a checked segment is state, not emphasis.
49
+
50
+ ## Gradients
51
+
52
+ **The interpolation space is a look, not a correctness setting.** Three are worth knowing, and the difference between them is most visible in the middle of the gradient:
53
+
54
+ ```css
55
+ /* sRGB: the default and the classic. Midpoint darkens and mutes. */
56
+ background: linear-gradient(#3b82f6, #ec4899);
57
+
58
+ /* oklab: even brightness across the transition. The best default. */
59
+ background: linear-gradient(in oklab, #3b82f6, #ec4899);
60
+
61
+ /* oklch: travels around the hue wheel, staying vivid throughout. */
62
+ background: linear-gradient(in oklch, #3b82f6, #ec4899);
63
+ ```
64
+
65
+ `oklab` and sRGB are **rectangular**, interpolating in a straight line through the color space. `oklch` is **polar**, interpolating the hue angle, so it arcs around the wheel through every hue between the stops. That is why it stays saturated and why it can produce hues nobody asked for. A blue-to-pink gradient routes through purple, which is either the look or a surprise.
66
+
67
+ **The gray dead zone is a rectangular-space problem.** Two hues on opposite sides of the wheel sit either side of the neutral axis. A straight line between them passes near gray, and the middle goes lifeless. Either switch to a polar space, which routes around the axis, or add a third stop between the two and keep the space you have.
68
+
69
+ With a polar space you also control which way it goes around:
70
+
71
+ ```css
72
+ /* The short way round, usually what you want */
73
+ background: linear-gradient(in oklch shorter hue, #3b82f6, #ec4899);
74
+
75
+ /* The long way, sweeps most of the spectrum */
76
+ background: linear-gradient(in oklch longer hue, #3b82f6, #ec4899);
77
+ ```
78
+
79
+ **Banding shows up on large areas.** A gradient spanning a hero with little contrast between its stops steps visibly on 8-bit displays. Widen the contrast, shrink the area or overlay a subtle noise texture.
80
+
81
+ **Keep text off gradients where you can.** Contrast varies continuously across one, so a single measurement does not describe it. Where text must sit on a gradient, measure the worst region rather than the average, or put a scrim behind it.
82
+
83
+ ## Color across cultures
84
+
85
+ Where a color carries meaning in finance, status or alerts, verify the meaning holds in every locale you ship to. Chinese financial UIs show gains in red and losses in green, the reverse of English ones. Where the product ships to such markets, make gain and loss per-locale tokens rather than hardcoded values.
86
+
87
+ ## Light, dark and increased contrast
88
+
89
+ When the product ships a dark appearance, every custom color needs a dark variant, derived per [palette-generation.md](palette-generation.md). Users who enable increased contrast expect visibly stronger differentiation in each appearance:
90
+
91
+ ```css
92
+ :root {
93
+ --color-accent-solid: var(--blue-600);
94
+ }
95
+
96
+ @media (prefers-contrast: more) {
97
+ :root { --color-accent-solid: var(--blue-900); }
98
+ }
99
+
100
+ @media (prefers-color-scheme: dark) {
101
+ :root { --color-accent-solid: var(--blue-400); }
102
+ }
103
+
104
+ @media (prefers-color-scheme: dark) and (prefers-contrast: more) {
105
+ :root { --color-accent-solid: var(--blue-200); }
106
+ }
107
+ ```
108
+
109
+ A single `prefers-contrast` block shared by both appearances darkens the color on a dark background too, lowering contrast there. The increased-contrast variant widens the gap to its background by at least `0.15` of OKLCH `L` over the default. Remeasure it, aiming for Lc 90 on body text. Widening the gap without remeasuring is not fixing it.
@@ -0,0 +1,70 @@
1
+ # Contrast
2
+
3
+ Contrast is measured between a **foreground color**, meaning text, an icon or a UI element, and the **background color** it actually renders against, usually the nearest ancestor that paints one. Identify that background first. Measuring against the page background when the element sits on a card gives the wrong answer.
4
+
5
+ `accessibility` decides which requirement applies to a pair. The thresholds below are what a measured pair is reported against. Where neither that skill nor the project names a standard, report the WCAG 2 result and add the APCA value.
6
+
7
+ ## WCAG 2 thresholds
8
+
9
+ WCAG 2 is the standard formal conformance claims are made against.
10
+
11
+ | Content type | AA | AAA |
12
+ | --- | --- | --- |
13
+ | Text | 4.5:1 | 7:1 |
14
+ | Large text, at least `24px` or `18.67px` bold | 3:1 | 4.5:1 |
15
+ | UI components and graphical objects | 3:1 | n/a |
16
+
17
+ Disabled or inactive controls and logos are exempt.
18
+
19
+ ## APCA thresholds
20
+
21
+ Lc, Lightness Contrast, is APCA's measure of perceived contrast. These levels simplify APCA's full font-size and weight lookup table:
22
+
23
+ | Content type | Minimum |
24
+ | --- | --- |
25
+ | Body text, columns or blocks of text | Lc 75, preferred Lc 90 |
26
+ | Non-body text such as labels and headlines | Lc 60 |
27
+ | Large text, at least `36px` regular or `24px` bold | Lc 45 |
28
+ | Fine-detail or outline icons | Lc 45 |
29
+ | Solid icons and UI components | Lc 30 |
30
+ | Non-text that only has to be discernible, such as dividers | Lc 15 |
31
+
32
+ Disabled and placeholder text are not covered by a requirement. Aim for Lc 30 so they stay legible.
33
+
34
+ Lc is signed. Positive means dark text on a light background, negative means light text on a dark background. Compare the absolute value against the threshold.
35
+
36
+ ## Fix a failing pair only on request
37
+
38
+ **Change lightness first.** It is the channel contrast responds to. Hue and saturation move the measured value far less.
39
+
40
+ Move the foreground away from the background in perceived lightness, holding hue and saturation, then remeasure. Keeping hue fixed is what stops a contrast fix becoming a palette change.
41
+
42
+ ```css
43
+ /* Failing: text too close to its background in lightness (Lc ≈ 50) */
44
+ color: #7d93b0;
45
+ background: #eef2f7;
46
+
47
+ /* Fixed: darker text, same hue (Lc ≈ 88) */
48
+ color: #2b3a4f;
49
+ background: #eef2f7;
50
+ ```
51
+
52
+ Two constraints on the fix:
53
+
54
+ - **Mid-lightness backgrounds cap what is achievable.** On a background near OKLCH `L` `0.75`, even pure black text reaches only about Lc 60. Body text needs a background near one extreme, so a mid-range background is the thing that has to change.
55
+ - **Pushing lightness can push the color out of gamut.** Reduce saturation as needed to keep it renderable. See [color-formats.md](color-formats.md).
56
+
57
+ Always remeasure after changing a value. Do not assume a fix landed.
58
+
59
+ ## Pick text polarity from the background
60
+
61
+ Compare black and white using the project's required contrast metric. APCA and WCAG 2 can favor different text colors on the same background. A higher score does not by itself mean the pair passes.
62
+
63
+ WCAG 2's neutral crossover is near 56% OKLCH lightness. At `oklch(65% 0 0)`, black measures about `6.49:1` and white `3.23:1`. Only black passes AA for normal text. For colored backgrounds or other foregrounds, measure the actual pair rather than applying a crossover.
64
+
65
+ ## What to check
66
+
67
+ - **Every pair, in every appearance.** APCA scores mirrored pairs differently, so a pair passing in light mode can fail in dark.
68
+ - **Translucent surfaces.** A color on a `backdrop-filter` header or an overlay shifts with whatever scrolls behind it. Test against the lightest and darkest content it can sit over, or make the surface opaque enough that the shift cannot break the pair.
69
+ - **Computed colors.** `color-mix()`, relative color syntax and opacity modifiers resolve at render time; measure the rendered result, not the declaration.
70
+ - **Text over images.** There is no single background color. Measure the worst region, or guarantee one with a scrim.
@@ -0,0 +1,108 @@
1
+ # Palette generation
2
+
3
+ Producing the values once the structure is decided. For which ramps to build and what each step is for, see [palette-structure.md](palette-structure.md).
4
+
5
+ ## Start from the brand color
6
+
7
+ A brand color arrives as one value, usually a hex. Two decisions come before any ramp exists:
8
+
9
+ **Which step does it occupy?** A brand color meant for buttons and links belongs on the solid-fill step, `600` in Tailwind and `9` in Radix. Then the primary button renders the actual brand color, not an approximation.
10
+
11
+ **Is it pinned or snapped?** Pin a contractually fixed brand color. It stays exact, the ramp builds outward from it and that one step spaces slightly unevenly. Otherwise snap it onto the ramp so the spacing stays regular, which almost always looks better.
12
+
13
+ A brand color that fails contrast behind white text is still the brand color, just not the solid-fill step. Put it where it lands and use a darker step for interactive fills. Never quietly darken the brand. In the example below, `#3b82f6` lands on `500` and fills use `600`, because white on `#3b82f6` measures 3.68:1.
14
+
15
+ ## What a correct ramp looks like
16
+
17
+ Properties of the finished ramp, checkable against any output in any notation:
18
+
19
+ - **Lightness changes steadily, measured in OKLCH `L`.** HSL lightness is not perceptual, and evenly spaced HSL values bunch at one end.
20
+ - **Hue is constant end to end.** Every step is recognisably the same color. A wandering hue reads as two colors blended and will not sit correctly against a neutral built on a different hue.
21
+ - **Vividness peaks in the middle and falls off at both ends.** The lightest and darkest steps are nearly neutral; the middle carries the color. Holding full vividness into the extremes gives a `50` that glows and a `950` like ink spilled on the brand.
22
+ - **Steps are finer at the light end.** Light backgrounds need finer distinctions than dark ones. Keep `50`–`200` about `0.04`–`0.05` apart in OKLCH `L` and mid-ramp steps about `0.07`–`0.10`. Even spacing across the whole range leaves too few pale steps, so `100` is already too dark for a subtle surface.
23
+ - **No two adjacent steps are indistinguishable.** Adjacent steps less than `0.03` apart in OKLCH `L` mean the ramp has more steps than decisions. Drop one.
24
+ - **Both ends stop short of pure black and white.** A ramp that reaches them loses its identity exactly where the page background lives.
25
+
26
+ ## Use a color library
27
+
28
+ Never compute these by hand or by eye. `culori`, `colorjs.io` and `chroma.js` all convert between notations, measure perceived lightness and interpolate perceptually. Read the brand color in whatever format it arrives, do the math in a perceptual space and emit the project's notation:
29
+
30
+ ```js
31
+ import { formatHex, interpolate, samples } from 'culori'
32
+
33
+ // Perceptual interpolation, hex in and hex out.
34
+ const ramp = interpolate(['#eff6ff', '#3b82f6', '#172554'], 'oklab')
35
+ const steps = samples(11).map((t) => formatHex(ramp(t)))
36
+ ```
37
+
38
+ This is a starting point. Linear sampling spaces lightness evenly within each segment, so check the output against the properties above and tighten `50`–`200` by hand.
39
+
40
+ The output format is the project's choice. For a ramp the interpolation space is not, because sRGB interpolation produces muddy mid-steps. Decorative gradients are the opposite case, where the space is a deliberate look ([color-usage.md](color-usage.md)).
41
+
42
+ For comparison, Tailwind's blue ramp has the finer light end the generated one lacks:
43
+
44
+ ```css
45
+ :root {
46
+ --blue-50: #eff6ff;
47
+ --blue-100: #dbeafe;
48
+ --blue-200: #bfdbfe;
49
+ --blue-300: #93c5fd;
50
+ --blue-400: #60a5fa;
51
+ --blue-500: #3b82f6;
52
+ --blue-600: #2563eb;
53
+ --blue-700: #1d4ed8;
54
+ --blue-800: #1e40af;
55
+ --blue-900: #1e3a8a;
56
+ --blue-950: #172554;
57
+ }
58
+ ```
59
+
60
+ ## Several hues at once
61
+
62
+ With an accent plus status ramps, the ramps must agree step for step. `red-500` and `blue-500` should read as equally bright and vivid, or a red button looks heavier than a blue one at the same step.
63
+
64
+ - **Match perceived lightness exactly.** Same step, same brightness, across every hue.
65
+ - **Match vividness relatively, not absolutely.** Hues do not share a maximum vividness. A saturated yellow and a saturated blue are not equally far from gray, and no format makes them so. Set each ramp to the same *proportion* of what its own hue reaches.
66
+
67
+ Yellows and cyans are the usual casualties, peaking much lower than reds and blues. Copy the numbers across and the warning color looks weak beside the danger one.
68
+
69
+ ## Dark mode
70
+
71
+ A dark palette is not the light one reversed. Reversal is the starting point, not the output.
72
+
73
+ Swap the semantic roles first, then tune the values:
74
+
75
+ ```css
76
+ :root {
77
+ --color-bg-page: var(--neutral-50);
78
+ --color-text-primary: var(--neutral-950);
79
+ }
80
+
81
+ .dark {
82
+ --color-bg-page: var(--neutral-950);
83
+ --color-text-primary: var(--neutral-50);
84
+ }
85
+ ```
86
+
87
+ Three things almost always need hand-tuning after the swap:
88
+
89
+ - **Vividness comes down.** A color that reads as confident on white reads as neon on near-black. Dark appearances need the accent a step or two less vivid.
90
+ - **The dark end needs more separation.** Steps distinguishable as pale backgrounds collapse into each other as dark surfaces.
91
+ - **Contrast does not survive the mirror.** APCA scores mirrored pairs differently, so recheck every pair in both appearances ([contrast.md](contrast.md)).
92
+
93
+ ### Choosing the switching mechanism
94
+
95
+ Use one mechanism throughout:
96
+
97
+ - **`prefers-color-scheme` alone** is correct with no theme toggle. Nothing to persist, nothing to hydrate.
98
+ - **A `.dark` class** is required as soon as users can override the system setting. The media query then sets only the initial value.
99
+ - **`light-dark()`** collapses both values into one declaration. It needs `color-scheme: light dark` and reads that property rather than a class, so a class-based toggle must set `color-scheme` too.
100
+
101
+ ```css
102
+ :root {
103
+ color-scheme: light dark;
104
+ --color-bg: light-dark(#ffffff, #172554);
105
+ }
106
+ ```
107
+
108
+ A media query setting some tokens and a class setting others gives a half-themed interface the moment a user overrides their system preference.
@@ -0,0 +1,72 @@
1
+ # Palette structure
2
+
3
+ What a color system is made of, before any values exist. For computing the values see [palette-generation.md](palette-generation.md); for what to call them see [token-naming.md](token-naming.md).
4
+
5
+ ## What a system needs
6
+
7
+ Most products need three kinds of ramp and nothing else:
8
+
9
+ | Ramp | How many | Notes |
10
+ | --- | --- | --- |
11
+ | Neutral | 1 | Carries 80–90% of the interface: backgrounds, borders, body text |
12
+ | Accent | 1 | The brand hue. Interactive and selected states |
13
+ | Status | 0–4 | `danger`, `warning`, `success`, `info`. Add one only when the product shows that state |
14
+
15
+ ## Every step has a job
16
+
17
+ Each step maps to a role. Generate the steps the roles below call for and skip the rest.
18
+
19
+ | Role | Tailwind | Radix |
20
+ | --- | --- | --- |
21
+ | Page background | `50` | `1` |
22
+ | Subtle background | `50` | `2` |
23
+ | Component background | `100` | `3` |
24
+ | Component hover | `200` | `4` |
25
+ | Component active / selected | `200` | `5` |
26
+ | Subtle border, separator | `200` | `6` |
27
+ | Border, focus ring | `300` | `7` |
28
+ | Hovered border | `400` | `8` |
29
+ | Solid fill | `600` | `9` |
30
+ | Solid fill hover | `700` | `10` |
31
+ | Low-contrast text | `700` | `11` |
32
+ | High-contrast text | `900` | `12` |
33
+
34
+ The two conventions differ in kind, not only in numbering:
35
+
36
+ - **Radix defines its 12 steps by role.** Step 9 is "the solid fill" in every ramp and appearance. The dark scale is a separate ramp reusing the same numbers, so `--accent-9` is the fill in both and component CSS never changes.
37
+ - **Tailwind defines its 11 steps by lightness.** `50` is light, `950` is dark. The mapping above therefore holds in light mode and inverts in dark, with the page background at `950` and high-contrast text at `50`. Components either swap step numbers per appearance or read a semantic token that swaps once.
38
+
39
+ Match whichever the project uses. For a new system prefer Radix's model, because a role-defined step survives a theme change that a lightness-defined step does not. On Tailwind, keep `50`–`950` and put the role mapping in the semantic tier.
40
+
41
+ Solid fill sits on `600` because white text on most Tailwind `500` hues fails 4.5:1. Where the table repeats a step, those roles render identically. A design that needs, say, component hover and subtle border to differ needs a 12-step ramp.
42
+
43
+ ## Neutrals
44
+
45
+ A pure gray ramp is a perfectly good default. It sits under any accent hue without competing and never needs revisiting when the brand color changes.
46
+
47
+ Tinting the neutral toward the accent hue is a stylistic option, not a correction. OKLCH chroma `0.005`–`0.02` at the accent's hue puts the grays in the accent's family. Enough to measure, not enough to name.
48
+
49
+ Warm neutrals, hue toward orange, read approachable and editorial; cool ones, toward blue, read technical and precise. Whichever you pick, including none, hold it across the whole ramp. A warm gray border on a cool gray background is visible even when neither color is nameable alone.
50
+
51
+ Neutrals carry the most roles, so they need the most steps. Never generate fewer neutral steps than accent steps.
52
+
53
+ ## Status colors
54
+
55
+ Convention constrains status hues before taste does. Red reads as danger, amber as warning, green as success. See the cultural exceptions in [color-usage.md](color-usage.md).
56
+
57
+ Two rules govern them:
58
+
59
+ - **Keep every status hue at least `15°` of OKLCH hue from the accent.** If the brand is red, danger cannot also be red. Where convention leaves nowhere to move, give the destructive action a distinct treatment, such as an outlined button with an icon, or it reads as the primary action.
60
+ - **Status ramps need fewer steps than the accent.** Most render four roles: a background, a border, a solid fill and text. Generate the full ramp only where the product styles status components across the whole range.
61
+
62
+ ## Auditing an existing palette
63
+
64
+ Before restructuring a system, inventory it. Most codebases hold several times more colors than the design has decisions.
65
+
66
+ 1. **Collect every literal.** Grep for hex, `rgb(`, `hsl(`, `oklch(` and the project's utility-class prefixes. Include SVG `fill` and `stroke`, chart configs and email templates.
67
+ 2. **Sort by perceived lightness within each hue family.** Duplicates surface immediately as near-identical neighbors.
68
+ 3. **Collapse near-duplicates.** Two colors within `0.02` of each other in OKLab ΔE are one color that drifted. Keep the one used most and retire the others. Never average them.
69
+ 4. **Assign each survivor a role** from the table above. A color matching no role is a missing token or a mistake. Decide which, and say so in the finding.
70
+ 5. **Count what is left.** More ramps than **What a system needs** lists means the palette outgrew its structure, not that the product needs more color.
71
+
72
+ Report the inventory before changing anything. Consolidating a palette changes rendered output on screens nobody asked you to touch, so it stays a proposal until the user accepts it.