Questions

Turns a page's Questions section into disclosures: each question a summary, its answer inside.

Organism · stable · v1.0.0 · owner: Site system lead · contract 19 of 20 points (open: figma)

Do and don't

Do: Questions

Rendered by faq-list.ts

Open example: Questions · Do: Questions Use the full-page example to follow page links.

Scan, then open.

Do: Japanese

Rendered by faq-list.ts

Open example: Questions · Do: Japanese Use the full-page example to follow page links.

Same pattern.

Don't: Essential content hidden

Rendered by faq-list.ts

Renders nothing for these props (by design).

Keep must-know content visible.

Don't: Statements as questions

Rendered by faq-list.ts

Renders nothing for these props (by design).

Questions are real questions.

Rules

RuleWhyCheck
Disclosures use details and summary.They work without JavaScript and announce their state.Automated: tests/site (axe)

API

PropTypeRequiredDefaultWhat it does
htmlhtmlYesThe rendered page body; the Questions section is transformed.

Contract details

The full contract: identity, anatomy, variants, states, tokens, layout, motion, accessibility, content, tests

Identity

AspectValue
Idfaq-list
LayerOrganisms
Categorycontent
OwnerSite system lead
Statusstable
Version1.0.0
Sourceapps/showcase/site/system/organisms/faq-list.ts (private repository; the contract and the render function are this one module)
VersionDateChange
1.0.02026-10-26Questions as one module: its markup moved out of the page builder (scripts/site) into the system.

Use when

  • A '## Questions' (よくある質問) section with '### ' questions. Why: Readers scan questions and open the one they have.

Do not use when

  • For essential content. Why: Hidden answers are skipped; what everyone needs stays in the text.

Anatomy

PartWhat it is
rootdiv.faq after the section's h2
itemdetails with the question's id, summary and the answer

Made of: heading, text.

Used in: pages directly.

Variants

VariantWhenWhy
defaultWherever the page declaration places it.One shape per job keeps pages predictable.

States

StateRendered or not applicable
defaultClosed.
hoverThe summary underlines.
focus-visible--focus on the summary.
activeNot applicable: No pressed style.
disabledNot applicable: Every question opens.
loadingNot applicable: Build time; works without JavaScript.
emptyA Questions section without ### questions is left as is.
errorNot applicable: No data.
currentNot applicable: No current item.
visitedNot applicable: Not links.
expandedOpen: the answer shows and the marker turns.

Tokens

PartToken
item.rule--rule-hair --line
summary.font--type-strong
--faq-list-border-top-rulevar(--rule)
--faq-list-border-top-inkvar(--ink)
--faq-list-border-bottom-rule-hairvar(--rule-hair)
--faq-list-border-bottom-linevar(--line)
--faq-list-gap-space-6var(--space-6)
--faq-list-padding-space-6var(--space-6)
--faq-list-font-type-strongvar(--type-strong)
--faq-list-font-family-font-displayvar(--font-display)
--faq-list-font-type-h3var(--type-h3)
--faq-list-transition-dur-moderatevar(--dur-moderate)
--faq-list-transition-ease-standardvar(--ease-standard)
--faq-list-padding-bottom-space-6var(--space-6)

Layout

AspectValue
breakpointsRequired review at 390, 768, 1024 and 1440 px; execution is not implied by this declaration; columns stack under 768 px; the wrap keeps a 16 px gutter on phones.
wrappingText wraps; nothing scrolls sideways.
textExpansionJapanese runs 20 to 40% longer; headings break between phrases (jaBreaks) and blocks grow downwards.

Spacing and rhythm

AspectValue
internal--space-5 per item.
externalIn the prose column.
rhythmAfter the Questions heading.

Motion

AspectValue
NoneNo intrinsic element animation. The optional claude-entrance consumer profile may translate below-fold structure once (20px, --dur-weave, --ease-enter, --stagger); reduced motion disables it. This preserved baseline entrance is separate from element playback.

Runtime and reuse

  1. Render-only element; mount any registered child enhancements separately. Preserve required Site CSS, fonts, responsive and locale rules from nativeElement.

Accessibility passport

AspectValue
rolea landmark or list, as stated in its parts
nameIts visible text
keyboardLinks and buttons inside, in reading order.
focusThe --focus ring on every link and button inside.
screenReaderRead in source order; decorative weaving is aria-hidden.
contrastInk on cotton 14:1; text on every dye field 4.5:1 or better (checked by check-brand).
targetLinks and buttons are 44 px tall.

Content

SlotLengthVoice
question15 wordsAs the reader would ask it

Good: “Do you change how our components look?”

Bad: “Pricing info”

Japanese: よくある質問

Icons and illustrations

None: this element uses no icon or illustration of its own.

Decisions and exceptions

  • None.

Usage

9 uses across the built pages (measured by npm run site:system).

Tests

AspectValue
unittests/unit/site-system.test.ts: renders every do and don't example through the registry and checks the classes it owns
visualNot yet: there are no screenshot baselines; the Library page is checked for sideways scroll at 1440 px by tests/site/system.spec.ts
a11ytests/site/system.spec.ts: axe (0 serious or critical) on the element's Library page in light and dark
parityscripts/site/system/check.ts: Library examples are rendered by the same render function the site imports

Figma

not-yet: The Loom Site Figma library is the last stage of the plan; this element is not mapped yet.

Open in Storybook

Start with a conversation about your system.

We read your system, show you what we found, and agree with your team what to fix first.