Text

Overview

Text controls body copy, helper text, muted descriptions, captions, metadata, inline code, keyboard shortcuts, emphasis, deleted and inserted text, and small UI copy across all Byteion product screens. It is a Typography component that pairs a visual variant (how the text looks) with an optional semantic HTML element (what the text means). Text supports standard paragraph sizes, muted secondary text, compact captions, inline code tokens, and keyboard shortcut labels.

Why this exists

Without a shared Text primitive, every page uses ad-hoc text sizes — text-sm text-muted-foreground here, text-xs there — creating visual drift and inconsistent reading experiences. Text unifies body copy, form helper text, metadata, inline code, keyboard shortcuts, and UI labels into a single, accessible, token-based system. It ensures that every paragraph, description, caption, and code fragment follows the same typographic scale without hardcoding one-off classes.

Mental model

• Body variants control the reading experience: body-lg for lead copy, body for standard text, body-sm for compact UI copy.
• Muted and caption reduce visual weight for secondary content: muted for supporting descriptions, caption for metadata and timestamps.
• Semantic HTML elements (<strong>, <em>, <code>, <kbd>, <del>, <ins>) carry meaning for screen readers and assistive technology — do not rely on visual styling alone.
• Text is not Heading — use Text for reading content, not for document structure. Structural titles belong on the Heading page.
• One size per context — body for paragraphs, muted for secondary content, caption for metadata, code for inline code, kbd for keyboard input. Do not mix variants arbitrarily.

Text vs Heading

Both Text and Heading are powered by the same underlying Typography component and share the same variant schema. The difference is intent:

• Heading is for structural page and section titles — page titles, dashboard sections, card titles, modal headings. It controls the document outline and uses display-2xl through h4 variants with semantic h1–h4 tags.
• Text is for body content, descriptions, metadata, and inline semantics — paragraphs, form helper text, table metadata, card descriptions, settings page copy, inline code, and keyboard shortcuts. It uses body-lg, body, body-sm, muted, caption, code, and kbd variants.

The Typography schema also includes display and heading variants (display-2xl–h4). These are documented on the Heading page. If you need a page title or section heading, use the Heading page instead of applying body variants to headings.

When to use

• Paragraphs and descriptions — standard body copy and product descriptions
• Form helper text — instructional text below form fields
• Table metadata — timestamps, row descriptions, secondary labels in data tables
• Card descriptions — supporting text inside cards below the card title
• Modal descriptions — explanatory text in modal dialogs
• Settings page copy — section descriptions, toggle labels, form explanations
• Ecommerce product metadata — SKU, stock status, price captions, review counts
• ERP / POS notes — order notes, invoice descriptions, line item annotations
• Inline code and package names — npm install @byteion/react
• Keyboard shortcuts — Ctrl+S labels in documentation and toolbar tooltips

When not to use

• Do not use Text for structural headings — use Heading with the appropriate h1–h4 variant for page and section titles
• Do not use Text to fake Button, Badge, Alert, or Link semantics — each of those components has its own accessible role, keyboard interaction, and styling
• Do not use muted or caption text for critical warnings or errors — low-contrast text is hard to read and fails WCAG for important messages
• Do not use code or kbd variants for decorative styling — these variants render semantic <code> and <kbd> elements, which should only be used for actual code and keyboard input
• Do not use caption for long paragraphs — caption is for short metadata and labels, not readable body content

Basic example

A standard settings page section with a title, description, and form field with helper text:

<div>
  <p class="text-sm text-foreground mb-1">Email notifications</p>
  <p class="text-sm text-muted-foreground">Choose which updates you receive via email.</p>
</div>

<div>
  <label class="text-sm font-medium text-foreground">Email address</label>
  <input type="email" class="..." />
  <p class="mt-1.5 text-xs text-muted-foreground">We will never share your email with anyone else.</p>
</div>

Inline semantics

HTML provides semantic inline elements that carry meaning for screen readers, search engines, and translation tools. Use the correct element — not just visual styling:

<p><strong>Strong importance</strong> — use &lt;strong&gt; for warnings.</p>
<p><em>Emphasis</em> — use &lt;em&gt; for subtle meaning shifts.</p>
<p><del>Deleted text</del> — use &lt;del&gt; for removed content, <ins>inserted text</ins> for additions.</p>
<p>
  Run <code class="rounded bg-muted px-1.5 py-0.5 font-mono text-[0.85em] text-foreground">npm install @byteion/react</code>
  then press <kbd class="rounded border border-border bg-background px-1.5 font-mono text-[10px] text-muted-foreground">Ctrl+S</kbd>.
</p>
<p class="text-xs text-muted-foreground">
  Last updated June 15, 2026 &middot; Order #ORD-1024
</p>

Text variants

The Typography schema includes 14 variants. The text-focused variants below handle all body copy, metadata, and inline text needs. Display and heading variants are documented on the Heading page.

Truncation

