Automated WCAG 2.1 AA a11y testing across all themes/modes

.changeset/badge-link-primary-strong.md

@@ -0,0 +1,6 @@
+---
+'@surfnet/curve-react': patch
+'@surfnet/curve-angular': patch
+---
+
+Use `--primary-strong` for link-style text (Badge `link`, and inline links in Field, Empty, and Item) so it meets contrast on the page background. Filled Primary is unchanged.

.changeset/combobox-trigger-aria.md

@@ -0,0 +1,6 @@
+---
+'@surfnet/curve-angular': patch
+'@surfnet/curve-react': patch
+---
+
+Wire combobox input trigger button `aria-expanded`, `aria-haspopup="listbox"`, and `aria-controls` to the listbox id. Add default `aria-label="Clear"` on the React clear button.

.changeset/command-accessible-label.md

@@ -0,0 +1,5 @@
+---
+'@surfnet/curve-react': patch
+---
+
+Give Command a default accessible label ("Type a command or search...") so cmdk no longer renders an empty visually hidden label.

.changeset/command-empty-live-region.md

@@ -0,0 +1,6 @@
+---
+'@surfnet/curve-angular': patch
+'@surfnet/curve-react': patch
+---
+
+Keep Command empty state mounted in the DOM and announce it with `aria-live="polite"` and `aria-atomic`. Use `role="option"` (`aria-disabled`, `aria-selected="false"`) so the empty message is a valid listbox child, and mark separators as presentational so listboxes only expose `option` / `group` children.

.changeset/command-input-aria-label.md

@@ -0,0 +1,5 @@
+---
+'@surfnet/curve-angular': patch
+---
+
+Forward `aria-label` and `aria-labelledby` from Command Input onto the underlying combobox `<input>` so the accessible name is on the field assistive technology uses, not the wrapper.

.changeset/data-table-action-cell-aria.md

@@ -0,0 +1,5 @@
+---
+'@surfnet/curve-angular': patch
+---
+
+Give the data table action-cell icon button and each menu item accessible names so the icon-only trigger and actions are announced by screen readers.

.changeset/input-otp-aria-label.md

@@ -0,0 +1,5 @@
+---
+'@surfnet/curve-angular': patch
+---
+
+Forward `aria-label` from Input OTP onto the underlying input so unlabeled examples (and consumers) can name the field for assistive technology.

.changeset/input-otp-complete-live-region.md

@@ -0,0 +1,6 @@
+---
+'@surfnet/curve-angular': patch
+'@surfnet/curve-react': patch
+---
+
+Announce Input OTP completion to screen readers with a polite live region so pasting a full code is perceivable.

.changeset/resizable-handle-aria.md

@@ -0,0 +1,5 @@
+---
+'@surfnet/curve-angular': patch
+---
+
+Set `aria-grabbed` and `aria-valuenow` on Resizable handles, and expose an `isDragging` signal on the group and handle.

.changeset/scroll-area-tabindex.md

@@ -0,0 +1,6 @@
+---
+'@surfnet/curve-angular': patch
+'@surfnet/curve-react': patch
+---
+
+Always set `tabindex="0"` on ScrollArea so the scrollable region is keyboard-accessible, including before overflow is measured.

.github/workflows/ci.yml

@@ -13,6 +13,13 @@ concurrency:
 jobs:
   checks:
     runs-on: ubuntu-latest
+    # The a11y steps write a PR comment and push violation screenshots to the
+    # a11y-screenshots branch.
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      PR_NUMBER: ${{ github.event.pull_request.number }}
     steps:
       - uses: actions/checkout@v4
 
@@ -42,3 +49,46 @@ jobs:
       - run: pnpm lint
 
       - run: pnpm build
