FDIC Design System

Appearance

Accessibility ​

This page is the canonical reference for cross-cutting WCAG 2.2 AA accessibility requirements in the FDIC design system. Every pattern documented here is non-negotiable.

Accessibility requirements

The FDIC design system targets WCAG 2.2 Level AA conformance. These requirements apply across all components, token usage, and content authored within the .prose container. They are not optional refinements — they are compliance baselines.

Token and theme baseline ​

If you use the supported token entrypoints as documented, the design system gives you this baseline:

  • semantic foreground and background tokens are authored with contrast intent across supported light and dark appearance modes
  • focus ring tokens remain visible across supported themes when consumers do not override them
  • status colors are published as semantic token families so meaning does not depend on brand colors
  • component registration warns when the required token runtime stylesheet is missing

Current validation boundary:

  • component-level automated tests disable axe-core's color-contrast rule in happy-dom because that environment does not compute rendered contrast reliably
  • Storybook browser accessibility audits run against every Storybook story in Chromium and fail the test suite on violations
  • browser-based audits now cover color-contrast and other rendered checks that happy-dom cannot verify
  • manual review is still required for page-level composition, downstream overrides, zoom/reflow, and forced-colors scenarios that fall outside the shipped story coverage

Those baseline expectations hold only when consumers stay on the documented token and component customization paths.

What the components handle for you ​

If you use the design system components as documented, you get the following accessibility requirements automatically — no extra work needed:

  • Rules 1-6 (focus rings, skip link, sr-only utility, ARIA on callouts, table wrappers, DPUB-ARIA on footnotes) are built into the components and prose styles. You do not need to add these yourself when using the documented HTML patterns.

You are responsible for:

  • Rule 7 — spelling out abbreviations on first use in your content.
  • Rule 8 — adding screen reader text inside <del> and <ins> elements you author.
  • Rule 9 — not adding custom animations that bypass prefers-reduced-motion.
  • Rule 10 — not overriding component styles in ways that break forced-colors mode.

If you only remember one thing: use the components as documented and write clear content. The system handles the technical accessibility requirements; you handle the content requirements.

Non-negotiable requirements ​

