@jonmilner/ui 0.6.1 → 0.8.0

package/dist/contrast/contrast.mjs

@@ -1,56 +1,63 @@
-import { decode as e, resolveColor as t } from "./color.mjs";
+import { subtleFills as e } from "../styles/subtle-fills.mjs";
+import { decode as t, resolveColor as n } from "./color.mjs";
 //#region src/contrast/contrast.ts
-var n = [
+var r = [
 	"bg",
 	"bgMuted",
 	"bgRaised"
-], r = (e, t, n) => e.flatMap((e) => t.map((t) => ({
+], i = (e, t, n) => e.flatMap((e) => t.map((t) => ({
 	fg: e,
 	bg: t,
 	min: n
-}))), i = [
-	...r([
+}))), a = Object.values(e).map(({ color: e, backgroundColor: t }) => [e, t]), o = [
+	...i([
 		"fg",
 		"fgMuted",
 		"accent",
 		"danger",
 		"success",
-		"warning"
-	], n, 4.5),
-	...r(["accentFg"], ["accent"], 4.5),
-	...r(["dangerFg"], ["danger"], 4.5),
-	...r(["successFg"], ["success"], 4.5),
-	...r(["warningFg"], ["warning"], 4.5),
-	...r(["borderStrong", "focus"], n, 3)
-], a = ["light", "dark"];
-function o({ r: t, g: n, b: r }) {
-	return .2126 * e(t) + .7152 * e(n) + .0722 * e(r);
+		"warning",
+		"done"
+	], r, 4.5),
+	...i(["accentFg"], ["accent"], 4.5),
+	...i(["accentFillFg"], ["accentFill"], 4.5),
+	...i(["dangerFg"], ["danger"], 4.5),
+	...i(["successFg"], ["success"], 4.5),
+	...i(["warningFg"], ["warning"], 4.5),
+	...i(["doneFg"], ["done"], 4.5),
+	...a.flatMap(([e, t]) => i([e], [t], 4.5)),
+	...i(["borderStrong", "focus"], r, 3),
+	...i(["focus"], a.map(([, e]) => e), 3),
+	...i(a.map(([e]) => e), ["bg"], 3)
+], s = ["light", "dark"];
+function c({ r: e, g: n, b: r }) {
+	return .2126 * t(e) + .7152 * t(n) + .0722 * t(r);
 }
-function s(e, n, r = "light") {
-	return c(t(e, r), t(n, r), n);
+function l(e, t, r = "light") {
+	return u(n(e, r), n(t, r), t);
 }
-function c(e, t, n) {
+function u(e, t, n) {
 	if (t.alpha < 1) throw Error(`Contrast background must be opaque: ${n}`);
-	let r = (t, n) => t * e.alpha + n * (1 - e.alpha), [i, a] = [o({
+	let r = (t, n) => t * e.alpha + n * (1 - e.alpha), [i, a] = [c({
 		r: r(e.r, t.r),
 		g: r(e.g, t.g),
 		b: r(e.b, t.b),
 		alpha: 1
-	}), o(t)].toSorted((e, t) => t - e);
+	}), c(t)].toSorted((e, t) => t - e);
 	return (i + .05) / (a + .05);
 }
-function l(e) {
-	return a.flatMap((n) => {
-		let r = /* @__PURE__ */ new Map(), a = (i) => r.get(i) ?? r.set(i, t(e.color[i], n)).get(i);
-		return i.flatMap((t) => {
-			let r = c(a(t.fg), a(t.bg), e.color[t.bg]);
-			return r < t.min ? [{
-				...t,
-				mode: n,
+function d(e) {
+	return s.flatMap((t) => {
+		let r = /* @__PURE__ */ new Map(), i = (i) => r.get(i) ?? r.set(i, n(e.color[i], t)).get(i);
+		return o.flatMap((n) => {
+			let r = u(i(n.fg), i(n.bg), e.color[n.bg]);
+			return r < n.min ? [{
+				...n,
+				mode: t,
 				ratio: r
 			}] : [];
 		});
 	});
 }
 //#endregion
-export { l as checkContrast, i as contrastPairs, s as contrastRatio };
+export { d as checkContrast, o as contrastPairs, l as contrastRatio };

package/dist/contrast/mixes.mjs

@@ -3,17 +3,26 @@ import { contrastRatio as t } from "./contrast.mjs";
 import { highlightFill as n, highlightText as r } from "../styles/highlight.mjs";
 import { hoverFill as i } from "../styles/hover-tint.mjs";
 //#region src/contrast/mixes.ts
-var a = [{
-	name: "Menu highlight",
-	fill: n,
-	text: r,
-	min: 4.5
-}, ...Object.entries(e).map(([e, { backgroundColor: t, color: n }]) => ({
-	name: `${e} Button hover`,
-	fill: (e) => i(e.fg, e[t]),
-	text: [n],
-	min: 4.5
-}))];
+var a = [
+	{
+		name: "Menu highlight",
+		fill: n,
+		text: r,
+		min: 4.5
+	},
+	...Object.entries(e).map(([e, { backgroundColor: t, color: n }]) => ({
+		name: `${e} Button hover`,
+		fill: (e) => i(e.fg, e[t]),
+		text: [n],
+		min: 4.5
+	})),
+	{
+		name: "pressed Chip hover",
+		fill: (e) => i(e.fg, e.accent),
+		text: ["accentFg"],
+		min: 4.5
+	}
+];
 function o(e) {
 	return ["light", "dark"].flatMap((n) => a.flatMap(({ name: r, fill: i, text: a, min: o }) => {
 		let s = i(e.color);

package/dist/docs/Badge.md

@@ -21,7 +21,8 @@ A static label that states the status of, or a short fact about, the thing besid
 
 ## Rules
 
-- `variant`: `neutral` (default, `fgMuted` on `bgMuted`) for most statuses and facts; `accent` (`accentFg` on `accent`) to draw the eye; `success` (`successFg` on `success`) for a done or healthy state; `warning` (`warningFg` on `warning`) for one that needs attention soon; `danger` (`dangerFg` on `danger`) for a failure or a blocked state.
+- `variant`: `neutral` (default, `fgMuted` on `bgMuted`) for most statuses and facts; `accent` (`accentFg` on `accent`) to draw the eye; `success` (`successFg` on `success`) for a passing or healthy state; `warning` (`warningFg` on `warning`) for one that needs attention soon; `danger` (`dangerFg` on `danger`) for a failure or a blocked state; `done` (`doneFg` on `done`, violet) for finished work, such as a merged PR or a closed issue.
+- `subtle`: `false` (default) is the solid fill above; `true` swaps it for the variant's tint, `<variant>SubtleFg` on `<variant>Subtle` (`neutralSubtleFg` on `neutralSubtle` and so on). Use subtle where many badges sit together, such as a list or a board, so each one stays calm and the color still means one thing; keep solid for the one status that should stand out.
 - `size`: `sm` or `med` (default), the label's `fontSize` step.
 - The label states the state. Color is never the only cue (WCAG 1.4.1): under forced colors every variant, `success` and `warning` included, is the same outlined box, and some readers cannot tell the fills apart (green from red above all). Write "Failed" or "Passed", not a red or green badge reading "3".
 - Keep it to one or two words; it never wraps. With no children it renders nothing.
@@ -44,6 +45,13 @@ A static label that states the status of, or a short fact about, the thing besid
 </Badge>
 ```
 
+```tsx
+// A row of statuses in a list: subtle, so none shouts.
+<Badge subtle variant="done">
+  Merged
+</Badge>
+```
+
 ## Don't
 
 ```tsx
@@ -60,8 +68,8 @@ A static label that states the status of, or a short fact about, the thing besid
 
 - It is plain text in a `span`: screen readers read the label in line with what is around it, so the label must make sense there ("Quarterly report Draft").
 - No role, no `aria-live`: a badge that changes is not announced. If a status change matters right away, announce it elsewhere (a toast).
-- Each variant's text and fill pass AA (4.5:1) in light and dark mode; the pairs are in `contrastPairs` (ADR 0033).
-- Under forced colors every badge is `CanvasText` on `Canvas` with a `CanvasText` outline, so the box survives and the variants look alike; the label carries the meaning. The role fills are not kept: `accent` would take the link color, on something that is not a link, and the browser's backplate would hide the filled variants' text. `success`, `warning` and `danger` map to the same system pair (ADR 0104), so only the label tells them apart.
+- Each variant's text and fill, solid and subtle, pass AA (4.5:1) in light and dark mode; the pairs are in `contrastPairs` (ADR 0033, 0121). Each subtle text also passes 3:1 on `bg`.
+- Under forced colors every badge is `CanvasText` on `Canvas` with a `CanvasText` outline, so the box survives and the variants, solid or subtle, look alike; the label carries the meaning. The role fills are not kept: `accent` would take the link color, on something that is not a link, and the browser's backplate would hide the filled variants' text. `success`, `warning`, `danger` and `done` map to the same system pair (ADR 0104, 0121), so only the label tells them apart.
 
 ## Props
 
@@ -72,6 +80,7 @@ Generated from the TypeScript types.
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
 | `size` | `"med" \| "sm"` | no |  |
-| `variant` | `"accent" \| "danger" \| "neutral" \| "success" \| "warning"` | no |  |
+| `subtle` | `boolean` | no |  |
+| `variant` | `"accent" \| "danger" \| "done" \| "neutral" \| "success" \| "warning"` | no |  |
 
 Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/Button.md

@@ -18,7 +18,7 @@ The labelled action: a `<button type="button">` with the house look, or a link s
 
 ## Rules
 
-- `primary` marks the one action a view or dialog exists for; everything else is `secondary`, the default. One primary per group.
+- `primary` marks the one action a view or dialog exists for; everything else is `secondary`, the default. One primary per group. Its fill is `accentFill` with `accentFillFg` text (ADR 0119): light text on a solid accent in both modes, 4.5:1 at rest and on hover.
 - `danger` (`dangerFg` on `danger`, ADR 0060) replaces `primary` when that action destroys data or cannot be undone, such as a confirm dialog's "Delete project". It takes `primary`'s place, so a group has one `primary` or one `danger`, not both. The label names the consequence ("Delete project", not "OK"): under forced colors `danger` looks like `primary`, so the word carries the meaning, not the color. Confirm before an irreversible action runs; `danger` does not.
 - Sizes are `sm`, `med` (default) and `lg`, never `md`. The label and the icons take the `fontSize` step of the same name.
 - `loading` renders `aria-busy="true"`, blocks clicks, Enter and Space, and swaps the label for three pulsing dots in the same space: the width never changes, and the label stays the accessible name. A label narrower than the dots (one character, such as a page number) widens by a few pixels; give such buttons a fixed `minInlineSize`. Announce the outcome elsewhere (a toast or a status message); `aria-busy` alone is not announced.

package/dist/docs/Icon.md

@@ -117,7 +117,7 @@ Generated from the TypeScript types.
 
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
-| `color` | `"accent" \| "accentFg" \| "bg" \| "bgMuted" \| "bgRaised" \| "border" \| "borderStrong" \| "danger" \| "dangerFg" \| "fg" \| "fgMuted" \| "focus" \| "success" \| "successFg" \| "warning" \| "warningFg"` | no |  |
+| `color` | `"accent" \| "accentFg" \| "accentFillFg" \| "accentSubtleFg" \| "bg" \| "bgMuted" \| "bgRaised" \| "border" \| "borderStrong" \| "danger" \| "dangerFg" \| "dangerSubtleFg" \| "done" \| "doneFg" \| "doneSubtleFg" \| "fg" \| "fgMuted" \| "focus" \| "neutralSubtleFg" \| "success" \| "successFg" \| "successSubtleFg" \| "warning" \| "warningFg" \| "warningSubtleFg"` | no |  |
 | `label` | `string` | no |  |
 | `size` | `"2xl" \| "3xl" \| "4xl" \| "lg" \| "med" \| "sm" \| "xl" \| "xs"` | no |  |
 | `strokeWidth` | `number` | no |  |

package/dist/docs/Tag.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-A label that puts content in a category: a topic, a label, a user-made category. A `span` with a `bgMuted` fill and an `lg` radius (half a one-line tag's height, so one line reads as a pill and wrapped lines stay inside the fill) around a `Text` in the `label` font. It can be read-only, a link, or removable.
+A label that puts content in a category: a topic, a label, a user-made category. A `span` with a subtle tone fill (gray by default) and an `lg` radius (half a one-line tag's height, so one line reads as a pill and wrapped lines stay inside the fill) around a `Text` in the `label` font. It can be read-only, a link, or removable.
 
 ## When to use
 
@@ -20,7 +20,8 @@ A label that puts content in a category: a topic, a label, a user-made category.
 
 ## Rules
 
-- `size`: `sm` or `med` (default), the label's `fontSize` step. There are no color variants yet: a Tag is neutral (`fg` on `bgMuted`, a `contrastPairs` pair).
+- `size`: `sm` or `med` (default), the label's `fontSize` step.
+- `variant`: the tone's subtle fill, `<variant>SubtleFg` on `<variant>Subtle`. `neutral` (default) for most categories; `accent`, `success`, `warning`, `danger` and `done` only where the category has a meaning those colors already carry in the app, as Badge's variants do. Tag has no solid fills: a category label stays calm (ADR 0121). The tone is never the only cue: the label names the category.
 - Read-only is the default. `href` makes the label a link (a `Clickable` `<a>` around the text, underlined). The tag itself stays a `span`, so a remove button never nests in the link.
 - `onRemove` adds a native `<button>` after the label with an `x` icon. Its name is "Remove <label>" from a string or number label; set `removeLabel` for any other label. Enter and Space activate it; the click calls `onRemove`. Tag handles no keys, so Backspace and Delete do nothing (ADR 0003, 0055).
 - Wrapping: an uncapped label wraps to the width it has, so a tag never overflows a narrow container or a 320px viewport at large text sizes. Every line stays inside the fill and its rounded corners, and inside the outline under forced colors.
@@ -56,6 +57,12 @@ Tell screen reader users the tag is gone, with the owner's live region or by nam
 <Tag style={{ maxInlineSize: "min(10rem, 100%)" }}>{longCategoryName}</Tag>
 ```
 
+```tsx
+<Tag variant="done" href="/labels/shipped">
+  Shipped
+</Tag>
+```
+
 ## Don't
 
 ```tsx
@@ -80,7 +87,8 @@ Tell screen reader users the tag is gone, with the owner's live region or by nam
 - A read-only tag is plain text in a `span`, no role. A link tag is a link in the tab order. A removable tag adds one button; each button's name says which tag it removes.
 - Nothing essential is only in a tooltip: truncated text is fully in the DOM and shows on hover and focus.
 - The `x` icon is `aria-hidden`; the button's `aria-label` names it. The link and the button each get the shared focus ring and a 24px target.
-- Under forced colors the tag is `CanvasText` on `Canvas` with a `CanvasText` outline, as Badge is.
+- Each variant's text passes 4.5:1 on its fill and 3:1 on `bg`, and the focus ring 3:1 on the fill, in light and dark mode; the pairs are in `contrastPairs`.
+- Under forced colors every variant is `CanvasText` on `Canvas` with a `CanvasText` outline, as Badge is, and the link and the button keep the `Highlight` focus ring.
 
 ## Props
 
@@ -94,5 +102,6 @@ Generated from the TypeScript types.
 | `onRemove` | `(() => void)` | no |  |
 | `removeLabel` | `string` | no |  |
 | `size` | `"med" \| "sm"` | no |  |
+| `variant` | `"accent" \| "danger" \| "done" \| "neutral" \| "success" \| "warning"` | no |  |
 
 Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/llms.txt

@@ -24,7 +24,7 @@
 - [SearchField](SearchField.md): A form field for a search query: an `<input type="search">` (role `searchbox`) with a search icon at its inline start and, while it holds a value, a clear button at its inline end. Escape empties a field that has a value, and the clear button empties it and puts focus back in the input, so a keyboard user never loses their place (ADR 0087). Built on Base UI's `Input` (ADR 0003); it composes `Field` for its label, description and error (ADR 0026). Three sizes at Button's heights (`sm`, `med`, `lg`: 32, 40 and 48 px).
 - [Stack](Stack.md): A vertical column of children with even space between them. `Stack` is a `Box` with `display="flex"` and `flexDirection="column"` as default style props, spaced by a required `gap`. Children render as they are: no wrapper per child.
 - [Tabs](Tabs.md): Switches between views that share one place on the page. The parts are `Tabs` (the root, a flex column; a row when vertical), `Tabs.List` (the `tablist`), `Tabs.Tab` (a `tab` button on `Clickable`) and `Tabs.Panel` (the `tabpanel`). Built on Base UI `Tabs` (ADR 0003, 0046): it owns the selection, one tab stop with arrow-key roving, `aria-selected`, and the ids that tie each tab to its panel. The selected tab shows an accent bar that fades and grows in (ADR 0049).
-- [Tag](Tag.md): A label that puts content in a category: a topic, a label, a user-made category. A `span` with a `bgMuted` fill and an `lg` radius (half a one-line tag's height, so one line reads as a pill and wrapped lines stay inside the fill) around a `Text` in the `label` font. It can be read-only, a link, or removable.
+- [Tag](Tag.md): A label that puts content in a category: a topic, a label, a user-made category. A `span` with a subtle tone fill (gray by default) and an `lg` radius (half a one-line tag's height, so one line reads as a pill and wrapped lines stay inside the fill) around a `Text` in the `label` font. It can be read-only, a link, or removable.
 - [Text](Text.md): The base of all visible text, and the primitive every text component builds on. Capsize trims the box to the cap height and the baseline, so the gap around text is the visible space. It takes every Box style prop (`color`, `textAlign`, margins), plus `size`, `font`, `weight`, `leading`, `truncate` and `wrap`.
 - [TextField](TextField.md): A form field for one line of text that is not a search: an `<input>` (role `textbox`) with SearchField's look and no icon or button over it. `type` picks `text`, `email`, `url` or `tel`. Built on Base UI's `Input` (ADR 0003); it composes `Field` for its label, description and error (ADR 0026, 0110). Three sizes at Button's heights (`sm`, `med`, `lg`: 32, 40 and 48 px).
 - [Toast](Toast.md): Tells the user briefly about the result of an action without interrupting them: "Changes saved", "Message sent", "Couldn't upload the file". Material calls it a snackbar and Atlassian a flag. Built on Base UI's Toast, which owns the queue, the timers and swipe-to-dismiss. The parts add the look: a raised card in a stack at the bottom end corner, an icon per variant, a close button, and a slide-up-and-fade that is a plain fade under reduced motion. A toast never takes focus and moves nothing on the page.

package/dist/docs/manifest.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./manifest.schema.json",
   "package": "@jonmilner/ui",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "components": [
     {
       "name": "AlertDialog",
@@ -174,13 +174,19 @@
             "sm"
           ]
         },
+        {
+          "name": "subtle",
+          "type": "boolean",
+          "required": false
+        },
         {
           "name": "variant",
-          "type": "\"accent\" | \"danger\" | \"neutral\" | \"success\" | \"warning\"",
+          "type": "\"accent\" | \"danger\" | \"done\" | \"neutral\" | \"success\" | \"warning\"",
           "required": false,
           "values": [
             "accent",
             "danger",
+            "done",
             "neutral",
             "success",
             "warning"
@@ -1061,11 +1067,13 @@
       "props": [
         {
           "name": "color",
-          "type": "\"accent\" | \"accentFg\" | \"bg\" | \"bgMuted\" | \"bgRaised\" | \"border\" | \"borderStrong\" | \"danger\" | \"dangerFg\" | \"fg\" | \"fgMuted\" | \"focus\" | \"success\" | \"successFg\" | \"warning\" | \"warningFg\"",
+          "type": "\"accent\" | \"accentFg\" | \"accentFillFg\" | \"accentSubtleFg\" | \"bg\" | \"bgMuted\" | \"bgRaised\" | \"border\" | \"borderStrong\" | \"danger\" | \"dangerFg\" | \"dangerSubtleFg\" | \"done\" | \"doneFg\" | \"doneSubtleFg\" | \"fg\" | \"fgMuted\" | \"focus\" | \"neutralSubtleFg\" | \"success\" | \"successFg\" | \"successSubtleFg\" | \"warning\" | \"warningFg\" | \"warningSubtleFg\"",
           "required": false,
           "values": [
             "accent",
             "accentFg",
+            "accentFillFg",
+            "accentSubtleFg",
             "bg",
             "bgMuted",
             "bgRaised",
@@ -1073,13 +1081,20 @@
             "borderStrong",
             "danger",
             "dangerFg",
+            "dangerSubtleFg",
+            "done",
+            "doneFg",
+            "doneSubtleFg",
             "fg",
             "fgMuted",
             "focus",
+            "neutralSubtleFg",
             "success",
             "successFg",
+            "successSubtleFg",
             "warning",
-            "warningFg"
+            "warningFg",
+            "warningSubtleFg"
           ]
         },
         {
@@ -1925,6 +1940,19 @@
             "med",
             "sm"
           ]
+        },
+        {
+          "name": "variant",
+          "type": "\"accent\" | \"danger\" | \"done\" | \"neutral\" | \"success\" | \"warning\"",
+          "required": false,
+          "values": [
+            "accent",
+            "danger",
+            "done",
+            "neutral",
+            "success",
+            "warning"
+          ]
         }
       ],
       "parts": [],
@@ -2195,11 +2223,15 @@
     },
     {
       "name": "backgroundColor",
-      "type": "\"accent\" | \"accentFg\" | \"bg\" | \"bgMuted\" | \"bgRaised\" | \"border\" | \"borderStrong\" | \"danger\" | \"dangerFg\" | \"fg\" | \"fgMuted\" | \"focus\" | \"success\" | \"successFg\" | \"warning\" | \"warningFg\"",
+      "type": "\"accent\" | \"accentFg\" | \"accentFill\" | \"accentFillFg\" | \"accentSubtle\" | \"accentSubtleFg\" | \"bg\" | \"bgMuted\" | \"bgRaised\" | \"border\" | \"borderStrong\" | \"danger\" | \"dangerFg\" | \"dangerSubtle\" | \"dangerSubtleFg\" | \"done\" | \"doneFg\" | \"doneSubtle\" | \"doneSubtleFg\" | \"fg\" | \"fgMuted\" | \"focus\" | \"neutralSubtle\" | \"neutralSubtleFg\" | \"success\" | \"successFg\" | \"successSubtle\" | \"successSubtleFg\" | \"warning\" | \"warningFg\" | \"warningSubtle\" | \"warningSubtleFg\"",
       "required": false,
       "values": [
         "accent",
         "accentFg",
+        "accentFill",
+        "accentFillFg",
+        "accentSubtle",
+        "accentSubtleFg",
         "bg",
         "bgMuted",
         "bgRaised",
@@ -2207,13 +2239,25 @@
         "borderStrong",
         "danger",
         "dangerFg",
+        "dangerSubtle",
+        "dangerSubtleFg",
+        "done",
+        "doneFg",
+        "doneSubtle",
+        "doneSubtleFg",
         "fg",
         "fgMuted",
         "focus",
+        "neutralSubtle",
+        "neutralSubtleFg",
         "success",
         "successFg",
+        "successSubtle",
+        "successSubtleFg",
         "warning",
-        "warningFg"
+        "warningFg",
+        "warningSubtle",
+        "warningSubtleFg"
       ]
     },
     {
@@ -2259,11 +2303,13 @@
     },
     {
       "name": "color",
-      "type": "\"accent\" | \"accentFg\" | \"bg\" | \"bgMuted\" | \"bgRaised\" | \"border\" | \"borderStrong\" | \"danger\" | \"dangerFg\" | \"fg\" | \"fgMuted\" | \"focus\" | \"success\" | \"successFg\" | \"warning\" | \"warningFg\"",
+      "type": "\"accent\" | \"accentFg\" | \"accentFillFg\" | \"accentSubtleFg\" | \"bg\" | \"bgMuted\" | \"bgRaised\" | \"border\" | \"borderStrong\" | \"danger\" | \"dangerFg\" | \"dangerSubtleFg\" | \"done\" | \"doneFg\" | \"doneSubtleFg\" | \"fg\" | \"fgMuted\" | \"focus\" | \"neutralSubtleFg\" | \"success\" | \"successFg\" | \"successSubtleFg\" | \"warning\" | \"warningFg\" | \"warningSubtleFg\"",
       "required": false,
       "values": [
         "accent",
         "accentFg",
+        "accentFillFg",
+        "accentSubtleFg",
         "bg",
         "bgMuted",
         "bgRaised",
@@ -2271,13 +2317,20 @@
         "borderStrong",
         "danger",
         "dangerFg",
+        "dangerSubtleFg",
+        "done",
+        "doneFg",
+        "doneSubtleFg",
         "fg",
         "fgMuted",
         "focus",
+        "neutralSubtleFg",
         "success",
         "successFg",
+        "successSubtleFg",
         "warning",
-        "warningFg"
+        "warningFg",
+        "warningSubtleFg"
       ]
     },
     {
@@ -2977,12 +3030,28 @@
     "color.borderStrong": "var(--color-border-strong)",
     "color.accent": "var(--color-accent)",
     "color.accentFg": "var(--color-accent-fg)",
+    "color.accentFill": "var(--color-accent-fill)",
+    "color.accentFillFg": "var(--color-accent-fill-fg)",
     "color.danger": "var(--color-danger)",
     "color.dangerFg": "var(--color-danger-fg)",
     "color.success": "var(--color-success)",
     "color.successFg": "var(--color-success-fg)",
     "color.warning": "var(--color-warning)",
     "color.warningFg": "var(--color-warning-fg)",
+    "color.done": "var(--color-done)",
+    "color.doneFg": "var(--color-done-fg)",
+    "color.neutralSubtle": "var(--color-neutral-subtle)",
+    "color.neutralSubtleFg": "var(--color-neutral-subtle-fg)",
+    "color.accentSubtle": "var(--color-accent-subtle)",
+    "color.accentSubtleFg": "var(--color-accent-subtle-fg)",
+    "color.successSubtle": "var(--color-success-subtle)",
+    "color.successSubtleFg": "var(--color-success-subtle-fg)",
+    "color.warningSubtle": "var(--color-warning-subtle)",
+    "color.warningSubtleFg": "var(--color-warning-subtle-fg)",
+    "color.dangerSubtle": "var(--color-danger-subtle)",
+    "color.dangerSubtleFg": "var(--color-danger-subtle-fg)",
+    "color.doneSubtle": "var(--color-done-subtle)",
+    "color.doneSubtleFg": "var(--color-done-subtle-fg)",
     "color.focus": "var(--color-focus)",
     "color.shadow": "var(--color-shadow)",
     "font.body": "var(--font-body)",

package/dist/docs/migrations/0.7.0.md

@@ -0,0 +1,53 @@
+# 0.7.0
+
+`Brand["color"]` gains two required roles, `accentFill` and `accentFillFg`, and the primary Button and IconButton fill with them instead of `accent` and `accentFg`, so the primary action carries white text in both modes (decision 0119). A brand that lists its colors without spreading a preset no longer type-checks, and one that recolors `accent` alone keeps the preset's blue primary Button.
+
+## Find
+
+In the app's source (`*.ts`, `*.tsx`), every `defineTheme(` call and every object typed `Brand` or `Brand["color"]`: regex `defineTheme\(|(:|satisfies|as)\s*Brand\b|Brand\["color"\]`. An aliased import of `Brand` needs its alias in place of `Brand`. For each, check its `color` object:
+
+- It lists every role itself: it is missing `accentFill` and `accentFillFg`.
+- It spreads a preset's colors (`...defaultBrand.color`) and sets `accent`: it type-checks, but its primary Button stays the preset's blue.
+- It spreads a preset's colors and leaves `accent` alone: no change.
+
+In `*.tsx`, a primary-looking fill drawn by hand from the accent pair, regex `backgroundColor=["{]["']?accent["'}]`, and in `*.css.ts`, `vars\.color\.accent\b` used as a `backgroundColor` beside `vars.color.accentFg`.
+
+## Replace
+
+Add the two roles after `accentFg`, each a `light-dark(<light>, <dark>)` pair. `accentFillFg` must pass 4.5:1 on `accentFill` in both modes, at rest and under the hover tint (`fg` at 15% over the fill); `defineTheme` throws in development if not. Under white text, keep the dark step a shade darker than the light one, since dark mode's hover tint lightens the fill.
+
+```ts
+// before
+color: {
+  // …every other role
+  accent: "light-dark(#1d4ed8, #93c5fd)",
+  accentFg: "light-dark(#fff, #111)",
+  danger: "light-dark(#c62828, #ef9a9a)",
+},
+// after
+color: {
+  // …every other role
+  accent: "light-dark(#1d4ed8, #93c5fd)",
+  accentFg: "light-dark(#fff, #111)",
+  accentFill: "light-dark(#1d4ed8, #1e40af)",
+  accentFillFg: "light-dark(#fff, #fff)",
+  danger: "light-dark(#c62828, #ef9a9a)",
+},
+```
+
+Or take the `default` brand's values: `accentFill: defaultBrand.color.accentFill` and `accentFillFg: defaultBrand.color.accentFillFg` (`light-dark(oklch(0.546 0.19 258), oklch(0.488 0.18 258))` and `light-dark(oklch(1 0 0), oklch(1 0 0))`).
+
+A hand-drawn primary fill takes the new pair:
+
+```tsx
+// before
+<Box backgroundColor="accent" color="accentFg" />
+// after
+<Box backgroundColor="accentFill" color="accentFillFg" />
+```
+
+Leave other `accent` uses alone: links, tabs, checked boxes, pressed chips and Badge's `accent` tone keep `accent` and `accentFg`.
+
+## Verify
+
+Run the app's typecheck (`pnpm typecheck`); it passes with no error naming `accentFill` or `accentFillFg`. Then load a page that renders the theme in development; `defineTheme` throws no contrast error, and a primary Button in dark mode shows white text.

package/dist/docs/migrations/0.8.0.md

@@ -0,0 +1,69 @@
+# 0.8.0
+
+`Brand["color"]` gains fourteen required roles: a violet `done` tone (`done`, `doneFg`) and a subtle fill and text pair for every tone (`neutralSubtle`, `accentSubtle`, `successSubtle`, `warningSubtle`, `dangerSubtle`, `doneSubtle`, each with its `*Fg`), for Badge's new `subtle` variants and Tag's new `variant` (decision 0121). A brand that lists its colors without spreading a preset no longer type-checks, and the neutral Tag's text moves from `fg` to `neutralSubtleFg` on the same gray fill.
+
+## Find
+
+In the app's source (`*.ts`, `*.tsx`), every `defineTheme(` call and every object typed `Brand` or `Brand["color"]`: regex `defineTheme\(|(:|satisfies|as)\s*Brand\b|Brand\["color"\]`. An aliased import of `Brand` needs its alias in place of `Brand`. For each, check its `color` object:
+
+- It lists every role itself: it is missing the fourteen roles.
+- It spreads a preset's colors (`...defaultBrand.color`) and recolors `accent`, `success`, `warning` or `danger`: it type-checks, but that tone's subtle pair stays the preset's.
+- It spreads a preset's colors and recolors no tone: it type-checks, but if it recolors `focus` or `bg`, `defineTheme` now also needs `focus` at 3:1 on each subtle fill and each `*SubtleFg` at 3:1 on `bg`.
+
+The only preset brand, `default`, ships every new role; an app on `brand="default"` needs no theme change.
+
+In `*.tsx`, a subtle status fill or category label drawn by hand: regex `<Tag\b[^>]*(style|className|backgroundColor|color)=` and `<Badge\b[^>]*(style|className|backgroundColor|color)=`, and app tokens named `\w+Subtle\b`.
+
+## Replace
+
+Add the roles after `warningFg`, each a `light-dark(<light>, <dark>)` pair. `doneFg` needs 4.5:1 on `done`, and `done` 4.5:1 on each surface. Each `*SubtleFg` needs 4.5:1 on its fill and 3:1 on `bg`, and `focus` 3:1 on each subtle fill; `defineTheme` throws in development if not.
+
+```ts
+// before
+color: {
+  // …every other role
+  warning: "light-dark(#b45309, #fbbf24)",
+  warningFg: "light-dark(#fff, #111)",
+  focus: "light-dark(#2563eb, #60a5fa)",
+},
+// after
+color: {
+  // …every other role
+  warning: "light-dark(#b45309, #fbbf24)",
+  warningFg: "light-dark(#fff, #111)",
+  done: "light-dark(#7c3aed, #a78bfa)",
+  doneFg: "light-dark(#fff, #111)",
+  neutralSubtle: "light-dark(#f3f4f6, #1f2937)",
+  neutralSubtleFg: "light-dark(#374151, #e5e7eb)",
+  accentSubtle: "light-dark(#dbeafe, #172554)",
+  accentSubtleFg: "light-dark(#1d4ed8, #93c5fd)",
+  successSubtle: "light-dark(#dcfce7, #052e16)",
+  successSubtleFg: "light-dark(#15803d, #86efac)",
+  warningSubtle: "light-dark(#fef3c7, #451a03)",
+  warningSubtleFg: "light-dark(#b45309, #fcd34d)",
+  dangerSubtle: "light-dark(#fee2e2, #450a0a)",
+  dangerSubtleFg: "light-dark(#b91c1c, #fca5a5)",
+  doneSubtle: "light-dark(#ede9fe, #2e1065)",
+  doneSubtleFg: "light-dark(#6d28d9, #c4b5fd)",
+  focus: "light-dark(#2563eb, #60a5fa)",
+},
+```
+
+Or take the `default` brand's values for any of them: `done: defaultBrand.color.done`, and so on for each new role.
+
+A hand-drawn subtle fill takes a variant:
+
+```tsx
+// before
+<Box backgroundColor="bgMuted" color="fgMuted" borderRadius="sm">Merged</Box>
+<Tag style={{ background: app.color.positiveSubtle }}>Docs</Tag>
+// after
+<Badge subtle variant="done">Merged</Badge>
+<Tag variant="success">Docs</Tag>
+```
+
+A neutral Tag that must keep `fg` text sets it: `<Tag color="fg">`.
+
+## Verify
+
+Run the app's typecheck (`pnpm typecheck`); it passes with no error naming a `*Subtle` role, `done` or `doneFg`. Then load a page that renders the theme in development; `defineTheme` throws no contrast error, and a `<Badge subtle variant="done">` shows violet text on a pale violet fill in light mode and light violet on deep violet in dark mode.

package/dist/docs/theming.md

@@ -26,7 +26,13 @@ import { defaultBrand } from "@jonmilner/ui/brands";
 const inbox = defineTheme({
   ...defaultBrand,
   name: "inbox",
-  color: { ...defaultBrand.color, accent: "light-dark(#b00020, #ff8a80)" },
+  color: {
+    ...defaultBrand.color,
+    accent: "light-dark(#b00020, #ff8a80)",
+    accentFill: "light-dark(#b00020, #8e001a)",
+    accentSubtle: "light-dark(#fde2e4, #3b0008)",
+    accentSubtleFg: "light-dark(#b00020, #ff8a80)",
+  },
 });
 
 <ThemeProvider theme={inbox} mode="system">
@@ -34,10 +40,14 @@ const inbox = defineTheme({
 </ThemeProvider>;
 ```
 
+`accent` colors links, tabs, checked boxes and pressed chips, and is also text on a surface; `accentFill` is the primary Button's solid fill, with `accentFillFg` text on it in both modes. Recolor both together, and the accent's subtle pair so an accent Tag or subtle Badge turns red too.
+
+Each tone (`neutral`, `accent`, `success`, `warning`, `danger`, `done`) also has a subtle pair, `<tone>Subtle` with `<tone>SubtleFg` text, for Badge's `subtle` variants and Tag's fills. Recolor a tone's subtle pair with it: the text needs 4.5:1 on its fill and 3:1 on `bg`, and `focus` 3:1 on the fill.
+
 `defineTheme(brand)` takes a full `Brand`: every color role as `light-dark(<light>, <dark>)` and every font role. A missing role is a type error. It returns CSS that `ThemeProvider` renders as `<style href precedence="ui-theme">`; React hoists it into `<head>` and renders it once per name.
 
 - **Give a custom brand its own name.** A theme applies page-wide, not only inside its provider: a theme named `default` recolors every `default` provider on the page. The name must be a CSS identifier.
-- **Contrast is checked in development.** Outside production, `defineTheme` throws when a text, fill or focus pair fails WCAG AA in either mode, and lists the pairs. It also checks text on component fills mixed from your roles, such as the dark-mode menu highlight (`fg` 10% into `bgRaised`), where `fg`, `fgMuted` and `danger` need 4.5:1 too, and Button's hover (`fg` 15% over each variant's fill), where `fg`, `accentFg` and `dangerFg` need 4.5:1 on `bg`, `accent` and `danger` tinted. The roles a fill mixes must be opaque. Colors must be literal: hex, `rgb()`, `oklab()`, `oklch()`, `color-mix()` or `light-dark()`. Named colors other than `white`, `black` and `transparent` are rejected, as is a translucent background. `var()` may only reference another color role (`var(--color-accent)`).
+- **Contrast is checked in development.** Outside production, `defineTheme` throws when a text, fill or focus pair fails WCAG AA in either mode, and lists the pairs. It also checks text on component fills mixed from your roles, such as the dark-mode menu highlight (`fg` 10% into `bgRaised`), where `fg`, `fgMuted` and `danger` need 4.5:1 too, and Button's hover (`fg` 15% over each variant's fill), where `fg`, `accentFillFg` and `dangerFg` need 4.5:1 on `bg`, `accentFill` and `danger` tinted, and a pressed Chip's, where `accentFg` does on `accent`. The roles a fill mixes must be opaque. Colors must be literal: hex, `rgb()`, `oklab()`, `oklch()`, `color-mix()` or `light-dark()`. Named colors other than `white`, `black` and `transparent` are rejected, as is a translucent background. `var()` may only reference another color role (`var(--color-accent)`).
 - **Override theme tokens in unlayered CSS or in the theme itself.** The theme is unlayered, so a token set in `@layer app` loses to it. Preset tokens live in `@layer tokens` and can be overridden from `@layer app`.
 - **Fallback faces are global.** A brand font's fallback faces are named for the web font and the local font, `"<Family> Fallback <Local>"` (`"Inter Fallback Arial"`). The theme declares only faces `base.css` lacks. A font reusing a family name must agree with every face it shares, weight and style included: a fallback listing fewer variants (such as capsize's per-font `arial` import) reuses the others' faces, but one that sizes a shared face differently, or adds a weight or style to a preset's family, throws.
 - **Values must be plain.** Color values and font names may not contain CSS syntax (`;`, braces, `<`, `>`, `\`, `!`, `/*`) or, for font names, quotes; `defineTheme` throws in every mode.