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.mdindex 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: 7kind: componentid: component:Code-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-27owners: [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