[cixzhang]

Exact decision needed

Record Badge's shipped behavior as a current component contract (component:Badge). No behavior, API, or output change.

Existing authority searched

• pnpm specs:for packages/core/src/Badge/Badge.tsx: only directory-wide architecture records apply. The record links architecture:public-component-api (INV5, INV6, INV8: passthrough, styling inputs, ref) and architecture:component-theming-surface (INV2, INV6, INV14: target, state reflection, extensible axis), the two whose clauses it relies on. No family or design record names Badge.
• No Badge.spec.md existed on main.
• Open PRs: none edits a Badge record. fix(Badge): a badge grows with its text #8236 changes Badge's height in code and docs (not a record); this record describes main.
• Open issues: Badge: full label should be reachable by focus and on touch, and only when it is actually clipped #5585 (full label reachable by focus and on touch) is recorded as an implementation gap (AR4) and OQ1. [gap] Badge: Badge accepts arbitrary string children; counts-only rule unenforced #6719 (counts-only rule unenforced) asks for a lint rule or prop restriction; it describes consumer guidance, not a component defect, so the record does not carry it.

Decision

One record, packages/core/src/Badge/Badge.spec.md (authority: current, approved_by: cixzhang, approved_at: 2026-10-24). It owns:

• the root, optional leading Icon slot, and Label container;
• one-line geometry, typography, and the ellipsis overflow (FR1–FR3);
• the title derived from a string or number label (FR4);
• the built-in tones, their reflection on badge, and the unthemed fallback of a theme-added variant (FR5, FR6);
• ref/passthrough/styling routing (FR7) and server-safe rendering (FR8, PR1);
• static-text accessibility, meaning-in-text, delegated icon exposure, and full text in the DOM (AR1–AR4).

Rejected alternatives

None.

Claim scope and non-goals

Covers only Badge as shipped on main. Product choice of status/category and wording, the supplied icon's exposure (component:Icon), sibling presentations (component:Token, component:StatusDot), and theme token contrast stay with their owners. The theming-anatomy JSON block is omitted because Badge.doc.mjs anatomy lists no root part to carry the badge target; the record states the target mapping in prose. No new behavior is decided; OQ1 stays open.

Evidence and implementation relationship

• FR1, FR3: Badge.tsx base and label styles (inline-flex, --spacing-5 height, --spacing-2 inline padding, --radius-full, supporting type, medium weight, nowrap, maxWidth: 100%, minWidth: 0, label overflow: hidden + text-overflow: ellipsis); Badge.stories.tsx "Long labels in tight space" fixture.
• FR2: Badge.tsx render order (icon, then label span, gap: --spacing-1); Badge.test.tsx "renders with icon".
• FR4: Badge.tsx labelTitle; Badge.test.tsx full-label suite (string, number, rich, empty).
• FR5, FR6: Badge.tsx variant styles and themeProps('badge', {variant}); index.ts BadgeVariantMap; Badge.test.tsx data-variant assertions; extensibleAxes.test.ts and themingTargets.test.ts structural checks. A theme-added value indexes no entry in the variant style map, so only the base styles apply.
• FR7: Badge.tsx mergeProps(themeProps, stylex.props(base, variant, xstyle), className, style) then title, then ...props; Badge.test.tsx ref and passthrough tests.
• FR8, PR1: no hooks or client imports in Badge.tsx; serverSafeComponents.test.ts lists Badge as server-safe by import graph.
• AR1–AR3: root is a plain span with no role, tabIndex, or live region; the icon is rendered as supplied.

Current-state impact

