Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): Kbd records its shipped contract as current (#9096)

Cindy Zhangfa3f76030382
diff --git a/packages/core/src/Kbd/Kbd.spec.md b/packages/core/src/Kbd/Kbd.spec.md
index f2741b6521..0964c7602d 100644
--- a/packages/core/src/Kbd/Kbd.spec.md
+++ b/packages/core/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