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

Person card

One person and what they are building: the name, the role, one line of work and one link. The card shows the person's initials, cut from their name by a pure core, instead of a photo; a photo belongs there only when the author writes it and the person's consent is recorded.

quiet warm playful

Open the live demo npx @susegad/cli add person-card

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

The prompt

the prompt

Make a person-card web component around an <article>: the person's name as a heading, their role in a few words, one line on what they are building, and one link (their site, a profile or an email) that is a plain link in the markup. With no photo, show the person's initials instead: a pure function initialsOf(name) cuts them from the heading's words (first and last word, one initial for a single name, middle names skipped, edge spaces trimmed, empty when the name has no letters), and the element draws them in an aria-hidden disc so the heading is read as usual. There is no photo by default, and the component never fetches one; a photo appears only when the author writes img.sg-person-photo inside the article, with that person's consent recorded, and then the disc steps aside. Give it three registers as lazy skins. Quiet: a hairline card, the initials in a plain disc. Warm: a soft card with a wash at the top and the initials in the hand. Playful: a disc coloured from a seeded hue, and a small seeded tilt that arrives when the pointer or the keyboard focus arrives and settles back; nothing loops, and under reduced motion nothing moves.

Words to code

When you sayTechniqueWhat happens
initials instead of photospure coreinitialsOf('Sarita Fernandes') is "SF": the first letter of the first and last word that has letters, one for a single name, middle names skipped, "" for a name with no letters. Runs in Node, no DOM.
the initials disc is added by the elementone owner#disc() writes the initials from the heading into span.sg-person-initials, aria-hidden, once, so author and element cannot disagree.
no photo until consenthonestyThe element never fetches or builds an image. Only img.sg-person-photo written by the author shows one; the element adds data-photo, removes the disc, and fills a missing alt from the name.
a seeded tilt, a seeded huetiltOf(seed), hueOf(seed)0.4 to 1.4 degrees, sign seeded, set once as --sg-person-tilt; hue 0 to 359 as --sg-person-hue. Same seed, same card, every time.
the tilt arrives on hover or focus ... settles backCSS onlyOn :hover or :focus-within, rotate: var(--sg-person-tilt) with the spring ease, once; the rest state is flat. Reduced motion keeps it flat. No loops, no timers.
one link, from the markupslotThe element never writes a link. The <a> in p.sg-person-link is yours.
the directory reads the trackattributedata-track on the card; filterPeople(people, { q, tracks }) in the pure core does the matching for the member-directory recipe.

