Cloaked Design SystemPrimitives

Text

The shared typography primitive for every display, heading, body, link, and overline ramp with semantic foregrounds and optional line clamping.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

6 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/primitives/Text/Text.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

The shared typography primitive for every display, heading, body, link, and overline ramp with semantic foregrounds and optional line clamping.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Text } from '@cloakedinc/design-system';

TextTextProps

packages/design-system/src/components/primitives/Text/Text.tsx:66

Prop	Type	Presence	Notes
`variant`	`"display-1" \| "display-2" \| "h1-serif" \| "h2-serif" \| "h3-serif" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "body" \| "body-small" \| "link" \| "overline"`	Required	Ramp step; sets family, weight, size, line height, and letter spacing together.
`color`	`TextColor \| undefined`	Optional	Semantic text token. Defaults to `inherit`, taking its color from the surrounding context.Source default: `'inherit'`
`as`	`keyof HTMLElementTagNameMap \| undefined`	Optional	HTML element used for the rendered text node.Source default: `'span'`Read the type source for the complete value set.
`lineClamp`	`number \| undefined`	Optional	Limits wrapped text to the provided number of lines.
`children`	`React.ReactNode`	Required
`className`	`string \| undefined`	Optional
`id`	`string \| undefined`	Optional
`ariaLabel`	`string \| undefined`	Optional	Overrides visual text when assistive technology needs a clearer announcement.
`ariaHidden`	`boolean \| undefined`	Optional	Prevents duplicate announcements when a labeled sibling exposes the same text.
`testId`	`string \| undefined`	Optional	Selector on the rendered element, whichever tag `as` selects.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

The single way to render text in the DS. variant owns typographic hierarchy and color owns meaning, so consumers never set font-size or color by hand.

Use when

Pick the variant for how the text ranks in the hierarchy, not for its pixel size. The ramp is one idea at many scales, so the rows below group the roles rather than list every ramp.

Set color for meaning: primary for the main line, secondary for supporting text (the most common pairing), success/danger/brand for status, and inherit inside a tone-colored container (Button, Tag) so the text follows its currentColor. The ai-primary/ai-secondary tokens exist for AI surfaces and are not yet used in the app. For a colored icon-in-a-circle reach for IconTile, not styled Text.

Variants

Every ramp side by side to compare hierarchy at a glance.

Truncation

lineClamp={n} caps wrapped text to n lines so cards and rows avoid one-off overflow CSS.

Usage by variant

Choice	Use when	Avoid when
`Variant: display-1 / display-2`	Marquee moments: hero numbers, splash headings, the single biggest thing on a screen.	Routine section titles — the display ramp overpowers ordinary layout.
`Variant: h1-serif / h2-serif / h3-serif`	Editorial serif headings reserved for special, branded moments.	Everyday UI headings — use the sans h-scale so the serif stays a signal.
`Variant: h1 ... h5`	Section and card hierarchy. `h4`/`h5` are the workhorses for card, row, and sheet titles.	Prose and supporting copy — use body.
`Variant: body / body-small`	Prose, descriptions, and metadata. `body-small` is the most-reached-for variant for secondary lines.	Section headings — use the h-scale so hierarchy stays legible.
`Variant: link`	Inline, baseline-aligned actionable text inside a sentence.	A full tap target — use a `Button` with `variant="link"`.
`Variant: overline`	A small all-caps eyebrow above a heading or grouping.	Body copy — the tracking and caps hurt readability at length.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: text
Label: Text
Description: Renders visible content with the selected typography ramp, semantic color, and HTML element.

Allowed Design Choices

Variants

Display 1

Label: Display 1

Display 2

Label: Display 2

H1 serif

Label: Heading 1 serif

H2 serif

Label: Heading 2 serif

H3 serif

Label: Heading 3 serif

Label: Heading 1

Label: Heading 2

Label: Heading 3

Label: Heading 4

Label: Heading 5

Body

Label: Body

Body small

Label: Body small

Link

Label: Link

Overline

Label: Overline

Sizes

Colors

Primary

Label: Primary
Description: Default text emphasis on page and surface backgrounds.

Secondary

Label: Secondary
Description: Supporting text emphasis on page and surface backgrounds.

Ai primary

Label: AI primary
Description: Primary text emphasis on the AI surface.

Ai secondary

Label: AI secondary
Description: Supporting text emphasis on the AI surface.

Brand

Label: Brand
Description: Brand-accent text.

Success

Label: Success
Description: Positive outcome text.

Danger

Label: Danger
Description: Error or destructive text.

Inherit

Label: Inherit
Description: Uses the parent foreground inside a tone-colored container.

Variants

Id: display-1
Label: Display 1
Description: 72-unit sans-serif display ramp for the largest metric or hero moment.
Platforms: ios
android
web

Id: display-2
Label: Display 2
Description: 48-unit sans-serif display ramp for large metrics.
Platforms: ios
android
web

Id: h1-serif
Label: Heading 1 serif
Description: 32-unit serif page-title ramp.
Platforms: ios
android
web

Id: h2-serif
Label: Heading 2 serif
Description: 28-unit serif secondary page-title ramp.
Platforms: ios
android
web

Id: h3-serif
Label: Heading 3 serif
Description: 24-unit serif section-title ramp, also used for prominent card questions (e.g. FAQ).
Platforms: ios
android
web

Id: h1
Label: Heading 1
Description: 32-unit sans-serif top-level heading ramp.
Platforms: ios
android
web

Id: h2
Label: Heading 2
Description: 28-unit sans-serif second-level heading ramp.
Platforms: ios
android
web