The truncate prop adds the Tailwind truncate utility, which prevents text from wrapping and adds an ellipsis overflow. Use truncate for long names, table cell text, product names, customer names, project titles, and report labels where layout width is limited:

<p class="text-sm text-foreground truncate">
  Premium Wireless Bluetooth Headphones with Noise Cancellation
</p>
<p class="text-xs text-muted-foreground truncate">
  SKU: PRO-AUDIO-WH-2000X-BLACK-EDITION
</p>
<p class="text-sm text-foreground truncate">
  Acme Corporation International Business Solutions Ltd.
</p>

Anatomy

• The HTML element — a <p> for body and muted variants, <span> for caption, <code> for inline code, <kbd> for keyboard shortcuts
• Visual variant — controls font size, weight, and color via the variant class
• Optional as prop — overrides the rendered HTML tag (React/Vue only)
• Optional truncate — adds text overflow ellipsis for constrained layouts
• Semantic inline wrappers — <strong>, <em>, <del>, <ins> for meaning inside body text

Usage guidelines

• Use body for standard UI copy, muted for supporting descriptions, and caption for metadata and timestamps
• Use code for actual inline code and package names — do not use it for decorative styling
• Use kbd for keyboard shortcuts — the variant renders a semantic <kbd> element
• Use truncate when text appears inside constrained layouts like table cells, sidebar items, and card headers
• Keep helper text close to the related form field — place it directly below the input, not at a distance
• Do not rely on color alone to communicate status — pair color with text labels or icons
• Test long translated strings — text that fits in English may be 30–50% longer in other languages

Do and Don't

Accessibility

Text has no keyboard behavior by itself. It renders semantic HTML elements that carry meaning for assistive technology:

• Use semantic HTML for meaning — <strong> for strong importance, <em> for emphasis, <code> for inline code, <kbd> for keyboard input, <del> for removed content, <ins> for inserted content
• Do not rely on color alone — never use green/red text as the only indicator of success or error. Pair with an icon, label, or context
• Do not make critical instructions too small or too muted — error messages and warnings must meet WCAG AA contrast requirements
• Ensure text contrast — muted and caption use text-muted-foreground which is designed to pass contrast against bg-background in light mode, dark mode, and branded themes
• Do not skip heading levels for visual size — use the as prop on Typography to keep semantic structure correct while applying a display variant
• Keyboard behavior — Text has no keyboard interaction by itself. Interactive children (links, buttons) manage their own focus

Customization

Typography should be customized through Byteion tokens — font family, font size scale, font weight, line height, tracking, and text color variables. Each variant's classes are defined in the core Typography component via CVA and reference the standard Tailwind token scale. Avoid arbitrary one-off text sizes unless intentionally extending the token scale. To add a new text variant, extend the component's variant map or use the className prop with standard Tailwind utilities.

HTML example

<!-- Paragraph with muted description -->
<div>
  <p class="text-sm text-foreground">Account settings</p>
  <p class="text-sm text-muted-foreground">Manage your profile, email, and password.</p>
</div>

<!-- Form helper text -->
<div>
  <label class="text-sm font-medium text-foreground">Full name</label>
  <input type="text" class="..." />
  <p class="mt-1 text-xs text-muted-foreground">Use your legal name as it appears on official documents.</p>
</div>

<!-- Table / card metadata -->
<div class="flex items-center gap-2">
  <span class="text-sm text-foreground">Premium Wireless Headphones</span>
  <span class="text-xs text-muted-foreground">SKU: PRO-WH-2000X</span>
  <span class="text-xs text-muted-foreground">Updated 2 hours ago</span>
</div>

<!-- Inline strong, em, del, ins -->
<p>
  <strong>Warning:</strong> This action <em>cannot</em> be undone.
  <del>$49.99</del> <ins>$29.99</ins>
</p>

<!-- Inline code and keyboard shortcut -->
<p>
  Run <code class="rounded bg-muted px-1.5 py-0.5 font-mono text-[0.85em] text-foreground">npm install @byteion/react</code>
  then press <kbd class="rounded border border-border bg-background px-1.5 font-mono text-[10px] text-muted-foreground">Ctrl+S</kbd>
</p>

<!-- Truncate for long names -->
<p class="text-sm text-foreground truncate max-w-[200px]">
  Premium Wireless Bluetooth Headphones with Noise Cancellation
</p>

React example

React exports the Typography component as Typography from @byteion/react. Use the variant prop for visual style and the as prop to override the rendered HTML tag:

import { Typography } from '@byteion/react';

function FormSection() {
  return (
    <div>
      <Typography variant="body">
        Manage your profile, email, and password.
      </Typography>
      <Typography variant="caption">
        Last updated 2 hours ago
      </Typography>
    </div>
  );
}

function ProductMetadata() {
  return (
    <div className="flex items-center gap-2">
      <Typography variant="body" truncate>
        Premium Wireless Bluetooth Headphones
      </Typography>
      <Typography variant="caption">
        SKU: PRO-WH-2000X
      </Typography>
    </div>
  );
}