These ten rules govern every element, component, and pattern in the system. Violating any of them is a conformance failure.

  1. Focus rings on all interactive elements

    Every focusable element must use :focus-visible with outline: 2px solid var(--fdic-color-border-input-focus, #38b6ff), outline-offset: 2px, and border-radius: 2px. No exceptions. Never remove or suppress focus indicators.

  2. Skip link

    The first element inside <body> must be a skip link: <a href="#main" class="skip-link sr-only">Skip to content</a>. It becomes visible on focus and bypasses navigation for keyboard users.

  3. .sr-only utility

    Visually hidden text for screen readers uses the clip-rect pattern: position: absolute; width: 1px; height: 1px; clip: rect(0,0,0,0); overflow: hidden. Use this class whenever visual context is insufficient for assistive technology.

  4. ARIA on callouts

    Callout containers require role="note" (or role="status" for the danger variant) and an aria-label matching the variant name. Icon spans must carry aria-hidden="true" to prevent screen readers from announcing decorative SVGs.

  5. Table wrapper

    Tables must be wrapped in .prose-table-wrapper with role="region", a descriptive aria-label, and tabindex="0" for keyboard scrolling. Never apply display: block to the <table> element itself — it destroys screen reader table navigation.

  6. DPUB-ARIA on footnotes

    Inline references use role="doc-noteref". The footnote section uses role="doc-endnotes". Apply role="doc-footnote" to the footnote content within each list item rather than to the <li> itself. Back-links use role="doc-backlink". These roles enable assistive technology to navigate bidirectional footnote references without conflicting with list semantics.

  7. Abbreviation expansion

    Spell out every abbreviation on first use in visible body text: Federal Deposit Insurance Corporation (FDIC). The title attribute alone is not sufficient — screen readers and mobile users may never see it.

  8. Screen reader text for <del> and <ins>

    Include <span class="sr-only">deleted: </span> inside every <del> element and <span class="sr-only">inserted: </span> inside every <ins> element. Screen reader support for these semantics is inconsistent without explicit text.

  9. prefers-reduced-motion

    All animations and transitions must be suppressed when the user prefers reduced motion. Animated highlights (such as the footnote flash) must fall back to a static visual equivalent. Never assume motion is safe.

  10. forced-colors (Windows High Contrast)

    Borders must use system colors (LinkText, ButtonText). Elements that convey meaning via color or background must use forced-color-adjust: none to remain visible. The <ins> element must fall back to underline instead of background color, since backgrounds are stripped in forced-colors mode.

Element-level accessibility guidance ​

Use this reference table when implementing or reviewing individual elements.

Element / PatternRequirementWCAG
HeadingsStrict hierarchy — never skip levels. One <h1> per page. Do not use headings for visual sizing alone.1.3.1
LinksDescriptive text that makes sense out of context. Never use "click here" or "read more."2.4.4
<mark>Surrounding text must convey the significance of the highlight — color alone is not enough. Screen reader support for role="mark" is inconsistent.1.4.1
<blockquote>Use only for quoted content, not visual indentation. Wrap attributions in <footer><cite>.1.3.1
<aside>Functions as an ARIA landmark. When multiple asides appear on a page, each must have a distinct aria-label.1.3.1, 2.4.1
Code blocksAdd tabindex="0" for keyboard-accessible overflow scrolling. Use role="region" and aria-label to provide context.2.1.1
<address>Use only for contact information. Telephone links must use international format (tel:+1-...).1.3.1
ListsAlways use semantic list elements (<ul>, <ol>, <dl>). Never simulate lists with <br> or <div>.1.3.1
Task listsDisabled checkboxes need aria-label. Add role="list" to <ul> for Safari/VoiceOver, which strips list semantics from styled lists.4.1.2, 1.3.1
<output>Has implicit role="status" (ARIA live region). Use the for attribute to associate with input controls.4.1.3
<progress>Must have a visible label. Use aria-label including the current value. Provide a text fallback inside the element for older browsers.4.1.2
<meter>The color bar alone is insufficient — always include a visible text descriptor alongside the meter.1.4.1, 4.1.2
Embedded media<iframe> requires a title attribute. <video> and <audio> require controls. Video must have captions.4.1.2, 1.2.2
ImagesEvery <img> must have an alt attribute. Describe the purpose, not the appearance. Use alt="" for purely decorative images.1.1.1
Color independenceNever use color as the sole means of conveying information. Pair with text, icons, patterns, or other non-color indicators.1.4.1
LanguageSet lang="en" on the <html> element. Mark foreign-language passages with the appropriate lang attribute.3.1.1, 3.1.2

Checklists ​

Use these checklists when adding new styles or components to the design system.

Adding a new element style ​

  1. Scope all rules to .prose — never add unscoped element styles.
  2. Use design tokens with hardcoded fallback values for every color, spacing, and font property.
  3. Add a forced-colors override if the element uses color or background to convey meaning.
  4. Add a print override if background or decoration should be removed on paper.
  5. Add a prefers-reduced-motion override if the element has transitions or animations.
  6. Add a responsive override at 640px if the element's layout changes on small screens.
  7. If the element conveys meaning via color alone, add a non-color alternative (text, icon, pattern, or border).
  8. If screen reader support is inconsistent, document the workaround inline in index.html.

Adding a new component ​

  1. Use .prose-{name} class naming.
  2. Include appropriate ARIA attributes in the documented HTML pattern.
  3. Add forced-colors, print, and prefers-reduced-motion overrides as needed.
  4. Add responsive overrides at 640px if the component's layout changes on small screens.
  5. Hide from print if the component is interactive-only.
  6. Ensure every interactive element within the component has :focus-visible styles using the standard focus ring pattern.
  7. If the component is a landmark element, require aria-label when multiple instances may appear on a single page.
  8. If the component has scrollable overflow, add tabindex="0", role="region", and a descriptive aria-label.
  9. Document the accessibility pattern inline in index.html alongside the visual demo.