Id: h3
Label: Heading 3
Description: 24-unit sans-serif third-level heading ramp.
Platforms: ios
android
web

Id: h4
Label: Heading 4
Description: 20-unit sans-serif fourth-level heading ramp.
Platforms: ios
android
web

Id: h5
Label: Heading 5
Description: 16-unit sans-serif compact or card-title ramp.
Platforms: ios
android
web

Id: body
Label: Body
Description: 16-unit primary prose and control-label ramp.
Platforms: ios
android
web

Id: body-small
Label: Body small
Description: 14-unit secondary prose and metadata ramp.
Platforms: ios
android
web

Id: link
Label: Link
Description: 12-unit compact inline-action and marker ramp.
Platforms: ios
android
web

Id: overline
Label: Overline
Description: 11-unit uppercase eyebrow and category-label ramp.
Platforms: ios
android
web

Sizes

None specified

Measurements

Id: body-type-size
Label: Body type size
Kind: exact
Token: --cds-type-body-size
Value: 16
Unit: px
Applies To: text
body

Id: body-small-type-size
Label: Body-small type size
Kind: exact
Token: --cds-type-body-small-size
Value: 14
Unit: px
Applies To: text
body-small

Id: display-type-size
Label: Display 1 type size
Kind: exact
Token: --cds-type-display-1-size
Value: 72
Unit: px
Applies To: text
display-1

Layout

Alignment: Text follows the inline or block behavior of the selected HTML element.
Flow: Content wraps naturally unless a positive line clamp limits the number of visible lines.
Notes: Choose the visual ramp independently from the semantic HTML element.
The overline ramp transforms visible content to uppercase.

Typography And Color

Typography

Label: Display 1
Description: Largest display ramp.
Token: --cds-type-display-1-size

Label: Display 2
Description: Secondary display ramp.
Token: --cds-type-display-2-size

Label: Heading 1 serif
Description: Largest serif page-title ramp.
Token: --cds-type-h1-serif-size

Label: Heading 2 serif
Description: Secondary serif page-title ramp.
Token: --cds-type-h2-serif-size

Label: Heading 3 serif
Description: Serif section-title ramp.
Token: --cds-type-h3-serif-size

Label: Heading 1
Description: Top sans-serif heading ramp.
Token: --cds-type-h1-size

Label: Heading 2
Description: Second sans-serif heading ramp.
Token: --cds-type-h2-size

Label: Heading 3
Description: Third sans-serif heading ramp.
Token: --cds-type-h3-size

Label: Heading 4
Description: Fourth sans-serif heading ramp.
Token: --cds-type-h4-size

Label: Heading 5
Description: Compact heading ramp.
Token: --cds-type-h5-size

Label: Body
Description: Primary prose ramp.
Token: --cds-type-body-size

Label: Body small
Description: Secondary prose ramp.
Token: --cds-type-body-small-size

Label: Link
Description: Compact inline-action ramp.
Token: --cds-type-link-size

Label: Overline
Description: Uppercase eyebrow ramp.
Token: --cds-type-overline-size

Colors

Label: Primary
Description: Default text emphasis.
Token: --cds-text-primary

Label: Secondary
Description: Supporting text emphasis.
Token: --cds-text-secondary

Label: AI primary
Description: Primary text on the AI surface.
Token: --cds-text-ai-primary

Label: AI secondary
Description: Supporting text on the AI surface.
Token: --cds-text-ai-secondary

Label: Brand
Description: Brand-accent text.
Token: --cds-brand

Label: Success
Description: Positive outcome text.
Token: --cds-status-success-solid

Label: Danger
Description: Error or destructive text.
Token: --cds-status-danger-solid

States

Id: natural-wrap
Label: Natural wrap
Description: Wraps content according to the parent width.

Id: line-clamped
Label: Line clamped
Description: Limits visible content to the requested positive line count and shows an ellipsis.

Id: inherited-color
Label: Inherited color
Description: Uses the parent foreground inside a tone-colored component.

Behavior

Label: Hierarchy
Description: Choose display, heading, body, link, or overline by visual hierarchy rather than by HTML tag.

Label: Semantic element
Description: Use the as option to preserve document structure independently from the selected visual ramp.

Label: Color choices
Description: Support primary, secondary, AI primary, AI secondary, brand, success, danger, and inherited foregrounds.

Accessibility

Label: Document hierarchy
Description: Render real heading elements for headings; a heading-looking span does not create semantic structure.

Label: Clamped content
Description: Ensure essential information remains available elsewhere when visual truncation hides text.

Label: Assistive announcements
Description: Set ariaLabel to override the announced text when the visual string reads poorly aloud, or ariaHidden to suppress a duplicate announcement when a labeled sibling already exposes the same text.

Content Adaptation

Label: Dynamic type
Description: Allow type sizes to scale with the user's text-size preference while fixed spacing and dimensions remain unchanged.

Label: Localization
Description: Prefer natural wrapping; clamp only when the surrounding layout has a documented limit.

Label: Serif use
Description: Reserve the serif ramps for page and section titles.

Motion Haptics

Motion

Label: No intrinsic motion
Description: Text does not animate itself.

Haptics

Label: No feedback
Description: Text is non-interactive and does not request haptic feedback.

Platform Differences

Platforms: web
Description: Web authors type sizes in rem so the native-injected root scale can drive Dynamic Type.
Rationale: iOS and Android consume the same 16px-root logical values as numeric pt and dp sizes, avoiding platform-specific drift while using native text scaling mechanisms.

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1