function InlineExamples() {
  return (
    <div>
      <p>
        <strong>Warning:</strong> This action <em>cannot</em> be undone.
      </p>
      <p>
        Run <Typography variant="code">npm install @byteion/react</Typography>
        then press <Typography variant="kbd">Ctrl+S</Typography>
      </p>
    </div>
  );
}

Vue example

Vue exports the Typography component as Typography from @byteion/vue. The same variant and truncate props apply:

<script setup lang="ts">
import { Typography } from '@byteion/vue';
</script>

<template>
  <div>
    <Typography variant="body">
      Manage your profile, email, and password.
    </Typography>
    <Typography variant="caption">
      Last updated 2 hours ago
    </Typography>
  </div>

  <div class="flex items-center gap-2">
    <Typography variant="body" :truncate="true">
      Premium Wireless Bluetooth Headphones
    </Typography>
    <Typography variant="caption">
      SKU: PRO-WH-2000X
    </Typography>
  </div>

  <p>
    Run <Typography variant="code">npm install @byteion/react</Typography>
    then press <Typography variant="kbd">Ctrl+S</Typography>
  </p>
</template>

API Reference

The Typography component is exposed as Typography in both @byteion/react and @byteion/vue. It provides heading, body, and inline text variants with automatic semantic tag rendering:

The full variant set includes 14 options. For text-focused usage, stick to body-lg, body, body-sm, muted, caption, code, and kbd. Display and heading variants (display-2xl through h4) are documented on the Heading page.

Developer tips

• Use Heading for structure and Text for supporting copy — every page should have one h1 via Heading, with Text providing descriptions, metadata, and body content
• Keep helper text close to the related form field — place it directly below the input with mt-1.5 spacing for clear visual association
• Test long translated strings — text that works in English may be 30–50% longer in other languages; test wrapping and truncation
• Avoid muted text for important instructions — error messages, warnings, and required field labels should always use text-foreground or text-danger with a supporting icon or label
• Keep code and kbd styles consistent — use the system-wide code and kbd variants across docs and product UI so inline code always looks the same
• Check dark mode contrast — text-muted-foreground adapts to dark mode; verify against background colors in both themes

Common mistakes

• Using Text instead of Heading for page structure — applying text-2xl font-bold to a <p> instead of using an <h1> breaks the document outline for screen readers
• Using muted text for errors or warnings — critical messages must have full contrast; text-muted-foreground is too low-contrast for important instructions
• Using caption for long paragraphs — caption uses text-xs, which is too small for comfortable reading of more than a few words
• Hardcoding text sizes instead of variants — if you need text-xs font-semibold text-muted-foreground, consider whether the caption or muted variant already matches your need
• Relying on color alone for status — green text for success and red text for error are invisible to colorblind users; always pair with an icon or label
• Using code or kbd for decoration — these variants render semantic HTML elements; screen readers will announce them as code and keyboard input even if the content is not code or a shortcut

Production usage tips

• Test dark mode contrast — verify all text foreground colours meet WCAG AA (4.5:1 for body text, 3:1 for large text) against their background in both light and dark themes
• Test responsive wrapping and truncation — text that fits a wide dashboard panel may overflow a narrow sidebar or modal; apply truncate where needed
• Test long translated text — German, Russian, and Arabic strings can be significantly longer than English; ensure layouts handle expansion without clipping
• Audit form helper text and error text — every form field that accepts user input should have clear helper text or error text guidance
• Keep React and Vue variants aligned with the core schema — both frameworks share the same variant set; any variant added to one should be reflected in both
• Use the canonical HTML as the source of truth — keep React and Vue wrappers aligned with the documented variants and token classes

Premium examples

Pro patterns available in Byteion Pro:

• Analytics metric text groups — a body-lg metric value with muted label and trend indicator in a compact KPI card
• Ecommerce product metadata rows — a product name with body styling, caption SKU, stock status badge, and price all in a single row
• ERP / POS helper note patterns — invoice line items with body-sm item descriptions and caption tax codes and reference numbers
• Settings page description blocks — settings sections with muted descriptions explaining each toggle or input field in context
• Keyboard shortcut documentation blocks — a list of kbd shortcut pairs with body labels in a compact help panel
• Table cell metadata patterns — data table cells with primary text in body and secondary metadata in caption, with truncate for long values

Related components

• Heading — page and section titles, display headings, document outline control
• Paragraph — standard body text with optimal readability
• Input — text input field that pairs with Text for helper and error text
• Form Field — wraps inputs with label, helper text, and validation
• Badge — compact status and count labels for metadata
• Alert — contextual feedback messages with icon and text
• Card — surface container where Text variants appear as descriptions and metadata

API Reference

Related components

Pair this component with adjacent Byteion primitives from the same workflow: form controls for data entry, feedback components for validation, and layout primitives for spacing.

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX