@astryxdesign/core 0.1.4-canary.39ffd21 → 0.1.4-canary.3d64ef2

package/src/docPropReferences.test.ts

@@ -0,0 +1,178 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+/**
+ * @file Guards doc prose against docs/source prop mismatches (#3360).
+ *
+ * Scans every {Name}.doc.mjs for prose phrases like "the foo prop on Bar"
+ * and verifies the referenced prop is documented on the referenced
+ * component. Doc prose is LLM training signal: a reference to a prop that
+ * doesn't exist steers codegen toward hallucinated APIs (#3360 shipped a
+ * bullet pointing at a nonexistent CodeBlock syntaxTheme prop).
+ *
+ * A reference to a missing prop is allowed only when the same string
+ * explicitly negates it ("no such prop exists" / "does not exist"), the
+ * corrective-bullet pattern used to counter known hallucinations.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {readdirSync} from 'node:fs';
+import {join, relative} from 'node:path';
+
+const SRC_DIR = __dirname;
+
+type DocModule = {
+  docs?: {
+    name?: string;
+    props?: {name: string}[];
+    components?: {name?: string; props?: {name: string}[]}[];
+  };
+};
+
+/**
+ * Props intentionally omitted from doc props[]: PropDoc in docs-types.ts
+ * says to skip internal/styling props, so prose may reference them even
+ * though no doc lists them.
+ */
+const UNIVERSAL_PROPS = new Set([
+  'xstyle',
+  'className',
+  'style',
+  'ref',
+  'data-testid',
+]);
+
+/**
+ * Matches prose like "the foo prop on Bar", "foo prop of Bar", and
+ * conjunction targets: "foo prop on Bar or Baz". Group 1 is the prop
+ * (camelCase, lowercase first letter), group 2 the component name list.
+ */
+const PROP_REF_PATTERN =
+  /\b([a-z][A-Za-z0-9]*) prop (?:on|of) (?:the )?([A-Z][A-Za-z0-9]*(?:(?:,(?: and| or)?| and| or) [A-Z][A-Za-z0-9]*)*)/g;
+
+/** A same-string negation marks the reference as a deliberate counter-signal. */
+const NEGATION_PATTERN = /no such prop|does not exist|doesn't exist/i;
+
+function findDocFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, {withFileTypes: true})) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...findDocFiles(full));
+    } else if (entry.name.endsWith('.doc.mjs')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/** Collect every string value reachable from a doc module export. */
+function collectStrings(value: unknown, out: string[]): void {
+  if (typeof value === 'string') {
+    out.push(value);
+  } else if (Array.isArray(value)) {
+    for (const item of value) {
+      collectStrings(item, out);
+    }
+  } else if (value && typeof value === 'object') {
+    for (const item of Object.values(value)) {
+      collectStrings(item, out);
+    }
+  }
+}
+
+const docFiles = findDocFiles(SRC_DIR);
+
+// Component name → documented prop names, from every doc file's props[]
+// (single and sub-component docs) and inline components[] entries.
+const documentedProps = new Map<string, Set<string>>();
+for (const file of docFiles) {
+  const mod = require(file) as DocModule;
+  const docs = mod.docs;
+  if (!docs) {
+    continue;
+  }
+  const entries = [
+    {name: docs.name, props: docs.props},
+    ...(docs.components || []),
+  ];
+  for (const {name, props} of entries) {
+    if (!name || !Array.isArray(props)) {
+      continue;
+    }
+    const set = documentedProps.get(name) || new Set<string>();
+    for (const prop of props) {
+      set.add(prop.name);
+    }
+    documentedProps.set(name, set);
+  }
+}
+
+interface Violation {
+  file: string;
+  component: string;
+  prop: string;
+  excerpt: string;
+}
+
+function findViolations(): Violation[] {
+  const violations: Violation[] = [];
+  for (const file of docFiles) {
+    const strings: string[] = [];
+    collectStrings(require(file), strings);
+    for (const text of strings) {
+      let match;
+      while ((match = PROP_REF_PATTERN.exec(text)) !== null) {
+        const [, prop, componentList] = match;
+        if (UNIVERSAL_PROPS.has(prop) || NEGATION_PATTERN.test(text)) {
+          continue;
+        }
+        for (const component of componentList.split(
+          /,(?: and| or)?| and | or /,
+        )) {
+          const name = component.trim();
+          if (!name) {
+            continue;
+          }
+          const known = documentedProps.get(name);
+          if (known && !known.has(prop)) {
+            violations.push({
+              file: relative(SRC_DIR, file),
+              component: name,
+              prop,
+              excerpt: text.slice(
+                Math.max(0, match.index - 40),
+                match.index + match[0].length + 20,
+              ),
+            });
+          }
+        }
+      }
+    }
+  }
+  return violations;
+}
+
+describe('doc prose prop references', () => {
+  it('sanity: discovers doc files and documented components', () => {
+    expect(docFiles.length).toBeGreaterThan(0);
+    expect(documentedProps.size).toBeGreaterThan(0);
+  });
+
+  it('every "X prop on Y" reference names a documented prop of Y', () => {
+    const violations = findViolations();
+    expect(
+      violations,
+      violations
+        .map(
+          v =>
+            `${v.file} references prop "${v.prop}" on ${v.component}, ` +
+            `which does not document it (…${v.excerpt}…). Either the prop ` +
+            `doesn't exist (fix the prose; negate with "no such prop ` +
+            `exists" if countering a known hallucination) or it exists in ` +
+            `source but is missing from the component's doc props[] (add it).`,
+        )
+        .join('\n'),
+    ).toEqual([]);
+  });
+});

package/src/hooks/focusableSelector.ts

@@ -22,4 +22,4 @@
  * re-declaring the string so behavior stays consistent across hooks.
  */
 export const FOCUSABLE_SELECTOR =
-  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]):not([disabled]), [contenteditable]:not([contenteditable="false"]), audio[controls], video[controls], iframe, details > summary:first-child';
+  'button:not([disabled]), a[href], area[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]):not([disabled]), [contenteditable]:not([contenteditable="false"]), audio[controls], video[controls], iframe, details > summary:first-child';

