@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/Indicator/Indicator.spec.md

@@ -0,0 +1,188 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Indicator
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-31
+owners: [cixzhang]
+review_triggers: [public-api, behavior, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Indicator/Indicator.test.tsx,
+    packages/core/src/Indicator/indicatorRegistry.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+    architecture:theme-authoring-contract,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Indicator component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                   |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. `@astryxdesign/core/Indicator` exports the three built-in indicators (`CheckboxIndicator`, `CheckIndicator`, `RadioIndicator`), the shared indicator props and types, the default registry, and name-based resolution.                                       |
+| Behavior                | Hosts draw a decorative control visual by name (`check`, `checkbox`, `radio`). A theme's `indicators` entry for that name replaces it in every host that resolves indicators by name; otherwise the built-in renders. Every indicator is hidden from assistive technology. |
+| End-user impact         | People see one consistent mark for a chosen option, a checkbox, or a radio across the components that resolve indicators by name, and screen-reader users hear the host control's semantics, never a duplicate.                                                            |
+| Builder impact          | None.                                                                                                                                                                                                                                                                      |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Three hosts render the built-ins directly instead of resolving by name; listed under Current-state impact.                                                                                                       |
+| Review checks           | Reject an indicator that is exposed to assistive technology, a theme override that a host resolving by name ignores, a falsy `children` that suppresses the built-in mark, or a role or tab stop on an indicator.                                                          |
+| Governing rules         | `architecture:component-theming-surface`; `architecture:public-component-api` INV5; `architecture:theme-authoring-contract`.                                                                                                                                               |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Indicator is the shared, replaceable set of decorative control visuals: the
+mark on a chosen option, the box a checkbox draws, and the circle a radio
+draws. It owns the indicator names, theme replacement by name, the shared
+decorative prop contract, and RadioIndicator. Consumer usage lives in
+`Indicator.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; with no theme override, `check`,
+  `checkbox`, and `radio` resolve to the built-ins
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
+- Controlled/uncontrolled behavior: not applicable; hosts supply `state`
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The core indicator names and the default registry that maps them to the
+  built-ins.
+- Theme replacement by name and the shared indicator prop contract.
+- RadioIndicator, documented as an inline component of `Indicator.doc.mjs`,
+  with the `radio-indicator` and `radio-indicator-dot` targets.
+- The `indicatorScope` marker hosts put on the element whose hover drives the
+  indicator's hover tint.
+
+**Does not own / non-goals**
+
+- CheckboxIndicator — owned by `component:CheckboxIndicator`.
+- CheckIndicator — owned by `component:CheckIndicator`.
+- Role, name, state, focus, keyboard, and activation of the host control —
+  owned by each host (CheckboxInput, RadioList, Selector, menu rows).
+- `useIndicator` and `getIndicator` as API — a public hook and function without
+  their own module records; uncontracted beyond the resolution FR2 states.
+
+## Public concepts
+
+| Concept             | Closed values or states                                | Meaning                                           | Availability by variant/orientation/state | Default  | Owner                 | Stability | Invalid-value behavior                                              |
+| ------------------- | ------------------------------------------------------ | ------------------------------------------------- | ----------------------------------------- | -------- | --------------------- | --------- | ------------------------------------------------------------------- |
+| Indicator name      | `check`, `checkbox`, `radio`, plus augmented names     | Which visual a host draws.                        | Always.                                   | —        | `component:Indicator` | Stable    | An augmented name no theme supplies resolves to nothing.            |
+| State               | `unchecked`, `checked`, and `indeterminate` (checkbox) | The host's selection state.                       | Per indicator family.                     | required | `component:Indicator` | Stable    | TypeScript rejects values outside the family.                       |
+| Size                | `sm`, `md`                                             | Indicator box size.                               | Always.                                   | `md`     | `component:Indicator` | Stable    | TypeScript rejects other values.                                    |
+| Replacement content | renderable `children`                                  | Content drawn instead of the built-in state mark. | Always.                                   | none     | `component:Indicator` | Stable    | Nullish, boolean, and empty-string children keep the built-in mark. |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Basis                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| FR1 | The default registry maps exactly `check` → CheckIndicator, `checkbox` → CheckboxIndicator, and `radio` → RadioIndicator.                                                                                                                                                                                                                                                                                                                                                                | Current tests                                           |
+| FR2 | A host resolves an indicator by name from the nearest theme: the theme's `indicators` entry for that name wins, otherwise the built-in. One override reaches every host that resolves that name. The Tokenizer bottom sheet and the Lab MobileTokenizer and MobilePowerSearch value editor render CheckboxIndicator and RadioIndicator directly, so a theme's `checkbox` or `radio` entry does not reach them. An augmented name resolves only when a theme supplies it.                 | `architecture:theme-authoring-contract`; current tests  |
+| FR3 | Every built-in indicator root sets `aria-hidden="true"` after caller props, so a caller cannot expose it; the public props type rejects `role` and `tabIndex`. Indicators receive `state`, `size`, `isDisabled`, and `children` and nothing that would give them semantics.                                                                                                                                                                                                              | `architecture:public-component-api` INV5; current tests |
+| FR4 | Renderable `children` replace the built-in state mark inside the indicator; nullish, boolean, and empty-string children keep it, and `0` counts as content.                                                                                                                                                                                                                                                                                                                              | Current tests                                           |
+| FR5 | RadioIndicator renders one circular span (20 or 24 CSS px) whose border and fill follow the state: an emphasized border on the surface when unchecked, an accent fill when checked with an on-accent dot (8 or 10 CSS px) inside. Disabled halves the opacity and mutes the border (and the fill when unchecked). Under a hover-capable pointer, hovering the host's `indicatorScope` tints it. The dot stays visible under forced colors. Transitions are instant under reduced motion. | Current source and tests                                |
+| FR6 | RadioIndicator's root carries `astryx-radio-indicator` with `data-size`, `data-checked`, and `data-disabled`; the dot carries `astryx-radio-indicator-dot` with `data-size`. No alias target is emitted. Caller props, `ref`, `className`, `style`, and `xstyle` reach the root.                                                                                                                                                                                                         | `architecture:component-theming-surface`; current tests |
+
+### Allowed variation
+
+- **AV1 — Replacement.** A theme may replace any named indicator with a
+  component that honors FR3.
+- **AV2 — Theme paint.** Themes may restyle the built-ins through their
+  targets without replacing them.
+
+### Representative states
+
+| State             | Required invariant                                    | Allowed variation |
+| ----------------- | ----------------------------------------------------- | ----------------- |
+| No theme override | Built-ins render for each name.                       | —                 |
+| Theme override    | Every host that resolves the name draws the override. | Override design.  |
+| Radio checked     | Accent circle with dot; `data-checked`.               | Size.             |
+| Falsy children    | Built-in mark still renders.                          | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Resolution.** Nearest theme's `indicators[name]`, then the built-in,
+  then nothing for an unsupplied augmented name.
+- **ORD2 — Attributes.** Caller props, then the indicator's own `aria-hidden`.
+
+### Performance and resources
+
+- **PR1 — Pure render.** Indicators own no state, effect, listener, or
+  observer.
+
+## Accessibility contract
+
+- **AR1 — Decorative.** Indicators are hidden from assistive technology; the
+  host owns all semantics (FR3).
+- **AR2 — Forced colors.** The radio dot stays visible under forced colors.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Radio circle     | Emphasized border unchecked; accent fill checked. | Current source           | Supporting     | FR5, FR6           |
+| Radio dot        | On-accent dot when checked.                       | Current source           | Supporting     | FR5, FR6           |
+
+No design record governs Indicator. The checkbox and check visuals are owned by
+their own records.
+
+## Family and system relationships
+
+- `architecture:theme-authoring-contract` owns how a theme supplies
+  `indicators`.
+- `component:CheckboxIndicator` and `component:CheckIndicator` own the other two
+  built-ins.
+- CheckboxInput, RadioListItem, Selector, and menu selection rows host
+  indicators.
+
+## Verification map
+
+| Contract        | Verification                                                                                               | Representative states                                                                                      | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Audit section                   |
+| --------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
+| FR1, FR2        | `indicatorRegistry.test.tsx`; `Indicator.test.tsx` useIndicator suite                                      | No theme; theme override; augmented names                                                                  | A wrong default, an ignored override, or a resolved unsupplied name fails.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `audit:Indicator/behavior`      |
+| FR3             | `Indicator.test.tsx` decorative-contract suite                                                             | Each built-in in the checked state; a caller `aria-hidden={false}`; `role` and `tabIndex` as literal props | An indicator a caller can expose, a dropped ordinary prop, or an accepted literal `role` or `tabIndex` fails. Evidence gap: no test checks `aria-hidden` on the unchecked states.                                                                                                                                                                                                                                                                                                                                                                | `audit:Indicator/accessibility` |
+| FR4             | `Indicator.test.tsx` falsy-children suite                                                                  | `null`, `false`, `''`, `0`, real children                                                                  | A falsy child (`false`, `null`, `undefined`, or `''`) that suppresses any built-in's mark fails, and CheckIndicator treating `0` as empty fails. Evidence gap: no test renders `0` as children of CheckboxIndicator or RadioIndicator.                                                                                                                                                                                                                                                                                                           | `audit:Indicator/behavior`      |
+| FR5, FR6, AR2   | `Indicator.test.tsx` radio-dot, disabled, and target-name cases                                            | Checked and unchecked; disabled; canonical targets                                                         | A dot when unchecked, no dot when checked, a missing checked `data-checked` or disabled `data-disabled`, or an alias target fails. Evidence gap: no test asserts the radio sizes, the state colors (emphasized border, accent fill, on-accent dot), the instant transitions under reduced motion, the disabled opacity and border, the hover tint, the forced-colors dot (the RadioList forced-colors case passes on any matching rule), radio `data-size` on the root and dot, `ref`, or caller `className`, `style`, and `xstyle` on the root. | `audit:Indicator/theming`       |
+| ORD1, ORD2, PR1 | Covered by the FR2 and FR3 rows. Evidence gap: no test asserts the absence of state, effects, or listeners | —                                                                                                          | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `audit:Indicator/behavior`      |
+
+## Current-state impact
+
+- **Direct indicator imports (FR2).** The Tokenizer bottom sheet and the Lab
+  MobileTokenizer and MobilePowerSearch value editor render CheckboxIndicator
+  and RadioIndicator directly, so a theme's `checkbox` or `radio` override does
+  not reach them.
+
+## Decision log
+
+No component-local decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/Indicator/RadioIndicator.tsx

@@ -16,7 +16,9 @@ import {
   easeVars,
   radiusVars,
 } from '../theme/tokens.stylex';
-import {isRenderable, mergeProps, themeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
+import {themeProps} from '../utils/themeProps';
 import {indicatorScope} from './indicator.markers.stylex';
 import type {IndicatorProps} from './types';
 

package/src/Item/Item.test.tsx

@@ -29,6 +29,7 @@ import {
 } from '@testing-library/react';
 import {rulesDeclaredFor} from '../__tests__/pressState';
 import userEvent from '@testing-library/user-event';
+import {LinkProvider} from '../Link/LinkProvider';
 import {Item} from './Item';
 import {ItemDescriptionContext} from './ItemDescriptionContext';
 import {List, ListItem} from '../List';
@@ -383,6 +384,65 @@ describe('Item', () => {
     expect(screen.getByTestId('item')).toHaveAttribute('aria-disabled', 'true');
   });
 
+  it("gives a disabled row's link no destination (spec:AST-085 FR2)", () => {
+    function RouterLink({ref, ...props}: React.ComponentPropsWithRef<'a'>) {
+      return <a ref={ref} data-router-link {...props} />;
+    }
+    render(
+      <LinkProvider component={RouterLink}>
+        <Item
+          label="Billing"
+          href="/billing"
+          target="_blank"
+          rel="noopener"
+          isDisabled
+        />
+        <Item label="Profile" href="/profile" />
+      </LinkProvider>,
+    );
+    // No href, target or rel, so a screen reader's click, Enter or a link
+    // menu cannot navigate; it keeps the link role and skips the router link.
+    const disabled = screen.getByRole('link', {name: 'Billing'});
+    expect(disabled).toHaveAttribute('aria-disabled', 'true');
+    for (const attribute of ['href', 'target', 'rel', 'data-router-link']) {
+      expect(disabled).not.toHaveAttribute(attribute);
+    }
+    const enabled = screen.getByRole('link', {name: 'Profile'});
+    expect(enabled).toHaveAttribute('href', '/profile');
+    expect(enabled).toHaveAttribute('data-router-link');
+    expect(enabled).not.toHaveAttribute('aria-disabled');
+  });
+
+  it('keeps focus on a focused link row that becomes disabled (spec:AST-085 FR4)', () => {
+    const {rerender} = render(<Item label="Billing" href="/billing" />);
+    screen.getByRole('link', {name: 'Billing'}).focus();
+    rerender(<Item label="Billing" href="/billing" isDisabled />);
+    // The disabled row renders a plain anchor in place of the link component;
+    // focus moves to it instead of falling to the page.
+    const disabled = screen.getByRole('link', {name: 'Billing'});
+    expect(disabled).not.toHaveAttribute('href');
+    expect(disabled).toHaveFocus();
+    rerender(<Item label="Billing" href="/billing" />);
+    expect(screen.getByRole('link', {name: 'Billing'})).toHaveFocus();
+  });
+
+  it('does not pull focus back to a row that changes while focus is elsewhere', () => {
+    const {rerender} = render(
+      <>
+        <Item label="Billing" href="/billing" />
+        <button type="button">Elsewhere</button>
+      </>,
+    );
+    screen.getByRole('button', {name: 'Elsewhere'}).focus();
+    rerender(
+      <>
+        <Item label="Billing" href="/billing" isDisabled />
+        <button type="button">Elsewhere</button>
+      </>,
+    );
+    expect(screen.getByRole('button', {name: 'Elsewhere'})).toHaveFocus();
+  });
+
   it('disables the invisible button when isDisabled', () => {
     const {container} = render(
       <Item label="Disabled" onClick={() => {}} isDisabled />,

package/src/Item/Item.tsx

@@ -48,7 +48,9 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {isRenderable, mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
+import {useFocusAcrossSwap} from '../utils/useFocusAcrossSwap';
 import {ItemDescriptionContext} from './ItemDescriptionContext';
 import {ItemMarkerColumnsContext} from './ItemMarkerColumnsContext';
 import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -610,6 +612,13 @@ export function Item({
   const pressable = usePressFeedback();
   const columnMarker = use(ItemMarkerColumnsContext);
   const LinkComponent = useLinkComponent();
+  // A disabled row's anchor has no destination, so no activation path (a
+  // screen reader's click, Enter, a link context menu) can navigate
+  // (spec:AST-085 FR2). Like a disabled Link, it keeps the link role and skips
+  // the router link component, which may require a live href. The element type
+  // then changes with `isDisabled`, so focus follows the swap (FR4).
+  const RowAnchor = isDisabled ? 'a' : LinkComponent;
+  const anchorRef = useFocusAcrossSwap<HTMLAnchorElement>();
 
   // Delegation mode: the row is an enlarged click/tap target for a nested
   // control (e.g. a checkbox) that owns the keyboard access and action. The
@@ -786,19 +795,18 @@ export function Item({
           {labelAndDescription}
         </span>
       ) : href != null && !isLinkRoot ? (
-        <LinkComponent
-          href={href}
-          target={target}
-          rel={rel}
-          aria-disabled={isDisabled || undefined}
-          tabIndex={isDisabled ? -1 : undefined}
+        <RowAnchor
+          ref={anchorRef}
+          {...(isDisabled
+            ? {role: 'link', 'aria-disabled': true, tabIndex: -1}
+            : {href, target, rel})}
           {...stylex.props(
             styles.invisibleAnchor,
             isInline && styles.inlineContent,
             isDisabled && styles.disabledContent,
           )}>
           {labelAndDescription}
-        </LinkComponent>
+        </RowAnchor>
       ) : onClick != null ? (
         <button
           type="button"

package/src/Item/ItemSwipeLayer.tsx

@@ -29,7 +29,7 @@ import {
   spacingVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useMediaQuery} from '../hooks/useMediaQuery';

package/src/Kbd/Kbd.spec.md

@@ -1,37 +1,57 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:Kbd
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
-review_triggers: [theming]
+review_triggers: [public-api, behavior, theming, accessibility]
 verified_by: [packages/core/src/Kbd/Kbd.test.tsx, scripts/check-knowledge.mjs]
 modules: []
 families: []
 design_specs: []
-architecture: [architecture:component-theming-surface]
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:internationalization,
+    architecture:public-component-api,
+  ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-102]
 ---
 
 # Kbd component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                            |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. Kbd takes a `keys` string and base props.                                                                                                                                             |
+| Behavior                | Kbd splits `keys` on `+`, draws one hidden key badge per key with platform-aware glyphs, and names the whole shortcut once with spoken key names.                                                   |
+| End-user impact         | Sighted people see familiar key glyphs; screen-reader users hear the shortcut as words. Those words are English in every locale.                                                                    |
+| Builder impact          | None.                                                                                                                                                                                               |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Badges hold a fixed height; listed under Current-state impact.                                                                            |
+| Review checks           | Reject a badge that is exposed to assistive technology, a caller `role` or `aria-label` that replaces the computed one, duplicate React keys for repeated keys, or `mod` that ignores the platform. |
+| Governing rules         | `architecture:component-theming-surface`; `architecture:internationalization` INV1, INV1a; `architecture:public-component-api` INV5; `spec:AST-102` FR4.                                            |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-Kbd presents a keyboard shortcut as one or more painted key badges. This draft
-records current consumer anatomy and theming reachability without changing
-runtime behavior, styling, targets, or public API.
+Kbd presents a keyboard shortcut as one or more painted key badges. It owns
+parsing the shortcut string, the platform-aware glyph for each key, the
+shortcut's accessible name, and the `kbd` target. Consumer usage lives in
+`Kbd.doc.mjs`.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, aliases, and public API remain unchanged
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
 - Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
 
@@ -43,54 +63,70 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 - The shortcut group, its current `kbd` target, and the painted key badges it
   renders from the supplied shortcut string.
+- Key parsing, aliases, platform-aware glyphs, and the spoken name.
 
 **Does not own / non-goals**
 
 - The action associated with the shortcut or how the shortcut is discovered —
   owned by the product callsite.
-- Whether an individual key badge should gain a public target — unresolved by
-  this factual backfill.
+- Whether an individual key badge should gain a public target — open (OQ1).
+- Listening for or handling the shortcut — not provided; Kbd is display only.
+- Caller DOM props, `ref`, `className`, `style`, and `xstyle` on the group —
+  shipped and documented, uncontracted here beyond FR4's role and label
+  precedence.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `Kbd.doc.mjs`.
+| Concept | Closed values or states                                             | Meaning               | Availability by variant/orientation/state | Default  | Owner           | Stability | Invalid-value behavior                    |
+| ------- | ------------------------------------------------------------------- | --------------------- | ----------------------------------------- | -------- | --------------- | --------- | ----------------------------------------- |
+| Keys    | `+`-separated key names; `mod`, named keys, aliases, any other text | The shortcut to show. | Always.                                   | required | `component:Kbd` | Stable    | An unknown key shows uppercased as typed. |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                          | Basis                           | Draft review state                                  |
-| --- | ------------------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------------------------------- |
-| FR1 | The current render contains one shortcut group and one painted key badge for every parsed key segment.       | Current source, docs, and tests | Verified current behavior; no new behavior decided  |
-| FR2 | The shortcut group carries the current `kbd` target; individual key badges currently carry no public target. | Current source, docs, and tests | Verified current behavior; theming intent unsettled |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Basis                                                                     |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | The current render contains one shortcut group and one painted key badge for every parsed key segment. `keys` splits on `+`; each segment is trimmed and lowercased, `esc` reads as `escape` and `return` as `enter`, and a repeated key gets its own badge. Each badge is at least the `--spacing-5` size and MUST grow with a set text size so its glyph never clips (`spec:AST-102` FR4). Implementation gap: the badge height is fixed at `--spacing-5`.                                                                                    | Current source, docs, and tests; `spec:AST-102` FR4                       |
+| FR2 | The shortcut group carries the current `kbd` target; individual key badges currently carry no public target (OQ1).                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source, docs, and tests                                           |
+| FR3 | Each badge shows a glyph: `mod` is ⌘ on Apple platforms and the catalog's short Control text ("Ctrl" in English) elsewhere and before hydration; `escape` shows the catalog's short Escape text ("Esc"); `ctrl`, `alt`, `shift`, `enter`, `backspace`, `tab`, and the arrows show their symbols; `plus` shows "+"; any other key shows uppercased.                                                                                                                                                                                              | `architecture:internationalization` INV1a; current source and tests       |
+| FR4 | The group has `role="img"` and an `aria-label` built from each key's spoken name, taken from the Astryx catalog (`mod` is "Command" on Apple platforms and "Control" elsewhere and before hydration; an unknown key is spoken uppercased), joined pairwise through the catalog's shortcut message (" + " in English, for example "Command + K"); every badge is `aria-hidden`. A caller's `role` and `aria-label` never replace the computed ones; other caller ARIA props, such as `aria-labelledby` and `aria-hidden`, still reach the group. | `architecture:internationalization` INV1, INV1a; current source and tests |
 
 ### Allowed variation
 
-- Platform-specific key text and caller-supplied shortcut combinations may vary
-  without changing the two-part anatomy recorded here.
+- **AV1 — Shortcut content.** Platform-specific key text and caller-supplied
+  shortcut combinations may vary without changing the two-part anatomy recorded
+  here.
 
 ### Representative states
 
-- The same anatomy applies to single-key, multi-key, modifier, and
-  platform-resolved shortcuts.
+| State        | Required invariant                                        | Allowed variation |
+| ------------ | --------------------------------------------------------- | ----------------- |
+| Single key   | One badge; the name is the key's spoken name.             | Key.              |
+| Mod + key    | ⌘ or Ctrl by platform; name "Command" or "Control" + key. | Platform.         |
+| Repeated key | One badge per occurrence.                                 | —                 |
 
 ### Transformation and precedence order
 
-- No new parsing, layout, or styling precedence rule is introduced.
+- **ORD1 — Key resolution.** Split on `+` → trim → lowercase → alias → glyph
+  and spoken name.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- **PR1 — No listener.** Kbd attaches no event listener.
 
 ## Accessibility contract
 
-This draft does not change or extend Kbd's existing accessible-name behavior.
+- **AR1 — One name.** The shortcut is one image named by its spoken keys,
+  unless a caller's `aria-labelledby` names it; the glyph badges are hidden
+  (FR4).
+- **AR2 — Localization.** Visible short texts and spoken names follow the
+  provider locale through the catalog (FR3, FR4).
 
 ## Design relationships
 
 | Anatomy or state | Design requirement                                                 | Representation authority       | Hierarchy role | Component contract |
 | ---------------- | ------------------------------------------------------------------ | ------------------------------ | -------------- | ------------------ |
-| Shortcut         | Groups the complete shortcut and carries its accessible name.      | Current source and public docs | Supporting     | FR1, FR2           |
-| Key badge        | Paints one visible badge for each key in the supplied combination. | Current source and public docs | Prominent      | FR1, FR2           |
+| Shortcut         | Groups the complete shortcut and carries its accessible name.      | Current source and public docs | Supporting     | FR1, FR2, FR4      |
+| Key badge        | Paints one visible badge for each key in the supplied combination. | Current source and public docs | Prominent      | FR1–FR3            |
 
 ### Theming anatomy
 
@@ -116,25 +152,32 @@ target.
 - `architecture:component-theming-surface` owns anatomy qualification, target
   mapping, and the difference between factual reachability and intended public
   theming API.
+- `architecture:internationalization` owns catalog-backed Astryx text; FR3
+  and FR4 take their short texts, spoken names, and joining message from it.
 
 ## Verification map
 
-| Contract            | Verification                                     | Representative states           | Mutation or failure expectation                                                                  | Audit section       |
-| ------------------- | ------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------- |
-| FR1                 | `Kbd.test.tsx` key rendering suites              | Single-key and multi-key output | Removing the group or a parsed badge fails existing role, element, or text assertions.           | `audit:Kbd/anatomy` |
-| FR2                 | Source inspection and current target inventories | Root target and child badges    | Adding or documenting a current target without updating the anatomy map fails repository checks. | `audit:Kbd/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                    | Canonical anatomy and targets   | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.            | `audit:Kbd/theming` |
+| Contract            | Verification                                                                                                                                         | Representative states                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                       | Audit section             |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1                 | `Kbd.test.tsx` single-key, multi-key, whitespace, alias, and repeated-key cases                                                                      | Single and multiple keys; spaced and mixed-case input; repeated aliases | A missing or extra badge, an untrimmed or wrongly cased key, or a lost alias fails. Evidence gap: no test asserts badge height or text growth.                                                                                                                                                                                                        | `audit:Kbd/anatomy`       |
+| FR2                 | `Kbd.test.tsx` theme-class case                                                                                                                      | Root target and child badges                                            | A missing root `kbd` target fails. Evidence gap: no test asserts that badges carry no target.                                                                                                                                                                                                                                                         | `audit:Kbd/theming`       |
+| FR3, FR4            | `Kbd.test.tsx` glyph, platform, accessible-name, override, and localization cases ("localizes visible key text and the spoken shortcut combination") | Mac and non-Mac; special and unknown keys                               | A wrong glyph for `mod`, `ctrl`, `alt`, `shift`, `enter`, `escape`, `plus`, or an unknown key, an exposed badge, a caller `role` or `aria-label` that replaces the computed one, or text that skips the catalog fails. Evidence gap: no test asserts the `backspace`, `tab`, or arrow glyphs, or the "Ctrl" text and "Control" name before hydration. | `audit:Kbd/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                        | Canonical anatomy and targets                                           | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                                                                                                                                 | `audit:Kbd/theming`       |
+| ORD1, PR1, AR1, AR2 | ORD1 is covered by the FR1 and FR3 rows and AR1 and AR2 by the FR3, FR4 row. Evidence gap: no test asserts the absence of listeners                  | —                                                                       | —                                                                                                                                                                                                                                                                                                                                                     | `audit:Kbd/behavior`      |
+
+## Current-state impact
+
+- **Fixed badge height (FR1).** Badges hold a fixed height instead of growing
+  with a set text size, against `spec:AST-102` FR4.
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design
-or theming decision.
+No component-local decision.
 
 ## Open questions
 
 - **OQ1 — Should each Key badge gain a stable public theming target?**
-  (`human-api`) Target exposure is unsettled; the current lack of reachability
-  does not decide the answer.
+  (`human-api`) The current lack of reachability does not decide the answer.
 
 ## Content boundary