Paragraph

Overview

Paragraph standardises body copy, descriptions, onboarding copy, documentation text, settings explanations, card descriptions, ecommerce admin notes, ERP/POS workflow instructions, and long-form readable content across all Byteion product screens. It applies consistent line-height, font-size, and spacing tokens so every block of text is comfortable to read — whether it is a settings explanation, an empty-state message, or a product description in an admin panel. Paragraph is a pure CSS/Tailwind pattern: it renders a semantic <p> element with Byteion typography tokens and has no JavaScript component dependency.

Why this exists

Without a shared typography scale, every page uses ad-hoc paragraph sizes — text-base leading-relaxed in one place, text-sm leading-6 in another — creating visual drift and inconsistent reading experiences. Paragraph unifies body copy across documentation, admin panels, POS screens, and ecommerce back-offices into a single token-based system. It ensures that every block of readable text follows the same typographic rhythm without hardcoding one-off classes.

Mental model

• Paragraph is for reading — use it for sentences and blocks of body copy, not for labels, inline metadata, or structural headings.
• Three sizes cover every context — small for dense UI, base for standard text, large for lead copy and onboarding.
• Line height is built in — each size uses a proven line-height ratio (leading-relaxed for base, leading-8 for large) so you do not need to adjust it per paragraph.
• Paragraph is not Heading or Text — structural titles use Heading, inline labels and captions use Text.
• No JavaScript required — Paragraph is pure HTML and Tailwind utility classes. No import, no component, no runtime.

Paragraph vs Text vs Heading

All three are powered by the same Byteion typography schema, but each serves a distinct purpose:

• Heading — structural page and section titles. Controls the document outline using h1–h4 semantic tags and display/heading variants.
• Paragraph — readable body-copy blocks. Full sentences and multi-line prose for descriptions, documentation, settings copy, empty states, and modal text.
• Text — inline labels, captions, metadata, helper text, inline code, and keyboard shortcuts. Short, scannable text elements that accompany or annotate other content.

In practice: use Heading for the page title, Paragraph for the section explanation, and Text(caption) for a "Last updated" timestamp below it.

When to use

• Product descriptions — item descriptions in ecommerce product pages and admin catalog views
• Onboarding copy — introductory text on welcome screens, setup wizards, and first-use tours
• Settings explanations — descriptive text below settings section titles explaining what each group of controls does
• Empty-state descriptions — explanatory copy in empty states that tells the user what to do next
• Modal body text — the main message or instruction inside a modal dialog
• Card descriptions — supporting text inside dashboard cards below the card title
• Ecommerce admin notes — internal notes on orders, products, and customer records
• ERP / POS workflow instructions — step guidance, invoice notes, and operational instructions
• Documentation and article content — body prose in docs pages, changelogs, guides, and help articles

When not to use

• Do not use Paragraph for structural headings — use Heading with the appropriate h1–h4 variant for page and section titles
• Do not use Paragraph for one-word labels — use Text with the muted or caption variant for short metadata and labels
• Do not use Paragraph for table cell metadata — Text(caption) is more appropriate for timestamps, SKUs, and small secondary data in tables
• Do not use Paragraph as a layout wrapper — paragraphs are for text content, not for grouping layout elements; use div or section for structure
• Do not put dense multi-paragraph reading content inside cramped cards — cards have limited horizontal space; use full-width sections or modal bodies for long text
• Do not use muted paragraphs for critical warnings or errors — low-contrast text fails WCAG for important messages; use text-foreground or Alert instead

Basic example

A settings page section with a heading, standard description paragraph, and a small helper paragraph:

<h3 class="text-lg font-semibold text-foreground">Notifications</h3>
<p class="text-base text-foreground leading-relaxed">
  Choose which updates you receive via email. You can opt out of marketing
  messages at any time, but transactional emails — order confirmations,
  password resets, security alerts — cannot be disabled.
</p>
<p class="text-sm text-muted-foreground leading-6">
  Email notifications are sent from <strong>notifications@byteion.dev</strong>.
  Add this address to your contacts to avoid spam filters.
</p>

Paragraph sizes

Three token-based sizes cover every body copy context. These are applied as Tailwind utility classes on a <p> element:

These are recommended Tailwind patterns, not component props. Use the classes directly on a <p> element. For display sizes, heading variants, code, kbd, caption, and inline text, refer to the Heading and Text pages.

Readability guidance

• Keep line length bounded — wrap paragraphs in a container with max-w-prose or max-w-2xl (approx 65–75 characters per line) for comfortable reading on large screens
• Maintain spacing rhythm — use space-y-4 between consecutive paragraphs to create clear visual separation without extra margins
• One idea per paragraph — break long copy into focused paragraphs rather than one wall of text
• Pair with headings — every major section should start with a heading, followed by one or more paragraphs
• Avoid dense text in small cards — cards are for scannable summaries; put long reading content in full-width sections or modals
• Use large size sparingly — text-lg leading-8 is for lead copy and emphasis, not for every paragraph