• AR4: the clipped tail of a long label is reachable only through the native title on pointer hover; keyboard and touch users cannot reveal it (Badge: full label should be reachable by focus and on touch, and only when it is actually clipped #5585). Assistive technology receives the full DOM text.

Writing rubric results

• R1 narration: none; every row is present tense and states shipped behavior.
• R2 research in the record: none.
• R3 evidence naming a change: none; evidence names source, tests, and the story fixture.
• R4 rejected alternatives over one line or outside a decision: none.
• R5 pull request or issue references remaining: none (searched # + digits, /pull/, /issues/).
• R6 ruled open questions still listing options: none; OQ1 is unanswered and keeps its options.

Scope

• This PR contains specification records only.
• It records observable behavior and preserves equivalent internal implementations.
• Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract: none named beyond the public title attribute and badge target.
• Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
• It records one intentional durable decision, not a rescue for a separable tagalong.
• The canonical knowledge owner, affected current claims, and overlapping open work are named; no ownership collision.
• Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
• Public text and artifacts contain no internal Meta context.

Validation

• pnpm check:knowledge: aligned
• Prettier: clean
• git diff --check: clean

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Oct 24, 2026 6:42pm UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
❓ Needs maintainer input (for maintainers only)	Oct 24, 2026, 7:20 PM UTC

[github-actions]

PR Analysis Report

Current run: The current change has no visual or preview-producing scope. Visual checks are not applicable; preview links are not shown.

The exact-head preview is not available yet.

---

_{Generated by PR Enrichment workflow | View current CI run}

[astracat-bot]

This record matches Badge's shipped behavior for default usage, but as a new current contract it needs an engineering owner's decision before it governs: an engineering owner records it by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner. Independently of that decision, three corrections are needed:

• AR2 says tone color is never the only carrier of status, but the record allows an empty label, which renders a color-only badge with nothing in the accessibility tree; describe what Badge itself does and leave a non-empty label to the callsite.
• AR1 says the root carries no role and is not focusable, while FR7 passes a caller's role and tabIndex through; say instead that Badge adds none of its own.
• The verification map maps FR5 (the neutral default and tone paint) and FR6's unthemed fallback to tests that would not fail if those changed; narrow those rows and name the gaps.

[Automated review]

[astracat-bot]

AR1 says the root carries no role and is not focusable, but FR7 sends supported ARIA props to the root and BaseProps keeps role and tabIndex, so <Badge role="status" tabIndex={0} label="Syncing" /> is a focusable live region. Suggested wording: "Badge adds no role, tabIndex, or live region of its own; caller ARIA reaches the root under FR7."

[astracat-bot]

As written, AR2 promises the tone is never the only carrier of status, but the Label row allows an empty string, and <Badge variant="error" label="" /> renders a color-only pill with nothing in the accessibility tree. Consider stating what Badge does and leaving a non-empty label to the callsite (Badge.doc.mjs already says to always include a text label), or listing the empty-label case under Current-state impact.

[astracat-bot]

No assertion in Badge.test.tsx fails if the default stops being neutral or a tone's paint changes: the tone tests only call getByText, and data-variant is checked only for purple and success. FR2's icon-before-label order isn't asserted either. Suggest narrowing this row to what the tests prove and naming FR5 and FR2's order as verification gaps.

[astracat-bot]

These structural tests say in their own header that they can't judge a fallback, and the verification for architecture:component-theming-surface INV14 also names a focused no-match fallback test, which Badge doesn't have yet. Suggest naming FR6's fallback sentence as a verification gap in this row.

[astracat-bot]

The AR1, AR2 and verification-map updates resolve the earlier corrections, and the record matches Badge's shipped behavior, but as a new current contract it still needs an engineering owner's decision before it governs: an engineering owner records it by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner. Independently of that decision, two record corrections remain:

• The verification map has no row for AR1–AR3 and covers only the title half of AR4; name their evidence or the gap (none of the listed checks fails if Badge adds its own role, tab stop, live region or icon semantics), and note that FR2's icon-before-label order is untested.
• The Review checks cell still says to reject "an interactive or focusable badge", while AR1 now lets a caller role or tabIndex through; reword it to "a badge that adds its own role, tab stop, or live region".

[Automated review]

[astracat-bot]

This projection still says to reject "an interactive or focusable badge", but AR1 (lines 146–148) now lets a caller role or tabIndex through under FR7, so the cell adds a rule the body does not have. Suggested wording: "a badge that adds its own role, tab stop, or live region".

[astracat-bot]

AR1–AR3 have no row in this map, and the FR4/AR4 row fails only when the title changes. None of the listed files fails if Badge adds its own role, tab stop, live region or icon semantics, or truncates the label text, so consider a row such as "AR1–AR3, AR4 DOM text | source review | Gap: no listed check fails if Badge adds its own role, tab stop, live region or icon semantics", and name FR2's icon-before-label order as a gap in the first row.

[astracat-bot]

This record matches Badge's shipped behavior and the corrections from the earlier rounds are in, so nothing else needs to change in it. As a new current contract it still needs an engineering owner's decision before it governs: an engineering owner records it by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner. Open #8236 changes the badge height and minimum width that FR1 and FR3 pin, so whichever of the two lands second should reconcile them.

[Automated review]

[cixzhang]

/approve-spec 7c16ab1