List

🧭 When to Use a List

Use a List when:

• You want to organize related content in a clear, scannable format

• The order of content matters (e.g., steps, rankings) or structure enhances comprehension

• You want to pair content with visual identifiers (e.g., icons or numbers)

Avoid using Lists when information is better expressed through paragraphs, tables, or cards.

🔢 List Identifiers

List Identifiers provide a visual anchor to each item in the list. They can guide the reader’s attention, show order, or reinforce meaning.

🧩 Identifier Types

• Icon – Uses a symbol or glyph (e.g. check, info, flag); ideal for feature lists or statuses

• Numeric – Shows a number for ordered lists or steps

• Process – Stylized numeric or labeled step indicator; great for onboarding flows

• Bullet – Simple dot or shape; works best in unordered or basic informational lists

Each identifier is token-driven and can be swapped using a variant toggle in Figma.

📏 Identifier Sizes

• Large (lg) – Use in hero layouts, onboarding flows, or full-width containers

• Medium (md) – Default; great for UI content, modals, and feature sections

• Small (sm) – Use in compact spaces or sidebars

Identifier size matches the list item’s size to maintain vertical alignment and spacing.

📦 List Items

A List Item includes:

• Optional List Identifier (icon, bullet, number, etc.)

• A Title (optional)

• A Supporting Description or content block

Each List Item uses token-based spacing and type styles to maintain consistency across all sizes.

📏 List Item Sizes

• Large (lg) – More padding and line height; for landing pages and detailed layouts

• Medium (md) – Default system size for most UI use

• Small (sm) – Use in dense UI areas like sidebars, tooltips, or compact components

You can toggle the Identifier Layer in each item to show or hide it independently.

🗂️ List (Composite Component)

The List component is a collection of one or more List Items. It handles vertical spacing, alignment, and heading logic.

🧠 Composite Properties

• Size – Applies uniformly to all items and identifiers within

  • lg, md, sm

• Heading (optional) – A label or title for the entire list; placed above the items and styled with standard heading tokens

• Indentation & alignment – Adjusts automatically based on identifier width or presence

Lists can be used as:

• Unordered (bullets or icons)

• Ordered (numeric or process)

• Descriptive (no identifier, just structured text)

♿ Accessibility Considerations

From a design perspective:

• Keep spacing consistent between items

• Use visual hierarchy to make lists easy to scan

• Ensure icons and bullets have sufficient contrast

From a code perspective (if implemented):

• Use semantic HTML: <ul> for unordered, <ol> for ordered

• Use <li> for each item

• For custom identifiers (like icons), ensure aria-hidden="true" if decorative

• For accessible step indicators, use aria-label or live region support if interactive

✅ Best Practices

• Keep each list item short and scannable

• Only use process/numeric identifiers when order matters

• Don’t overload a single list — break long ones into sub-groups

• Pair icons with tooltips or descriptions if the symbol could be unclear

• Use a heading when the list acts as a major section in a layout