+
+      # The audit runs @storybook/test-runner, which drives Playwright Chromium
+      # headless (no display needed on CI). Install it once, scoped to
+      # @surfnet/curve-storybook-config which pins playwright, so both framework
+      # runs share one browser.
+      - name: Install Playwright Chromium
+        run: pnpm --filter @surfnet/curve-storybook-config exec playwright install --with-deps chromium
+
+      # Headless axe sweep of every story across all themes/modes. Fast: the
+      # test phase is a few seconds per framework once Storybook is built (the
+      # build-storybook step dominates). Report-only for now; flip to blocking by
+      # removing `continue-on-error`.
+      - name: Accessibility audit (WCAG 2.1 AA)
+        continue-on-error: true
+        run: pnpm test:a11y
+
+      - name: Upload a11y reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: a11y-reports
+          path: packages/*/.a11y-report/**
+          if-no-files-found: ignore
+
+      # Pushes violating-element screenshots to the `a11y-screenshots` branch
+      # so the PR comment below can embed them by raw.githubusercontent.com
+      # URL. PR-only: there's no PR to attach screenshots to on a push build.
+      - name: Publish a11y screenshots
+        if: always() && github.event_name == 'pull_request'
+        run: ./scripts/publish-a11y-screenshots.sh
+
+      # Summarise the JSON reports into .a11y-report/comment.md.
+      - name: Summarise a11y findings
+        if: always()
+        run: pnpm exec jiti scripts/a11y-comment.ts
+
+      # One sticky comment, updated in place.
+      - name: Comment a11y findings on PR
+        if: always() && github.event_name == 'pull_request'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: a11y-audit
+          path: .a11y-report/comment.md

.gitignore

@@ -1,31 +1,34 @@
-# dependencies
-node_modules
-.pnpm-store
-
-# secrets
-.env
-.env.local
-
-# build output
-dist
-storybook-static
-
-# turbo
-.turbo
-
-# angular
-.angular
-
-# logs
-*.log
-npm-debug.log*
-pnpm-debug.log*
-
-# editor / os
-.DS_Store
-.vs
-!.vscode
-.vscode/*
-!.vscode/extensions.json
-!.vscode/mcp.json
-.idea
+# dependencies
+node_modules
+.pnpm-store
+
+# secrets
+.env
+.env.local
+
+# build output
+dist
+storybook-static
+
+# accessibility audit reports
+.a11y-report
+
+# turbo
+.turbo
+
+# angular
+.angular
+
+# logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# editor / os
+.DS_Store
+.vs
+\!.vscode
+.vscode/*
+\!.vscode/extensions.json
+\!.vscode/mcp.json
+.idea

docs/decision-log.md

@@ -46,6 +46,7 @@ the replacement.
 | 17  | [Prove it in a real app](#adr-017--prove-it-in-a-real-app)                                                           | Proposed | 2026-06-30 |
 | 18  | [Relative imports for vendored helm cross-references](#adr-018--relative-imports-for-vendored-helm-cross-references) | Accepted | 2026-07-01 |
 | 19  | [Only add components available in both frameworks](#adr-019--only-add-components-available-in-both-frameworks)       | Accepted | 2026-07-13 |
+| 20  | [Keep Command off Storybook until we use it](#adr-020--keep-command-off-storybook-until-we-use-it)                   | Accepted | 2026-09-01 |
 
 ### Open questions (not yet decided)
 
@@ -452,3 +453,32 @@ here than let per-framework drift creep in one component at a time.
 - **Typography** — decide whether this becomes a real component (e.g. `Heading`/`Text`
   wrapper components with contract-enforced size/weight scales) or stays documentation-only
   (a Storybook foundations page, like the existing Design Tokens stories) before building it.
+
+---
+
+## ADR-020 — Keep Command off Storybook until we use it
+
+**Status:** Accepted · **Date:** 2026-09-01
+
+**Context.** Command is vendored in both frameworks (`@surfnet/curve-react` and
+`@surfnet/curve-angular`) because shadcn and Spartan ship it as a primitive. We don't
+intend to offer it as a public, documented component yet — there is no product use for
+a command palette — but ADR-016/013 would otherwise require a Storybook story for every
+shipped component. Leaving those stories in place surfaces Command in the catalog and
+the a11y audit as if it were ready for consumers.
+
+**Decision.** Keep the Command **implementation** in both packages (and still export it),
+but **do not document it in Storybook**. The React and Angular story files were removed
+so Command stays out of the sidebar, Docs, and the a11y sweep.
+
+**Rationale.** Storybook is the living catalog (ADR-013). Showing a component we are not
+ready to stand behind is more confusing than keeping the code "under water" until there
+is a real use. Deleting stories rather than deleting the component avoids re-vendoring
+later.
+
+**Consequences.** Command is an explicit exception to "every component gets a story"
+(ADR-016). Bring it back when we decide to use it: restore
+`packages/react/src/components/ui/command/command.stories.tsx` and
+`packages/angular/src/lib/ui/command/src/lib/hlm-command.stories.ts` (git history has the
+last versions), covering the full surface the way the other components do. Until then,
+treat Command as internal plumbing, not a documented Curve component.

package.json

@@ -14,6 +14,7 @@
     "storybook": "turbo run storybook",
     "build-storybook": "turbo run build-storybook",
     "lint": "turbo run lint",
+    "test:a11y": "turbo run test:a11y:ci",
     "format": "prettier --write \"**/*.{ts,tsx,js,mjs,cjs,json,md,css,html}\"",
     "format:check": "prettier --check \"**/*.{ts,tsx,js,mjs,cjs,json,md,css,html}\"",
     "changeset": "changeset",

