An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): Text records its shipped contract as current (#8664)
Cindy Zhanga4ca90cc305e
diff --git a/packages/core/src/Text/Text.spec.md b/packages/core/src/Text/Text.spec.mdindex 48485c1547..ed5fcfbf53 100644--- a/packages/core/src/Text/Text.spec.md+++ b/packages/core/src/Text/Text.spec.md@@ -1,199 +1,187 @@---schema_version: 3-template_version: 3+template_version: 7kind: componentid: component:Text-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: [theming]+review_triggers: [public-api, behavior, layout, theming, accessibility]verified_by:[+ .github/visual-baseline/manifest.json,packages/core/src/Text/Text.test.tsx,- packages/core/src/Heading/Heading.test.tsx,+ packages/core/src/Text/useTruncation.test.tsx,packages/core/src/theme/themingTargets.test.ts,- scripts/check-knowledge.mjs,+ apps/storybook/stories/Text.stories.tsx,]modules: []families: []design_specs: []-architecture: [architecture:component-theming-surface]+architecture:+ [architecture:component-theming-surface, architecture:public-component-api]contributing: []-system_specs: []+system_specs: [spec:AST-009]---# Text component contract+## Contract at a glance++| Area | Contract |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| Public contract | A polymorphic text element with a semantic `type`, optional `size`, `color`, and `weight` overrides, an `as` element choice, and the text layout controls documented in `Text.doc.mjs`. |+| Behavior | `type` sets size, weight, and default color from the theme; theme-added types and colors fall back to the body and primary baselines; truncated text offers its full content in a Tooltip. |+| End-user impact | Readers get consistent type across the product; clamped text keeps its full content available on hover and in the DOM. |+| Builder impact | None; the record describes shipped behavior. |+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact. |+| Review checks | Reject a theme-added type or color that renders unstyled, a native `title` beside the truncation Tooltip, or measurement when the tooltip is off. |+| Governing rules | `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`. |++This table is a review projection; the body below is authoritative.+## Intent-Text renders themed body text through the Text component and semantic headings-through its referenced Heading member. This draft records their current consumer-anatomy, the two live root targets owned by the canonical Text documentation, and-the conditional Tooltip delegation used for truncated content. It does not-change runtime behavior, styling, targets, or public API.+Text renders themed body copy, labels, captions, and display text. It owns the+mapping from a semantic type to theme typography, the element it renders, and+the truncation behavior of that element. Heading is documented beside Text in+`Text.doc.mjs` but is a separate component with its own record.## Compatibility and migration- Released default preserved: `yes`-- Compatibility class: additive documentation only; runtime, DOM, styling,- targets, and public API remain unchanged+- Compatibility class: records shipped behavior; no public prop, default, DOM,+ or styling output changes- Controlled/uncontrolled behavior: not applicable- Migration decision: noneConsumer migration instructions belong in consumer docs and release notes.+## Current-state impact++- **Truncation tooltip not reachable by keyboard (FR4).** A truncated Text+ is not focusable, so Tooltip attaches no focus trigger and sighted keyboard+ users cannot reveal the clipped text, where WCAG 2.2 2.1.1 expects+ functionality to be keyboard operable. The full text stays in the DOM for+ assistive technology.+## Ownership boundary**Owns**-- The polymorphic Text element and its current `text` theming target.-- The referenced Heading member's semantic heading element and its current- `heading` theming target.-- Deciding from the current truncation state whether to compose Tooltip against- the Text or Heading element.+- The polymorphic text element and its `text` theming target.+- Type-based size, weight, and default color; size, color, and weight+ overrides; and the text layout controls on that element.+- Measuring truncation and deciding when to compose the truncation Tooltip.**Does not own / non-goals**-- The truncation tooltip surface, layer behavior, or `tooltip` target — owned by- Tooltip when that composed surface renders.-- Content supplied as Text or Heading children — owned by the caller.-- A separate Heading component contract; Heading remains a referenced member of- the canonical Text documentation and target inventory.-- New typography behavior, truncation behavior, semantics, styling, targets,- public API, or target aliases.+- Heading, its `h1`–`h6` element, and its `heading` target — owned by+ `component:Heading`. The `heading` target and Heading anatomy listed in+ `Text.doc.mjs` belong to that record.+- The truncation tooltip surface, layer, and `tooltip` target — owned by+ Tooltip.+- Typography token values — owned by the active theme.+- Text content — owned by the caller.## Public concepts-No new public concept is introduced. Text and Heading props, defaults, and usage-remain documented in `Text.doc.mjs` and `Heading.doc.mjs`.+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ---------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------- | ---------------- | --------- | --------------------------------------------------------------------------------- |+| Type | `body`, `large`, `label`, `supporting`, `code`, `display-1`, `display-2`, `display-3`, `inherit`; theme additions | Selects size, weight, line height, and default color. | Always | `body` | `component:Text` | Stable | A theme-added type is reflected on `text` and renders with body baseline styles. |+| Color | built-in text colors; theme additions | Text color. | Always | `secondary` for `supporting`, `inherit` for `inherit`, else `primary` | `component:Text` | Stable | A theme-added color is reflected on `text` and renders with the primary baseline. |+| Element | `span`, `p`, `div`, `label`, `h1`, `h2`, `h3` | The rendered element. | Always | `span` | `component:Text` | Stable | TypeScript rejects other values. |+| Truncation | `maxLines` 0 (none), 1, or more; tooltip on, off, or at a placement | Clamps lines and offers the full text in a Tooltip. | Always | 0; tooltip on | `component:Text` | Stable | — |## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------- |-| FR1 | Text renders one polymorphic text element carrying the current `text` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |-| FR2 | Heading renders one semantic `h1`–`h6` element carrying the current `heading` target. Heading is a referenced member of Text rather than a nested Text element. | Current source, docs, tests, and target history | Verified current behavior and canonical ownership |-| FR3 | Text or Heading composes Tooltip only when `maxLines` is positive, truncation tooltips are enabled, and measurement reports that the rendered content is truncated. Otherwise the truncation Tooltip path does not render. | Current source, tests, and truncation history | Verified current conditional behavior |-| FR4 | When the conditional truncation path renders, Tooltip owns the layer surface and applies the `tooltip` target. Text and Heading retain their own root targets and do not apply or claim Tooltip's target. | Current source and owner target metadata | Verified current ownership; no target change |-| FR5 | Text reflects `type`, `size`, and resolved `color` on `text`; Heading reflects `level`, `color`, and an explicitly supplied `type` on `heading`. Display mode, truncation state, semantic element choice, and Tooltip open state do not become separate anatomy parts or Text-owned targets. | Current source, docs, tests, and target inventory | Verified current capabilities; no new anatomy decided |--### Observed current behavior--These observations describe the implementation; they do not establish new-intent:--- Text defaults to a `span` and may render another supported text element through- `as`. Heading maps `level` directly to `h1` through `h6`.-- Both members render caller content directly inside their targeted root element;- neither creates a separately targeted content wrapper.-- Both members measure truncation only when `maxLines` is positive. When the- measurement reports overflow and `hasTruncateTooltip` is not `false`, they- lazy-load Tooltip in sibling-anchor mode.-- Tooltip owns its layer lifecycle and applies `tooltip` only to its own rendered- layer. The truncated Text or Heading element remains the anchor and keeps only- its own target.-- Text and Heading no longer add a native `title` for this path; the composed- Tooltip is the single tooltip presentation.+| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |+| FR1 | Text renders one element chosen by `as` (default `span`) carrying the `text` target, which reflects `type`, `size`, and the resolved `color`. | Current source and tests |+| FR2 | A built-in `type` applies its size, line height, and default weight; a theme-added type applies the body baseline. `size` overrides the type's size while keeping its other properties; `weight` overrides the type's default weight. The resolved color is `color`, else the type's default; a theme-added color applies the primary baseline. | Current source and tests |+| FR3 | `hasCapsize` renders `block` and trims to cap height; otherwise `maxLines` above 1 renders the line-clamp box, `maxLines={1}` renders `block`, and otherwise `display` (default `inline`) applies. `justify` uses logical values; `start`, the default, sets no alignment, so the element follows its container's. `textWrap`, `hasStrikethrough`, and `hasTabularNumbers` apply their text treatments. | Current source and tests |+| FR4 | `maxLines={1}` clips one line with an ellipsis; a larger value clamps to that many lines unless `hasCapsize` is set, whose `block` display removes the clamp. With truncation, `wordBreak` defaults to `break-all` for one line and `break-word` otherwise. When the text is measured as truncated and `hasTruncateTooltip` is not `false`, a lazily loaded Tooltip anchored to the element shows the full text at the given placement (default `above`), and Text adds no native `title`. `hasTruncateTooltip={false}` takes no measurement. A truncation tooltip can be opened from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip opens on hover and touch only, because the element is not focusable (Current-state impact). Truncation re-measures when the content changes without a resize. | Current source and tests |+| FR5 | `ref` reaches the element. Supported DOM, ARIA, data, and event props reach it; `xstyle`, `className`, and `style` merge in that order after component styles, with the line clamp applied after `style`. | Current source and tests |### Allowed variation-- **AV1 — Text element and content.** Text may use any currently supported `as`- element and either member may contain caller-supplied content without changing- target ownership.-- **AV2 — Typography.** Level, type, size, color, weight, wrapping, decoration,- and theme or consumer styling may vary through the existing APIs and targets.-- **AV3 — Conditional tooltip.** Fitting content, disabled truncation tooltips,- and non-truncating configurations omit the delegated Tooltip path.+- **AV1 — Theme paint.** A theme may restyle `text` per `type`, `size`, and+ `color`, and define added types and colors, without changing the element.+- **AV2 — Element.** Callers choose any supported `as` element.### Representative states-| State | Required invariant | Allowed variation |-| ----------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------- |-| Text without truncation | One Text element carries `text`; no truncation Tooltip path renders. | Supported element, content, and typography props. |-| Heading without truncation | One semantic heading carries `heading`; no Text target or truncation Tooltip path renders. | Heading level, accessibility level, and type. |-| Truncation configured but content fits | The owning Text or Heading root remains; no truncation Tooltip path renders. | Line limit and available width. |-| Truncated with tooltip disabled | The owning root remains clipped; no truncation Tooltip path renders. | Text or Heading owner. |-| Truncated with tooltip enabled and opened | The owning root anchors one Tooltip-owned surface carrying `tooltip`. | Placement and full text content. |+| State | Required invariant | Allowed variation |+| ----------------------- | ------------------------------------------------------- | ----------------- |+| Default | `span` with body type and primary color. | Content. |+| Supporting | Supporting type with secondary color. | Color override. |+| Theme-added type | Body baseline; `data-type` names the added type. | Theme paint. |+| Truncated with tooltip | Clamped element anchors one Tooltip; no native `title`. | Placement. |+| Truncation, tooltip off | Clamped element; no measurement; no Tooltip. | — |### Transformation and precedence order-- No new typography, truncation, element-selection, or styling precedence rule is- introduced.+- **ORD1 — Color.** `color` → type default → `primary`; a theme-added value+ styles from the primary baseline.+- **ORD2 — Size and weight.** `size` and `weight` → type values → body baseline+ for a theme-added type.+- **ORD3 — Display.** `hasCapsize` (`block`) → `maxLines` above 1 (line-clamp+ box) → `maxLines={1}` (`block`) → `display` prop.### Performance and resources-- This draft records the current shared ResizeObserver-based truncation path and- lazy Tooltip composition but introduces no new measurement, observer, render,- or loading requirement.+- **PR1 — Measured only when needed.** Truncation is measured only when+ `maxLines` is positive and the tooltip is enabled; re-measuring follows size+ and content changes without a per-element observer; the Tooltip module loads+ only when the text is truncated.## Accessibility contract-This draft does not change or extend Text's polymorphic semantics, Heading's-native heading level and optional `aria-level`, or Tooltip's existing-`aria-describedby` ownership for truncated content.+- **AR1 — Caller-chosen semantics.** Text adds no role; its semantics are those+ of the `as` element. Heading semantics for section titles come from+ `component:Heading`.+- **AR2 — Truncated text.** The full text stays in the element's DOM; the+ truncation Tooltip is the only tooltip, and any description it adds is+ Tooltip's.## Design relationships-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |-| ------------------ | --------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |-| Text | Presents caller content in the current polymorphic text element. | Current source and public docs | Prominent | FR1, FR5 |-| Heading | Presents caller content in the referenced semantic Heading member. | Current source and public docs | Prominent | FR2, FR5 |-| Truncation tooltip | Presents the full content only on the current measured-overflow and enabled path. | `component:Tooltip` | Supporting | FR3, FR4 |+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ------------------ | -------------------------------------------- | ------------------------ | -------------- | ------------------ |+| Text | Caller content in themed typography. | Current source and docs | Prominent | FR1–FR3, AR1 |+| Heading | A separate component documented beside Text. | `component:Heading` | Prominent | — |+| Truncation tooltip | The full text when the element is clamped. | Tooltip | Supporting | FR4, AR2 |-Text and Heading are sibling public components represented by the canonical Text-documentation; Heading is not nested inside Text. The Tooltip row is conditional-composition rather than a Text- or Heading-owned surface.--### Theming anatomy--<!-- anatomy-theming:v1 -->--```json-{- "Text": {"target": "text"},- "Heading": {"target": "heading"},- "Truncation tooltip": {- "delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}- }-}-```--The two local targets are the exact current targets declared by the canonical-Text doc. The delegated `tooltip` target applies only when the conditional-truncation path reaches Tooltip and Tooltip renders its layer; it is not a-Text- or Heading-owned target. No anatomy part requires a `none` disposition.+Theming: the element is the single `text` target. `Text.doc.mjs` also lists the+`heading` target and Heading anatomy, which `component:Heading` owns, so this+record declares no anatomy-theming block rather than assign `heading` to Text.## Family and system relationships-- `architecture:component-theming-surface` owns anatomy qualification, aggregate- parent/member target ownership, exact target mapping, and delegation.-- Text is the canonical documentation and contract owner for both `text` and- `heading`; Heading remains a referenced member and does not receive a separate- component spec.-- Tooltip retains ownership of its delegated surface, interaction behavior, and- `tooltip` target.+- `component:Heading` shares Text's type styles and truncation mechanism and+ owns its own element, target, and accessibility.+- `architecture:component-theming-surface` sets the rules the `text` target+ follows (INV6) and the safe baseline for theme-added types and colors+ (INV14).+- `architecture:public-component-api` owns ref, passthrough, and styling-input+ rules; FR5 applies them.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------- |-| FR1, FR5 | `Text.test.tsx` and `themingTargets.test.ts` | Default, polymorphic, custom type/color, explicit size | Removing, renaming, or changing the current Text target capabilities fails focused or global target assertions. | `audit:Text/theming` |-| FR2, FR5 | `Heading.test.tsx`, `themingTargets.test.ts`, and target-introduction history | Levels 1–6, display type, custom color | Removing, renaming, or changing the current Heading target capabilities fails focused or global assertions. | `audit:Heading/theming` |-| FR3, FR4 | Text and Heading source inspection, truncation tests, Tooltip target metadata, and fix history | Fitting, overflowing, disabled, enabled | Moving the surface or target into Text/Heading, or restoring a native duplicate tooltip, violates current evidence. | `audit:Text/anatomy` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy, both local targets, Tooltip delegate | Missing, extra, prefixed, stale, multiply assigned, or invalid delegated mappings fail repository validation. | `audit:Text/theming` |--Current focused tests pin both local target names and Text's lack of a duplicate-native `title`. The conditional Tooltip path and Heading's matching no-`title`-behavior are established by shared source shape and history rather than a-separate focused assertion in each suite.+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |+| FR1, AR1 | `Text.test.tsx` element, target, and reflection tests | Default `span`; `p`, `div`, `label` | A wrong element, a lost `text` class, or a lost `data-type`, `data-size`, or `data-color` reflection fails. Gap: no test asserts that Text adds no role, and no accessibility-tree check proves the element's role (`spec:AST-009` FR3). | `audit:Text/behavior` |+| FR2 | `Text.test.tsx` theme-added type and color tests; stable visual baseline `core-text--body` | Theme-added type and color; built-in color; body default | A theme-added type or color losing its reflection, a theme-added color losing its primary baseline, or a lost color override, fails; a changed body scale or color comes back changed for review. Gap: no test asserts a theme-added type's body baseline (the custom-type test checks only the class and `data-type`), and the built-in type tests assert presence only, so each type's size, line height, and weight, and the `size` and `weight` overrides in paint, have no automated check. Each type's default color and a built-in color's paint also have no automated check; the color tests assert `data-color` only. | `audit:Text/theming` |+| FR3 | `Text.stories.tsx` | Display, cap-height trim, wrap, strikethrough, tabular numbers | Gap: the prop tests assert presence only, so `display` precedence, `justify`, and every text treatment have no automated check. | `audit:Text/behavior` |+| FR4, AR2, PR1 | `Text.test.tsx` native-title and truncation-measurement tests; `useTruncation.test.tsx` | Truncated with tooltip; tooltip off; content change | A native `title`, measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. Gap: the ellipsis and line clamp, the `wordBreak` defaults, and the tooltip's appearance and placement have no automated check. | `audit:Text/a11y` |+| FR5 | `Text.test.tsx` ref and passthrough tests | Rerender; `data-testid` | A detached ref or a lost test id fails. Gap: no test covers other DOM passthrough, the styling-input merge order, or the line clamp after `style`. | `audit:Text/behavior` |## Decision log-None. This draft records current facts and introduces no component-local design,-API, behavior, accessibility, or theming decision.+None recorded. The record describes shipped behavior.## Open questions@@ -201,6 +189,5 @@ None.## Content boundary-This file does not duplicate consumer prop tables/examples, typography token-values, truncation measurement mechanics, Tooltip internals, implementation-steps, current audit results, or system theming rules. It links to their owners.+This file does not duplicate consumer prop tables/examples, current audit+results, implementation steps, or family/system rules. It links to their owners.