Text Elements / Lists & Columns

Lists

This module handles two related jobs. First, it gives the project a small set of reusable list patterns: plain resets, section indexes, feeds, and browseable catalogs. Second, it provides three ways to lay long lists out across multiple columns when a single vertical stack becomes too tall to scan comfortably.

Use native <ul> and <ol> whenever the default document flow is enough. Reach for these classes when the list needs a clearer visual role, richer item metadata, or a deliberate multi-column layout. Definition lists (<dl>) are covered with the special text elements — they are a text pattern, not a list pattern.

Small building blocks

.list-unstyled

The base reset for structural lists. It removes bullets and left padding but keeps the semantic list markup intact.

• Navigation remains a real list
• Bullets disappear
• Indentation resets to zero

Use it for navigation blocks, groups of links, table-of-contents lists, and any custom list pattern where the marker would be visual noise.

.list-title

An uppercase, bold label for a list group. It works above unstyled lists, inside .list-group-pack columns, and as the title of an .index-list. It is a pure label utility: it carries no margins of its own — vertical rhythm belongs to the surrounding context. A plain <span> is the right element for it — the label is a visual marker, not a document heading; the utility pins font-family and font-size: 1em so it stays stable even if it lands on a heading element.

Reference

• Specification
• Changelog
• Migration Notes

Index lists

.index-list

index-list is the compact "section title + short link list" pattern used for table-of-contents style navigation. The title is the thing you scan first; the items underneath stay tight and quiet.

The markup is deliberately plain: a .list-title label on a <span>, then a bare <ul> — the component styles its own ul/li (resets markers, sets item rhythm), because any list item inside an index list is an index entry by definition; no extra classes needed. The block itself owns the bottom rhythm (margin-bottom), so stacked or packed index lists separate cleanly — it is also the canonical content unit inside .list-group-pack columns.

Use it when each list needs a named category above it. If the items themselves need metadata or a richer browse-to-pick reading, move up to .catalog-list.

Multi-column list layouts

All three utilities below solve the same problem in different ways: a list is too tall to read comfortably as one vertical stack. The right choice depends on what you want to control.

How to choose quickly

• Use .list-columns when you have one long plain list and just want it to become shorter on screen.
• Use .list-group-pack when the list is made of named groups and each group should stay whole.
• Use .list-fixed-rows when you want a strict visual rhythm, for example exactly 3 or 4 rows. For a fixed two-column layout (most commonly a table of contents), set --list-rows to half the item count — the columns come out equal-width automatically.

In short: .list-columns controls columns, .list-group-pack protects groups, .list-fixed-rows controls rows.

.list-columns

.list-group-pack

For grouped sublists with subheadings. This utility packs the groups into columns sequentially and keeps each child block intact with break-inside: avoid, so a label and its items travel together. The canonical child is an .index-list — the packer arranges the columns, the index lists carry the content and their own bottom rhythm.

Important: column-fill: auto only does useful work when the container has a height. Add a height utility such as .height-xxxl or set a custom height inline. You can also tune the minimum column width with --list-group-pack-min.

On narrow viewports the utility ignores the height-driven packing and falls back to a balanced fixed-count layout: 2 columns on mobile, 3 on tablet.

.list-fixed-rows

The grid-based option. Instead of choosing a column count, you choose the number of rows with the custom property --list-rows. The browser then fills columns automatically in source order.

This is useful when visual rhythm depends on a fixed row count rather than on balanced columns.

On mobile the fixed-row contract is dropped: the list reflows into two equal columns in row order. If two columns are too tight or too loose for your items, override the count with the responsive grid utilities — mobile:grid-cols-1, mobile:grid-cols-3, and so on — right on the same element.

1. Clarify module purpose
2. Document the public classes
3. Add live examples
4. Check naming consistency
5. Verify responsive behavior
6. Link the next typography page

Two equal columns (tables of contents)

A two-column table of contents is just a fixed-rows list whose row count is half the item count. With eight entries and --list-rows: 4, the grid fills four rows and wraps into two equal-width columns — .list-fixed-rows sizes its implicit columns with minmax(0, 1fr), so they stay equal without any extra class.

1. What the library is for
2. Installation
3. Tokens
4. Typography
5. Layout
6. Components
7. Navigation
8. Decorations

Feed lists

.feed-list, .feed-list__item, .feed-list__title, .feed-list__meta

A feed is a chronological vertical stream — and a navigation surface, not body copy. Authors put content into a feed precisely because it deserves the reader's attention, so the pattern spends visual budget on it: full-size titles and generous vertical whitespace between line-separated items signal that the entries are valuable. Each item gets a top rule, a title, and a quiet meta line that keeps dates and tags from competing with the title. The pattern is intentionally narrow: it is for updates, logs, changelogs, or knowledge-base streams where sequence matters more than per-item detail.

Use a feed when each item is mostly "date + title + optional tags". If readers need to compare entries as options rather than follow them as a timeline, .catalog-list is usually the better fit.

Catalog lists

.catalog-list, .catalog-list__item

The browseable list pattern for catalogs, search results, documentation indexes, portfolios, and other "pick one of these" situations. The component is deliberately minimal: it owns the item rhythm, the title and the meta line — nothing else. Tag chips sit inline in the meta line; any extra content (a short summary paragraph, a nested list) is host content and renders with document defaults.

.catalog-list__title

The entry title. The visual anchor of each record.

.catalog-list__meta

Muted supporting metadata. Links inside stay muted too, so they remain part of the meta line instead of competing with the title. .tag chips can sit directly in the meta line — no dedicated wrapper needed.

The summary paragraphs above are plain <p> elements — host content, not component API.

.catalog-list--nest

Indents everything under the title, so each entry reads as a parent with its nested contents: the children of the thing named in the title. Use it for file trees, API surfaces, section maps, and other hierarchical indexes.