Typography List

Overview

Typography List styles readable ordered and unordered content lists inside prose, documentation, dashboard copy, settings pages, onboarding flows, pricing sections, release notes, admin screens, ecommerce back offices, ERP and POS workflow notes, and starter-kit pages. It provides semantic <ul>, <ol>, and <li> markup with token-based spacing, marker colors, and line-height that adapt to light mode, dark mode, and branded themes. Typography List is a Typography variant available through @byteion/react and @byteion/vue.

Why this exists

Without a shared list style, product screens and documentation use inconsistent marker spacing — one page uses list-disc ml-6 space-y-4, another uses list-none p-0 with custom icons, a third uses hardcoded • characters in paragraphs. Dark-mode contrast is not tested, line heights vary, nested lists break alignment, and icon lists lose semantic structure. Typography List unifies all content lists into a single, accessible, token-based system with consistent marker style, spacing, indentation, and dark-mode support.

Mental model

• Use unordered lists when order does not matter. Features, options, related items, and bullet points belong in <ul>.
• Use ordered lists when sequence matters. Setup steps, instructions, ranked items, and procedural content belong in <ol>.
• Use icon lists for benefits, features, and checklists. Custom SVG icons or check marks replace the default marker but must preserve list semantics.
• Semantic list markup comes first. <ul>, <ol>, and <li> convey meaning to assistive technology. Styling should enhance, not remove, that meaning.
• Typography List is for prose content. For interactive navigation, action menus, structured data, or chronological events, use List, Dropdown, Table, or Timeline respectively.

Typography List vs List vs Menu vs Table

When to use

• Documentation bullet lists — features, constraints, related topics
• Setup and installation steps — ordered sequence of actions
• Pricing feature lists — benefits per plan tier
• Onboarding checklist content — steps to complete setup
• Release notes — grouped bullet items per category
• Dashboard insight notes — quick-reference bullet items
• Settings explanations — options or configuration items
• Ecommerce product requirements — specs, dimensions, materials
• ERP and POS workflow instructions — step-by-step task flows

When not to use

• Do not use Typography List for navigation menus — use List or Sidebar for interactive link lists.
• Do not use it for dropdown or menu actions — use Dropdown for interactive action menus.
• Do not use it for selectable options or listbox behavior — use Select or Multi-Select.
• Do not use it for tabular data — use Table for rows and columns.
• Do not use it for timelines — use Timeline for chronological events.
• Do not use it for complex repeated cards — use Card with Stack or Grid for structured card layouts.
• Do not use ordered lists when the order does not matter — unordered bullets communicate "these are related" without implying sequence.
• Do not use unordered lists for step-by-step instructions — numbered steps tell the reader "do this first, then this."

Basic example

A minimal unordered list with token-based marker and text color.

• Install @byteion/core via npm
• Import the CSS variables into your project
• Configure content paths in tailwind.config.js
• Start building your UI

Unordered lists

Use <ul> with list-disc for default bullet markers. The marker inherits text-muted-foreground from the parent list. For compact layouts, reduce space-y-2 to space-y-1.

Ordered lists

Use <ol> with list-decimal when sequence matters. The numbers use the same text-muted-foreground color as the default marker.

Icon lists

For feature lists, pricing benefits, and checklists, replace the default marker with a custom icon. Preserve list semantics by keeping <ul> and <li> and using list-none with a flex layout for the icon and text.

Nested lists

Nest a second <ul> or <ol> inside an <li> for sub-items. The nested list should have reduced spacing and a different marker style — list-circle or list-disc — to visually distinguish the level.

Variants and composition

Typography List does not expose variant props — it relies on semantic HTML and utility classes. The following composition patterns cover common use cases:

• Unordered list — <ul class="list-disc list-outside ml-5 space-y-2 text-muted-foreground"> for related items where order does not matter.
• Ordered list — <ol class="list-decimal list-outside ml-5 space-y-2 text-muted-foreground"> for step-by-step instructions where sequence matters.
• Icon list — <ul class="list-none space-y-3"> with flex items-start gap-3 per item for benefits and checklists.
• Compact list — space-y-1 instead of space-y-2 for dense dashboard or settings copy.
• Spacious list — space-y-3 and text-base for documentation and long-form content.
• Nested list — a child <ul> or <ol> inside an <li> with ml-6 space-y-1 text-sm.

Anatomy

1. List container — <ul> (unordered) or <ol> (ordered) with list-disc, list-decimal, or list-none
2. Marker — default bullets or numbers styled via marker:text-muted-foreground or custom icons
3. List item — <li> with text-muted-foreground (or text-foreground for emphasis)
4. Spacing — vertical gap between items via space-y-*
5. Nested list (optional) — child list indented with ml-5 or ml-6

Usage guidelines

