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.mjsindex 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.mdnew file mode 100644index 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.