packages/angular/.storybook/preview.ts

@@ -1,4 +1,5 @@
 import {
+  a11yParameters,
   frameworkGlobalTypes,
   frameworkSwitcher,
   sharedParameters,
@@ -16,6 +17,7 @@ export default {
   decorators: [frameworkSwitcher('angular'), themeSwitcher()],
   parameters: {
     ...sharedParameters,
+    ...a11yParameters,
     // Must be a literal (Storybook reads it via static analysis, not
     // execution). Keep in sync with packages/react/.storybook/preview.ts.
     options: {

packages/angular/.storybook/test-runner.ts

@@ -0,0 +1,12 @@
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+import { runStoryA11yAudit } from '@surfnet/curve-storybook-config/test-runner';
+
+// Delegate to the shared audit so React and Angular stay in lockstep.
+const config: TestRunnerConfig = {
+  async postVisit(page, context) {
+    await runStoryA11yAudit(page, context);
+  },
+};
+
+export default config;

packages/angular/package.json

@@ -26,7 +26,10 @@
     "lint": "ngc --noEmit -p tsconfig.json",
     "storybook": "ng run angular:storybook",
     "build-storybook": "ng run angular:build-storybook",
-    "fix-helm-imports": "jiti scripts/rewrite-helm-imports.ts"
+    "fix-helm-imports": "jiti scripts/rewrite-helm-imports.ts",
+    "storybook:serve": "http-server storybook-static -p 6007 --silent",
+    "test:a11y": "test-storybook --url http://127.0.0.1:6007 --testTimeout 180000",
+    "test:a11y:ci": "start-server-and-test storybook:serve http://127.0.0.1:6007 test:a11y"
   },
   "peerDependencies": {
     "@angular/common": "^22.0.0",
@@ -63,15 +66,19 @@
     "@storybook/addon-a11y": "10.4.5",
     "@storybook/addon-docs": "10.4.5",
     "@storybook/angular": "10.4.5",
+    "@storybook/test-runner": "0.24.4",
     "@surfnet/curve-contracts": "workspace:*",
     "@surfnet/curve-storybook-config": "workspace:*",
     "@surfnet/curve-tokens": "workspace:*",
     "@surfnet/curve-typescript-config": "workspace:*",
     "@tailwindcss/cli": "4.3.1",
     "@tailwindcss/postcss": "4.3.1",
+    "axe-playwright": "2.2.2",
+    "http-server": "14.1.1",
     "jiti": "2.7.0",
     "ng-packagr": "22.0.0",
     "rxjs": "7.8.2",
+    "start-server-and-test": "3.0.11",
     "storybook": "10.4.5",
     "tailwindcss": "4.3.1",
     "tw-animate-css": "1.4.0",

packages/angular/src/lib/ui/badge/src/lib/hlm-badge.ts

@@ -10,7 +10,7 @@ const badgeVariantClasses = {
     'bg-destructive/10 [a]:hover:bg-destructive/20 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 text-destructive dark:bg-destructive/20',
   outline: 'border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground',
   ghost: 'hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50',
-  link: 'text-primary underline-offset-4 hover:underline',
+  link: 'text-primary-strong underline-offset-4 hover:underline',
 } satisfies Record<BadgeVariantName, string>;
 
 const badgeVariants = cva(

packages/angular/src/lib/ui/breadcrumb/src/lib/hlm-breadcrumb-ellipsis.ts

@@ -11,14 +11,8 @@ import type { ClassValue } from 'clsx';
   providers: [provideIcons({ phosphorDotsThree })],
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: `
-    <span
-      data-slot="breadcrumb-ellipsis"
-      role="presentation"
-      aria-hidden="true"
-      [class]="_computedClass()"
-    >
+    <span data-slot="breadcrumb-ellipsis" aria-hidden="true" [class]="_computedClass()">
       <ng-icon hlm size="sm" name="phosphorDotsThree" />
-      <span class="sr-only">{{ srOnlyText() }}</span>
     </span>
   `,
 })

packages/angular/src/lib/ui/breadcrumb/src/lib/hlm-breadcrumb.ts

@@ -9,5 +9,5 @@ import { Directive, input } from '@angular/core';
   },
 })
 export class HlmBreadcrumb {
-  public readonly ariaLabel = input<string>('breadcrumb', { alias: 'aria-label' });
+  public readonly ariaLabel = input<string>('You are here: ', { alias: 'aria-label' });
 }

