Catalog · Documentation
Page head
The top of a documentation page: the eyebrow, the title, one sentence and the chips that say what the page covers.
Fits best: docs — the top of a documentation page
Example
The head of a page about installing a command line tool.
A picture of the head: it holds a title of its own, so it is hidden from assistive technology on this page. Its text is in the markup below.
The chips wrap on a narrow screen.
Known issues
None known.
Code
Copy the markup
import "@luz-ds/catalog/components/doc-header.css";<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/doc-header.min.css" integrity="sha384-cVHBijhO5S1m513QmZHN7btnqgne60iGIX8ZA3KRh9BkZafEAbeVcEurGxtfGbg+" crossorigin="anonymous">The head, as the first child of the content:
<header class="luz-doc-header">
<p class="luz-doc-header__eyebrow">Guides · Setup</p>
<h1>Install the command line tool</h1>
<p class="luz-doc-header__lead">Add the tool to a project and check that it runs, in about two minutes.</p>
<ul class="luz-doc-header__meta">
<li>Version 2</li>
<li>macOS, Linux and Windows</li>
<li><a href="#known-issues">No known issues</a></li>
</ul>
</header>Variants and options
No modifier. The head is a class on a native <header> with four parts.
| Class | Effect |
|---|---|
.luz-doc-header | On a <header> in the content: one column, with a gap between its parts and room under it. Its h1 is --luz-text-4xl, and --luz-text-2xl at 640px and below |
.luz-doc-header | On a <p>: the area and the group, in small spaced capitals and the secondary colour. A <code> in it, a package name, keeps its own case. In Arabic the spacing between letters is left out |
.luz-doc-header | On a <p>: one sentence, larger than the text, in the secondary colour |
.luz-doc-header | On a <ul>: the chips. Each <li> is a word or two in a rounded outline, at least --luz-control-sm (28px) tall. A link in one is the same height |
.luz-doc-header | On a <p>, instead of the chips, on a page that is not a component: "Files:" and each file in a <code>, one small line in the secondary colour |
How it works
CSS from components/doc-header.css of @luz-ds/catalog. It sets the rhythm and the sizes; the words are yours.
- The head is a grid of one column. The gap between the parts is
--luz-space-smand the space under the head is--luz-space-xl. - The
h1is a plain element inside the head, with no class: the head styles it by position. - The chips are a list of facts a reader asks before reading: which files, which script, which modes, whether it is tested, whether it has known issues. A chip that leads somewhere is a link.
- A long word in a chip breaks instead of widening the page, so the chips wrap at 320px.
Without JavaScript
Nothing changes. The head is text and links, and the package has no script.
Keyboard and ARIA
- Order: the order of the source: eyebrow, title, lead, then the chips. Tab reaches only the links in the chips.
- Headings: the
h1is the oneh1of the page. A<header>inside<main>is not a banner landmark. - Chips: a list of plain items, announced as a list. A chip with no link is text and takes no focus.
Contrast and focus are in the Design tab.
Design
When to use
Use the head at the top of every page of a documentation site, so a reader finds the title and what the page covers in the same place.
- One sentence that says what the page lets a reader do.
- A few chips for the facts that decide whether to read on.
When not to use
Do not use the head for the banner of the site: it holds the page's h1.
- One head per page. A section of a long page has an
h2, not another head. - For the header of an article in a blog, use the CMS article header.
- A landing page opens with the hero.
Do and don't
Writing the content
- Eyebrow: the area, then the group, with a space, a middle dot and a space: "Guides · Setup". Sentence case; the style makes the capitals.
- Title: what the page is about, or a task that starts with a verb: "Install the command line tool". No full stop.
- Lead: one sentence that ends with a full stop, in about twenty words or fewer.
- Chips: two to five, a word or a few. State a fact ("Version 2"), never a slogan. "No known issues" links to the list.
Contrast and focus
All the text sits on the page surface. The outline of a chip is decoration: the word inside carries the meaning.
| Part | Colour on background | Light | Dark | High contrast | Needs |
|---|---|---|---|---|---|
Title | --luz-text-primary on --luz-surface-page | 15.8:1 | 15.1:1 | 21.0:1 | 4.5:1 |
Eyebrow | --luz-text-secondary on --luz-surface-page | 6.2:1 | 7.5:1 | 19.3:1 | 4.5:1 |
Lead | --luz-text-secondary on --luz-surface-page | 6.2:1 | 7.5:1 | 19.3:1 | 4.5:1 |
Chip | --luz-text-secondary on --luz-surface-page | 6.2:1 | 7.5:1 | 19.3:1 | 4.5:1 |
Link in a chip | --luz-brand-primary on --luz-surface-page | 5.6:1 | 7.7:1 | 14.1:1 | 4.5:1 |
Focus ring | --luz-focus-ring on --luz-surface-page | 5.6:1 | 7.7:1 | 21.0:1 | 3:1 |
Measured from the token values of each mode, rounded down. Needs is the WCAG 2.2 AA minimum: 4.5:1 for text, 3:1 for focus rings, borders and icons.
- Focus: a link in a chip keeps core's ring, 2 px of
--luz-focus-ring. - Target: a chip and a link in it are at least 28 by 28 px, above the 24 px minimum of WCAG 2.2 (2.5.8).
- Edges: the outline of a chip (
--luz-divider) is decorative and has no minimum.
Tokens it uses
The 12 tokens that the .luz-doc-header rules of catalog’s components/doc-header.css read, by family. Each family links to its page, with the values in every mode. In Figma they are variables with the same names: see Tokens in Figma.
- Spacing and sizing
--luz-control-sm,--luz-space-sm,--luz-space-xs- Typography
--luz-font-sans,--luz-text-2xl,--luz-text-4xl,--luz-text-base,--luz-text-lg,--luz-text-xs- Radius
--luz-radius-full
Keyboard and ARIA are in the Code tab.