An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-102): typography stays theme-owned, and a text size the person set wins (#8351)
Cindy Zhangb023d1c8299d
diff --git a/docs/design/mobile-typography.md b/docs/design/mobile-typography.mdindex 7d37f90c96..b3959a6043 100644--- a/docs/design/mobile-typography.md+++ b/docs/design/mobile-typography.md@@ -14,7 +14,7 @@ verified_by: [scripts/check-knowledge.mjs]architecture: [architecture:theme-tokens, architecture:theme-authoring-contract]components: []families: []-deciding_specs: []+deciding_specs: [spec:AST-102/DEC-2]---# Mobile typography design specification@@ -26,7 +26,7 @@ minimum on coarse-pointer iOS devices.## Design principles-- **DR1 — Reading base.** The mobile base MUST be `M = max(B, 16)`; 16px-reference is `1rem`.+- **DR1 — Reading base.** The mobile base MUST be `M = max(B, 16)`; 16px-reference is `1rem`. When the person has set a text size, it replaces this base and DR2's pin does not apply (`spec:AST-102` FR3).- **DR2 — Pin target.** The selected role MUST retain its desktop size; other roles follow the derived scale.## Anatomy and hierarchy@@ -55,7 +55,7 @@ divide by 16 for rem. Above the pin, roles shrink; below it, they grow## State representationOutside the mobile condition, retain desktop sizes.-When `B >= 16`, the mobile profile retains the desktop base and ratio.+When `B >= 16` and no text size is set, the mobile profile retains the desktop base and ratio.## Responsive and input behaviordiff --git a/docs/families/input-fields.md b/docs/families/input-fields.mdindex 8997a81a1f..4dff588afd 100644--- a/docs/families/input-fields.md+++ b/docs/families/input-fields.md@@ -98,7 +98,8 @@ another implementation helper.owns the group label and supporting text.- `FormLayout` owns outer arrangement, spacing, direction, and form-leveloptionality. It does not redefine a member's internal control geometry.-- `InputGroup` owns the fixed row height, connected outer surface, edge alignment,+- `InputGroup` owns the row height (fixed today; it grows with a set text size+ under `spec:AST-102` FR4, and the fixed height is a gap), connected outer surface, edge alignment,and group-level focus presentation for admitted children. Admission follows thecapability contract in FR3, not a permanent component allowlist; input-familymembership alone does not imply support.@@ -117,20 +118,20 @@ another implementation helper.## Canonical concepts-| Concept | Values or states | Default semantics | Stability |-| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |-| field shell | standalone Field or supported InputGroup path | One label/status owner surrounds the control | shipped pattern |-| field size | `sm`, `md`, `lg` where supported | Same-size single-line controls align without one state changing the row | approved family rule |-| inline size | intrinsic, explicit `Field.width`, or containing layout | A member keeps its available inline size across value and busy-state changes | approved rule; Selector exception below |-| end controls | absent, clear, busy, status, disclosure, or component content | Every rendered control has non-overlapping space; absent controls leave no unexplained reserve | approved family rule |-| grouped row | standalone or admitted InputGroup child | InputGroup owns fixed height, connected edges, and group focus; the child owns its grouped adaptation | approved capability contract; shipped adoption below |-| disabled reason | absent or component-supported `disabledMessage` | The reason remains keyboard- and assistive-technology-reachable while mutation stays blocked | approved family rule where exposed |-| input busy | explicit `isLoading` or pending `changeAction` where exposed | The field value is resolving or being saved | approved by DEC-2 and AST-001 |-| focus-zoom floor | iOS or non-iOS text entry | iOS text-entry controls floor rendered text at 16 CSS px to prevent focus zoom; other platforms retain theme sizing | approved family rule |-| source busy | component-owned async search or option loading | Supporting data work is separate from input `isLoading` | component/system-spec owned |-| Transition Action | absent or component-supported `changeAction` | Callback first, optimistic value next, Action in a transition, one busy presentation | approved family rule where exposed |-| status placement | `attached`, `detached`, or `tooltip` at the input-family layer | Attached is the default where the member supports safe overlap; detached and tooltip remain available to every input | approved family rule |-| prop targets | base props, `container*`, `control*` | Base props reach the primary semantic control; `container*` reaches Field; `control*` reaches the control box; no root styling input | approved by DEC-7 |+| Concept | Values or states | Default semantics | Stability |+| ----------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |+| field shell | standalone Field or supported InputGroup path | One label/status owner surrounds the control | shipped pattern |+| field size | `sm`, `md`, `lg` where supported | Same-size single-line controls align without one state changing the row | approved family rule |+| inline size | intrinsic, explicit `Field.width`, or containing layout | A member keeps its available inline size across value and busy-state changes | approved rule; Selector exception below |+| end controls | absent, clear, busy, status, disclosure, or component content | Every rendered control has non-overlapping space; absent controls leave no unexplained reserve | approved family rule |+| grouped row | standalone or admitted InputGroup child | InputGroup owns row height (grows with a set text size under `spec:AST-102` FR4), connected edges, and group focus; the child owns its grouped adaptation | approved capability contract; shipped adoption below |+| disabled reason | absent or component-supported `disabledMessage` | The reason remains keyboard- and assistive-technology-reachable while mutation stays blocked | approved family rule where exposed |+| input busy | explicit `isLoading` or pending `changeAction` where exposed | The field value is resolving or being saved | approved by DEC-2 and AST-001 |+| focus-zoom floor | iOS or non-iOS text entry | iOS text-entry controls floor rendered text at 16 CSS px to prevent focus zoom; other platforms retain theme sizing | approved family rule |+| source busy | component-owned async search or option loading | Supporting data work is separate from input `isLoading` | component/system-spec owned |+| Transition Action | absent or component-supported `changeAction` | Callback first, optimistic value next, Action in a transition, one busy presentation | approved family rule where exposed |+| status placement | `attached`, `detached`, or `tooltip` at the input-family layer | Attached is the default where the member supports safe overlap; detached and tooltip remain available to every input | approved family rule |+| prop targets | base props, `container*`, `control*` | Base props reach the primary semantic control; `container*` reaches Field; `control*` reaches the control box; no root styling input | approved by DEC-7 |## Cross-component invariants@@ -179,7 +180,8 @@ another implementation helper.FR2, and FR3 where grouped.- **FR8 — Status placement follows member capability.** Every input MUST offer`detached` and `tooltip`. A member supports `attached` only when its direct- control is opaque, bordered, fixed-height, and its owning root reliably+ control is opaque, bordered, fixed-height (a height set by its resolved size,+ which grows with a set text size under `spec:AST-102` FR4), and its owning root reliablyreflects the resolved size used for overlap. Where supported, `attached` isthe default. Wrapped, custom, tall, or translucent surfaces normally use`detached` or a component-owned placement. Direct FieldStatus continues to@@ -449,7 +451,9 @@ Every input offers detached and tooltip status placement. A member offersattached only when its direct control is opaque, bordered, fixed-height, and itsowning root reliably reflects the resolved size used for overlap. Attached is thedefault whenever it is supported. Wrapped, custom, tall, or translucent surfaces-normally use detached or retain component-owned placement.+normally use detached or retain component-owned placement. A fixed height is+one set by the resolved size, which grows with a set text size under+`spec:AST-102` FR4.Direct FieldStatus remains limited to attached and detached presentation. Tooltipis an input-family composition that Field consumes before rendering FieldStatus.diff --git a/docs/specs/AST-102-typography-theme-owned/spec.md b/docs/specs/AST-102-typography-theme-owned/spec.mdnew file mode 100644index 0000000000..c0b53966b9--- /dev/null+++ b/docs/specs/AST-102-typography-theme-owned/spec.md@@ -0,0 +1,178 @@+---+schema_version: 4+template_version: 2+kind: system-spec+id: spec:AST-102+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-10-25+phase: accepted+owners: [cixzhang]+affects_architecture: [architecture:theme-tokens]+affects_families: [family:input-fields]+affects_contributing: []+affects_consumer_docs: []+---++# Typography stays theme-owned system spec++<!-- path-applicability:v1 -->++```json+{+ "paths": ["packages/core/src/**", "packages/lab/src/**", "packages/themes/**"]+}+```++<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->++## Intent++People who set their own text size see it in every Core and Lab web+component, whatever the theme; people who have not set one see exactly the+font family and size the theme chose. No component swaps in a platform font or+its own text size. Where a shipped Astryx theme has no brand typeface for body+text, it can use the platform's own body font, so text reads like the rest of+the person's device.++## Non-goals++- Which typeface a branded theme uses; a brand keeps its own.+- The type scale itself: `design:typography-hierarchy` and+ `design:mobile-typography` own roles, sizes, and the mobile reading base.++## Requirements++- **FR1 — Components never override typography.** No Core or Lab web+ component sets the font family, font size, or line height of text it renders+ except through the theme's typography tokens; a value inherited from the+ surrounding text conforms. That includes platform font keywords such as `-apple-system-body`+ and system font stacks: a component never applies one directly, on any+ pointer. A hidden internal element that only measures a platform text style+ renders no text and conforms. A font size that sizes an icon, such as a `1em` icon at a+ `spec:AST-087` FR10 size, is not text typography. Native components follow+ the platform's own text settings (`spec:AST-082` FR11). Values a component+ sets come only from the theme. The one+ exception is a size floor a current family record requires, such as the iOS+ 16 px text-entry floor of `family:input-fields` FR9.+- **FR2 — Unbranded shipped themes may use the system body font.** An Astryx+ shipped theme whose body font is not branded MAY set its body font token to+ the platform's system body font family, such as `system-ui` or Apple's+ system font. A branded theme+ keeps its brand font for body text. The choice lives in the theme's token+ value, so components pick it up without change (FR1).++- **FR3 — A text size the person set wins; otherwise the theme's.** When the+ person has set a text size, through iOS Dynamic Type, the Android font scale,+ the browser's default font size, or zoom, Core and Lab web text follows it in+ every theme, branded included: the theme's sizes scale from the person's+ size, each role keeps its order, and the family stays the theme's. When the+ person has not set one, or the platform gives no signal, text uses exactly+ the theme's family and size. Following the setting adds no public theme+ option, prop, or document attribute and does not change the document-root+ font size (`design:mobile-typography` DR4). A size the person set+ replaces the mobile reading base of `design:mobile-typography` DR1, smaller+ or larger, and DR2's pin does not apply: every role scales from that size;+ DR1 and DR2 apply when none is set, and the iOS text-entry floor of+ `family:input-fields` FR9 still holds.+- **FR4 — Larger text stays usable.** Up to 200% of the theme's sizes, every+ component keeps all of its content and function (WCAG 2.2 success criterion+ 1.4.4). Above 200%, reading text keeps growing; a label inside a dense control, such+ as a tab, badge, table cell, or segmented control, MAY stop growing at 200%.+ A control grows with its text rather than holding a fixed height, so its+ height never clips a label; a truncation a component record already defines,+ such as the ellipsis of `component:Badge` FR3, `component:Button` FR5, or+ `component:Token` FR7, still applies.++### Platform support++- Supported feature/engine floor: the package's supported browsers+ (`spec:AST-013` FR1, FR3). Platform font keywords that an engine does not+ recognize fall back to the rest of the theme's font stack.+- Unsupported behavior: none beyond the font fallback above.+- Browser evidence (`spec:AST-013` FR10): Safari on iOS proves an FR2 theme's+ body text in the system body font and FR3 across Dynamic Type categories;+ Chrome on Android in the emulator proves FR3 with the system font scale; a+ desktop browser proves FR3 with its default font size and zoom, and FR4 at+ 200% and above; token and source checks prove FR1.++## Current-state impact++- Core's default body font is the system font stack, an unbranded value FR2+ allows. Each shipped theme package sets a brand body font and keeps it.+- Some components set typography outside the theme today, such as Lab's+ Sankey labels using `system-ui` directly and several Core and Lab components+ setting their own sizes or line heights; under FR1 those are conformance+ gaps.+- `architecture:theme-tokens`: text size tokens stay rem; Butter, Stone, and+ Y2K's 12 px supporting-size token is the token-level gap below. Spacing and+ element size tokens keep their values when a size is set; a control grows+ with its text under FR4.+- Defects under FR3 and FR4:+ - On iOS and iPadOS, text ignores Dynamic Type in every theme.+ - Butter, Stone, and Y2K fix supporting text at 12 px, so it does not follow+ a larger browser or Android text size.+ - Controls hold fixed heights, such as 40 px elements, `component:Badge`+ FR1's block size, `component:Button` FR4's and `component:Token` FR1's+ element sizes, and InputGroup's row height in `family:input-fields`, so a+ larger label can overflow; those records treat their sizes as minimums+ under FR4.+ - Whether Chrome on Android carries the system font scale to Astryx text is+ unverified until the emulator check FR3 names.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Source check over Core and Lab component styles plus token review | family, size, and line height of rendered text in component styles; an inherited value; a `1em` icon size; coarse and fine pointer; a platform font keyword; the iOS text-entry floor | A Core or Lab web component sets the family, size, or line height of text it renders outside typography tokens and not by inheritance, or applies a platform font keyword directly; icon sizing, the family floor, and a hidden internal element that only measures a platform text style are not failures |+| FR2 | Theme token review plus Safari on iOS, top-level document | an unbranded shipped theme using the system body font family; a branded theme; the default theme | A branded theme's body font replaced by the system font, or a system body font applied by a component instead of a theme token |+| FR3 | Safari on iOS across Dynamic Type categories; Chrome on Android in the emulator with font scale; a desktop browser with a larger default font size and with zoom; theme review | a branded and an unbranded theme; no size set; default category; a size set on each platform; macOS Safari | Text that ignores a size the person set; text that differs from the theme's family or size when none is set, other than the `family:input-fields` FR9 iOS text-entry floor; a theme family replaced; a public option, prop, or document attribute; a changed root font size |+| FR4 | Desktop browser at 200%, 250%, and 300% text size, plus Safari on iOS at accessibility categories | reading text; a button, text input, tab, badge, table cell, and segmented control | Lost content or function at 200% or less; a label clipped by its control's height at any size; a control that keeps a fixed height while its text grows |++## Decision log++### DEC-1 — Typography is the theme's; unbranded shipped themes may use the system body font++**Reference:** `spec:AST-102/DEC-1`+**Decider:** `cixzhang`, `2026-10-24`++A component that swaps in a platform font or its own text size breaks the+theme's typography for that one surface, and a product cannot see or tune it.+Keeping the family, size, and line height of component text in theme tokens+means the theme decides for that text. Where a shipped theme has no brand typeface, the system+body font is the most familiar choice for the person reading, so those themes+may use it through their own token; a brand keeps its typeface.++Rejected: components applying a platform font such as `-apple-system-body` directly.++### DEC-2 — A text size the person set wins in every theme++**Reference:** `spec:AST-102/DEC-2`+**Decider:** `cixzhang`, `2026-10-25`++A person who sets their text size expects to see it everywhere; a person who+has not expects the font the app chose. So every theme, branded included,+follows a size the person set, keeping its own family and scale relative to+that size, and gives its exact sizes when none is set. Large text stays usable+to 200% everywhere, and dense controls may stop at 200% without cutting text+off.++Rejected: only unbranded or opted-in themes following the person's size.++### DEC-3 — Following the person's size adds no public surface++**Reference:** `spec:AST-102/DEC-3`+**Decider:** `cixzhang`, `2026-10-25`++The person's size is honored by default, so products need no switch to turn it+on. Core reads it where the platform exposes it only through a system text+style, as on iOS, and lets the root font size carry it elsewhere; neither read+is a theme option, prop, or document attribute.++Rejected: a public opt-in option or document attribute for the size.++## Open questions++None.diff --git a/packages/core/src/Badge/Badge.spec.md b/packages/core/src/Badge/Badge.spec.mdindex 99a8198a11..4370b310ab 100644--- a/packages/core/src/Badge/Badge.spec.md+++ b/packages/core/src/Badge/Badge.spec.md@@ -98,16 +98,16 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |-| FR1 | Badge renders one inline-flex `span` root, centered on both axes, with block size `--spacing-5`, no block padding, inline padding `--spacing-2`, `--radius-full` corners, inherited font family, `--text-supporting-size` and `--text-supporting-leading` type, and `--font-weight-medium` weight. | Current source |-| FR2 | When `icon` is supplied it renders directly inside the root, before the Label container, separated by `--spacing-1`; the label always renders inside its own Label container. | Current source and tests |-| FR3 | The badge is one line and never wraps. The root is capped at the inline size of its container and may shrink below its content size; a label that does not fit is clipped with a trailing ellipsis inside the Label container and does not escape the badge. | Current source and consumer docs |-| FR4 | A non-empty string label or any number label sets the root `title` to the label text, whether or not the label is clipped. A rich-node or empty-string label sets no `title`. | Current source and tests |-| FR5 | `variant` defaults to `neutral`. `neutral` paints `--color-neutral` with primary text; `info`, `success`, `warning`, and `error` paint the solid accent, success, warning, and error colors with their matching on-color text; each color variant paints its tinted background with its matching colored text. | Current source and consumer docs |-| FR6 | The `badge` target carries the resolved `variant` for every value, including a value a theme adds through `BadgeVariantMap`. A theme-added value receives no component fill or text color, so it renders the FR1 geometry over a transparent background in the inherited text color until a theme paints it. | Current source and extensible-axis test |-| FR7 | `ref` reaches the root `span`. Supported DOM, ARIA, data, and event props reach the root; `xstyle`, `className`, and `style` merge in that order after the component styles. | Current source and tests |-| FR8 | Badge uses no hooks, measurement, or client-only API, so it renders identically on the server and the client. | Current source and server-safety test |+| ID | Invariant | Basis |+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |+| FR1 | Badge renders one inline-flex `span` root, centered on both axes, with block size `--spacing-5` (at least that size once it grows with a set text size under `spec:AST-102` FR4; today's fixed size is a gap), no block padding, inline padding `--spacing-2`, `--radius-full` corners, inherited font family, `--text-supporting-size` and `--text-supporting-leading` type, and `--font-weight-medium` weight. | Current source |+| FR2 | When `icon` is supplied it renders directly inside the root, before the Label container, separated by `--spacing-1`; the label always renders inside its own Label container. | Current source and tests |+| FR3 | The badge is one line and never wraps. The root is capped at the inline size of its container and may shrink below its content size; a label that does not fit is clipped with a trailing ellipsis inside the Label container and does not escape the badge. | Current source and consumer docs |+| FR4 | A non-empty string label or any number label sets the root `title` to the label text, whether or not the label is clipped. A rich-node or empty-string label sets no `title`. | Current source and tests |+| FR5 | `variant` defaults to `neutral`. `neutral` paints `--color-neutral` with primary text; `info`, `success`, `warning`, and `error` paint the solid accent, success, warning, and error colors with their matching on-color text; each color variant paints its tinted background with its matching colored text. | Current source and consumer docs |+| FR6 | The `badge` target carries the resolved `variant` for every value, including a value a theme adds through `BadgeVariantMap`. A theme-added value receives no component fill or text color, so it renders the FR1 geometry over a transparent background in the inherited text color until a theme paints it. | Current source and extensible-axis test |+| FR7 | `ref` reaches the root `span`. Supported DOM, ARIA, data, and event props reach the root; `xstyle`, `className`, and `style` merge in that order after the component styles. | Current source and tests |+| FR8 | Badge uses no hooks, measurement, or client-only API, so it renders identically on the server and the client. | Current source and server-safety test |### Allowed variationdiff --git a/packages/core/src/Button/Button.spec.md b/packages/core/src/Button/Button.spec.mdindex 9566717fb6..d74820befb 100644--- a/packages/core/src/Button/Button.spec.md+++ b/packages/core/src/Button/Button.spec.md@@ -120,7 +120,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR1 | Without link mode Button renders one native `<button>` with `type="button"` unless `type` says otherwise; `name`, `value`, and `form` reach that element. | `family:buttons` FR2; current source and tests || FR2 | Content renders in this order: the leading `icon` slot, the label text (`children` when supplied, else `label`), then `endContent`. Icon-only renders the icon alone and omits the label text and `endContent`. `endContent` inherits the Button's text color. | `family:buttons` AV2; current source and tests || FR3 | An Astryx Icon in the `icon` slot without an explicit size renders `sm` in `sm` and `md` Buttons and `md` in `lg` Buttons; an explicit Icon size wins. | `family:buttons` FR7; current source |-| FR4 | Height comes from the shared element size for the resolved size: an explicit `size` wins, then the nearest size provider, then `md`. Icon-only is square (`--button-icon-only-aspect`, default `1 / 1`) with no padding. | `family:buttons` FR7; `architecture:component-size-cascade` INV3–INV5 |+| FR4 | Height comes from the shared element size for the resolved size, as a minimum that grows with a set text size under `spec:AST-102` FR4 (today's fixed height is a gap): an explicit `size` wins, then the nearest size provider, then `md`. Icon-only is square (`--button-icon-only-aspect`, default `1 / 1`) with no padding. | `family:buttons` FR7; `architecture:component-size-cascade` INV3–INV5 || FR5 | The label stays on one line. A labelled Button may shrink in a row, never exceeds its container's inline size, and truncates the label with an ellipsis. An explicit `width` applies in button and link modes and is still capped at the container. Icon-only does not shrink and is not capped. | Current source and tests || FR6 | On activation `onClick` runs first. If it calls `preventDefault()`, `clickAction` does not run. Otherwise `clickAction` runs, and the Button is pending until its promise settles. | `family:buttons` FR5; current source and tests || FR7 | A fire-once `clickAction` runs once per in-flight action: a second activation while it is pending, including a same-tick double-click, does nothing. With `isInterruptible`, a pending Button stays operable and each activation starts a new `clickAction`. | `family:buttons` FR5; current source and tests |diff --git a/packages/core/src/Token/Token.spec.md b/packages/core/src/Token/Token.spec.mdindex 10c942e5d7..6b7b454def 100644--- a/packages/core/src/Token/Token.spec.md+++ b/packages/core/src/Token/Token.spec.md@@ -129,7 +129,7 @@ Consumer migration instructions belong in consumer docs and release notes.| ID | Invariant | Basis || ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | Content renders in logical inline order: Icon, Label, End content, Remove button. The root is inline-flex with `--spacing-1` gaps, inline padding `--spacing-2`, `--radius-inner` corners, `--text-supporting-size` type at `--font-weight-medium`, and block size `--size-element-sm`, `-md`, or `-lg` minus 8px for `sm`, `md`, and `lg`. | Current source and tests |+| FR1 | Content renders in logical inline order: Icon, Label, End content, Remove button. The root is inline-flex with `--spacing-1` gaps, inline padding `--spacing-2`, `--radius-inner` corners, `--text-supporting-size` type at `--font-weight-medium`, and a minimum block size of `--size-element-sm`, `-md`, or `-lg` minus 8px for `sm`, `md`, and `lg`. That size grows with a set text size under `spec:AST-102` FR4; today's fixed size is a gap. | Current source and tests || FR2 | With no `href`, `onClick`, or enclosing trigger context, the token is a static `span` holding its content directly. | Current source and tests || FR3 | With an enabled `href` and no `onRemove`, the token root is the shared link component carrying the destination; it takes the root ref, passthrough props, and its own focus-visible outline. A supplied `onClick`, as an accepted event input, reaches the element that owns the contract (`architecture:public-component-api` INV5). Implementation gap: in both link structures `onClick` is not attached or called (Current-state impact). | Current source and tests || FR4 | With `onClick`, or an enclosing trigger context that resolves the token to a button, the root is a `span` container holding an inner `button` that wraps only the Label and calls `onClick`; a click on the container outside any nested button or link also calls `onClick`. With an enabled `href` and `onRemove`, the container instead holds an inner link wrapping only the Label; a plain click on the surface outside the Remove button follows that link, and a Cmd/Ctrl-click or middle click on the surface opens it in a new tab. A caller `onMouseUp` on the link-and-remove container runs before its delegation. | Current source and tests |