Skip to content

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

TypeScript

docs(core): record factual Text anatomy (#5757)

Cindy Zhangb09e3fd512e1
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index 89d3c654cc..533b5d7e23 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -1,12 +1,44 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Text',
+ required: true,
+ description:
+ 'Polymorphic text element that renders the supplied content with themed typography.',
+ },
+ {
+ name: 'Heading',
+ required: false,
+ description:
+ 'Referenced Heading member that renders the supplied content as a semantic h1–h6 element.',
+ },
+ {
+ name: 'Truncation tooltip',
+ required: false,
+ description:
+ 'Tooltip-owned surface available only when Text or Heading is measured as truncated and truncation tooltips are enabled.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
name: 'Text',
displayName: 'Text',
category: 'Content',
- keywords: ["text","typography","label","paragraph","heading","caption","font","body","subtitle"],
+ keywords: [
+ 'text',
+ 'typography',
+ 'label',
+ 'paragraph',
+ 'heading',
+ 'caption',
+ 'font',
+ 'body',
+ 'subtitle',
+ ],
playground: {
defaults: {
children: 'The quick brown fox jumps over the lazy dog.',
@@ -19,12 +51,14 @@ export const docs = {
{className: 'astryx-text', visualProps: ['type', 'size', 'color']},
],
},
- description: 'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.',
+ description:
+ 'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.',
props: [
{
name: 'type',
type: "'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3' | 'inherit'",
- description: "Semantic text type. Determines size, weight, and line-height from the theme. 'inherit' takes all three from the surrounding text instead. Themes may add custom types. Note: this prop is called `type`, not `variant`.",
+ description:
+ "Semantic text type. Determines size, weight, and line-height from the theme. 'inherit' takes all three from the surrounding text instead. Themes may add custom types. Note: this prop is called `type`, not `variant`.",
default: "'body'",
},
{
@@ -36,12 +70,14 @@ export const docs = {
{
name: 'size',
type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
- description: 'Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone.',
+ description:
+ 'Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone.',
},
{
name: 'color',
type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
- description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others. Themes may add custom colors.",
+ description:
+ "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others. Themes may add custom colors.",
},
{
name: 'weight',
@@ -51,7 +87,8 @@ export const docs = {
{
name: 'display',
type: "'inline' | 'block'",
- description: "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
+ description:
+ "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
default: "'inline'",
},
{
@@ -63,19 +100,22 @@ export const docs = {
{
name: 'maxLines',
type: 'number',
- description: 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
+ description:
+ 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
default: '0',
},
{
name: 'hasTruncateTooltip',
type: "boolean | 'above' | 'below' | 'start' | 'end'",
- description: "Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a placement string ('above' | 'below' | 'start' | 'end') sets a specific position.",
+ description:
+ "Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a placement string ('above' | 'below' | 'start' | 'end') sets a specific position.",
default: 'true',
},
{
name: 'wordBreak',
type: "'break-word' | 'break-all'",
- description: "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
+ description:
+ "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
},
{
name: 'textWrap',
@@ -85,13 +125,15 @@ export const docs = {
{
name: 'justify',
type: "'start' | 'center' | 'end'",
- description: 'Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility.',
+ description:
+ 'Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility.',
default: "'start'",
},
{
name: 'hasCapsize',
type: 'boolean',
- description: 'Enable optical alignment using text-box-trim. Forces block display.',
+ description:
+ 'Enable optical alignment using text-box-trim. Forces block display.',
default: 'false',
},
{
@@ -114,25 +156,61 @@ export const docs = {
{
name: 'xstyle',
type: 'StyleXStyles',
- description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
+ description:
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
},
],
- components: [
- {name: 'Heading'},
- ],
+ components: [{name: 'Heading'}],
usage: {
+ anatomy,
description:
'Text renders styled body text and headings from the theme. Use Text with a semantic type for body copy, labels, and captions, and Heading for section titles that output the correct h1\u2013h6 element.',
bestPractices: [
- { guidance: true, description: 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.' },
- { guidance: true, description: 'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.' },
- { guidance: true, description: 'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.' },
- { guidance: true, description: 'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.' },
- { guidance: false, description: 'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.' },
- { guidance: false, description: 'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.' },
- { guidance: false, description: 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.' },
- { guidance: false, description: 'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.' },
- { guidance: false, description: 'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.' },
+ {
+ guidance: true,
+ description:
+ 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.',
+ },
],
},
};
@@ -143,35 +221,104 @@ export const docsZh = {
description:
'Text renders styled body text and headings from the theme. Use Text with a semantic type for body copy, labels, and captions, and Heading for section titles that output the correct h1\u2013h6 element.',
bestPractices: [
- { guidance: true, description: 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.' },
- { guidance: true, description: 'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.' },
- { guidance: true, description: 'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.' },
- { guidance: true, description: 'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.' },
- { guidance: false, description: 'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.' },
- { guidance: false, description: 'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.' },
- { guidance: false, description: 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.' },
- { guidance: false, description: 'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.' },
- { guidance: false, description: 'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.' },
+ {
+ guidance: true,
+ description:
+ 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.',
+ },
],
},
};
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
- description: 'semantic body text + headings w/ theme-driven type scale, truncation, tabular numbers',
+ description:
+ 'semantic body text + headings w/ theme-driven type scale, truncation, tabular numbers',
usage: {
description:
'Text renders styled body text and headings. Text for body copy with semantic types, Heading for h1\u2013h6 with theme tokens.',
bestPractices: [
- { guidance: true, description: 'Semantic type (body, label, supporting, large, code) instead of manual size/weight.' },
- { guidance: true, description: 'accessibilityLevel on Heading when visual level differs from document outline.' },
- { guidance: true, description: 'maxLines for truncation; tooltip shows full text on hover.' },
- { guidance: true, description: 'hasTabularNumbers for aligned numeric columns.' },
- { guidance: false, description: 'Override size/weight when a semantic type already matches.' },
- { guidance: false, description: 'Skip heading levels; sequential h1 \u2192 h2 \u2192 h3.' },
- { guidance: false, description: 'Raw <p>/<h1>/<span>; use Text/Heading for theme tokens.' },
- { guidance: false, description: '`variant` prop, which does not exist. Use `type` for text styling or Heading for headings.' },
- { guidance: false, description: 'Text for headings: use Heading with level (1\u20136).' },
+ {
+ guidance: true,
+ description:
+ 'Semantic type (body, label, supporting, large, code) instead of manual size/weight.',
+ },
+ {
+ guidance: true,
+ description:
+ 'accessibilityLevel on Heading when visual level differs from document outline.',
+ },
+ {
+ guidance: true,
+ description:
+ 'maxLines for truncation; tooltip shows full text on hover.',
+ },
+ {
+ guidance: true,
+ description: 'hasTabularNumbers for aligned numeric columns.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Override size/weight when a semantic type already matches.',
+ },
+ {
+ guidance: false,
+ description: 'Skip heading levels; sequential h1 \u2192 h2 \u2192 h3.',
+ },
+ {
+ guidance: false,
+ description: 'Raw <p>/<h1>/<span>; use Text/Heading for theme tokens.',
+ },
+ {
+ guidance: false,
+ description:
+ '`variant` prop, which does not exist. Use `type` for text styling or Heading for headings.',
+ },
+ {
+ guidance: false,
+ description: 'Text for headings: use Heading with level (1\u20136).',
+ },
],
},
};
diff --git a/packages/core/src/Text/Text.spec.md b/packages/core/src/Text/Text.spec.md
new file mode 100644
index 0000000000..fc2431f753
--- /dev/null
+++ b/packages/core/src/Text/Text.spec.md
@@ -0,0 +1,205 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Text
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+ [
+ packages/core/src/Text/Text.test.tsx,
+ packages/core/src/Heading/Heading.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Text component contract
+
+## 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.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+ targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## 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.
+
+**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.
+
+## 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`.
+
+## 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.
+
+### 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.
+
+### 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. |
+
+### Transformation and precedence order
+
+- No new typography, truncation, element-selection, or styling precedence rule is
+ introduced.
+
+### 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.
+
+## 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.
+
+## 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 |
+
+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.
+
+## 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.
+
+## 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.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, behavior, accessibility, or theming decision.
+
+## Open questions
+
+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.