@cueplusplus/ui 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @cueplusplus/ui
 
+## 0.24.0
+
+### Minor Changes
+
+- 082ef7c: **A focused field's ring is faint now, and you set how faint.** A text field shows its focus ring
+  on a mouse click as well as on Tab, so a full-strength `--cue-focus` ring (pure white on the
+  default theme) lit up every clicked field like a box. Every recessed field (inputs, textareas,
+  selects, comboboxes, the date, colour and number fields, grouped fields) now draws
+  `--cue-focus` mixed to **15%**, and its border still lifts to `border-strong` on focus.
+
+  - **`--cue-style-field-focus-mix`** sets the share, from `0%` (no ring, only the border lift) to
+    `100%` (the full ring). Name it in a style set, or on any element:
+    `style={{ "--cue-style-field-focus-mix": "40%" }}`.
+  - **Inside `data-field-edge="contrast"`** the ring is back at 100%, beside the 3:1 edge.
+  - **An invalid field** keeps its danger border, and its ring turns red at the same share.
+  - Buttons, tabs, links and every other control keep their full ring, which only shows to a
+    keyboard.
+
+### Patch Changes
+
+- Updated dependencies [082ef7c]
+  - @cueplusplus/tokens@0.24.0
+
+## 0.23.0
+
+### Minor Changes
+
+- dae9dec: **A field's edge can reach 3:1: `data-field-edge="contrast"`** (cue-ui-60). Every shipped theme's
+  `--cue-border` measured 1.07:1 to 2.02:1 against `surface-1`, under WCAG 1.4.11's 3:1 for the line
+  that marks out where to type. The border stays as it is, because it is a box edge and a quiet one on
+  purpose, and a field's edge becomes a role of its own.
+
+  - **`--cue-field-edge`** is each block's border moved toward its ink until it clears 3:1 on its
+    `surface-1`, written per block as a literal. Every theme package, `theme-base`'s own palette and
+    `createTheme()` write it, and the contrast report holds it to 3:1 as the required pair
+    `field-edge/surface-1`.
+  - **Opt in with `data-field-edge="contrast"`** on any element, `<html>` included. Every recessed
+    control inside then draws its resting edge in `--cue-field-edge`, disabled ones too, and over a
+    paint pack's stroke. Hover, focus and invalid edges keep their own colours. Outside the attribute,
+    nothing changes.
+  - **`edgeToContrast(edge, ground, toward, minimum = 3)`** is the arithmetic, exported from
+    `@cueplusplus/theme-base/contrast` and `@cueplusplus/ui/theming`.
+  - `@cueplusplus/tokens` publishes `field-edge` as a derived name, with `var(--cue-border)` as its
+    template. A stylesheet built before this release falls back to the plain border.
+
+  **For a theme package of your own:** `theme-tools` now writes one more line per block. Run
+  `generate` once after upgrading; until then `check` reports the stylesheet out of date.
+
+- 39884b3: **`MarkdownText` renders GitHub tables** (cue-ui-58). An agent's table used to arrive as one
+  paragraph of pipes: the parser read CommonMark only, and the sanitizer allowed no table elements.
+  Tables are now the one part of GFM the parser reads. Each column is aligned as its delimiter row
+  says, header cells sit on `surface-2`, and the table scrolls sideways inside a named,
+  keyboard-reachable region rather than widening the turn. Task lists, footnotes and autolink literals
+  stay out, and raw HTML is still refused: a cell's markup is text, and alignment is the only style a
+  cell carries.
+
+  **`remarkPlugins`** adds parser plugins after the table syntax. It is a seam for the parser, not
+  for the page: whatever a plugin puts in the tree passes the same sanitizer, so it can change what
+  the markdown means but cannot widen what renders.
+
+  ### Migrating
+  - **`@cueplusplus/ui/elements/markdown` has two more optional peers**, the table half of GFM:
+    `pnpm add micromark-extension-gfm-table mdast-util-gfm-table`. Like `react-markdown` and
+    `rehype-sanitize`, they are needed only where this subpath is imported. A build that imports it
+    without them fails to resolve the module, and names it.
+
+### Patch Changes
+
+- Updated dependencies [dae9dec]
+  - @cueplusplus/tokens@0.23.0
+  - @cueplusplus/theme-base@1.4.0
+
 ## 0.22.0
 
 ### Minor Changes

package/README.md

@@ -105,7 +105,7 @@ their own, so importing a button never pulls a charting library into your bundle
 | `@cueplusplus/ui/chat` | the multi-agent transcript: messages, composer, HITL questions, agent colour |
 | `@cueplusplus/ui/agent-runtime` | the streaming layer under Chat; needs `@assistant-ui/react` |
 | `@cueplusplus/ui/elements` | the agent's own surface, vendored from assistant-ui and repainted onto the tokens; needs `lucide-react` and `heat-graph` (+ `./elements.css`) |
