Susegad UI Accessibility GitHub

How this site looks

The view settings need JavaScript. Every page reads well without them.

Mood

The same pages, in three moods.

Theme

Components

Accordion

Frequently asked questions on the browser's own details and summary: the summary is a real toggle that takes Tab and turns on Enter and Space, and questions sharing a name form an exclusive group, only one open at a time.

quiet warm playful

Open the live demo npx @susegad/cli add accordion

Stands on: Core, Core: components, Engine, Tokens

The prompt

the prompt

Frequently asked questions: a homestay's FAQ, a workshop's common questions, a page of "how it works".

A list of questions the reader opens one at a time. Built on the browser's own details and summary, so the keyboard, the screen reader and the exclusive group come from the platform; the component's job is the drawing and the account of what is open.

<link rel="stylesheet" href="susegad/components/accordion/accordion.css">
<script type="module" src="susegad/components/accordion/accordion.js"></script>

<sg-accordion name="faq">
  <details name="faq" open>
    <summary>Where is the homestay, and how do I get there?</summary>
    <p>In Aldona, a village in the fields north of Panjim.</p>
  </details>
  <details name="faq">
    <summary>Is breakfast included?</summary>
    <p>Yes, on the veranda from 7:30 to 10.</p>
  </details>
</sg-accordion>

The prompt

Make a FAQ accordion web component around native <details> and <summary>, in the light DOM only. Do not build your own open and close: the summary is already a button-like toggle that takes Tab and turns on Enter and Space, the open state is already in the accessibility tree, and several <details> sharing one name attribute already form an exclusive group, only one open at a time (Chromium and Safari, Firefox from 130). The element <sg-accordion> wraps a list of details; it copies its own name attribute onto any child that has none and leaves children that carry a name alone, so one accordion can hold an exclusive group and free-standing sections side by side. Two items of one group starting open are settled by the browser while parsing, so the element does not re-judge them; a build step can check the source with resolveOpen() from the pure core instead. The element keeps an account and hands it out: on every turn it dispatches sg-accordion-change with { open, total, exclusive }, once per turn even though both group-mates fire a toggle, and exposes details, items and account. It adds no words anywhere: every word a reader sees is the author's markup, and the STRINGS shelf in the core is empty on purpose. The pure core (accordion.core.js) runs in Node with no DOM: groups from groupsOf, the clash plan from resolveOpen (first of each named group keeps open, the rest closed, each with a warning), the open account from describeItems ({ total, open, exclusive, groups }, exclusive false when two of a named group are open at once), and othersToClose for what one turn of a named item closes. Three registers. Quiet: hairline rules between items and across the top of the first, generous space, a thin chevron that turns when the item opens, nothing else. Warm: the marker drawn in the hand face, a small hand-set plus that becomes a minus when the item opens, and a soft open transition, the answer sliding down and fading in. Playful: the questions set in the hand face, and the marker a drawn glyph in the accent colour, each with its own small seeded tilt (two to seven degrees, from a seed), that flips 180 degrees with a spring ease when the item opens. The open transition animates the native ::details-content (block size, opacity and content-visibility) with interpolate-size: allow-keywords set on the element, so the height animates to and from auto; every transition lives under the element's data-motion word, which is still under reduced motion, state in quiet, ambient in warm and full in playful. Under reduced motion nothing carries a transition and an item still opens and closes as a finished still.

Words to code

When you sayTechniqueWhat happens
native details and summarythe platformNo custom toggle anywhere. The summary takes Tab and turns on Enter and Space; the open state is in the accessibility tree without a line of ARIA.
exclusive group<details name>Several details sharing a name keep each other: only one open at a time. Chromium and Safari, Firefox from 130. Without a name, every item stands alone.
the element's name adopts the childrenconnected() in accordion.jsA name on <sg-accordion> is set on every child that has none; a child that already carries a name keeps its own.
two open in one group at parsethe browserThe browser keeps the first and drops the rest while parsing, before custom element code runs. resolveOpen() in the pure core does the same job in the open, with a warning per closed item, for a build step.
the accountdescribeItems(items) in the core{ total, open, exclusive, groups }. exclusive is false only when two items of a named group are open at once; an unnamed open one beside them does not break the promise.
tells the page what is open, once per turnthe element's update()Both group-mates fire a toggle on one turn (the event bubbles in modern Chromium); the element signs the account and emits sg-accordion-change only when it changed.
no words of its ownSTRINGS = {} in the coreEvery word a reader sees is the author's markup. The shelf is empty on purpose, so a future string has a home.
hairline rules, a thin chevronquiet registerCSS only: a chevron of two borders that rotates 45 degrees between closed and open, no easing, a state not a motion.
the marker in the hand facewarm registerCSS: content: "+" becomes "–" on [open], set in var(--sg-font-hand) in the accent colour; the answer opens with a soft slide on ::details-content.
a glyph that flipsplayful registerCSS: the marker is a drawn glyph in the hand face, rotated by --sg-acc-tilt (set per item by the skin from a seed, two to seven degrees) and flipping 180 degrees more when the item opens, on the spring ease.
a soft open transition::details-contentThe answer's block size, opacity and content-visibility transition, with interpolate-size: allow-keywords on the element so the height animates to and from auto. Warm uses the ease-out, playful the spring.
nothing moves under reduced motiondata-motionThe element's motion word is still under reduced motion; every transition in the CSS is gated on data-motion and on prefers-reduced-motion, and the still is finished: items still open and close.

