FAQ

Code

Copy the markup

import "@luz-ds/catalog/components/faq.css";

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/faq.min.css" integrity="sha384-m1FP6KJs/RtOCSvuxpyMHSpdpfzKoGkqbqzJ0s4TSjTWAiZi584APY4HqMvX9xkV" crossorigin="anonymous">

A <luz-faq> around a title, a lead, the groups and, last, a line for the visitor who did not find the answer. Each question is a <details> and each answer is a <div> with its own id. The title is yours to level: use the heading that fits your page, and the next level for the groups.

<luz-faq>
  <h2 class="luz-faq__title">Questions about renting a bike</h2>
  <p class="luz-faq__lead">What to know before you pick up your bike.</p>
  <nav class="luz-faq__nav" aria-label="In this FAQ">
    <ul>
      <li><a href="#booking">Booking and pickup</a></li>
      <li><a href="#road">On the road</a></li>
    </ul>
  </nav>
  <section class="luz-faq__group" aria-labelledby="booking">
    <h3 class="luz-faq__group-title" id="booking">Booking and pickup</h3>
    <details class="luz-faq__item">
      <summary class="luz-faq__question">Can I cancel a booking?</summary>
      <div class="luz-faq__answer" id="faq-cancel">
        <p>Yes, free of charge until 24 hours before pickup.</p>
      </div>
    </details>
    <details class="luz-faq__item">
      <summary class="luz-faq__question">What do I need to bring?</summary>
      <div class="luz-faq__answer" id="faq-bring">
        <p>Bring a photo ID and the confirmation e-mail.</p>
      </div>
    </details>
  </section>
  <section class="luz-faq__group" aria-labelledby="road">
    <h3 class="luz-faq__group-title" id="road">On the road</h3>
    …
  </section>
  <p class="luz-faq__more">Not here? <a href="/contact/">Write to the shop</a></p>
</luz-faq>

Variants and options

Only the list of questions is needed. The title, the lead, the groups, the links to the groups and the last line are optional parts.

How it works

CSS from @luz-ds/catalog. No JavaScript: <luz-faq> is a tag that no script ever defines.

• Every answer is in the HTML the server sends, so a reader, a search engine and a tool that does not run scripts all get it.
• Put the id on the .luz-faq__answer, never on the <details>. A link to an id on the <details> lands on its <summary>, which is already in view, so the browser opens nothing. A link to an id inside the hidden answer opens the question, and the answer keeps the question above it when the page scrolls.
• The browser’s Find in page also opens a question whose answer holds the words it found.
• The whole question is the control, at least a large control high, not only the plus. Its text can be selected, so a visitor can copy it to quote it.
• The state is the shape of the marker: a plus when closed, a minus when open. The open question also takes the brand colour, so it reads apart from its answer, and a question under the pointer takes the same colour, with no underline. The marker folds with a short ease, and with reduced motion it changes without it.
• Long words break, and code or a table inside an answer scrolls inside it: the page never scrolls sideways.
• On paper every answer prints, open or closed, and the markers do not.

Without JavaScript

Nothing changes: all of it works. Opening, closing, the exclusive group, the link to an answer and Find in page are the browser’s.

Keyboard and ARIA

Tab reaches each question in order. Enter or Space opens or closes it. There are no arrow-key shortcuts between questions.

• The control: the <summary> is the control and the browser gives it its role and its state. Add no aria-expanded, no aria-controls and no role: they repeat what the element already says.
• Headings: the questions are not headings. A heading inside a <summary> is not announced as one in every screen reader. The group titles are the headings of the list, so a reader can move through the topics by headings.
• Groups and links: a group is a <section> named by its title with aria-labelledby. The links to the groups go in a <nav> with an aria-label.
• Keep links and buttons out of a question: the question is itself the control. Links belong in the answer.
• The FAQ has not been tested with a screen reader.

Contrast and focus are in the Design tab.

Design

When to use

Use it for a list of several questions that visitors really ask, which you can answer in a few sentences each: opening hours, prices, how to book, what a product does not do.

• It fits a landing page, a help page or the foot of a product page, in a site of any kind.
• Group the questions when there are several topics; leave the groups out of a short list.

When not to use

Do not use it for one disclosure: a single <details>, or the accordion of core, is enough and carries no list around it.

• Do not put a long guide in an answer. Answer in a few sentences and link to the page that explains it.
• Do not use it to hide content the visitor needs on every visit: show that on the page.
• Do not use it to stuff a page with keywords. A question nobody asks helps nobody.

Do and don't

Writing the content

An answer can be read alone, in a search result, in a quote or in a link, so write each one to stand on its own.

• Write each question in natural language, one doubt per question, as the visitor would ask it. Never write one only to carry a keyword.
• Answer in the first sentence. Then add the context, the steps or the exceptions.
• Make every answer understandable alone: no “this”, “the above” or “as said before”. Use the concrete names: the product, the file, the element.
• Give facts, conditions and examples, and link to the page that explains the subject in depth instead of copying it.
• Keep the answers up to date and consistent with the rest of the site. A figure that appears elsewhere is written once.
• Use a list for steps and a short code block for a command. Keep sentence case in the questions, with the question mark.

Structured data of type FAQPage is your call, and the component adds none. Search engines show rich results for FAQs on a few kinds of sites only, and no markup makes a page appear in an AI answer. Add it if it applies to your site, and promise nothing with it.

Contrast and focus

The questions, answers and links sit on the page surface.

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 the marker and focus rings. On a surface other than the page, measure again.

• Focus: the question has core’s 2 px --luz-focus-ring outline, 2 px outside its box.
• Open or closed is never told by colour alone: the marker changes shape, from a plus to a minus.
• The hairlines between questions (--luz-divider) are decoration: the text of each question, not a border, says where it is.
• In forced colours the marker takes the system’s text colour and stays visible.

Tokens it uses

The 21 tokens that the rules of catalog’s components/faq.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.

Color

--luz-brand-primary, --luz-divider, --luz-surface-hover, --luz-text-primary, --luz-text-secondary

Spacing and sizing

--luz-control-lg, --luz-space-2xl, --luz-space-2xs, --luz-space-lg, --luz-space-md, --luz-space-sm, --luz-space-xl, --luz-space-xs

Typography

--luz-font-body, --luz-font-heading, --luz-font-sans, --luz-text-lg, --luz-text-sm

Radius

--luz-radius-sm

Motion

--luz-duration-fast, --luz-easing-standard

Keyboard and ARIA are in the Code tab.