package/src/hooks/useFocusTrap.doc.mjs

@@ -39,10 +39,11 @@ export const docs = {
   ],
   usage: {
     description:
-      'Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. Mouse clicks outside the container are not intercepted; use a light-dismiss handler for that.',
+      'Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. When the trap deactivates or unmounts, focus is restored to the element that was focused before activation, unless focus was already moved elsewhere. Mouse clicks outside the container are not intercepted; use a light-dismiss handler for that.',
     bestPractices: [
       { guidance: true, description: 'Call focusFirst() when opening a dialog/modal to move focus into the trapped region.' },
       { guidance: true, description: 'Provide an onEscape callback to close the dialog when Escape is pressed.' },
+      { guidance: true, description: 'Rely on the built-in focus restoration on close; only add your own onHide focus handling when you need to send focus somewhere other than the previously-focused element.' },
       { guidance: false, description: 'Use on non-modal content like tooltips or dropdowns; those need light-dismiss, not focus trapping.' },
     ],
   },
@@ -67,10 +68,11 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted; use light-dismiss handler for that.',
+      'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. On deactivate/unmount, restores focus to the element focused before activation unless focus already moved elsewhere. Mouse clicks outside container not intercepted; use light-dismiss handler for that.',
     bestPractices: [
       { guidance: true, description: 'Call focusFirst() when opening dialog/modal to move focus into trapped region.' },
       { guidance: true, description: 'Provide onEscape callback to close dialog when Escape pressed.' },
+      { guidance: true, description: 'Rely on built-in focus restoration on close; add own onHide focus handling only to send focus somewhere other than previously-focused element.' },
       { guidance: false, description: 'Use on non-modal content like tooltips / dropdowns; those need light-dismiss, not focus trapping.' },
     ],
   },

package/src/hooks/useFocusTrap.test.tsx