• Choose <ul> or <ol> based on meaning. Default bullets for unordered, decimal numbers for ordered. Do not use ordered lists just because you have numbers.
• Keep list items parallel. All items should follow the same grammatical structure — start with a verb, a noun, or a full sentence consistently.
• Keep items short. A list item should be scannable in under two lines. If an item needs a paragraph, it is not a list item — consider a subheading and body text.
• Use list-outside to keep the marker visible and aligned regardless of item length.
• Indent nested lists with ml-5 or ml-6 and use a different marker style for each nesting level.
• Use text-muted-foreground for list items. Reserve text-foreground for items that need extra emphasis.

Do and Don't

Accessibility

• Use semantic <ul>, <ol>, and <li> elements. Assistive technology announces the number of items and the list role. Div-only markup loses this information.
• Do not replace list semantics with div-only markup. A <div> with bullet characters or manual numbers has no list semantics for screen readers.
• Ordered lists should be used when order or sequence matters. Screen readers announce the number of each item, helping users navigate step-by-step content.
• Unordered lists should be used when order does not matter. Screen readers announce bullet items without implying sequence.
• Custom icon lists must preserve list semantics. Use list-none on the <ul> and keep <li> elements. Do not replace with <div>.
• Links inside list items must be visually identifiable (underline or distinct color) and keyboard accessible.
• Avoid very long list items that become hard to scan. Screen reader users navigate lists item by item — each should be a digestible unit.

Customization

Typography List should be customized through typography and spacing tokens:

• Marker color — marker:text-muted-foreground or marker:text-primary for emphasized lists
• Text color — text-muted-foreground for items, text-foreground for emphasis
• Line height — leading-relaxed for readability in documentation, leading-normal for compact UIs
• Item spacing — space-y-1 (compact), space-y-2 (default), space-y-3 (spacious)
• Indentation — ml-4 or ml-5 for top-level, ml-6 for nested
• Icon size — h-5 w-5 for default icons, text-base for icon font
• Nested spacing — mt-2 space-y-1 text-sm for second-level lists

HTML example

<!-- Unordered list -->
<ul class="list-disc list-outside ml-5 space-y-2 text-muted-foreground">
  <li>Install <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono">@byteion/core</code></li>
  <li>Import the CSS variables into your project</li>
  <li>Configure content paths in tailwind.config.js</li>
  <li>Start building your UI</li>
</ul>

<!-- Ordered list -->
<ol class="list-decimal list-outside ml-5 space-y-2 text-muted-foreground">
  <li>Create a new project with npm create byteion</li>
  <li>Choose your framework — React, Vue, or HTML</li>
  <li>Select the components you need</li>
  <li>Run npm run dev to start developing</li>
</ol>

<!-- Icon list (list semantics preserved) -->
<ul class="list-none space-y-3">
  <li class="flex items-start gap-3">
    <span class="mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center
      rounded-full bg-emerald-500/10 text-emerald-500 text-xs">✓</span>
    <span class="text-sm text-muted-foreground">
      Framework-agnostic — works with HTML, React, and Vue
    </span>
  </li>
  <li class="flex items-start gap-3">
    <span class="mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center
      rounded-full bg-emerald-500/10 text-emerald-500 text-xs">✓</span>
    <span class="text-sm text-muted-foreground">
      Token-based theming with light, dark, and brand mode support
    </span>
  </li>
</ul>

React example

export default function Checklist() {
  return (
    <div className="space-y-6">
      <div>
        <h3 className="text-sm font-semibold text-foreground mb-3">
          Getting started
        </h3>
        <ul className="list-disc list-outside ml-5 space-y-2 text-muted-foreground">
          <li>Install <code className="rounded bg-muted px-1.5 py-0.5 text-xs font-mono">
            @byteion/core</code></li>
          <li>Import CSS variables into your entry point</li>
          <li>Configure tailwind.config.js</li>
        </ul>
      </div>

      <div>
        <h3 className="text-sm font-semibold text-foreground mb-3">
          Setup steps
        </h3>
        <ol className="list-decimal list-outside ml-5 space-y-2 text-muted-foreground">
          <li>Run <code className="rounded bg-muted px-1.5 py-0.5 text-xs font-mono">
            npm create byteion</code></li>
          <li>Choose your framework</li>
          <li>Select your components</li>
        </ol>
      </div>

      <div>
        <h3 className="text-sm font-semibold text-foreground mb-3">
          Benefits
        </h3>
        <ul className="list-none space-y-3">
          <li className="flex items-start gap-3">
            <span className="mt-0.5 flex h-5 w-5 shrink-0 items-center
              justify-center rounded-full bg-emerald-500/10
              text-emerald-500 text-xs">✓</span>
            <span className="text-sm text-muted-foreground">
              Framework-agnostic
            </span>
          </li>
          <li className="flex items-start gap-3">
            <span className="mt-0.5 flex h-5 w-5 shrink-0 items-center
              justify-center rounded-full bg-emerald-500/10
              text-emerald-500 text-xs">✓</span>
            <span className="text-sm text-muted-foreground">
              Token-based theming
            </span>
          </li>
        </ul>
      </div>
    </div>
  );
}

Vue example

<script setup lang="ts">
// No additional logic needed for static list markup
</script>