Accessibility

  • No ARIA: <details> and <summary> already say everything.
  • The markers and rules are pseudo-elements; they carry no meaning and sit outside the accessibility tree.
  • The focus ring is visible in every register; the tab order is the order the questions are written.
  • Without JavaScript, everything still opens and closes, and the quiet look applies.

Checks

accordion.check.mjs proves all of it in a browser: axe in three registers and two themes and without JavaScript (0 violations everywhere), Tab reaching a summary with a visible ring, Enter and Space turning it, the exclusive group displacing its neighbours by click and by keyboard, two shipped-open items settled to one, a child with its own name left out of the adoption, no JavaScript (open and close, and the exclusive promise, on the platform alone), 390 px with no sideways scroll, reduced motion as a finished still with the transition under a millisecond, and a control: the same exclusive-group probe on plain unnamed details, where all three stay open, reads red once to prove the check has teeth.

<sg-accordion> is a list of questions and answers for an FAQ. It enhances the browser's own <details> and <summary>: the browser does the opening and closing, with or without JavaScript.

Markup

ElementWhat it is
details (children of the element)one question. Several sharing the same name form an exclusive group: only one open at a time.
summarythe question, one per details. It is the reader's toggle: Tab to it, Enter or Space to turn it.
everything after the summarythe answer, plain markup (paragraphs, lists, links). Write it as you would any prose.

The element adds no words and no structure of its own. Two things it does add:

  • A name attribute on the element becomes the group for every child that has none. A child that already carries its own name keeps it, so one accordion can hold an exclusive group and free-standing sections side by side.
  • Attributes for the skins: data-skin (set by the element), data-motion, data-open-count, data-any-open.

Two or more items of one group starting open are settled by the browser while parsing: it keeps the first and drops the rest. Check the source with resolveOpen() from the pure core at build time if you want the clash named where an author can see it.

Attributes

AttributeValuesDefault
namea group name for the children that have nonenone: every item stands alone unless it carries a name
registerquiet, warm, playfulinherited

Event: sg-accordion-change { open, total, exclusive }, when an item moves (open is the indices now open). The element also exposes details (its items), items ({ name, open, label }[]) and account ({ total, open, exclusive, groups }) for a page that wants the state in JS.

The platform owns the behaviour

  • A summary is a real toggle: it takes Tab, opens on Enter and Space, and shows a 2 px focus ring.
  • Screen readers get the open and closed state from the <details> itself; the element adds no ARIA, because none is needed.
  • The exclusive group is <details name="…">, native in Chromium and Safari, Firefox from 130.
  • Without JavaScript everything still opens and closes. The quiet look applies.

Registers

Look
quiethairline rules between items and across the top of the first, generous space, a thin chevron that turns when the item opens. No ornament.
warmthe marker drawn in the hand face: a small hand-set + that becomes a – when the item opens, and a soft open transition (the answer slides down and fades in).
playfulthe questions set in the hand face; the marker a drawn glyph in the accent colour, each with its own small seeded tilt, that flips 180 degrees with a spring when the item opens.

Nothing moves under reduced motion: every register keeps its finished still, and an item still opens and closes.

Sample

<link rel="stylesheet" href="susegad/components/accordion/accordion.css">
<script type="module" src="susegad/components/accordion/accordion.js"></script>

<sg-accordion name="faq">
  <details name="faq" open>
    <summary>Where is the homestay, and how do I get there?</summary>
    <p>In Aldona, a village in the fields north of Panjim. Half an hour by car or bus; we send directions when you book.</p>
  </details>
  <details name="faq">
    <summary>Is breakfast included?</summary>
    <p>Yes, on the veranda from 7:30 to 10.</p>
  </details>
</sg-accordion>

Accessibility

How this component meets WCAG 2.2 level A and AA, criterion by criterion, how each was checked, and what your page still owns.

  • Meets 15
  • Meets with author's part 1