packages/angular/src/lib/ui/checkbox/src/lib/hlm-checkbox.stories.ts

@@ -30,7 +30,7 @@ export const Default: Story = {
   render: (args) => ({
     props: args,
     template: `
-			<hlm-checkbox inputId="testCheckbox" checked [disabled]="disabled" />
+			<hlm-checkbox inputId="testCheckbox" checked [disabled]="disabled" aria-label="Checkbox" />
 		`,
   }),
 };

packages/angular/src/lib/ui/combobox/src/lib/hlm-combobox-chip.ts

@@ -17,7 +17,7 @@ import { HlmComboboxChipRemove } from './hlm-combobox-chip-remove';
     <ng-content />
 
     @if (showRemove()) {
-      <button hlmComboboxChipRemove>
+      <button hlmComboboxChipRemove aria-label="Remove">
         <ng-icon name="phosphorX" />
       </button>
     }

packages/angular/src/lib/ui/combobox/src/lib/hlm-combobox-input.ts

@@ -2,8 +2,13 @@ import { BooleanInput } from '@angular/cdk/coercion';
 import { booleanAttribute, ChangeDetectionStrategy, Component, input } from '@angular/core';
 import { NgIcon, provideIcons } from '@ng-icons/core';
 import { phosphorCaretDown, phosphorX } from '@ng-icons/phosphor-icons/regular';
-import { BrnComboboxImports, BrnComboboxPopoverTrigger } from '@spartan-ng/brain/combobox';
+import {
+  BrnComboboxImports,
+  BrnComboboxPopoverTrigger,
+  injectBrnComboboxBase,
+} from '@spartan-ng/brain/combobox';
 import { HlmInputGroupImports } from '../../../input-group/src';
+import { injectHlmComboboxListboxId } from './hlm-combobox-listbox-id';
 
 @Component({
   selector: 'hlm-combobox-input',
@@ -26,9 +31,13 @@ import { HlmInputGroupImports } from '../../../input-group/src';
       <hlm-input-group-addon align="inline-end">
         @if (showTrigger()) {
           <button
+            aria-label="Open combobox"
+            aria-haspopup="listbox"
             brnComboboxPopoverTrigger
             hlmInputGroupButton
             data-slot="input-group-button"
+            [attr.aria-expanded]="_isExpanded() ? 'true' : 'false'"
+            [attr.aria-controls]="_listboxId"
             [disabled]="comboboxInput.disabled()"
             size="icon-xs"
             variant="ghost"
@@ -46,6 +55,7 @@ import { HlmInputGroupImports } from '../../../input-group/src';
             [disabled]="comboboxInput.disabled()"
             size="icon-xs"
             variant="ghost"
+            aria-label="Clear"
           >
             <ng-icon name="phosphorX" />
           </button>
@@ -59,6 +69,10 @@ import { HlmInputGroupImports } from '../../../input-group/src';
 export class HlmComboboxInput {
   private static _id = 0;
 
+  private readonly _combobox = injectBrnComboboxBase();
+  protected readonly _listboxId = injectHlmComboboxListboxId();
+  protected readonly _isExpanded = this._combobox.isExpanded;
+
   public readonly inputId = input<string>(`hlm-combobox-input-${HlmComboboxInput._id++}`);
   public readonly placeholder = input<string>('');