XDS — Design System

Heading@xds/core · XDSHeading v0.0.13

Usage

Text renders styled body text and headings from the theme. Use XDSText with a semantic type for body copy, labels, and captions, and XDSHeading for section titles that output the correct h1–h6 element.

ts
import {XDSHeading} from '@xds/core/Text'

Best practices

Guidance	Practices
Do	Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight — the theme handles the details.
Do	Set accessibilityLevel on XDSHeading when the visual level differs from the document outline so screen readers announce the correct hierarchy.
Do	Use maxLines with a number to truncate long content — a tooltip appears automatically on hover so no text is lost.
Do	Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.
Don't	Override size and weight when a semantic type already matches — extra overrides fight the theme and break when themes change.
Don't	Skip heading levels in the document outline — go h1 then h2 then h3, never h1 then h3.
Don't	Use raw HTML tags like <p>, <h1>–<h6>, or <span> for text — XDSText and XDSHeading apply the correct theme tokens automatically.

Examples

Common configurations, variations, and states.

Heading — Card GridResponsive card grid with truncated headings and descriptions for uniform layout

tsx
'use client';
import {XDSHeading, XDSText} from '@xds/core/Text';
const cards = [
  {
    title: 'Very Long Card Title That Gets Truncated',
    updated: '1 hour ago',
  },
  {
    title: 'Another Card',
    updated: '2 hours ago',
  },
  {
    title: 'Third Card With An Even Longer Title That Will Be Truncated',
    updated: '3 hours ago',
  },
];
export default function HeadingCardGrid() {
  return (
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: 'repeat(auto-fill, minmax(250px, 1fr))',
        gap: 16,
        maxWidth: 800,
      }}>
      {cards.map(card => (
        <div
          key={card.title}
          style={{
            padding: 16,
            borderRadius: 8,
            border: '1px solid #e0e0e0',
            boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
          }}>
          <XDSHeading level={3} maxLines={1}>
            {card.title}
          </XDSHeading>
          <XDSText type="body" maxLines={2} display="block">
            This is a card description that might be quite long and needs to be
            truncated after two lines to keep the card compact and uniform.
          </XDSText>
          <XDSText type="supporting" display="block">
            Updated {card.updated}
          </XDSText>
        </div>
      ))}
    </div>
  );
}

Heading — Page HierarchyReal-world page layout demonstrating heading levels h1 through h3 with supporting text

tsx
'use client';
import {XDSHeading, XDSText} from '@xds/core/Text';
export default function HeadingPageLayout() {
  return (
    <div style={{maxWidth: 800}}>
      <XDSHeading level={1}>Dashboard Overview</XDSHeading>
      <XDSText type="supporting" display="block">
        Last updated 5 minutes ago
      </XDSText>
      <div style={{marginTop: 32}}>
        <XDSHeading level={2}>Recent Activity</XDSHeading>
        <XDSText type="body" display="block">
          Here's what's been happening in your workspace.
        </XDSText>
      </div>
      <div style={{marginTop: 24}}>
        <XDSHeading level={3}>Today</XDSHeading>
        <XDSText type="body" display="block">
          • Project Alpha updated
          <br />
          • 3 new comments
          <br />• Task completed
        </XDSText>
      </div>
    </div>
  );
}

Heading — TruncationSingle-line and multi-line heading truncation with ellipsis for constrained layouts

tsx
'use client';
import {XDSHeading} from '@xds/core/Text';
export default function HeadingTruncation() {
  return (
    <div style={{display: 'flex', flexDirection: 'column', gap: 24}}>
      <div style={{width: 300, border: '1px solid #ccc', padding: 12}}>
        <XDSHeading level={2} maxLines={1}>
          Very Long Heading That Will Be Truncated To One Line With Ellipsis
        </XDSHeading>
      </div>
      <div style={{width: 300, border: '1px solid #ccc', padding: 12}}>
        <XDSHeading level={2} maxLines={2}>
          Very Long Heading That Will Be Truncated To Two Lines To Keep Card
          Layout Compact
        </XDSHeading>
      </div>
    </div>
  );
}

Showcase source

tsx
'use client';
import {XDSHeading} from '@xds/core/Text';
export default function HeadingShowcase() {
  return <XDSHeading level={1}>Dashboard Overview</XDSHeading>;
}

Usage

import {XDSHeading} from '@xds/core/Text'

Best practices

Guidance	Practices
Do	Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight — the theme handles the details.
Do	Set accessibilityLevel on XDSHeading when the visual level differs from the document outline so screen readers announce the correct hierarchy.
Do	Use maxLines with a number to truncate long content — a tooltip appears automatically on hover so no text is lost.
Do	Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.
Don't	Override size and weight when a semantic type already matches — extra overrides fight the theme and break when themes change.
Don't	Skip heading levels in the document outline — go h1 then h2 then h3, never h1 then h3.
Don't	Use raw HTML tags like <p>, <h1>–<h6>, or <span> for text — XDSText and XDSHeading apply the correct theme tokens automatically.

tsx

'use client'; import {XDSHeading, XDSText} from '@xds/core/Text'; const cards = [ { title: 'Very Long Card Title That Gets Truncated', updated: '1 hour ago', }, { title: 'Another Card', updated: '2 hours ago', }, { title: 'Third Card With An Even Longer Title That Will Be Truncated', updated: '3 hours ago', }, ]; export default function HeadingCardGrid() { return ( <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(250px, 1fr))', gap: 16, maxWidth: 800, }}> {cards.map(card => ( <div key={card.title} style={{ padding: 16, borderRadius: 8, border: '1px solid #e0e0e0', boxShadow: '0 2px 4px rgba(0,0,0,0.1)', }}> <XDSHeading level={3} maxLines={1}> {card.title} </XDSHeading> <XDSText type="body" maxLines={2} display="block"> This is a card description that might be quite long and needs to be truncated after two lines to keep the card compact and uniform. </XDSText> <XDSText type="supporting" display="block"> Updated {card.updated} </XDSText> </div> ))} </div> ); }

tsx

'use client'; import {XDSHeading, XDSText} from '@xds/core/Text'; export default function HeadingPageLayout() { return ( <div style={{maxWidth: 800}}> <XDSHeading level={1}>Dashboard Overview</XDSHeading> <XDSText type="supporting" display="block"> Last updated 5 minutes ago </XDSText> <div style={{marginTop: 32}}> <XDSHeading level={2}>Recent Activity</XDSHeading> <XDSText type="body" display="block"> Here's what's been happening in your workspace. </XDSText> </div> <div style={{marginTop: 24}}> <XDSHeading level={3}>Today</XDSHeading> <XDSText type="body" display="block"> • Project Alpha updated <br /> • 3 new comments <br />• Task completed </XDSText> </div> </div> ); }

tsx

'use client'; import {XDSHeading} from '@xds/core/Text'; export default function HeadingTruncation() { return ( <div style={{display: 'flex', flexDirection: 'column', gap: 24}}> <div style={{width: 300, border: '1px solid #ccc', padding: 12}}> <XDSHeading level={2} maxLines={1}> Very Long Heading That Will Be Truncated To One Line With Ellipsis </XDSHeading> </div> <div style={{width: 300, border: '1px solid #ccc', padding: 12}}> <XDSHeading level={2} maxLines={2}> Very Long Heading That Will Be Truncated To Two Lines To Keep Card Layout Compact </XDSHeading> </div> </div> ); }