Anatomy

• Paragraph element — a semantic <p> tag that contains readable body text
• Size class — text-sm, text-base, or text-lg controls the font size
• Line-height class — leading-6, leading-relaxed, or leading-8 controls vertical rhythm
• Color class — text-foreground for primary content, text-muted-foreground for secondary descriptions
• Optional inline children — <strong>, <em>, <a>, <code>, and <kbd> for meaning inside paragraphs

Usage guidelines

• Use text-base leading-relaxed for standard body copy in docs, settings, modals, and cards
• Use text-sm leading-6 for dense UI: compact dashboards, sidebar content, and small cards
• Use text-lg leading-8 for lead copy, onboarding introductions, and empty-state hero text
• Use text-muted-foreground for secondary descriptions, not for primary content or warnings
• Keep line length under ~75 characters by wrapping paragraphs in max-w-2xl on wide layouts
• Space consecutive paragraphs with space-y-4 or mb-4 for consistent vertical rhythm

Do and Don't

Accessibility

Paragraph has no keyboard behavior by itself. It renders a semantic <p> element that screen readers announce as a paragraph of text:

• Use real <p> elements — screen readers identify paragraphs and allow users to navigate between them. Do not use <div> or <span> as paragraph replacements
• Keep line length readable — aim for 65–75 characters per line on desktop to reduce eye strain. Use max-w-prose or max-w-2xl on wide containers
• Preserve color contrast — text-muted-foreground is designed to pass WCAG AA (4.5:1) against bg-background in light mode, dark mode, and branded themes
• Do not make critical instructions too muted or too small — error messages and warnings must use text-foreground with full contrast
• Links inside paragraphs must remain identifiable — inline links need a distinct underline or colour so users can distinguish them from surrounding text
• Do not rely on color alone to communicate status — pair green/red text with an icon or label so colorblind users receive the same information

Customization

Paragraph typography is customized through Byteion tokens — font family, font size scale, line height, tracking, text color, and spacing rhythm. Each size references the standard Tailwind token scale (text-sm, text-base, text-lg). Avoid arbitrary one-off sizes unless intentionally extending the token scale. For custom line-height or spacing overrides, use Tailwind utilities like leading-relaxed, leading-8, or space-y-4 on the parent container.

HTML example

<!-- Standard paragraph below a heading -->
<h2 class="text-2xl font-semibold tracking-tight text-foreground">Account settings</h2>
<p class="text-base text-foreground leading-relaxed">
  Manage your profile information, email preferences, and security settings.
  Changes are saved automatically.
</p>

<!-- Small paragraph inside a card or settings panel -->
<div class="rounded-xl border border-border bg-card p-4">
  <h3 class="text-lg font-semibold text-foreground">Email notifications</h3>
  <p class="text-sm text-muted-foreground leading-6">
    Choose which transactional and marketing emails you receive. You can
    unsubscribe from marketing at any time.
  </p>
</div>

<!-- Large lead paragraph for onboarding or empty state -->
<p class="text-lg text-foreground leading-8">
  Welcome to Byteion. Set up your workspace, invite your team, and start
  building better products — all from one dashboard.
</p>

<!-- Paragraph with inline link and emphasis -->
<p class="text-base text-foreground leading-relaxed">
  By continuing, you agree to our <a href="/terms" class="text-primary underline hover:no-underline">Terms of Service</a>
  and <a href="/privacy" class="text-primary underline hover:no-underline">Privacy Policy</a>.
  We <em>never</em> share your data with third parties.
</p>

<!-- Muted description paragraph for secondary information -->
<p class="text-sm text-muted-foreground leading-6">
  This information is used for shipping and billing purposes only.
</p>

React example

Paragraph is a pure HTML/Tailwind pattern — there is no React component. Apply the className attributes directly on a <p> element:

function SettingsSection() {
  return (
    <div>
      <h2 className="text-2xl font-semibold tracking-tight text-foreground">
        Account settings
      </h2>
      <p className="text-base text-foreground leading-relaxed">
        Manage your profile information, email preferences, and security settings.
      </p>
    </div>
  );
}

function CardParagraph() {
  return (
    <div className="rounded-xl border border-border bg-card p-4">
      <h3 className="text-lg font-semibold text-foreground">
        Email notifications
      </h3>
      <p className="text-sm text-muted-foreground leading-6">
        Choose which transactional and marketing emails you receive.
      </p>
    </div>
  );
}

function LeadParagraph() {
  return (
    <p className="text-lg text-foreground leading-8">
      Welcome to Byteion. Set up your workspace, invite your team, and start
      building better products.
    </p>
  );
}

function MutedDescription() {
  return (
    <p className="text-sm text-muted-foreground leading-6">
      This information is used for shipping and billing purposes only.
    </p>
  );
}

