{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "text", "title": "Text", "description": "Semantic plain UI text with atomic tokenized typography recipes, measurable line boxes, and composition-owned wrapping and truncation.", "type": "registry:ui", "meta": { "library": "@ds-mo/ui", "distribution": "npm", "storybook": "https://zainadeel.github.io/compomo/?path=/story/text", "source": "src/wc/components/Text/Text.tsx", "intentStatus": "complete", "intent": { "audience": "general", "status": "stable", "summary": "Semantic plain UI text with atomic tokenized typography recipes, measurable line boxes, and composition-owned wrapping and truncation.", "useWhen": [ "Plain UI text needs a complete design-system typography recipe.", "Headings, paragraphs, labels, or inline phrasing need native HTML semantics independent from their visual scale.", "A component needs a stable measurable text box aligned to shared typography metrics.", "Changing numeric values need tabular glyph widths." ], "avoidWhen": [ "Content is markdown, rich prose, or an arbitrary nested document structure.", "The element is interactive; use the correct native or design-system control and compose Text only for its label.", "Individual font metrics must be overridden instead of selecting an existing complete variant.", "Typography alone would be used to repair an incorrect heading hierarchy." ], "alternatives": [ { "when": "Predictable text geometry is pending while content loads.", "component": "component:ds-skeleton", "reason": "Skeleton owns aria-hidden loading geometry aligned to Text line metrics." }, { "when": "Compact static metadata or semantic status needs a contained treatment.", "component": "component:ds-tag", "reason": "Tag owns compact labelled metadata and intent surfaces." } ], "commonlyComposedWith": [ "component:ds-icon", "component:ds-card-setting", "component:ds-field", "component:ds-button-filled" ], "accessibility": [ "Choose the native element from document meaning and hierarchy; choose the visual variant independently.", "Composition authors preserve logical h1–h6 order regardless of visual size.", "Visible content and the selected native element provide accessible meaning; avoid redundant roles and labels.", "Use label semantics and its for association only for a real form control.", "When truncating essential content, the owner provides an accessible way to obtain the omitted text.", "Tertiary and quaternary foregrounds are restricted to text inside genuinely inactive or disabled UI, or to purely decorative content whose removal would not change meaning; quaternary is the fainter tier, and aria-hidden alone does not exempt meaningful visible text from contrast requirements.", "Underline link text by default. Brand-blue links may omit the resting underline when color already supplies the affordance.", "Use dotted underline for hidden or supplemental interaction such as a tooltip; the owning trigger must provide focus, keyboard interaction, and accessible tooltip semantics." ], "states": [ "A variant is atomic: font size, line height, weight, and letter spacing stay together and are not overridden by consumers.", "Emphasis selects the supported stronger recipe for local hierarchy; it does not independently mean selected or active.", "Omitted color inherits currentColor without imposing a host color declaration, so an owning component may apply its semantic foreground directly without depending on stylesheet order. Explicit semantic aliases or CSS-variable references are used when Text has an independent color role.", "Prefer the owning control's isInactive or native disabled state over manually selecting tertiary or quaternary so visual treatment and inactive semantics remain synchronized.", "Line truncation and wrapping require an owner-supplied width constraint and content-aware composition decision.", "Solid underline is the default link affordance; brand-blue links may omit it at rest. Solid and dotted underlines share the tokenized decoration thickness and offset. Dotted underline communicates hidden or supplemental interaction such as a tooltip. Decoration does not make Text interactive by itself.", "Tabular numbers are for changing numeric values or aligned numeric columns where stable glyph width matters.", "Shimmer is reserved for visible generating/loading status text whose owner provides status semantics; reduced motion keeps static readable text." ], "responsiveBehavior": [ "The composition owns width, wrapping, truncation, alignment, and any responsive variant change.", "Text preserves complete token recipes and does not scale fluidly or infer breakpoints." ], "frameworkCaveats": { "customElements": [ "Set as explicitly for inline text, headings, and labels; omitted as renders a paragraph." ], "react": [ "Keep semantic as choices aligned with the rendered document hierarchy rather than component styling." ], "angular": [ "Use the for prop only when Text renders a label associated with a real control ID." ] }, "references": [ { "label": "Storybook examples", "path": "src/wc/components/Text/Text.stories.ts" }, { "label": "Typography contract", "path": "AGENTS.md" } ] }, "api": { "props": { "align": { "type": "TextAlign | undefined", "resolvedType": "\"center\" | \"left\" | \"right\" | undefined", "attribute": "align", "required": false, "mutable": false }, "as": { "type": "TextElement", "resolvedType": "\"div\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | \"label\" | \"p\" | \"span\"", "attribute": "as", "default": "'p'", "required": false, "mutable": false }, "color": { "type": "TextColor", "resolvedType": "\"ai\" | \"brand\" | \"caution\" | \"inherit\" | \"negative\" | \"on-bold\" | \"on-strong\" | \"positive\" | \"primary\" | \"quaternary\" | \"secondary\" | \"tertiary\" | \"warning\" | `var(--${string})`", "attribute": "color", "default": "'inherit'", "required": false, "mutable": false, "description": "Semantic foreground color token or CSS variable. `tertiary` and the\nstill-fainter `quaternary` are restricted to genuinely inactive/disabled\nUI content or purely decorative content; prefer the owning control's\ninactive state whenever one exists." }, "decoration": { "type": "TextDecoration | undefined", "resolvedType": "\"dotted-underline\" | \"none\" | \"underline\" | undefined", "attribute": "decoration", "required": false, "mutable": false, "description": "Link underline or dotted hidden-interaction affordance; does not add semantics." }, "emphasis": { "type": "boolean", "resolvedType": "boolean", "attribute": "emphasis", "default": "false", "required": false, "mutable": false, "description": "Heavier weight + tighter letter-spacing for the variant.\n`false` (default): one step below emphasis (display semibold, title/body\nmedium, caption medium).\n`true`: display bold, title/caption semibold, body medium." }, "fontFeature": { "type": "TextFontFeature", "resolvedType": "\"normal\" | \"tabular-nums\"", "attribute": "font-feature", "default": "'normal'", "required": false, "mutable": false }, "for": { "type": "string | undefined", "resolvedType": "string | undefined", "attribute": "for", "required": false, "mutable": false, "description": "Maps to `for` attribute on