CriterionStatusHow it was checked
1.1.1 Non-text contentMeetsThe open and closed marker (a chevron, a drawn plus or minus) is a CSS pseudo-element in packages/components/accordion/accordion.css, so it is not in the accessibility tree and carries no meaning that the native open state does not. The demo holds no images.
1.3.1 Info and relationshipsMeetsNative <details> and <summary>: the summary is the button, the open state is the browser's own. packages/components/accordion/accordion.check.mjs: "no JavaScript: a click on the summary opens it" and "no JavaScript: opening the third closes the first, on the platform alone". Headings or lists inside an answer are the author's markup.
1.4.1 Use of colorMeetsThe open state is a turned chevron in quiet and a plus that becomes a minus in warm, and the answer itself appears; none of it is a colour change alone (packages/components/accordion/accordion.css, summary::before rules). Links inside an answer are underlined (text-underline-offset in the same file).
1.4.3 Contrast (minimum)MeetsSummary text is --sg-text and answers are --sg-text-soft, both tested at 4.5:1 or more on every surface, palette and theme in packages/tokens/tokens.test.js ("AA: ... every text role on every surface is 4.5:1 or more"). accordion.check.mjs: "axe, light, all three registers: 0 violations" and the same in dark, color-contrast included.
1.4.4 Resize textMeetsManual test, 2026-10-06: the demo with the root font size at 200 percent in three registers (1280 px wide), no sideways scroll and no clipped text, including the open answer (throwaway Playwright script). Type is in rem and em in packages/components/accordion/accordion.css.
1.4.10 ReflowMeetsaccordion.check.mjs: "at 390 px the open accordion does not scroll sideways" and the same for the playful demo. Manual test at 320 CSS px, three registers, 2026-10-06: no sideways scroll, no element past the viewport.
1.4.11 Non-text contrastMeetsThe marker is drawn in currentColor (quiet) or --sg-accent-text (warm and playful), text roles tested at 4.5:1 on every surface in packages/tokens/tokens.test.js; the hairline between questions is --sg-rule-strong, and the focus ring is --sg-focus, both tested 3:1 or more on every surface for every palette and theme in the same file.
1.4.12 Text spacingMeetsManual test, 2026-10-06: the WCAG text-spacing values (line height 1.5, letter 0.12em, word 0.16em, paragraph spacing 2em) injected on the demo in three registers, no clipped or overlapping text, including the open answer (throwaway Playwright script). No check in the repository asserts it yet.
2.1.1 KeyboardMeetsaccordion.check.mjs: in each register Tab reaches the summary and shows a ring, Enter opens the answer, Space closes it, and opening another with the keyboard closes the first in an exclusive group.
2.1.2 No keyboard trapMeetsManual test: packages/components/accordion/accordion.js binds no key handler and sets no tabindex; the summaries are native and Tab and Shift+Tab pass through them.
2.4.3 Focus orderMeetsaccordion.check.mjs: "Tab reaches the second summary" in each register. Summaries follow the markup order, and nothing in accordion.js moves focus.
2.4.7 Focus visibleMeetsaccordion.check.mjs: "Tab reaches the second summary (N presses) and shows a focus ring" in each register; the rule is summary:focus-visible in packages/components/accordion/accordion.css, and tools/touch.check.mjs requires a focus style on it too.
2.4.11 Focus not obscured (minimum)Meets with author's partManual test: packages/components/accordion/accordion.css has no position: fixed or sticky, so the component covers nothing. A sticky header or banner the page adds can cover a summary that scrolls into view.
2.5.3 Label in nameMeetsThe summary's accessible name is its visible text, because the component adds no aria-label; the marker is generated content and does not change it (packages/components/accordion/accordion.js sets no ARIA).
2.5.8 Target size (minimum)MeetsEach summary is the full width of the accordion and at least 3.25rem (52 px at 16 px type) tall (min-height in packages/components/accordion/accordion.css). Manual test, 2026-10-06: no focusable control under 24 by 24 CSS px at 1280 px or at 390 px with touch, in all three registers (throwaway Playwright script).
4.1.2 Name, role, valueMeetsNative <details> and <summary> give the name, the button role and the expanded state with no ARIA. accordion.check.mjs: axe with 0 violations in light and dark, in each register, and on the page without JavaScript.

The page author owns:

  • The question and answer text, in the language of the page.
  • lang on a question or answer in another language (3.1.2).
  • Alt text for images and the semantics of lists, links or headings put inside an answer.
  • Sticky headers or banners that could cover a summary when it takes focus (2.4.11).
  • The colours the page sets behind the accordion, if it overrides the tokens.

How it behaves

  • No ARIA: <details> and <summary> already say everything. Adding role or aria-expanded here would only be noise.
  • The drawn markers and the open rule are decoration on a pseudo-element; they carry no meaning and sit outside the accessibility tree.
  • The focus ring is visible on every register, and the summary is reachable in the tab order in the order the questions are written.
  • At phone width nothing scrolls sideways; the answer wraps inside the measure.

All 57 tables, and how the library tests

Pure core

accordion.core.js runs in Node with no DOM: groupsOf(items) and namedGroups(items) for the exclusive groups, resolveOpen(items) for which items should start open (the first of each named group, the rest closed, each with a warning), describeItems(items) for the open account ({ total, open, exclusive, groups }), and othersToClose(items, index) for what one turn of a named item closes. An item is { name, open, label }. Build steps and tests use these; the element uses describeItems.