-| `@cueplusplus/ui/elements/markdown` | `MarkdownText`; needs `react-markdown`, `rehype-sanitize` |
+| `@cueplusplus/ui/elements/markdown` | `MarkdownText`; needs `react-markdown`, `rehype-sanitize`, `micromark-extension-gfm-table`, `mdast-util-gfm-table` |
 | `@cueplusplus/ui/elements/generative` | the generative-UI renderer and its spec (+ `./elements/generative.css`) |
 | `@cueplusplus/ui/elements/replay` | the scripted session-replay frame |
 | `@cueplusplus/ui/dmx` | 512 bytes at wire rate: the bar, the strip, the patch bar, the channel grid |

package/dist/elements/markdown.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import Markdown from "react-markdown";
 //#region src/elements/markdown.d.ts
 /** A fenced block, handed to a highlighter that was opted into. */
 interface MarkdownCodeBlock {
@@ -50,6 +51,16 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
    * behaviour they inherited.
    */
   renderCodeBlock?: (block: MarkdownCodeBlock) => React.ReactNode;
+  /**
+   * More remark plugins, run after the component's own table syntax.
+   *
+   * A seam for the parser, not for the page: whatever a plugin adds to the
+   * tree still passes the same sanitizer, so a plugin can change what the
+   * markdown *means* — a mention syntax, a glossary link — but cannot widen
+   * what renders. An element outside the subset is dropped, and an attribute
+   * the schema does not name never arrives.
+   */
+  remarkPlugins?: React.ComponentProps<typeof Markdown>["remarkPlugins"];
 }
 /**
  * Model output, rendered.
@@ -84,9 +95,11 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
  * - **Attributes are enumerated, not filtered.** An element that is not in the
  *   schema renders nothing; an element that is renders only the attributes
  *   named beside it — `href`/`title` on a link, `src`/`alt`/`title` on an
- *   image, `language-…` on a `code`. No element in the subset accepts `id`,
+ *   image, `language-…` on a `code`, and `align` on a table cell, held to
+ *   `left`, `center` or `right`. No element in the subset accepts `id`,
  *   `style`, `srcset`, `formaction` or any `on*` handler, so none of them has
- *   an attribute to arrive on.
+ *   an attribute to arrive on; the one inline style anything carries is a
+ *   cell's `text-align`, which the renderer writes from that `align`.
  * - **URLs are allow-listed twice.** `http`, `https` and `mailto` on both
  *   `href` and `src`; a relative URL stays relative; everything else — a
  *   `javascript:` link, a `data:text/html` image, `vbscript:`, `blob:`,
@@ -98,10 +111,14 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
  *
  * **The subset.** Paragraphs, ATX and setext headings, bullet and ordered
  * lists, block quotes, thematic breaks, fenced and indented code, inline code,
- * emphasis, strong, strikethrough, links, images, and hard breaks. No GFM
- * plugin is enabled, so no tables, task lists, footnotes or autolink literals —
- * an explicit `<https://…>` autolink still works. Fenced blocks are plain text
- * unless {@link MarkdownTextProps.renderCodeBlock} is given.
+ * emphasis, strong, strikethrough, links, images, hard breaks, and GitHub
+ * tables. Tables are the one part of GFM the parser reads, each column aligned
+ * as its delimiter row says and wrapped in a named region that scrolls
+ * sideways; task lists, footnotes and autolink literals stay out — an explicit
+ * `<https://…>` autolink still works. Fenced blocks are plain text unless
+ * {@link MarkdownTextProps.renderCodeBlock} is given, and
+ * {@link MarkdownTextProps.remarkPlugins} adds parser plugins without widening
+ * the subset.
  *
  * **Streaming.** Pass `streaming` while the turn is arriving and the token the
  * model is halfway through typing is hidden rather than rendered as
@@ -110,10 +127,11 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
  * words appear as they arrive; only their formatting waits for the closing
  * token.
  *
- * `react-markdown` and `rehype-sanitize` are optional peers of this subpath
- * alone, which is why this component is not re-exported from
+ * `react-markdown`, `rehype-sanitize` and GFM's table pair
+ * (`micromark-extension-gfm-table`, `mdast-util-gfm-table`) are optional peers
+ * of this subpath alone, which is why this component is not re-exported from
  * `@cueplusplus/ui/elements`: a console that renders a transcript without
- * markdown should install neither.
+ * markdown should install none of them.
  *
  * @example
  * <Message agent="researcher">
@@ -125,6 +143,8 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
  * <MarkdownText renderCodeBlock={({ language, code }) => <Highlight lang={language} code={code} />}>
  *   {answer}
  * </MarkdownText>
+ * @example
+ * <MarkdownText remarkPlugins={[remarkMentions]}>{turn.text}</MarkdownText>
  */
 declare const MarkdownText: React.ForwardRefExoticComponent<MarkdownTextProps & React.RefAttributes<HTMLDivElement>>;
 //#endregion

package/dist/elements/markdown.js

@@ -4,6 +4,8 @@ import { FOCUS_RING } from "../system/_focus-ring.js";
 import { codeScroll, codeSurface, field, mono } from "./surfaces.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
+import { gfmTableFromMarkdown } from "mdast-util-gfm-table";
+import { gfmTable } from "micromark-extension-gfm-table";
 import Markdown from "react-markdown";
 import rehypeSanitize from "rehype-sanitize";
 //#region src/elements/markdown.tsx