Vue example

Paragraph is a pure HTML/Tailwind pattern — there is no Vue component. Apply classes directly on a <p> element:

<template>
  <!-- Standard paragraph -->
  <div>
    <h2 class="text-2xl font-semibold tracking-tight text-foreground">
      Account settings
    </h2>
    <p class="text-base text-foreground leading-relaxed">
      Manage your profile information, email preferences, and security settings.
    </p>
  </div>

  <!-- Card paragraph -->
  <div class="rounded-xl border border-border bg-card p-4">
    <h3 class="text-lg font-semibold text-foreground">
      Email notifications
    </h3>
    <p class="text-sm text-muted-foreground leading-6">
      Choose which transactional and marketing emails you receive.
    </p>
  </div>

  <!-- Lead paragraph -->
  <p class="text-lg text-foreground leading-8">
    Welcome to Byteion. Set up your workspace, invite your team, and start
    building better products.
  </p>

  <!-- Muted description -->
  <p class="text-sm text-muted-foreground leading-6">
    This information is used for shipping and billing purposes only.
  </p>
</template>

API Reference

Paragraph uses the standard HTML <p> element with Byteion typography tokens applied via Tailwind utility classes. There is no component, no props, and no JavaScript import:

React and Vue projects use the same approach: a plain <p> element with Byteion Tailwind classes. No import needed. For display sizes, heading variants, code, kbd, caption, and inline text, refer to the Heading and Text documentation.

Developer tips

• Pair Paragraph with Heading for readable sections — every major content area should start with a heading, followed by one or more paragraphs
• Use Text for captions and helper text — do not force Paragraph into every small text case; the Text page covers captions, metadata, inline code, and keyboard shortcuts
• Keep line length readable on large screens — constrain paragraphs with max-w-prose or max-w-2xl to prevent lines exceeding 75 characters
• Test wrapping on mobile — paragraph text should reflow naturally at 375 px without horizontal overflow or awkward orphans
• Test long translated content — German, Russian, and Arabic text can be 30–50% longer than English; verify layouts expand gracefully
• Avoid overusing muted paragraphs — text-muted-foreground is for secondary descriptions; primary content should use text-foreground

Common mistakes

• Using Paragraph for headings — applying text-xl font-bold to a <p> instead of using an <h2> breaks the document outline for screen readers and search engines
• Using Paragraph for labels or metadata — one-word labels, timestamps, and SKU values belong in Text with caption or muted variants
• Writing long blocks inside small cards — cards have limited horizontal space; reserve them for summaries and put long reading content in full-width sections
• Hardcoding text sizes instead of using token-based patterns — if you need text-[15px] leading-[1.6], consider whether the standard text-base or text-sm sizes already match your need
• Making important text muted — critical messages, warnings, and required-field notices must use text-foreground to meet WCAG contrast
• Forgetting mobile wrapping and translated text — text that fits comfortably on desktop may overflow on mobile or in longer languages; always test both scenarios

Production usage tips

• Test line length on desktop — verify paragraphs in wide layouts are constrained to ~75 characters per line for comfortable reading
• Test wrapping on mobile — check paragraph reflow at 375 px, 768 px, and 1024 px breakpoints
• Test dark mode contrast — verify all paragraph text meets WCAG AA (4.5:1) against background colours in both light and dark themes
• Test translated content — enable a long-language locale (German, Russian) and verify no horizontal overflow or broken layouts
• Review empty states and onboarding copy for readability — onboarding text is often the user's first impression; ensure it is clear, scannable, and properly sized
• Keep React and Vue output aligned with the core typography schema — all frameworks use the same Tailwind classes; there is no component API to synchronise

Premium examples

Pro patterns available in Byteion Pro:

• Onboarding copy sections — multi-step onboarding wizard using text-lg leading-8 lead paragraphs paired with feature lists and CTAs
• Empty-state description blocks — centred empty states with a large lead paragraph, muted secondary description, and action button in a card
• Settings page explanation groups — settings sections with a heading, base paragraph explanation, and small muted helper note below each toggle
• Ecommerce admin help copy — product edit pages with text-sm leading-6 helper paragraphs explaining each field's purpose
• ERP / POS workflow instruction blocks — step-by-step instruction blocks with a numbered heading, base paragraph explanation, and small implementation note
• Documentation and article layout presets — article body with text-base leading-relaxed, constrained by max-w-prose, with proper heading hierarchy and space-y-4 rhythm

Related components

• Heading — page and section titles, display headings, document outline control
• Text — inline labels, captions, metadata, helper text, inline code, and keyboard shortcuts
• Card — surface container where Paragraph appears as descriptions and body copy
• Alert — contextual feedback messages that replace muted paragraphs for warnings and errors
• Blockquote — quotation blocks with visual emphasis, distinct from standard body paragraphs

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