Skip to content

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

TypeScript

docs(spec): Code records its shipped contract as current (#8573)

Cindy Zhang423ebd18ddeb
diff --git a/packages/core/src/Code/Code.spec.md b/packages/core/src/Code/Code.spec.md
index 8686a02220..19c834a757 100644
--- a/packages/core/src/Code/Code.spec.md
+++ b/packages/core/src/Code/Code.spec.md
@@ -1,22 +1,20 @@
---
schema_version: 3
-template_version: 6
+template_version: 7
kind: component
id: component:Code
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-27
owners: [cixzhang]
review_triggers: [public-api, behavior, theming, accessibility, visual]
verified_by:
[
+ .github/visual-baseline/manifest.json,
packages/core/src/Code/Code.test.tsx,
packages/core/src/theme/themingTargets.test.ts,
- packages/core/src/docPropLiterals.test.ts,
- packages/core/src/docPropReferences.test.ts,
- packages/cli/foundation/doc-compiler/inputs.test.mjs,
.github/scripts/story-play-guard.js,
apps/storybook/stories/Code.stories.tsx,
apps/storybook/rtl-audit/verified-not-applicable.json,
@@ -31,7 +29,7 @@ architecture:
architecture:component-test-sufficiency,
]
contributing: []
-system_specs: []
+system_specs: [spec:AST-009]
---
# Code component contract
@@ -43,12 +41,12 @@ system_specs: []
| Public contract | `Code` is exported from `@astryxdesign/core/Code`; it requires `children`, defaults `color` to `primary`, optionally accepts `secondary` or `inherit`, and accepts `size="inherit"`. |
| Behavior | Code renders one semantic `<code>` element, uses the code type scale by default, and may inherit surrounding color or typography through explicit props. |
| End-user impact | Readers receive recognizable inline code that wraps instead of forcing its prose container wider. |
-| Builder impact | Builders can discover the complete released API, use Code for short inline references, and use CodeBlock for standalone or multi-line snippets. |
-| Compatibility/readiness | This audit restores missing consumer metadata and expands browser evidence. Runtime types, defaults, layout, and production component output are unchanged. |
+| Builder impact | None; the record describes shipped behavior. Short inline references use Code; standalone or multi-line snippets use CodeBlock. |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. |
| Review checks | Reject a non-`code` root, dropped content or root props, a ref that misses the root, a visual prop not reflected on the `code` target, undocumented released props/defaults, or a change that turns the inline component into a block-code replacement. |
| Governing rules | `architecture:public-component-api/INV1,INV5,INV6,INV8–INV9`; `architecture:component-theming-surface/INV3–INV7`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`. |
-This table is a review projection; the body below is authoritative only after owner approval.
+This table is a review projection; the body below is authoritative.
## Intent
@@ -57,7 +55,7 @@ Present short technical references inside prose with native code semantics and a
## Compatibility and migration
- Released default preserved: yes
-- Compatibility class: documentation and ownership restoration only; no runtime, type, default, style, target, or export change
+- Compatibility class: records shipped behavior; no runtime, type, default, style, target, or export change
- Controlled/uncontrolled behavior: not applicable; Code owns no state
- Migration decision: none
@@ -85,13 +83,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------ |
-| FR1 | Code MUST render one semantic `<code>` root containing the caller content. | shipped source, tests, docs, and HTML semantics | verify |
-| FR2 | Omitting `size` MUST use the code type-scale size; `size="inherit"` MUST inherit the surrounding font size and line height. `color` MUST select primary, secondary, or inherited text color. | shipped public types, source, tests, and stories | verify |
-| FR3 | Long inline content MUST remain wrap-capable, and Code MUST add only logical inline/block padding rather than physical-direction geometry. | shipped source and representative prose stories | verify |
-| FR4 | Supported DOM props, `className`, `style`, and `xstyle` MUST compose on the root, and the public ref MUST reach that root. | `architecture:public-component-api/INV5,INV6,INV8`; shipped source and tests | verify |
-| FR5 | The painted root MUST retain the public `code` target and reflect the `color` visual axis. No internal target or separate state target is part of the shipped surface. | `architecture:component-theming-surface/INV3–INV7`; source and theming-target inventory | verify |
+| ID | Invariant | Basis |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| FR1 | Code renders one semantic `<code>` root containing the caller content. | Shipped source, tests, docs, and HTML semantics |
+| FR2 | The root uses the code font family and, when `size` is omitted, `--text-code-size` with the surrounding line height; `size="inherit"` also inherits the surrounding font size. `color` selects primary text (default), secondary text, or the inherited color. | Shipped public types, source, tests, and stories |
+| FR3 | The root paints `--color-background-muted` with `--radius-inner` corners and logical `--spacing-1` inline and `--spacing-0` block padding, and long inline content breaks to wrap rather than widening its prose container. | Shipped source and representative prose stories |
+| FR4 | Supported DOM props, `className`, `style`, and `xstyle` compose on the root, and the public ref reaches that root. The `code` target and `data-color` reflection apply after caller DOM props; `xstyle`, `className`, and `style` compose as ORD1 orders them. | `architecture:public-component-api/INV5,INV6,INV8`; shipped source and tests |
+| FR5 | The painted root carries the public `code` target and reflects the `color` visual axis. No internal target or separate state target is part of the shipped surface. | `architecture:component-theming-surface/INV3–INV7`; source and target inventory |
### Allowed variation
@@ -129,7 +127,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------ | ------------------ |
| Container | Distinguishes short technical text through code typography and compact background treatment. | observed shipped representation | inline technical content | FR1–FR5, AR1–AR2 |
-No current design record prescribes exact Code pixels. This observational draft records the shipped representation without promoting draft typography guidance.
+No current design record prescribes exact Code pixels; exact tuning stays in code and visual evidence.
### Theming anatomy
@@ -145,27 +143,27 @@ No current design record prescribes exact Code pixels. This observational draft
- `architecture:public-component-api` owns export reachability, accepted root props, styling composition, ref reachability, released defaults, and consumer documentation.
- `architecture:component-theming-surface` owns target qualification, target placement, visual-axis reflection, and metadata ownership.
-- `architecture:component-test-sufficiency` owns the rational evidence set and rejects component functional tests for documentation-only corrections when shared schema and projection checks are the capable layer.
+- `architecture:component-test-sufficiency` owns the rational evidence set.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ----------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| FR1, AR1–AR2 | `Code.test.tsx`; semantic review of the Storybook fixtures | default and prose composition | The root stops being a code element, content disappears, or the component invents interaction or accessible naming. | `audit:Code/a11y` |
-| FR2 | `Code.test.tsx`; `Colors` and `TextSizes` play assertions in the required Chromium story-play guard | primary, secondary, inherited color, inherited size | A color choice stops reaching the target or inherited typography becomes visually indistinguishable from the fixed default. | `audit:Code/behavior` |
-| FR3 | `LongInlineContent` play assertion in the required Chromium story-play guard | constrained prose with an unbroken identifier | Inline code forces physical-direction geometry or no longer wraps in constrained prose. | `audit:Code/responsive` |
-| FR4 | `Code.test.tsx`; strict type/lint validation | ref plus supported styling and DOM passthrough | The ref misses the root or supported consumer inputs stop composing on it. | `audit:Code/api` |
-| FR5 | `themingTargets.test.ts`; Code consumer docs; source review | every color value | The target disappears or moves off the painter, color is no longer reflected, or metadata assigns the target to another owner. | `audit:Code/theming` |
-| RTL N/A | `verified-not-applicable.json` | every current story | Directional glyph, physical inline placement, ordering, scrolling, overlay, or horizontal keyboard behavior appears unmeasured. | `audit:Code/rtl` |
-| Consumer metadata | CLI `component Code --json`; docs typecheck; `docPropLiterals.test.ts`; `docPropReferences.test.ts` | required content, color values/default, inherited size | A released prop/default/target disappears from consumer discovery or docs name a value the source does not accept. | `audit:Code/docs` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1, AR1, AR2 | `Code.test.tsx` render test | Default | A non-`code` root or missing content fails. Gap: the render test still passes when a wrapper becomes the root, and no test fails if Code adds a role, tab stop, or name, and no accessibility-tree check proves the exposed content (`spec:AST-009` FR3). | `audit:Code/a11y` |
+| FR2, ORD2 | `Code.test.tsx` color tests; `Code.stories.tsx` `Colors` and `TextSizes` play checks in the story-play guard | Primary, secondary, inherited color; inherited size at four text sizes | A missing `data-color` reflection, secondary matching primary, inherited color or size not matching the parent, or every inherited size collapsing to one fails. Gap: the code font family and the default `--text-code-size` have no automated check beyond the visual baseline. | `audit:Code/behavior` |
+| FR3 | `Code.stories.tsx` `LongInlineContent` play check; stable visual baseline `core-code--default` | Constrained prose with an unbroken identifier; default | Code that stops wrapping or widens its container fails the play check; a changed background, radius, or padding comes back changed for review. Gap: no unit test asserts the paint or padding. | `audit:Code/responsive` |
+| FR4, ORD1 | `Code.test.tsx` ref and passthrough tests | Ref; `aria-label`, `className`, `style`, `xstyle` | A dropped ref, or a dropped caller prop, class, inline style, or `xstyle` class, fails. Gap: the ref test still passes when a wrapper receives the ref, and no test asserts that the target and `data-color` override caller DOM props or that caller `xstyle` follows the base styles. | `audit:Code/api` |
+| FR5 | `themingTargets.test.ts`; `Code.test.tsx` color tests | Every color value | A missing target or `data-color` reflection fails. | `audit:Code/theming` |
+| RTL not applicable | `@astryx/no-physical-properties` lint rule; `apps/storybook/rtl-audit/verified-not-applicable.json` entry | Every story | The lint rule fails a physical left/right property or value in Code's styles. Gap: no browser right-to-left check covers Code; the entry records the decision. | `audit:Code/rtl` |
+| PR1 | Source review | Every state | Gap: no automated check fails if Code adds state, an effect, or a listener. | `audit:Code/behavior` |
## Decision log
-None. This audit restores missing consumer metadata and records shipped behavior; it makes no new product decision.
+None recorded. The record describes shipped behavior.
## Open questions
-None. This observational draft does not decide exact visual tuning or broaden Code into a block-code component.
+None.
## Content boundary