@@ -19,9 +21,13 @@ import rehypeSanitize from "rehype-sanitize";
 * `MarkdownText`'s JSDoc quotes it, and a test asserts nothing outside it
 * survives.
 *
+* The six table elements are here because GFM's table syntax is the one part
+* of GFM the parser reads (see {@link remarkTables}): a table is inert, and it
+* is how an agent presents a comparison.
+*
 * Deliberately absent, and each for a reason: `input` (GFM task lists would
-* put a control inside a transcript), `table` and friends (no GFM plugin is
-* enabled, so the parser never produces them), `svg`/`math` (an untrusted
+* put a control inside a transcript), `sup`/`section` (footnotes, which a
+* reply does not need), `svg`/`math` (an untrusted
 * vector is a script host in several browsers' history), `details`/`summary`
 * (disclosure is a component, not a token stream), and every sectioning or
 * embedding tag — `iframe`, `object`, `embed`, `script`, `style`, `form`.
@@ -46,6 +52,12 @@ const ALLOWED_TAGS = [
 	"p",
 	"pre",
 	"strong",
+	"table",
+	"tbody",
+	"td",
+	"th",
+	"thead",
+	"tr",
 	"ul"
 ];
 /**
@@ -72,6 +84,9 @@ const ALLOWED_PROTOCOLS = [
 * handler unreachable by construction instead of by deny-list. `code` may
 * carry a `className`, and only one matching `language-…`, because that is how
 * a fenced block's info string reaches {@link MarkdownTextProps.renderCodeBlock}.
+* A table cell may carry `align`, and only one of the three values the
+* delimiter row can write; the renderer turns it into `text-align`, which is
+* the one inline style anything in this surface ever carries.
 */
 const SCHEMA = {
 	tagNames: [...ALLOWED_TAGS],
@@ -84,6 +99,18 @@ const SCHEMA = {
 		],
 		code: [["className", /^language-[\w+#.-]+$/]],
 		ol: ["start"],
+		th: [[
+			"align",
+			"left",
+			"center",
+			"right"
+		]],
+		td: [[
+			"align",
+			"left",
+			"center",
+			"right"
+		]],
 		"*": []
 	},
 	protocols: {
@@ -304,6 +331,20 @@ function sealStream(source) {
 	for (let index = 0; index < tail.length; index += 1) if (!erase.has(index)) sealed += tail[index];
 	return head + sealed;
 }
+/**
+* GitHub's table syntax, as a remark plugin, and nothing else from GFM.
+*
+* `remark-gfm` would bring task lists (a checkbox in a transcript), footnotes
+* and autolink literals along with tables. This registers the table tokenizer
+* and its tree handlers alone, which is what `remark-gfm` itself does for each
+* of its five extensions, one at a time. The sanitizer still decides what a
+* table may render as: the six elements and a cell's `align`.
+*/
+function remarkTables() {
+	const data = this.data();
+	(data.micromarkExtensions ??= []).push(gfmTable());
+	(data.fromMarkdownExtensions ??= []).push(gfmTableFromMarkdown());
+}
 /** The text and info string of a fenced block, read off its hast node. */
 function readCodeBlock(node) {
 	const code = node?.children?.find((child) => child.tagName === "code");
@@ -347,9 +388,11 @@ function readCodeBlock(node) {
 * - **Attributes are enumerated, not filtered.** An element that is not in the
 *   schema renders nothing; an element that is renders only the attributes
 *   named beside it — `href`/`title` on a link, `src`/`alt`/`title` on an
-*   image, `language-…` on a `code`. No element in the subset accepts `id`,
+*   image, `language-…` on a `code`, and `align` on a table cell, held to
+*   `left`, `center` or `right`. No element in the subset accepts `id`,
 *   `style`, `srcset`, `formaction` or any `on*` handler, so none of them has
-*   an attribute to arrive on.
+*   an attribute to arrive on; the one inline style anything carries is a
+*   cell's `text-align`, which the renderer writes from that `align`.
 * - **URLs are allow-listed twice.** `http`, `https` and `mailto` on both
 *   `href` and `src`; a relative URL stays relative; everything else — a
 *   `javascript:` link, a `data:text/html` image, `vbscript:`, `blob:`,
@@ -361,10 +404,14 @@ function readCodeBlock(node) {
 *
 * **The subset.** Paragraphs, ATX and setext headings, bullet and ordered
 * lists, block quotes, thematic breaks, fenced and indented code, inline code,
-* emphasis, strong, strikethrough, links, images, and hard breaks. No GFM
-* plugin is enabled, so no tables, task lists, footnotes or autolink literals —
-* an explicit `<https://…>` autolink still works. Fenced blocks are plain text
-* unless {@link MarkdownTextProps.renderCodeBlock} is given.
+* emphasis, strong, strikethrough, links, images, hard breaks, and GitHub
+* tables. Tables are the one part of GFM the parser reads, each column aligned
+* as its delimiter row says and wrapped in a named region that scrolls
+* sideways; task lists, footnotes and autolink literals stay out — an explicit
+* `<https://…>` autolink still works. Fenced blocks are plain text unless
+* {@link MarkdownTextProps.renderCodeBlock} is given, and
+* {@link MarkdownTextProps.remarkPlugins} adds parser plugins without widening
+* the subset.
 *
 * **Streaming.** Pass `streaming` while the turn is arriving and the token the
 * model is halfway through typing is hidden rather than rendered as
@@ -373,10 +420,11 @@ function readCodeBlock(node) {
 * words appear as they arrive; only their formatting waits for the closing
 * token.
 *
-* `react-markdown` and `rehype-sanitize` are optional peers of this subpath
-* alone, which is why this component is not re-exported from
+* `react-markdown`, `rehype-sanitize` and GFM's table pair
+* (`micromark-extension-gfm-table`, `mdast-util-gfm-table`) are optional peers
+* of this subpath alone, which is why this component is not re-exported from
 * `@cueplusplus/ui/elements`: a console that renders a transcript without
-* markdown should install neither.
+* markdown should install none of them.
 *
 * @example
 * <Message agent="researcher">
@@ -388,8 +436,10 @@ function readCodeBlock(node) {
 * <MarkdownText renderCodeBlock={({ language, code }) => <Highlight lang={language} code={code} />}>
 *   {answer}
 * </MarkdownText>
+* @example
+* <MarkdownText remarkPlugins={[remarkMentions]}>{turn.text}</MarkdownText>
 */
-const MarkdownText = React.forwardRef(function MarkdownText({ className, children, streaming = false, target = "_blank", headingLevel = 2, renderCodeBlock, ...elementProps }, ref) {
+const MarkdownText = React.forwardRef(function MarkdownText({ className, children, streaming = false, target = "_blank", headingLevel = 2, renderCodeBlock, remarkPlugins, ...elementProps }, ref) {
 	const source = streaming ? sealStream(children) : children;
 	const components = React.useMemo(() => markdownComponents({
 		target,
@@ -408,6 +458,7 @@ const MarkdownText = React.forwardRef(function MarkdownText({ className, childre
 		...elementProps,
 		children: /* @__PURE__ */ jsx(Markdown, {
 			components,
+			remarkPlugins: [remarkTables, ...remarkPlugins ?? []],
 			rehypePlugins: [[rehypeSanitize, SCHEMA]],
 			skipHtml: true,
 			urlTransform: safeUrl,
@@ -522,7 +573,45 @@ function markdownComponents(options) {
 					children: renderCodeBlock(block)
 				})
 			});
-		}
+		},
+		table: ({ children }) => /* @__PURE__ */ jsx("div", {
+			role: "region",
+			"aria-label": "Table",
+			tabIndex: 0,
+			"data-slot": "markdown-table-scroll",
+			className: cn("rounded-control border border-border outline-none", codeScroll, FOCUS_RING),
+			children: /* @__PURE__ */ jsx("table", {
+				"data-slot": "markdown-table",
+				className: "w-full border-collapse text-(length:--cue-text-ui)",
+				children
+			})
+		}),
+		thead: ({ children }) => /* @__PURE__ */ jsx("thead", {
+			"data-slot": "markdown-table-head",
+			className: "bg-surface-2",
+			children
+		}),
+		tbody: ({ children }) => /* @__PURE__ */ jsx("tbody", {
+			"data-slot": "markdown-table-body",
+			children
+		}),
+		tr: ({ children }) => /* @__PURE__ */ jsx("tr", {
+			"data-slot": "markdown-table-row",
+			className: "border-b border-border last:border-b-0",
+			children
+		}),
+		th: ({ children, style }) => /* @__PURE__ */ jsx("th", {
+			"data-slot": "markdown-table-header",
+			style,
+			className: "px-(--cue-space-3) py-(--cue-space-2) text-start align-bottom font-medium text-fg",
+			children
+		}),
+		td: ({ children, style }) => /* @__PURE__ */ jsx("td", {
+			"data-slot": "markdown-table-cell",
+			style,
+			className: "px-(--cue-space-3) py-(--cue-space-2) align-top text-fg",
+			children
+		})
 	};
 }
 //#endregion

package/dist/forms/_chassis.d.ts

@@ -35,6 +35,15 @@ import { FormControlSize } from "./_chassis-size.js";
  * as it does on Tab. Only the non-typing controls that ride this chassis — the
  * `Select` trigger, the date triggers — actually distinguish the two.
  *
+ * **And quiet means faint** (the owner's call, 2026-10-09). At full strength a
+ * white `--cue-focus` ring around every clicked field read as a glaring box, so
+ * the ring is `--cue-focus` mixed with transparent to
+ * `--cue-style-field-focus-mix`: 15% unless a style set, `:root` or any subtree
+ * names another share (`_focus-ring-field.ts`). The rim's lift to
+ * `border-strong` carries the rest of the signal. The 3:1 paragraphs below
+ * hold for the `--cue-focus` role itself, and so for the ring at 100%, which
+ * is what `data-field-edge="contrast"` restores for a reader who needs it.
+ *
  * `--cue-focus`, not `--cue-accent`. Every theme ships both roles, and keeping
  * them separable is what WCAG 1.4.11 needs: one role whose job is "read at 3:1
  * against the surface behind the ring", independent of the role whose job is
@@ -77,9 +86,10 @@ import { FormControlSize } from "./_chassis-size.js";
  * while focused. Pushing the ring off the rim would mean either floating it on
  * a gap (WCAG 2.4.13 then wants 3px, and the halo is back) or insetting it
  * further (which buries it deeper). So the ring takes the danger colour instead
- * — `data-[invalid]:focus-visible:outline-danger` — which is the ruling shadcn
- * and Radix both reached: the border stays danger, the ring communicates focus,
- * and red communicates invalid whichever of the two is painting.
+ * — `--cue-danger` at the same faint share as the focus ring — which is the
+ * ruling shadcn and Radix both reached: the border stays danger, the ring
+ * communicates focus, and red communicates invalid whichever of the two is
+ * painting. At the faint share the danger rim shows through the ring.
  *
  * The compound modifier outranks the plain one on specificity — an attribute
  * selector and a pseudo-class against one pseudo-class — so its position in
@@ -105,7 +115,10 @@ import { FormControlSize } from "./_chassis-size.js";
  * **`field-ground`** is `styles.css`'s opt-in relative fill (spec
  * 2026-10-08-field-ground R3): inside `[data-field-ground="relative"]` it
  * re-declares this field's own `--cue-sunken` one step off the ground it stands
- * on; anywhere else it compiles to nothing that applies.
+ * on; anywhere else it compiles to nothing that applies. The same hook carries
+ * the contrast edge (cue-ui-60): inside `[data-field-edge="contrast"]` this
+ * field's resting stroke reads `--cue-field-edge`, its theme's border moved to
+ * 3:1 on `surface-1`.
  *
  * **The resting shade** ({@link REST_SHADE_CLASS}, spec §3.10) is the one
  * shadow this recipe draws: the stroke paints a border and a ground and no
@@ -115,7 +128,7 @@ import { FormControlSize } from "./_chassis-size.js";
  * own `shadow-` utility replaces it through `twMerge`, as it would have
  * replaced nothing before.
  */
-declare const controlSurface = "w-full field-ground rounded-[var(--cue-style-field-radius,calc(var(--cue-style-control-radius,var(--cue-radius-control))*var(--cue-radius-scale)))] border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-style-field-fill,var(--cue-sunken)),var(--cue-style-field-fill,var(--cue-sunken))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] bg-origin-border [background-clip:padding-box,border-box] shadow-[shadow:0_calc(2px*var(--cue-paint-shadow-scale))_calc(4px*var(--cue-paint-shadow-scale))_var(--cue-paint-rest-shade,transparent)] font-[family-name:var(--cue-style-input-face,var(--cue-font-mono))] font-[number:var(--cue-style-body-weight,inherit)] text-fg placeholder:text-fg-subtle outline-none hover:border-[color:var(--cue-style-field-hover-edge,transparent)] focus:border-[color:var(--cue-style-focus-edge,var(--cue-border-strong))] focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus) focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)] disabled:opacity-[var(--cue-style-disabled-opacity,0.4)] data-[disabled]:opacity-[var(--cue-style-disabled-opacity,0.4)] disabled:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken))),var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken)))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[disabled]:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken))),var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken)))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[invalid]:border-danger data-[invalid]:focus-visible:outline-danger";
+declare const controlSurface = "w-full field-ground rounded-[var(--cue-style-field-radius,calc(var(--cue-style-control-radius,var(--cue-radius-control))*var(--cue-radius-scale)))] border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-style-field-fill,var(--cue-sunken)),var(--cue-style-field-fill,var(--cue-sunken))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] bg-origin-border [background-clip:padding-box,border-box] shadow-[shadow:0_calc(2px*var(--cue-paint-shadow-scale))_calc(4px*var(--cue-paint-shadow-scale))_var(--cue-paint-rest-shade,transparent)] font-[family-name:var(--cue-style-input-face,var(--cue-font-mono))] font-[number:var(--cue-style-body-weight,inherit)] text-fg placeholder:text-fg-subtle outline-none hover:border-[color:var(--cue-style-field-hover-edge,transparent)] focus:border-[color:var(--cue-style-focus-edge,var(--cue-border-strong))] focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-[color:color-mix(in_oklab,var(--cue-focus)_var(--cue-style-field-focus-mix,15%),transparent)] focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)] disabled:opacity-[var(--cue-style-disabled-opacity,0.4)] data-[disabled]:opacity-[var(--cue-style-disabled-opacity,0.4)] disabled:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken))),var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken)))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[disabled]:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken))),var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken)))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[invalid]:border-danger data-[invalid]:focus-visible:outline-[color:color-mix(in_oklab,var(--cue-danger)_var(--cue-style-field-focus-mix,15%),transparent)]";
 /**
  * The full recessed-control recipe, one variant per rung of the control ladder.
  *
@@ -185,6 +198,6 @@ declare const bareControlClasses = "min-w-0 flex-1 border-0 bg-transparent p-0 f
  * pass's browser run caught it (`form-focus.spec.ts`, a grouped field). The
  * wrapper never takes focus itself, so `:has(:focus)` is the same test.
  */
-declare const controlGroupFocusClasses = "has-focus:border-border-strong has-focus-visible:outline-solid has-focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] has-focus-visible:outline-(--cue-focus) has-focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)] data-[invalid]:has-focus-visible:outline-danger";
+declare const controlGroupFocusClasses = "has-focus:border-border-strong has-focus-visible:outline-solid has-focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] has-focus-visible:outline-[color:color-mix(in_oklab,var(--cue-focus)_var(--cue-style-field-focus-mix,15%),transparent)] has-focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)] data-[invalid]:has-focus-visible:outline-[color:color-mix(in_oklab,var(--cue-danger)_var(--cue-style-field-focus-mix,15%),transparent)]";
 //#endregion
 export { ControlVariantProps, type FormControlSize, bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants };

package/dist/forms/_chassis.js

@@ -42,6 +42,15 @@ import { INPUT_FACE } from "../system/_style-input-face.js";
 * as it does on Tab. Only the non-typing controls that ride this chassis — the
 * `Select` trigger, the date triggers — actually distinguish the two.
 *
+* **And quiet means faint** (the owner's call, 2026-10-09). At full strength a
+* white `--cue-focus` ring around every clicked field read as a glaring box, so
+* the ring is `--cue-focus` mixed with transparent to
+* `--cue-style-field-focus-mix`: 15% unless a style set, `:root` or any subtree
+* names another share (`_focus-ring-field.ts`). The rim's lift to
+* `border-strong` carries the rest of the signal. The 3:1 paragraphs below
+* hold for the `--cue-focus` role itself, and so for the ring at 100%, which
+* is what `data-field-edge="contrast"` restores for a reader who needs it.
+*
 * `--cue-focus`, not `--cue-accent`. Every theme ships both roles, and keeping
 * them separable is what WCAG 1.4.11 needs: one role whose job is "read at 3:1
 * against the surface behind the ring", independent of the role whose job is
@@ -84,9 +93,10 @@ import { INPUT_FACE } from "../system/_style-input-face.js";
 * while focused. Pushing the ring off the rim would mean either floating it on
 * a gap (WCAG 2.4.13 then wants 3px, and the halo is back) or insetting it
 * further (which buries it deeper). So the ring takes the danger colour instead
-* — `data-[invalid]:focus-visible:outline-danger` — which is the ruling shadcn
-* and Radix both reached: the border stays danger, the ring communicates focus,
-* and red communicates invalid whichever of the two is painting.
+* — `--cue-danger` at the same faint share as the focus ring — which is the
+* ruling shadcn and Radix both reached: the border stays danger, the ring
+* communicates focus, and red communicates invalid whichever of the two is
+* painting. At the faint share the danger rim shows through the ring.
 *
 * The compound modifier outranks the plain one on specificity — an attribute
 * selector and a pseudo-class against one pseudo-class — so its position in
@@ -112,7 +122,10 @@ import { INPUT_FACE } from "../system/_style-input-face.js";
 * **`field-ground`** is `styles.css`'s opt-in relative fill (spec
 * 2026-10-08-field-ground R3): inside `[data-field-ground="relative"]` it
 * re-declares this field's own `--cue-sunken` one step off the ground it stands
-* on; anywhere else it compiles to nothing that applies.
+* on; anywhere else it compiles to nothing that applies. The same hook carries
+* the contrast edge (cue-ui-60): inside `[data-field-edge="contrast"]` this
+* field's resting stroke reads `--cue-field-edge`, its theme's border moved to
+* 3:1 on `surface-1`.
 *
 * **The resting shade** ({@link REST_SHADE_CLASS}, spec §3.10) is the one
 * shadow this recipe draws: the stroke paints a border and a ground and no
@@ -122,7 +135,7 @@ import { INPUT_FACE } from "../system/_style-input-face.js";
 * own `shadow-` utility replaces it through `twMerge`, as it would have
 * replaced nothing before.
 */
-const controlSurface = `w-full field-ground ${FIELD_RADIUS} ${STROKE_SUNKEN} ${REST_SHADE_CLASS} ${INPUT_FACE} ${BODY_WEIGHT} text-fg placeholder:text-fg-subtle outline-none ${FIELD_HOVER_EDGE} focus:border-[color:var(--cue-style-focus-edge,var(--cue-border-strong))] ${FOCUS_RING_FIELD} ${DISABLED_OPACITY} ${DATA_DISABLED_OPACITY} ${FIELD_DISABLED_FILL} ${INVALID_EDGE} data-[invalid]:focus-visible:outline-danger`;
+const controlSurface = `w-full field-ground ${FIELD_RADIUS} ${STROKE_SUNKEN} ${REST_SHADE_CLASS} ${INPUT_FACE} ${BODY_WEIGHT} text-fg placeholder:text-fg-subtle outline-none ${FIELD_HOVER_EDGE} focus:border-[color:var(--cue-style-focus-edge,var(--cue-border-strong))] ${FOCUS_RING_FIELD} ${DISABLED_OPACITY} ${DATA_DISABLED_OPACITY} ${FIELD_DISABLED_FILL} ${INVALID_EDGE} data-[invalid]:focus-visible:outline-[color:color-mix(in_oklab,var(--cue-danger)_var(--cue-style-field-focus-mix,15%),transparent)]`;
 /**
 * The full recessed-control recipe, one variant per rung of the control ladder.
 *
@@ -195,6 +208,6 @@ const bareControlClasses = `min-w-0 flex-1 border-0 bg-transparent p-0 ${INPUT_F
 * pass's browser run caught it (`form-focus.spec.ts`, a grouped field). The
 * wrapper never takes focus itself, so `:has(:focus)` is the same test.
 */
-const controlGroupFocusClasses = `has-focus:border-border-strong ${FOCUS_RING_GROUP_FIELD} data-[invalid]:has-focus-visible:outline-danger`;
+const controlGroupFocusClasses = `has-focus:border-border-strong ${FOCUS_RING_GROUP_FIELD} data-[invalid]:has-focus-visible:outline-[color:color-mix(in_oklab,var(--cue-danger)_var(--cue-style-field-focus-mix,15%),transparent)]`;
 //#endregion
 export { bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants };

package/dist/primitives/chip.d.ts

@@ -2,7 +2,7 @@ import { ClassProp, VariantProps } from "../lib/cva.js";
 import * as React from "react";
 //#region src/primitives/chip.d.ts
 declare const chipVariants: (props?: ({
-  tone?: "danger" | "info" | "warn" | "busy" | "accent" | "ok" | "neutral" | null | undefined;
+  tone?: "danger" | "info" | "warn" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
   variant?: "outline" | "tinted" | "tag" | null | undefined;
   interactive?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/dist/styles.css

@@ -179,9 +179,28 @@
  * the chain the stroke already reads, `var(--cue-style-field-fill,
  * var(--cue-sunken))`: a named fill still wins, a disabled field follows, and
  * no field's class grows by more than this utility's name. A consumer's own
- * field can wear `field-ground` too. */
+ * field can wear `field-ground` too.
+ *
+ * The contrast edge (cue-ui-60), and opt-in too. A theme's `--cue-border` is a
+ * box edge, quiet on purpose, and against `surface-1` it measured 1.07:1 to
+ * 2.02:1 in every shipped theme: under WCAG 1.4.11's 3:1 for the line that
+ * marks out where to type. `--cue-field-edge` is that border moved toward the
+ * ink until it clears 3:1 (each theme writes it per block, as a literal), and
+ * inside an ancestor carrying `data-field-edge="contrast"` a field's resting
+ * stroke reads it. Declared on the field for the reason the fill is: resolved
+ * here, it is the theme the field stands in, island or not. It sets both ends
+ * of the stroke, so it wins over a paint pack's gradient edge — the opt-in is
+ * a reader's need, and a pack is a look. The hover, focus and invalid edges are
+ * their own colours and do not move. Same hook as the relative fill, so no
+ * field's class grows for it. */
 @utility field-ground {
   :where([data-field-ground="relative"]) & {
     --cue-sunken: color-mix(in oklab, var(--cue-ground, var(--cue-bg)), var(--cue-style-field-toward, var(--cue-fg)) var(--cue-style-field-step, 6%));
   }
+  :where([data-field-edge="contrast"]) & {
+    --cue-paint-stroke-from: var(--cue-field-edge, var(--cue-border));
+    --cue-paint-stroke-to: var(--cue-field-edge, var(--cue-border));
+    /* The full focus ring too: a field's is faint by default (`_focus-ring-field.ts`). */
+    --cue-style-field-focus-mix: 100%;
+  }
 }

package/dist/system/_focus-ring-field.js

@@ -11,19 +11,31 @@
 * would move with the buttons). `FOCUS_RING_INSET` keeps its fixed offset
 * for its ten other consumers.
 *
+* **Faint, and configurable.** A text field matches `:focus-visible` on a
+* mouse click as well as on Tab, so its ring is the one every click lights up.
+* Drawn at full strength (a white `--cue-focus` on the default theme) it read
+* as a glaring box, so a field paints `--cue-focus` mixed with transparent to
+* `--cue-style-field-focus-mix`: 15% unless a style set, `:root` or any
+* subtree names another share (0% hides it, 100% is the full ring). The
+* border's lift to `border-strong` on `:focus` carries the rest of the signal.
+* Inside `data-field-edge="contrast"` (`styles.css`) the share is 100%, so the
+* reader who opted into the 3:1 edge gets the full ring back. Every other
+* control's keyboard ring (`_focus-ring.ts`) is unchanged: it only ever shows
+* to a keyboard.
+*
 * Its own module, not a constant in `_focus-ring.ts`: docgen attributes a
 * token to a component by the file its class string lives in, and every
 * focusable component imports that module.
 *
 * @internal Not part of the public API.
 */
-const FOCUS_RING_FIELD = "focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus) focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)]";
+const FOCUS_RING_FIELD = "focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-[color:color-mix(in_oklab,var(--cue-focus)_var(--cue-style-field-focus-mix,15%),transparent)] focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)]";
 /**
 * `FOCUS_RING_GROUP_INSET` with {@link FOCUS_RING_FIELD}'s offset: the
 * grouped field's ring reads `style-field-focus-offset` as the field it wraps
 * does (plan V.2, T25), so a grouped field and a plain one keep one focus
 * geometry under every Look.
 */
-const FOCUS_RING_GROUP_FIELD = "has-focus-visible:outline-solid has-focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] has-focus-visible:outline-(--cue-focus) has-focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)]";
+const FOCUS_RING_GROUP_FIELD = "has-focus-visible:outline-solid has-focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] has-focus-visible:outline-[color:color-mix(in_oklab,var(--cue-focus)_var(--cue-style-field-focus-mix,15%),transparent)] has-focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)]";
 //#endregion
 export { FOCUS_RING_FIELD, FOCUS_RING_GROUP_FIELD };

package/dist/theming/contrast.d.ts

@@ -1,2 +1,2 @@
-import { CONTRAST_REQUIREMENTS, ContrastCheck, ContrastInput, ContrastReport, ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, relativeLuminance } from "@cueplusplus/theme-base/contrast";
-export { CONTRAST_REQUIREMENTS, type ContrastCheck, type ContrastInput, type ContrastReport, type ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, relativeLuminance };
+import { CONTRAST_REQUIREMENTS, ContrastCheck, ContrastInput, ContrastReport, ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, edgeToContrast, relativeLuminance } from "@cueplusplus/theme-base/contrast";
+export { CONTRAST_REQUIREMENTS, type ContrastCheck, type ContrastInput, type ContrastReport, type ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, edgeToContrast, relativeLuminance };

package/dist/theming/contrast.js

@@ -1,2 +1,2 @@
-import { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, relativeLuminance } from "@cueplusplus/theme-base/contrast";
-export { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, relativeLuminance };
+import { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, edgeToContrast, relativeLuminance } from "@cueplusplus/theme-base/contrast";
+export { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, edgeToContrast, relativeLuminance };

package/dist/theming/create-theme.js

@@ -1,5 +1,5 @@
 import { formatColorString } from "../color/_convert.js";
-import { WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport } from "./contrast.js";
+import { WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport, edgeToContrast } from "./contrast.js";
 import { RESOLVED_MONO, assertCssValue, assertThemeName, derivedTokens, serializeSystemModeAliases, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
 import { COLOR_CONTRACT, resolve } from "@cueplusplus/theme-base";
 import { clampChroma, converter, formatHex, inGamut, parse } from "culori";
@@ -462,7 +462,10 @@ function createTheme(anchors) {
 	if (anchors.radiusScale !== void 0 && !(anchors.radiusScale > 0)) throw new TypeError(`radiusScale must be a positive number, got ${anchors.radiusScale}`);
 	const dark = resolveDark(anchors, preset.dark);
 	const light = anchors.supportsLight ?? preset.light !== null ? resolveLight(dark, preset.light) : null;
-	const derived = Object.entries(derivedTokens());
+	const fieldEdge = (colors) => edgeToContrast(colors["border"], colors["surface-1"], colors["fg"]);
+	const derivedFor = (colors) => Object.entries(derivedTokens()).map(([property, value]) => property === tokenProperty("field-edge") ? [property, fieldEdge(colors)] : [property, value]);
+	const derived = derivedFor(dark.colors);
+	const derivedLight = light === null ? null : derivedFor(light.colors);
 	const fonts = resolveFonts$1(anchors, preset.fonts);
 	const radius = anchors.radiusScale === void 0 ? null : radiusBlocks(name, anchors.radiusScale);
 	const darkPaletteSections = [
@@ -482,7 +485,7 @@ function createTheme(anchors) {
 	}]];
 	const lightSections = light === null ? null : [{ declarations: colorDeclarations(light.colors) }, {
 		comment: DERIVED_COMMENT,
-		declarations: derived
+		declarations: derivedLight ?? derived
 	}];
 	const blocks = [
 		{
@@ -502,10 +505,16 @@ function createTheme(anchors) {
 	];
 	const inputs = [{
 		mode: "dark",
-		tokens: dark.colors
+		tokens: {
+			...dark.colors,
+			"field-edge": fieldEdge(dark.colors)
+		}
 	}, ...light === null ? [] : [{
 		mode: "light",
-		tokens: light.colors,
+		tokens: {
+			...light.colors,
+			"field-edge": fieldEdge(light.colors)
+		},
 		provisional: light.provisional
 	}]];
 	const explicitCss = serializeThemeCss(blocks, { banner: `@cueplusplus/ui — theme "${name}"` }).trimEnd();
@@ -522,7 +531,7 @@ function createTheme(anchors) {
 			sections: lightSections ?? darkPaletteSections
 		}])}\n`,
 		tokens: Object.fromEntries(darkSections.flatMap((section) => section.declarations)),
-		light: light === null ? null : Object.fromEntries([...colorDeclarations(light.colors), ...derived]),
+		light: light === null ? null : Object.fromEntries([...colorDeclarations(light.colors), ...derivedLight ?? derived]),
 		report: contrastReport(inputs)
 	};
 }