<template>
  <div class="space-y-6">
    <div>
      <h3 class="text-sm font-semibold text-foreground mb-3">
        Getting started
      </h3>
      <ul class="list-disc list-outside ml-5 space-y-2 text-muted-foreground">
        <li>Install <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono">
          @byteion/core</code></li>
        <li>Import CSS variables into your entry point</li>
        <li>Configure tailwind.config.js</li>
      </ul>
    </div>

    <div>
      <h3 class="text-sm font-semibold text-foreground mb-3">
        Benefits
      </h3>
      <ul class="list-none space-y-3">
        <li class="flex items-start gap-3">
          <span class="mt-0.5 flex h-5 w-5 shrink-0 items-center
            justify-center rounded-full bg-emerald-500/10
            text-emerald-500 text-xs">✓</span>
          <span class="text-sm text-muted-foreground">
            Framework-agnostic
          </span>
        </li>
        <li class="flex items-start gap-3">
          <span class="mt-0.5 flex h-5 w-5 shrink-0 items-center
            justify-center rounded-full bg-emerald-500/10
            text-emerald-500 text-xs">✓</span>
          <span class="text-sm text-muted-foreground">
            Token-based theming
          </span>
        </li>
      </ul>
    </div>
  </div>
</template>

API Reference

Typography List is rendered through semantic HTML — <ul>, <ol>, and <li> — with utility classes for spacing, markers, and color. The list below shows the recommended utility pattern for each style:

Developer tips

• Choose <ul> or <ol> based on meaning, not visual preference. If you want bullets, use <ul>. If the sequence matters, use <ol>.
• Keep items parallel in grammar and length. Consistent structure makes lists scannable. Start each item with the same part of speech.
• Use icon lists for feature or benefit sections — the visual marker reinforces the message (checkmark, number, icon).
• Use compact spacing inside cards (space-y-1) and spacious spacing in documentation (space-y-2 or space-y-3).
• Test wrapping on mobile. A two-line item on desktop may wrap to three lines on a small screen. Ensure the marker stays visible with list-outside.
• Preserve list semantics when using custom SVG icons. Keep <ul> and <li>, use list-none, and place the icon inside the <li>.

Common mistakes

• Using divs instead of <ul> / <ol> / <li> — non-semantic markup loses list role and item count for assistive technology.
• Using unordered bullets for ordered steps — readers cannot distinguish "step 1" from "step 2" without numbers in progressive instructions.
• Using ordered numbers for unordered benefits — numbering implies sequence. If the items can be rearranged, use bullets.
• Hardcoding marker colors — text-gray-400 or list-disc text-blue-500 breaks in dark mode. Use marker:text-muted-foreground.
• Using Typography List for navigation menus — interactive navigation needs role="navigation" or a dedicated List component.
• Writing long paragraph-like list items — items longer than two sentences should be promoted to subheadings and body text.
• Breaking mobile wrapping — fixed-width containers without overflow handling clip list items on small screens.

Production usage tips

• Test list wrapping on mobile. Ensure list-outside keeps markers visible and items do not overflow their parent.
• Test dark mode and branded themes. Marker contrast via text-muted-foreground should remain readable in all themes.
• Check marker contrast. The default marker inherits text-muted-foreground. Verify WCAG AA 4.5:1 against the background.
• Review long translated list items. Translated text can be 30–50% longer than the source. Test all languages used in your app.
• Keep React and Vue output aligned with semantic HTML. The same <ul> / <ol> / <li> contract applies across frameworks.
• Confirm custom icon lists remain accessible. Test with a screen reader to verify the list structure is announced even when markers are replaced with icons.

Premium examples

Advanced patterns available in Pro extend Typography List into richer product and documentation contexts.

• Pricing feature checklist — an icon list per plan tier with checkmarks for included features and muted dashes for excluded ones, enclosed in a Card.
• Onboarding task list — an ordered list of setup steps with completion status icons and a progress indicator alongside each item.
• Release note bullet group — categorized unordered lists under Heading labels — "Added", "Fixed", "Changed" — with version and date metadata.
• Documentation setup checklist — a multi-column grid of ordered steps flanked by tooltips and code blocks, with checkable items for tracking progress.
• Dashboard insight list — compact unordered list inside a dashboard card showing key metrics or alerts with time context.
• Ecommerce product requirement list — an icon list with size and material icons showing specifications, materials, and care instructions below a product image.
• ERP / POS workflow instruction list — a multi-step ordered list with nested sub-items for each workflow stage, paired with a stepper component for position context.

Related components

• List — repeated structured UI records and navigation link groups
• Text — body copy, helper text, captions, inline code, and keyboard labels
• Paragraph — readable body copy for descriptions, documentation, and prose
• Heading — semantic heading hierarchy for list section titles
• Timeline — chronological event lists (not a prose list replacement)
• Accordion — expandable content sections for grouped list details
• Badge — compact status and count labels used inside list items
• Card — surface container for grouping a list with related content

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