{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "text", "name": "Text", "category": "Primitives", "summary": "The shared typography primitive for every display, heading, body, link, and overline ramp with semantic foregrounds and optional line clamping.", "documentation": { "summary": "The shared typography primitive for every display, heading, body, link, and overline ramp with semantic foregrounds and optional line clamping.", "guidance": [ { "heading": "Overview", "body": "The single way to render text in the DS. `variant` owns typographic hierarchy and\n`color` owns meaning, so consumers never set `font-size` or `color` by hand." }, { "heading": "Use when", "body": "Pick the `variant` for how the text ranks in the hierarchy, not for its pixel size. The\nramp is one idea at many scales, so the rows below group the roles rather than list every\nramp.\n\nSet `color` for meaning: `primary` for the main line, `secondary` for supporting text (the\nmost common pairing), `success`/`danger`/`brand` for status, and `inherit` inside a\ntone-colored container (Button, Tag) so the text follows its `currentColor`. The\n`ai-primary`/`ai-secondary` tokens exist for AI surfaces and are not yet used in the app.\nFor a colored icon-in-a-circle reach for `IconTile`, not styled `Text`." }, { "heading": "Variants", "body": "Every ramp side by side to compare hierarchy at a glance." }, { "heading": "Truncation", "body": "`lineClamp={n}` caps wrapped text to `n` lines so cards and rows avoid one-off overflow CSS." } ], "usage": [ { "variant": "display-1 / display-2", "use": "Marquee moments: hero numbers, splash headings, the single biggest thing on a screen.", "avoid": "Routine section titles — the display ramp overpowers ordinary layout.", "axis": "Variant" }, { "variant": "h1-serif / h2-serif / h3-serif", "use": "Editorial serif headings reserved for special, branded moments.", "avoid": "Everyday UI headings — use the sans h-scale so the serif stays a signal.", "axis": "Variant" }, { "variant": "h1 ... h5", "use": "Section and card hierarchy. `h4`/`h5` are the workhorses for card, row, and sheet titles.", "avoid": "Prose and supporting copy — use body.", "axis": "Variant" }, { "variant": "body / body-small", "use": "Prose, descriptions, and metadata. `body-small` is the most-reached-for variant for secondary lines.", "avoid": "Section headings — use the h-scale so hierarchy stays legible.", "axis": "Variant" }, { "variant": "link", "use": "Inline, baseline-aligned actionable text inside a sentence.", "avoid": "A full tap target — use a `Button` with `variant=\"link\"`.", "axis": "Variant" }, { "variant": "overline", "use": "A small all-caps eyebrow above a heading or grouping.", "avoid": "Body copy — the tracking and caps hurt readability at length.", "axis": "Variant" } ], "examples": [], "source": "packages/design-system/src/components/primitives/Text/Text.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." }, "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "code": "import React from 'react';\nimport { cn } from '../../../utilities';\nimport styles from './Text.module.scss';\n\n/**\n * Every typography ramp, in hierarchy order. The single source of truth for `TextVariant` — consumers\n * that need to enumerate the ramp (stories, docs, audits) read this instead of re-listing the names.\n */\nexport const TEXT_VARIANTS = [\n 'display-1',\n 'display-2',\n 'h1-serif',\n 'h2-serif',\n 'h3-serif',\n 'h1',\n 'h2',\n 'h3',\n 'h4',\n 'h5',\n 'body',\n 'body-small',\n 'link',\n 'overline',\n] as const;\n\nexport type TextVariant = (typeof TEXT_VARIANTS)[number];\n\nexport type TextColor =\n | 'primary'\n | 'secondary'\n | 'ai-primary'\n | 'ai-secondary'\n | 'brand'\n | 'success'\n | 'danger'\n | 'inherit';\n\n/**\n * Props for the typography primitive. `variant` is styling only — an `h1` variant still renders\n * a `` until `as` says otherwise.\n */\nexport interface TextProps {\n /** Ramp step; sets family, weight, size, line height, and letter spacing together. */\n variant: TextVariant;\n /** Semantic text token. Defaults to `inherit`, taking its color from the surrounding context. */\n color?: TextColor;\n /** HTML element used for the rendered text node. */\n as?: keyof HTMLElementTagNameMap;\n /** Limits wrapped text to the provided number of lines. */\n lineClamp?: number;\n children: React.ReactNode;\n className?: string;\n id?: string;\n /** Overrides visual text when assistive technology needs a clearer announcement. */\n ariaLabel?: string;\n /** Prevents duplicate announcements when a labeled sibling exposes the same text. */\n ariaHidden?: boolean;\n /** Selector on the rendered element, whichever tag `as` selects. */\n testId?: string;\n}\n\n/**\n * Renders one step of the type ramp. It owns typography only — its margin and padding are zeroed,\n * so spacing belongs to the surrounding layout.\n */\nexport function Text({\n variant,\n color = 'inherit',\n as: Tag = 'span',\n lineClamp,\n children,\n className,\n id,\n ariaLabel,\n ariaHidden,\n testId,\n}: TextProps) {\n const cls = cn(styles.text, styles[variant], styles[`color-${color}`], lineClamp && styles.lineClamp, className);\n const style = lineClamp ? ({ '--text-line-clamp': String(lineClamp) } as React.CSSProperties) : undefined;\n\n return (\n \n {children}\n \n );\n}\n" }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Text", "status": "preview", "version": "1.0.0", "summary": "The shared typography primitive for every display, heading, body, link, and overline ramp with semantic foregrounds and optional line clamping." }, "parts": [ { "id": "text", "label": "Text", "description": "Renders visible content with the selected typography ramp, semantic color, and HTML element." } ], "allowedDesignChoices": { "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" }, "h1": { "label": "Heading 1" }, "h2": { "label": "Heading 2" }, "h3": { "label": "Heading 3" }, "h4": { "label": "Heading 4" }, "h5": { "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": [], "measurements": [ { "id": "body-type-size", "label": "Body type size", "kind": "exact", "token": "--cds-type-body-size", "value": 16, "unit": "px", "appliesTo": [ "text", "body" ] }, { "id": "body-small-type-size", "label": "Body-small type size", "kind": "exact", "token": "--cds-type-body-small-size", "value": 14, "unit": "px", "appliesTo": [ "text", "body-small" ] }, { "id": "display-type-size", "label": "Display 1 type size", "kind": "exact", "token": "--cds-type-display-1-size", "value": 72, "unit": "px", "appliesTo": [ "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." ] }, "typographyAndColor": { "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." } ], "contentAdaptation": [ { "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." } ], "motionHaptics": { "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." } ] }, "platformDifferences": [ { "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." } ] }, "spec_source": "packages/design-system/src/components/primitives/Text/Text.spec.json", "guidance_source": { "path": "packages/design-system/src/components/primitives/Text/Text.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec, UsageTable, Do, Dont, Compare } from '../../../../.storybook/blocks';\nimport * as Stories from './Text.stories';\nimport textSpec from './Text.spec.json';\n\n\n\n# Text\n\nThe single way to render text in the DS. `variant` owns typographic hierarchy and\n`color` owns meaning, so consumers never set `font-size` or `color` by hand.\n\n\n\n## Use when\n\nPick the `variant` for how the text ranks in the hierarchy, not for its pixel size. The\nramp is one idea at many scales, so the rows below group the roles rather than list every\nramp.\n\n\n\nSet `color` for meaning: `primary` for the main line, `secondary` for supporting text (the\nmost common pairing), `success`/`danger`/`brand` for status, and `inherit` inside a\ntone-colored container (Button, Tag) so the text follows its `currentColor`. The\n`ai-primary`/`ai-secondary` tokens exist for AI surfaces and are not yet used in the app.\nFor a colored icon-in-a-circle reach for `IconTile`, not styled `Text`.\n\n## Variants\n\nEvery ramp side by side to compare hierarchy at a glance.\n\n\n\n## Color\n\n\n\n## Truncation\n\n`lineClamp={n}` caps wrapped text to `n` lines so cards and rows avoid one-off overflow CSS.\n\n\n\n\n## Dark theme\n\n\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "props": [ { "name": "variant", "type": "\"display-1\" | \"display-2\" | \"h1-serif\" | \"h2-serif\" | \"h3-serif\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"body\" | \"body-small\" | \"link\" | \"overline\"", "declared_type": "TextVariant", "required": true, "description": "Ramp step; sets family, weight, size, line height, and letter spacing together.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 44 }, "values": [ "body-small", "body", "display-1", "display-2", "h1-serif", "h1", "h2-serif", "h2", "h3-serif", "h3", "h4", "h5", "link", "overline" ], "values_complete": true }, { "name": "color", "type": "TextColor | undefined", "declared_type": "TextColor", "required": false, "description": "Semantic text token. Defaults to `inherit`, taking its color from the surrounding context.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 46 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true, "default": "'inherit'", "default_kind": "source-expression" }, { "name": "as", "type": "keyof HTMLElementTagNameMap | undefined", "declared_type": "keyof HTMLElementTagNameMap", "required": false, "description": "HTML element used for the rendered text node.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 48 }, "literal_count": 112, "values_complete": false, "default": "'span'", "default_kind": "source-expression" }, { "name": "lineClamp", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Limits wrapped text to the provided number of lines.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 50 } }, { "name": "children", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": true, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 51 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 52 } }, { "name": "id", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 53 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Overrides visual text when assistive technology needs a clearer announcement.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 55 } }, { "name": "ariaHidden", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Prevents duplicate announcements when a labeled sibling exposes the same text.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 57 }, "values": [ false, true ], "values_complete": true }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector on the rendered element, whichever tag `as` selects.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 59 } } ], "prop_shapes": {}, "examples": [], "tokens": [ { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-type-body-small-size", "light": "0.875rem", "dark": "0.875rem" }, { "name": "--cds-type-display-1-size", "light": "4.5rem", "dark": "4.5rem" }, { "name": "--cds-type-display-2-size", "light": "3rem", "dark": "3rem" }, { "name": "--cds-type-h1-serif-size", "light": "2rem", "dark": "2rem" }, { "name": "--cds-type-h2-serif-size", "light": "1.75rem", "dark": "1.75rem" }, { "name": "--cds-type-h3-serif-size", "light": "1.5rem", "dark": "1.5rem" }, { "name": "--cds-type-h1-size", "light": "2rem", "dark": "2rem" }, { "name": "--cds-type-h2-size", "light": "1.75rem", "dark": "1.75rem" }, { "name": "--cds-type-h3-size", "light": "1.5rem", "dark": "1.5rem" }, { "name": "--cds-type-h4-size", "light": "1.25rem", "dark": "1.25rem" }, { "name": "--cds-type-h5-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-type-link-size", "light": "0.75rem", "dark": "0.75rem" }, { "name": "--cds-type-overline-size", "light": "0.6875rem", "dark": "0.6875rem" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-text-secondary", "light": "#646260", "dark": "#ffffff99" }, { "name": "--cds-text-ai-primary", "light": "#f3f1ed", "dark": "#f3f1ed" }, { "name": "--cds-text-ai-secondary", "light": "#84827e", "dark": "#84827e" }, { "name": "--cds-brand", "light": "#ff550c", "dark": "#ff550c" }, { "name": "--cds-status-success-solid", "light": "#008924", "dark": "#008924" }, { "name": "--cds-status-danger-solid", "light": "#b83100", "dark": "#b83100" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-primitives-text--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/Text", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--overflow", "name": "Overflow", "title": "Cloaked Design System/Primitives/Text", "exportName": "Overflow", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--overflow&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--line-clamp", "name": "Line Clamp", "title": "Cloaked Design System/Primitives/Text", "exportName": "LineClamp", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--line-clamp&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--variant-matrix", "name": "Variant Matrix", "title": "Cloaked Design System/Primitives/Text", "exportName": "VariantMatrix", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--variant-matrix&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--color-matrix", "name": "Color Matrix", "title": "Cloaked Design System/Primitives/Text", "exportName": "ColorMatrix", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--color-matrix&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Primitives/Text", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--dark-theme&viewMode=story" } ], "name": "Text", "id": "text", "category": "Primitives" }, "stories": [ { "id": "cloaked-design-system-primitives-text--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/Text", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--overflow", "name": "Overflow", "title": "Cloaked Design System/Primitives/Text", "exportName": "Overflow", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--overflow&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--line-clamp", "name": "Line Clamp", "title": "Cloaked Design System/Primitives/Text", "exportName": "LineClamp", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--line-clamp&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--variant-matrix", "name": "Variant Matrix", "title": "Cloaked Design System/Primitives/Text", "exportName": "VariantMatrix", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--variant-matrix&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--color-matrix", "name": "Color Matrix", "title": "Cloaked Design System/Primitives/Text", "exportName": "ColorMatrix", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--color-matrix&viewMode=story" }, { "id": "cloaked-design-system-primitives-text--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Primitives/Text", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "source_digest": "47bc35692bf280f8529b2e2dc07e0bdb6da57005ceb8be2a0968722421ebaff5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-text--dark-theme&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/primitives/Text/Text.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { selectArgType, TEXT_COLOR_OPTIONS } from '../../../storybook/controlOptions';\nimport { Text, TEXT_VARIANTS, type TextColor } from './Text';\n\nconst TEXT_COLORS = [\n 'primary',\n 'secondary',\n 'ai-primary',\n 'ai-secondary',\n 'brand',\n 'success',\n 'danger',\n] as const satisfies readonly TextColor[];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Primitives/Text',\n component: Text,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'The one way to render text in the DS — it owns every typography ramp (`--cds-type-*`) and ' +\n 'semantic color (`--cds-text-*`), so consumers never set `font-size`/`color` by hand. Pick the ' +\n '`variant` for hierarchy and `color` for meaning; use `as` to keep the DOM semantic (an `h2` ' +\n 'ramp on an `

`). For a colored icon-in-a-circle reach for `IconTile`, not styled `Text`.',\n },\n },\n },\n args: {\n variant: 'body',\n color: 'primary',\n children: 'Design system typography',\n },\n argTypes: {\n variant: {\n ...selectArgType(TEXT_VARIANTS),\n description:\n 'Typography ramp (`--cds-type-*`): `display-*` for hero moments, `h1-serif`/`h2-serif`/`h3-serif` ' +\n 'for serif titles and prominent card questions (e.g. FAQ), `h1`–`h5` for ' +\n 'section hierarchy, `body` (16px) for reading content the user reads to understand (FAQ answers, ' +\n 'descriptions, empty-state and modal copy), `body-small` (14px) for supporting/dense UI text that ' +\n 'annotates other content (captions, metadata, list-item subtitles, helper text) — never for ' +\n 'multi-line prose, `link` for inline actions, `overline` for eyebrows.',\n },\n color: {\n ...selectArgType(TEXT_COLOR_OPTIONS),\n description:\n 'Semantic color token (`--cds-text-*`). `inherit` leaves color to the parent — use it inside ' +\n 'tone-colored containers (Button, Tag) so the text follows their `currentColor`.',\n },\n lineClamp: {\n control: { type: 'number', min: 1, max: 4 },\n description:\n 'Truncates wrapped text to N lines with an ellipsis, so cards and rows avoid one-off overflow CSS.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\n\nexport const Overflow: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Body text wraps naturally in a constrained width — the baseline for dense mobile layouts.',\n },\n },\n },\n render: () => (\n
\n \n Long text wraps naturally so consumers can check dense mobile layouts without one-off CSS.\n \n
\n ),\n};\n\nexport const LineClamp: Story = {\n parameters: {\n docs: {\n description: {\n story: '`lineClamp={2}` caps overflow to two lines — the built-in truncation for cards and rows.',\n },\n },\n },\n args: {\n variant: 'body',\n color: 'primary',\n lineClamp: 2,\n children:\n 'Long text can be clamped by the typography primitive so cards, rows, and dense mobile layouts do not duplicate overflow CSS.',\n },\n decorators: [\n Story => (\n
\n \n
\n ),\n ],\n};\n\nexport const VariantMatrix: Story = {\n parameters: {\n docs: { description: { story: 'Every `variant` ramp side by side to compare hierarchy at a glance.' } },\n },\n render: () => (\n \n {TEXT_VARIANTS.map(variant => (\n \n \n {variant}\n \n \n Cloaked protects your privacy\n \n \n ))}\n \n ),\n};\n\nexport const ColorMatrix: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Every semantic `color` token (excluding `inherit`, which has no standalone color).',\n },\n },\n },\n render: () => (\n \n {TEXT_COLORS.map(color => (\n \n {color} text color\n \n ))}\n \n ),\n};\n\nexport const DarkTheme: Story = {\n args: {\n color: 'primary',\n children: 'Dark theme typography',\n },\n globals: { theme: 'dark' },\n};\n" }, "links": { "human": "/component-text", "json": "/data/components/text.json", "markdown": "/data/components/text.md", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-text--playground" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Text", "public_path": "Text", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Text", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 66 }, "props_type": "TextProps", "props": [ { "name": "variant", "type": "\"display-1\" | \"display-2\" | \"h1-serif\" | \"h2-serif\" | \"h3-serif\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"body\" | \"body-small\" | \"link\" | \"overline\"", "declared_type": "TextVariant", "required": true, "description": "Ramp step; sets family, weight, size, line height, and letter spacing together.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 44 }, "values": [ "body-small", "body", "display-1", "display-2", "h1-serif", "h1", "h2-serif", "h2", "h3-serif", "h3", "h4", "h5", "link", "overline" ], "values_complete": true }, { "name": "color", "type": "TextColor | undefined", "declared_type": "TextColor", "required": false, "description": "Semantic text token. Defaults to `inherit`, taking its color from the surrounding context.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 46 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true, "default": "'inherit'", "default_kind": "source-expression" }, { "name": "as", "type": "keyof HTMLElementTagNameMap | undefined", "declared_type": "keyof HTMLElementTagNameMap", "required": false, "description": "HTML element used for the rendered text node.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 48 }, "literal_count": 112, "values_complete": false, "default": "'span'", "default_kind": "source-expression" }, { "name": "lineClamp", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Limits wrapped text to the provided number of lines.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 50 } }, { "name": "children", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": true, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 51 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 52 } }, { "name": "id", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 53 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Overrides visual text when assistive technology needs a clearer announcement.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 55 } }, { "name": "ariaHidden", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Prevents duplicate announcements when a labeled sibling exposes the same text.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 57 }, "values": [ false, true ], "values_complete": true }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector on the rendered element, whichever tag `as` selects.", "source": { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 59 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 9, "name": "TEXT_VARIANTS", "code": "TEXT_VARIANTS = [\n 'display-1',\n 'display-2',\n 'h1-serif',\n 'h2-serif',\n 'h3-serif',\n 'h1',\n 'h2',\n 'h3',\n 'h4',\n 'h5',\n 'body',\n 'body-small',\n 'link',\n 'overline',\n] as const" }, { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 26, "name": "TextVariant", "code": "export type TextVariant = (typeof TEXT_VARIANTS)[number];" }, { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 28, "name": "TextColor", "code": "export type TextColor =\n | 'primary'\n | 'secondary'\n | 'ai-primary'\n | 'ai-secondary'\n | 'brand'\n | 'success'\n | 'danger'\n | 'inherit';" }, { "path": "packages/design-system/src/components/primitives/Text/Text.tsx", "line": 42, "name": "TextProps", "code": "export interface TextProps {\n /** Ramp step; sets family, weight, size, line height, and letter spacing together. */\n variant: TextVariant;\n /** Semantic text token. Defaults to `inherit`, taking its color from the surrounding context. */\n color?: TextColor;\n /** HTML element used for the rendered text node. */\n as?: keyof HTMLElementTagNameMap;\n /** Limits wrapped text to the provided number of lines. */\n lineClamp?: number;\n children: React.ReactNode;\n className?: string;\n id?: string;\n /** Overrides visual text when assistive technology needs a clearer announcement. */\n ariaLabel?: string;\n /** Prevents duplicate announcements when a labeled sibling exposes the same text. */\n ariaHidden?: boolean;\n /** Selector on the rendered element, whichever tag `as` selects. */\n testId?: string;\n}" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." }, { "code": "literal-values-in-source", "detail": "Literal sets larger than 100 values remain in the referenced type source; an incomplete enum is never presented as exhaustive." } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." } }