Text

import { Text, textVariants } from '@macaw-ds/ui';

{
  "name": "Text",
  "slug": "text",
  "package": "@macaw-ds/ui",
  "status": "beta",
  "since": "0.1.0",
  "level": "atom",
  "category": "typography",
  "purpose": "Renders text in a named typographic role and tone. Every string on screen goes through it; nothing else sets font size or colour.",
  "description": "The typography primitive. `variant` picks size, line height, weight and tracking from the type scale; `tone` picks the colour; `as` picks the HTML element for semantics. `numeric` switches on tabular numerals and the 7:1 numeric colour for money, counts and dates.",
  "exports": [
    "Text",
    "textVariants"
  ],
  "props": {
    "as": {
      "type": "enum",
      "values": [
        "p",
        "span",
        "div",
        "h1",
        "h2",
        "h3",
        "h4",
        "h5",
        "h6",
        "label",
        "dt",
        "dd",
        "legend",
        "strong",
        "em",
        "time"
      ],
      "default": "p",
      "required": false,
      "description": "Rendered element. Choose for meaning: h2 for a section title, label for a field, time for a date.",
      "a11y": "Heading levels must not skip (h2 then h3). A label must point at a control with htmlFor.",
      "control": "select"
    },
    "variant": {
      "type": "enum",
      "values": [
        "display-lg",
        "display-md",
        "heading-lg",
        "heading-md",
        "heading-sm",
        "body-lg",
        "body-md",
        "body-sm",
        "label-md",
        "label-sm",
        "caption",
        "numeric-lg",
        "numeric-md",
        "numeric-sm",
        "code"
      ],
      "default": "body-md",
      "required": false,
      "description": "Typographic variant from the scale. Independent of the element, so an h2 can use heading-sm in a dense panel.",
      "control": "select"
    },
    "tone": {
      "type": "enum",
      "values": [
        "primary",
        "secondary",
        "muted",
        "inverse",
        "numeric",
        "success",
        "warning",
        "critical",
        "info",
        "accent"
      ],
      "default": "primary",
      "required": false,
      "description": "Colour. primary and numeric meet 7:1; the rest meet 4.5:1 on every surface in both themes.",
      "control": "select"
    },
    "align": {
      "type": "enum",
      "values": [
        "start",
        "center",
        "end"
      ],
      "default": "start",
      "required": false,
      "description": "Text alignment. Money columns align end."
    },
    "numeric": {
      "type": "boolean",
      "default": false,
      "required": false,
      "description": "Tabular numerals plus the numeric colour (unless tone is set). Use for every number that will be compared or summed.",
      "a11y": "Numerals at 7:1 contrast (DECISIONS.md #8)."
    },
    "truncate": {
      "type": "boolean",
      "default": false,
      "required": false,
      "description": "One line with an ellipsis.",
      "a11y": "Truncated text must be available in full elsewhere (a title attribute or a tooltip)."
    },
    "children": {
      "type": "node",
      "default": "Available balance",
      "required": false,
      "description": "The text."
    }
  },
  "slots": [
    "children"
  ],
  "tokens": [
    "text.size.body-md",
    "text.leading.body-md",
    "text.weight.body-md",
    "font.family.sans",
    "font.family.mono",
    "color.fg.primary",
    "color.fg.secondary",
    "color.fg.muted",
    "color.fg.numeric",
    "color.fg.inverse",
    "color.status.success-fg",
    "color.status.warning-fg",
    "color.status.critical-fg",
    "color.status.info-fg",
    "color.status.accent-fg"
  ],
  "a11y": {
    "role": "none (inherits the element's role: heading, paragraph, label, time). The HTML role attribute passes through.",
    "focusable": false,
    "keyboard": [],
    "name": "Not applicable; Text is content. For label, the name is the text and it names the control via htmlFor.",
    "notes": [
      "Pick `as` for document structure first; use `role` for size. Screen readers navigate by heading level, not by font size.",
      "Do not convey status by tone alone; pair a tone with words or an icon with a label."
    ]
  },
  "budget": {
    "gzip": 2000
  },
  "rules": [
    "All text goes through Text. Never apply text-* or font-* utilities to raw elements.",
    "Money, counts and dates use numeric (or a numeric-* role) so columns line up.",
    "Heading levels descend without skipping.",
    "label elements use htmlFor and point at the control's id."
  ],
  "dos": [
    "Use heading-sm for card titles and panel headers.",
    "Use caption with tone=\"muted\" for helper text under a field."
  ],
  "donts": [
    "Do not use display roles inside cards or tables.",
    "Do not use tone=\"muted\" for anything the user must read to act (errors, amounts)."
  ],
  "examples": [
    {
      "name": "Default",
      "props": {
        "children": "Available balance"
      }
    },
    {
      "name": "Heading",
      "props": {
        "as": "h2",
        "children": "Invoices",
        "variant": "heading-md"
      }
    },
    {
      "name": "Money",
      "description": "Tabular numerals, end aligned, numeric colour.",
      "props": {
        "numeric": true,
        "align": "end",
        "children": "$12,480.00",
        "variant": "numeric-md"
      }
    },
    {
      "name": "Status",
      "props": {
        "tone": "critical",
        "children": "Overdue by 12 days",
        "variant": "label-sm"
      }
    },
    {
      "name": "Helper",
      "props": {
        "tone": "muted",
        "children": "Updated 2 minutes ago",
        "variant": "caption"
      }
    }
  ],
  "registryDependencies": [],
  "dependencies": [
    "class-variance-authority"
  ],
  "related": [
    "badge",
    "card"
  ]
}