Accessibility

  • An <article> named by its heading (the person's name).
  • The initials disc is aria-hidden; the person is read as their name, not as letters.
  • The link takes Tab and shows a 2 px focus ring.
  • The tilt is decoration; no meaning is carried by motion.
  • Without JavaScript the written markup shows in full: name, role, work, link.

<sg-person-card> is one person, and what they are building. It enhances an <article>.

Markup

ElementWhat it is
a heading (h2 to h4)the person's name; the article is named by it, and the initials are cut from the same words
p.sg-person-roletheir role in a few words ("Teacher, Aldona")
p.sg-person-buildingone line on what they are building
p.sg-person-linkone link: their site, a profile or an email. The card never writes a link.
img.sg-person-photooptional, and only with that person's consent (see below). Written by you; it takes the disc's slot exactly.

The initials, not a photo

By default the card shows no photo. The element adds an aria-hidden disc with the person's initials, cut from the heading by initialsOf(name) in person.core.js: first and last word ("Sarita Fernandes" gives "SF"), one initial for a single name, middle names skipped, edge spaces trimmed, "" when the name has no letters at all (the disc is then plain, and the heading is read as usual).

A photo goes on the card only when the person gave it and their consent is recorded wherever you keep such things. Put the <img class="sg-person-photo" alt="…"> inside the article yourself; the element notices it and takes the disc away. The card never fetches a photo of its own, and nothing here implies consent.

Attributes

AttributeValuesDefault
data-trackone of the project's tracks ("AI for Kids", "Tech for Good", ...)none; the member-directory recipe reads it
seedthe playful disc's colour and the card's tiltthe name
registerquiet, warm, playfulinherited

Event: sg-person-ready when the disc is first drawn.

Registers

Look
quieta hairline card, the initials in a plain disc
warma soft card with a wash at the top, the initials in the hand
playfula colour disc, its hue seeded, the name in the hand, and a small seeded tilt that arrives on hover or focus and settles back

Reduced motion keeps every register still.

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 2
CriterionStatusHow it was checked
1.1.1 Non-text contentMeetsThe initials disc is aria-hidden and the heading is read as words: packages/components/person-card/person-card.check.mjs, "the disc is not in the accessibility tree (aria-hidden), so the heading is read as words". A photo needs the author's alt; the element only fills a missing one with "<name>'s photo" ("a photo without alt gets one filled from the name").
1.3.1 Info and relationshipsMeetsAn <article> named by the person's own heading, with the role, the building line and the link as real elements. person-card.check.mjs: "without JavaScript: name, role, building line and link show on every card", and axe without JavaScript: 0 violations.
1.4.1 Use of colorMeetsThe link keeps its underline (packages/components/person-card/person-card.css sets only the offset and thickness); the playful card's seeded hue and tilt are decoration.
1.4.3 Contrast (minimum)MeetsText roles on the page surface: packages/tokens/tokens.test.js ("AA: every text role on every surface is 4.5:1 or more") for every palette and theme; person-card.check.mjs runs axe in light and dark, all three registers: 0 violations.
1.4.4 Resize textMeetsManual test, 2026-10-07: demo with the root font size at 200 percent, three registers, no sideways scroll and nothing clipped (throwaway Playwright script).
1.4.10 ReflowMeetsperson-card.check.mjs: "at 390 px the <register> demo does not scroll sideways". Manual test, 2026-10-07: demo at 320 CSS px, three registers, no sideways scroll (document width 320).
1.4.11 Non-text contrastMeetsThe initials disc is decoration beside the name in words, and the focus ring is tested 3:1 or more on every surface for every palette and theme in packages/tokens/tokens.test.js.
1.4.12 Text spacingMeetsManual test, 2026-10-07: the WCAG text-spacing values (line height 1.5, letter 0.12em, word 0.16em, paragraph 2em) injected on the demo, three registers, no clipped or overlapping text (throwaway Playwright script). No check in the repository asserts it yet.
2.1.1 KeyboardMeetspackages/components/person-card/person-card.check.mjs: "<register>: Tab reaches the link ... and it shows a focus ring" in each register, and "a card with no link puts nothing on Tab (nothing was invented for it)". The card's only control is the author's native link.
2.1.2 No keyboard trapMeetsManual test, 2026-10-07: packages/components/person-card/person-card.js and its skins bind no key handler, set no tabindex and call no focus(), so Tab and Shift+Tab pass through the native links.
2.4.3 Focus orderMeetsManual test, 2026-10-07 (throwaway Playwright script): the person-card demo at 390 px in quiet, warm and playful, Tab pressed through every stop (4 stops in each register, one link per card); each focused control was on screen and not covered (the element at its centre is the control itself) and every stop came after the previous one in document order. The same script on a page with a full-screen fixed layer added reported every stop covered, so it can fail. Each card has at most one stop, so the order is the order of the cards.
2.4.4 Link purpose (in context)Meets with author's partThe link is the author's own link text ("Her notes", packages/components/person-card/person-card.check.mjs: "without JavaScript: name, role, building line and link show on every card"), under the person's heading in the same article. Whether it says enough alone is the author's.
2.4.7 Focus visibleMeetsperson-card.check.mjs: "<register>: Tab reaches the link ... and it shows a focus ring"; tools/touch.check.mjs requires a focus style in each register. A card with no link puts nothing on Tab ("a card with no link puts nothing on Tab").
2.4.11 Focus not obscured (minimum)Meets with author's partpackages/components/person-card/person-card.css has no position: fixed or sticky, so the component never covers a focused control itself. Manual test, 2026-10-07 (throwaway Playwright script): the person-card demo at 390 px in three registers, every Tab stop was on screen and not covered (the element at its centre is the control itself); the same script with a full-screen fixed layer added reported every stop covered, so it can fail.
2.5.3 Label in nameMeetsThe link is named by its own visible text because the component adds no aria-label to it (packages/components/person-card/person-card.js sets none; the aria-labelledby in its header comment is on the article, from the heading).
2.5.8 Target size (minimum)MeetsManual test, 2026-10-07, 390 px touch: the link is 22.0 px tall in quiet and warm (51.4 to 94.4 px wide) and 27.0 px in playful, so quiet and warm are under 24 px. They meet the spacing exception: the nearest other link is 209.1 px away (one card higher or lower), so a 24 px circle on the link touches no other target. A page that packs links or cards closer than 24 px would lose that. No check in the repository asserts target size for the card yet.
4.1.2 Name, role, valueMeetsA native <article> and <a>; person-card.check.mjs: axe with and without JavaScript, 0 violations.

The page author owns:

  • The person's name, role and building line, in the language of the page, and lang on text in another language (3.1.2).

  • A real alt on a photo that carries information.

  • The link's text and where it goes (2.4.4), and the room around the links: cards laid out so two links are never closer than 24 px (2.5.8).

  • The colours the page sets behind the card, if it overrides the tokens.

  • A sticky header or banner that could cover the card's link when it takes focus (2.4.11).

How it behaves

  • The <article> is named by the person's own heading.
  • The initials disc is aria-hidden; the name is read as words, not letters.
  • The link is an ordinary link: it takes Tab and shows a focus ring.
  • A photo needs a real alt you write; the element fills only a missing alt.
  • Without JavaScript the markup you wrote shows in full, in the quiet look.

All 57 tables, and how the library tests