@@ -11,6 +11,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import {FOCUSABLE_SELECTOR} from './focusableSelector';
 import {useFocusTrap} from './useFocusTrap';
 
 function Trap({children}: {children: React.ReactNode}) {
@@ -49,6 +50,41 @@ function EscapeTrap({
   );
 }
 
+function RestoreTrap({isActive}: {isActive: boolean}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({isActive});
+  return (
+    <div ref={containerRef} data-testid="restore-trap">
+      <button type="button" data-testid="inside">
+        Inside trap
+      </button>
+    </div>
+  );
+}
+
+function RestoreFixture({
+  isActive,
+  showPrev = true,
+  showTrap = true,
+}: {
+  isActive: boolean;
+  showPrev?: boolean;
+  showTrap?: boolean;
+}) {
+  return (
+    <div>
+      {showPrev && (
+        <button type="button" data-testid="prev">
+          Previously focused
+        </button>
+      )}
+      <button type="button" data-testid="other">
+        Other outside
+      </button>
+      {showTrap && <RestoreTrap isActive={isActive} />}
+    </div>
+  );
+}
+
 describe('useFocusTrap tabbable model (infra-8)', () => {
   it('treats a contenteditable as focusable (focusFirst lands on it)', () => {
     render(
@@ -84,6 +120,48 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
   });
 });
 
+describe('FOCUSABLE_SELECTOR href matching', () => {
+  // Only real links (<a href>/<area href>) are focusable via href. A bare
+  // [href] term also matched non-focusable elements carrying href (e.g. a
+  // <link> in the head, or a custom element), which useFocusTrap would then
+  // treat as tab stops when computing trap boundaries.
+  it('matches real links but not other elements carrying href', () => {
+    const container = document.createElement('div');
+    container.innerHTML =
+      '<a href="#a" data-testid="anchor">Anchor</a>' +
+      '<map name="m">' +
+      '<area href="#area" shape="rect" coords="0,0,1,1" data-testid="area" />' +
+      '</map>' +
+      '<span href="#span" data-testid="span">Span</span>' +
+      '<link href="#link" data-testid="link" />';
+
+    const matches = Array.from(
+      container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+    );
+    const byTestId = (id: string) =>
+      container.querySelector(`[data-testid="${id}"]`);
+
+    // Real links are focusable via href.
+    expect(matches).toContain(byTestId('anchor'));
+    expect(matches).toContain(byTestId('area'));
+    // Non-link elements carrying href are not focusable and must be excluded.
+    expect(matches).not.toContain(byTestId('span'));
+    expect(matches).not.toContain(byTestId('link'));
+  });
+
+  it('treats an <a href> inside a trap as focusable (focusFirst lands on it)', () => {
+    render(
+      <Trap>
+        <a href="#link" data-testid="anchor">
+          Link
+        </a>
+      </Trap>,
+    );
+    fireEvent.click(screen.getByTestId('focus-first'));
+    expect(screen.getByTestId('anchor')).toHaveFocus();
+  });
+});
+
 describe('useFocusTrap Escape coordination', () => {
   it('calls onEscape for a single active trap', () => {
     const onEscape = vi.fn();
@@ -125,8 +203,78 @@ describe('useFocusTrap Escape coordination', () => {
     const {rerender} = render(
       <EscapeTrap isActive onEscape={onEscape} label="toggle" />,
     );
-    rerender(<EscapeTrap isActive={false} onEscape={onEscape} label="toggle" />);
+    rerender(
+      <EscapeTrap isActive={false} onEscape={onEscape} label="toggle" />,
+    );
     fireEvent.keyDown(document, {key: 'Escape'});
     expect(onEscape).not.toHaveBeenCalled();
   });
 });
+
+describe('useFocusTrap focus restoration', () => {
+  it('restores focus to the previously-focused element when deactivated', () => {
+    const {rerender} = render(<RestoreFixture isActive={false} />);
+    const prev = screen.getByTestId('prev');
+    prev.focus();
+    expect(prev).toHaveFocus();
+
+    // Activate the trap (captures `prev` as the restore target) and move focus
+    // inside it, as auto-focus or a keyboard user would.
+    rerender(<RestoreFixture isActive={true} />);
+    screen.getByTestId('inside').focus();
+    expect(screen.getByTestId('inside')).toHaveFocus();
+
+    // Deactivating returns focus to where it was before the trap opened.
+    rerender(<RestoreFixture isActive={false} />);
+    expect(prev).toHaveFocus();
+  });
+
+  it('does not steal focus when it was moved elsewhere outside the trap', () => {
+    const {rerender} = render(<RestoreFixture isActive={false} />);
+    const prev = screen.getByTestId('prev');
+    prev.focus();
+
+    rerender(<RestoreFixture isActive={true} />);
+    // The user (or a consumer that self-restores) moves focus to a different
+    // outside control while the trap is open.
+    const other = screen.getByTestId('other');
+    other.focus();
+
+    rerender(<RestoreFixture isActive={false} />);
+    // Focus is left where the user put it — not yanked back to `prev`.
+    expect(other).toHaveFocus();
+    expect(prev).not.toHaveFocus();
+  });
+
+  it('does not crash or restore when the captured element was removed', () => {
+    const {rerender} = render(<RestoreFixture isActive={false} />);
+    const prev = screen.getByTestId('prev');
+    prev.focus();
+
+    rerender(<RestoreFixture isActive={true} />);
+    screen.getByTestId('inside').focus();
+
+    // Remove the captured element from the DOM before the trap deactivates.
+    rerender(<RestoreFixture isActive={true} showPrev={false} />);
+    expect(() =>
+      rerender(<RestoreFixture isActive={false} showPrev={false} />),
+    ).not.toThrow();
+  });
+
+  it('restores focus when the trap unmounts while active', () => {
+    const {rerender} = render(
+      <RestoreFixture isActive={true} showTrap={false} />,
+    );
+    const prev = screen.getByTestId('prev');
+    prev.focus();
+
+    // Mounting the trap active captures `prev`; then focus moves inside it.
+    rerender(<RestoreFixture isActive={true} showTrap={true} />);
+    screen.getByTestId('inside').focus();
+    expect(screen.getByTestId('inside')).toHaveFocus();
+
+    // Unmounting the trap (cleanup path, not an isActive flip) still restores.
+    rerender(<RestoreFixture isActive={true} showTrap={false} />);
+    expect(prev).toHaveFocus();
+  });
+});

package/src/hooks/useFocusTrap.ts

@@ -5,7 +5,8 @@
 /**
  * @file useFocusTrap.ts
  * @input Uses React useCallback, useEffect, useRef
- * @output Exports useFocusTrap hook for trapping focus within a container
+ * @output Exports useFocusTrap hook for trapping focus within a container and
+ *   restoring focus to the previously-focused element on deactivation
  * @position Core hook; used by dialogs, modals, date pickers
  *
  * Based on WAI-ARIA dialog pattern:
@@ -178,6 +179,9 @@ export interface UseFocusTrapReturn<T extends HTMLElement = HTMLElement> {
  * - Listens to focus events on the document
  * - Redirects focus back into the container if it escapes
  * - Handles both Tab and Shift+Tab navigation
+ * - Restores focus to the element that was focused before activation when the
+ *   trap deactivates or unmounts, unless focus was already moved elsewhere
+ *   (so consumers that restore focus themselves are unaffected)
  *
  * @example
  * ```
@@ -217,6 +221,51 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
     }
   }, []);
 
+  /**
+   * Capture the element focused before the trap activated, and restore focus to
+   * it when the trap deactivates (or the component unmounts). Overlays are
+   * opened imperatively (e.g. `showPopover()`), so the browser's declarative
+   * popover focus restoration does not apply — without this, closing a Popover
+   * via Escape or light dismiss drops keyboard focus to `<body>`.
+   *
+   * The restore is guarded so it never steals focus a consumer moved on
+   * purpose: it only runs when focus would otherwise be lost — i.e. the active
+   * element is nothing, the document body/root, or still inside the (possibly
+   * now-unmounted) trap container. If focus already moved to some other element
+   * outside the trap (the user clicked elsewhere, or a consumer such as
+   * DropdownMenu already refocused its trigger), the restore is a no-op.
+   */
+  useEffect(() => {
+    if (!isActive) {
+      return;
+    }
+
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    // Snapshot the container now; by cleanup it may be detached or unmounted.
+    const container = containerRef.current;
+
+    return () => {
+      const active = document.activeElement;
+      const focusWasLost =
+        active == null ||
+        active === document.body ||
+        active === document.documentElement ||
+        (container != null && container.contains(active));
+
+      if (!focusWasLost) {
+        return;
+      }
+
+      if (
+        previouslyFocused != null &&
+        previouslyFocused.isConnected &&
+        typeof previouslyFocused.focus === 'function'
+      ) {
+        previouslyFocused.focus();
+      }
+    };
+  }, [isActive]);
+
   /**
    * Handle focus events - redirect focus back into container if it escapes.
    * Only redirects for keyboard navigation, not mouse clicks.

package/src/theme/SyntaxTheme.doc.mjs

@@ -50,9 +50,9 @@ export const docs = {
           'Syntax themes support light-dark() tuples: each token can have different values for light and dark mode, resolved automatically by the color scheme.',
       },
       {
-        guidance: false,
+        guidance: true,
         description:
-          'Wrap individual CodeBlock instances with SyntaxTheme: use the syntaxTheme prop on CodeBlock directly for per-instance overrides.',
+          'For a single CodeBlock, pass the syntaxTheme prop directly: it is shorthand for wrapping that block in SyntaxTheme. Use the SyntaxTheme wrapper when theming a whole region of code components.',
       },
     ],
   },
@@ -96,9 +96,9 @@ export const docsDense = {
           'Syntax themes support light-dark() tuples: each token can have different values for light/dark mode, resolved automatically by color scheme.',
       },
       {
-        guidance: false,
+        guidance: true,
         description:
-          'Wrap individual CodeBlock instances w/ SyntaxTheme: use syntaxTheme prop on CodeBlock directly for per-instance overrides instead.',
+          'Single CodeBlock: pass syntaxTheme prop (shorthand for wrapping in SyntaxTheme). Whole region of code components: wrap w/ SyntaxTheme.',
       },
     ],
   },

package/src/theme/defineTheme.ts

@@ -56,14 +56,8 @@ import {
   generateTypeScaleComponents,
   type TypeScaleConfig,
 } from './expandTypeScale';
-import {
-  expandMotionScale,
-  type MotionScaleConfig,
-} from './expandMotionScale';
-import {
-  expandRadiusScale,
-  type RadiusScaleConfig,
-} from './expandRadiusScale';
+import {expandMotionScale, type MotionScaleConfig} from './expandMotionScale';
+import {expandRadiusScale, type RadiusScaleConfig} from './expandRadiusScale';
 import {expandColorScale, type ColorScaleConfig} from './expandColorScale';
 
 import type {DomainTokenName} from './domainTokens';
@@ -153,10 +147,7 @@ export type StyleOverrides = Record<string, string | Record<string, string>>;
  * }
  * ```
  */
-export type ComponentStyleMap = Record<
-  string,
-  Record<string, StyleOverrides>
->;
+export type ComponentStyleMap = Record<string, Record<string, StyleOverrides>>;
 
 /** Input to defineTheme */
 export interface DefineThemeInput {
@@ -287,7 +278,7 @@ export interface DefineThemeInput {
   /**
    * Default syntax highlighting theme for code components.
    * Sets --color-syntax-* tokens at the theme root. Can be overridden
-   * per-region via SyntaxTheme or per-instance via syntaxTheme prop.
+   * per-region (or per-instance) by wrapping in SyntaxTheme.
    *
    * @example
    * ```tsx

package/src/theme/derivedVarRegistry.test.ts

@@ -14,8 +14,8 @@
 
 import {describe, it, expect} from 'vitest';
 import {derivedVarRegistry, getDerivedVars} from './derivedVarRegistry';
-import {readdirSync, readFileSync} from 'fs';
-import {join} from 'path';
+import {readdirSync, readFileSync} from 'node:fs';
+import {join} from 'node:path';
 
 const SRC_DIR = join(__dirname, '..');
 

package/src/theme/expandColorScale.test.ts

@@ -3,6 +3,7 @@
 import {describe, it, expect} from 'vitest';
 import {expandColorScale} from './expandColorScale';
 import {defineTheme} from './defineTheme';
+import {generateThemeRules} from './generateThemeRules';
 
 describe('expandColorScale', () => {
   it('produces all expected token keys', () => {
@@ -60,6 +61,19 @@ describe('expandColorScale', () => {
     expect(warm['--color-neutral']).not.toBe(neutral['--color-neutral']);
   });
 
+  it('emits derived accent tokens as references to --color-accent', () => {
+    const tokens = expandColorScale({accent: '#0064E0'});
+    // Reference tokens follow a scoped --color-accent override at runtime.
+    expect(tokens['--color-text-accent']).toBe('var(--color-accent)');
+    expect(tokens['--color-icon-accent']).toBe('var(--color-accent)');
+    expect(tokens['--color-accent-muted']).toBe(
+      'light-dark(color-mix(in srgb, var(--color-accent) 20%, transparent), color-mix(in srgb, var(--color-accent) 25%, transparent))',
+    );
+    // The base token and the contrast-computed on-accent stay resolved.
+    expect(tokens['--color-accent']).toMatch(/^light-dark\(#/);
+    expect(tokens['--color-on-accent']).toMatch(/^light-dark\(#/);
+  });
+
   it('contrast high produces different --color-text-primary than standard', () => {
     const standard = expandColorScale({
       accent: '#0064E0',
@@ -81,4 +95,19 @@ describe('expandColorScale + defineTheme integration', () => {
     });
     expect(theme.tokens['--color-accent']).toBe('red');
   });
+
+  it('generated theme CSS keeps the accent references (#3495)', () => {
+    const theme = defineTheme({
+      name: 'test-accent-refs',
+      color: {accent: '#DC2626'},
+    });
+    const css = generateThemeRules(theme).join('\n');
+    expect(css).toContain('--color-text-accent: var(--color-accent);');
+    expect(css).toContain('--color-icon-accent: var(--color-accent);');
+    expect(css).toContain(
+      '--color-accent-muted: light-dark(color-mix(in srgb, var(--color-accent) 20%, transparent), color-mix(in srgb, var(--color-accent) 25%, transparent));',
+    );
+    // The base token itself stays a resolved color pair.
+    expect(css).toMatch(/--color-accent: light-dark\(#/);
+  });
 });

package/src/theme/expandColorScale.ts

@@ -77,6 +77,10 @@ function ld(light: string, dark: string): string {
   return `light-dark(${light}, ${dark})`;
 }
 
+function accentWithAlpha(alpha: number): string {
+  return `color-mix(in srgb, var(--color-accent) ${alpha * 100}%, transparent)`;
+}
+
 /**
  * Expand a color scale config into Astryx color token overrides.
  *
@@ -117,10 +121,11 @@ export function expandColorScale(
   return {
     // Core semantic
     '--color-accent': ld(P[40], P[80]),
-    '--color-accent-muted': ld(
-      hexWithAlpha(P[40], 0.2),
-      hexWithAlpha(P[80], 0.25),
-    ),
+    // Derived accent tokens reference --color-accent instead of baking its
+    // resolved hex, so a scoped override of the base token re-accents the
+    // whole subtree at runtime. --color-on-accent stays baked: it is a
+    // contrast computation against the accent, which CSS cannot express.
+    '--color-accent-muted': ld(accentWithAlpha(0.2), accentWithAlpha(0.25)),
     '--color-on-accent': ld(P[100], P[20]),
     '--color-neutral': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[90], 0.2)),
     '--color-background-surface': ld(N[99], N[10]),
@@ -146,10 +151,10 @@ export function expandColorScale(
       NV[textSecondaryDarkTone],
     ),
     '--color-text-disabled': ld(NV[60], NV[40]),
-    '--color-text-accent': ld(P[30], P[80]),
+    '--color-text-accent': 'var(--color-accent)',
 
     // Icon
-    '--color-icon-accent': ld(P[40], P[80]),
+    '--color-icon-accent': 'var(--color-accent)',
     '--color-icon-primary': ld(N[textPrimaryLightTone], N[textPrimaryDarkTone]),
     '--color-icon-secondary': ld(
       NV[textSecondaryLightTone],

package/src/theme/hct.ts

@@ -16,6 +16,8 @@
  * - Tone from L* (CIE Lightness, 0=black, 100=white)
  */
 
+import {parseHex, formatHex} from '../utils/color';
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -121,21 +123,11 @@ export function yToTone(y: number): number {
 // =============================================================================
 
 function hexToRgb(hex: string): [number, number, number] {
-  const h = hex.replace('#', '');
-  const full =
-    h.length === 3 ? h[0] + h[0] + h[1] + h[1] + h[2] + h[2] : h.slice(0, 6);
-  const n = parseInt(full, 16);
-  return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
-}
-
-function rgbToHex(r: number, g: number, b: number): string {
-  return (
-    '#' +
-    [r, g, b]
-      .map(c => c.toString(16).padStart(2, '0'))
-      .join('')
-      .toUpperCase()
-  );
+  const parsed = parseHex(hex);
+  if (parsed === null) {
+    return [0, 0, 0];
+  }
+  return [parsed.r, parsed.g, parsed.b];
 }
 
 // =============================================================================
@@ -181,7 +173,7 @@ export function hctToHex(hct: HCT): string {
   }
   if (chroma < 0.5) {
     const gray = toneToGray(tone);
-    return rgbToHex(gray, gray, gray);
+    return formatHex(gray, gray, gray);
   }
 
   let lo = 0;
@@ -241,7 +233,7 @@ function hctComponentToHex(
     return null;
   }
 
-  return rgbToHex(r, g, bVal);
+  return formatHex(r, g, bVal);
 }
 
 // =============================================================================