Automated WCAG 2.1 AA a11y testing across all themes/modes

.agents/skills/add-component/SKILL.md

@@ -6,7 +6,12 @@ description: Use when adding, scaffolding, or vendoring a component into the des
 # Add a component
 
 The design system ships components per framework. Decide the scope first, then follow the
-matching playbook(s) in this skill's subfiles:
+matching playbook(s) in this skill's subfiles.
+
+**Already in the repo?** Do not re-run this add flow. Use
+[`update-component`](../update-component/SKILL.md) so Curve design and accessibility
+edits are merged, not overwritten. Changes can have an effect on accessibility —
+see that playbook before restyling or re-vendoring.
 
 - **React only** → follow [`react.md`](react.md) (shadcn/Base UI flow for `@surfnet/curve-react`).
 - **Angular only** → follow [`angular.md`](angular.md) (Spartan flow for `@surfnet/curve-angular`).

.agents/skills/add-component/angular.md

@@ -117,6 +117,13 @@ pnpm format
   the contract object.
 - `pnpm build`, `pnpm format`, and `build-storybook` all pass.
 
+## Updating an existing component
+
+Do not re-run `ng g @spartan-ng/cli:ui` on a component that is already vendored
+— the generator overwrites helm. Follow
+[`update-component/angular.md`](../update-component/angular.md). Restyling or
+merging upstream can have an effect on accessibility.
+
 ## Notes
 
 - The Spartan CLI always vendors cross-component imports through the `@spartan-ng/helm/*`

.agents/skills/add-component/react.md

@@ -136,6 +136,12 @@ pnpm format
   the contract object.
 - `pnpm build`, `pnpm lint`, `pnpm format`, and `build-storybook` all pass.
 
+## Updating an existing component
+
+Do not re-run `shadcn add` (or `--overwrite`) on a component that is already
+vendored. Follow [`update-component/react.md`](../update-component/react.md).
+Restyling or merging upstream can have an effect on accessibility.
+
 ## Notes
 
 - Icons: import from `@phosphor-icons/react` (components are suffixed `Icon`, e.g.

.agents/skills/update-component/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: update-component
+description: >-
+  Merge upstream shadcn or Spartan changes into an already-vendored Curve
+  component without overwriting local design or accessibility edits. Use when
+  updating, upgrading, re-vendoring, re-adding, or refreshing an existing
+  component; when running shadcn add or ng g on a component that is already in
+  the repo; or when preserving CURVE customizations against upstream.
+---
+
+# Update a component
+
+Use this playbook for a component that **already lives in the repo**. For a
+component that is not vendored yet, use [`add-component`](../add-component/SKILL.md)
+instead.
+
+- **React only** → [`react.md`](react.md) (`@surfnet/curve-react` / shadcn).
+- **Angular only** → [`angular.md`](angular.md) (`@surfnet/curve-angular` / Spartan).
+- **Both** → do each playbook, then keep variants, sizes, stories, and a11y
+  behaviour in parity.
+
+**Never treat a re-vendor as an install.** The CLIs copy source into the package;
+running them again on an existing component can wipe Curve edits. Git is the
+source of truth. Diff, then merge.
+
+## Accessibility
+
+**Changes can have an effect on accessibility.** Styling, markup, ARIA, focus
+order, contrast, and keyboard behaviour are coupled. A visual tweak (hiding a
+label, restyling a focus ring, swapping an icon-only control, changing
+hover-only state) can make the component unusable with a keyboard or screen
+reader. An upstream merge can silently drop a Curve a11y fix.
+
+Before you finish any update or local edit:
+
+1. Re-read the component as assistive tech would: name, role, state, keyboard
+   path, visible focus, contrast.
+2. Check the Storybook **Accessibility** addon (`@storybook/addon-a11y`) on the
+   Playground and on state stories (disabled, invalid, open, icon-only).
+3. Keep or update story tags: `a11y-gap` (known WCAG gap) and `a11y-minor`
+   (smaller concern). They come from the shared config in
+   `@surfnet/curve-storybook-config`. If you **fix** an issue, remove or
+   downgrade the tag. If you **confirm** or **introduce** one, add the matching
+   tag. Do not drop these tags during a merge “to match upstream.”
+4. Prefer putting durable a11y fixes in markup / ARIA / Brain-adjacent helm
+   behaviour, and covering them with a story or test so a later re-vendor
+   fails loudly.
+
+## Where to put the change
+
+| Kind of change | Put it here | Survives a re-vendor? |
+| --- | --- | --- |
+| Color, radius, type, spacing | Tokens (`packages/tokens`) + `@theme` mapping | Yes |
+| Variant / size / axis **names** | `@surfnet/curve-contracts` + `satisfies` on both frameworks | Compile error if upstream reintroduces a stray name |
+| Extra look on top of upstream | Compose via `cn()` / `hlm()`, keep the extra classes Curve-owned | Only if you re-apply them in the merge |
+| Missing `aria-*`, roles, focus, names, keyboard | Vendored TS / templates (helm, not Brain) | No — mark with `CURVE:` and cover with a story/test |
+| Headless behaviour (Angular) | Stay on `@spartan-ng/brain` via npm. Do **not** edit `node_modules`. Compensate in helm or wrap. | Brain updates with `pnpm update` + `healthcheck` |
+
+Design that only exists as “we rewrote 40 Tailwind classes in the vendored
+file” will fight every upstream update. Design that lives in tokens will not.
+
+## Mark Curve deviations
+
+Every intentional difference from upstream gets a durable marker next to the
+code, so a `--diff` / `git diff` review can keep it:
+
+```ts
+// CURVE: a11y — icon-only buttons need an accessible name (do not drop on re-vendor)
+// CURVE: design — focus ring uses ring-offset-background to match tokens
+```
+
+Use `a11y` or `design` (or both) and a short why. Same idea in `cva` maps and
+Angular templates (`<!-- CURVE: a11y — … -->`).
+
+Audit markers with:
+
+```bash
+rg "CURVE:" packages/react/src/components/ui packages/angular/src/lib/ui
+```
+
+Do **not** add a `CURVE:` comment for contract `satisfies` wiring, barrels,
+stories, or `fix-helm-imports` rewrites — those are standard Curve scaffolding,
+not deviations.
+
+## Hard rules (agents and humans)
+
+1. **Do not** run `shadcn add --overwrite`, `shadcn add --all`, or
+   `ng g @spartan-ng/cli:ui` on an existing component as a refresh. Follow the
+   per-framework playbook.
+2. **Do not** use the shadcn MCP `add` tool to update an existing component — it
+   writes files flat and skips the `--path` layout.
+3. Preserve every `CURVE:` hunk unless the user explicitly drops that
+   customization. Preserve contract `satisfies` / `*Name` typing.
+4. After Angular helm is regenerated, run
+   `pnpm --filter @surfnet/curve-angular fix-helm-imports` and confirm `dist`
+   has no `@spartan-ng/helm` imports.
+5. Stop and ask if the upstream diff is large, renames the public API, or
+   disagrees with the contract.
+
+## After both frameworks (parity)
+
+If the component exists in both packages, confirm after the merge:
+
+- Variant / size / axis **names** still match the contract (`pnpm lint`).
+- Story names still match across Storybooks.
+- A11y behaviour matches: the same issue is not fixed on one side and left
+  tagged `a11y-gap` on the other without a documented reason.
+
+## Definition of done
+
+- Upstream hunks merged; Curve `CURVE:` edits and contract wiring kept.
+- Story `a11y-gap` / `a11y-minor` tags match the current state.
+- Storybook a11y addon checked for the stories you touched.
+- `pnpm build`, `pnpm lint`, and `pnpm format` pass for the packages you
+  touched; rebuild Storybook if stories changed.
+- A changeset added (`pnpm changeset`) if a publishable package changed.
+- Any React/Angular gap left after the update is documented, not hidden.

.agents/skills/update-component/angular.md

@@ -0,0 +1,124 @@
+# Update an Angular component (`@surfnet/curve-angular`)
+
+Part of the **update-component** skill — see [`SKILL.md`](SKILL.md) for shared
+rules, `CURVE:` markers, and accessibility.
+
+Spartan splits each component in two:
+
+| Layer | Where | How it updates |
+| --- | --- | --- |
+| **Brain** | `@spartan-ng/brain/<name>` in `node_modules` | `pnpm update` + `ng g @spartan-ng/cli:healthcheck --autoFix` |
+| **Helm** | copied into `src/lib/ui/<name>/` | You own it. Re-running the `ui` generator **overwrites** helm. There is no `--diff`. |
+
+Do **not** edit Brain sources. Put accessibility and design fixes in helm (or a
+wrapper). If the bug is in Brain itself, compensate in helm and document the
+gap rather than patching `node_modules`.
+
+## Brain (npm)
+
+After bumping `@spartan-ng/brain` / `@spartan-ng/cli`:
+
+```bash
+cd packages/angular
+pnpm exec ng g @spartan-ng/cli:healthcheck
+pnpm exec ng g @spartan-ng/cli:healthcheck --autoFix
+```
+
+Healthcheck reconciles deprecated Brain APIs. It is not a helm merge. Review
+the diff; keep `CURVE:` helm edits.
+
+## Helm (copied source)
+
+The `ui` generator copies helm into `componentsPath` and may also pull
+**dependent** components. Treat every already-vendored directory it would
+touch as in-scope.
+
+### Steps
+
+1. **Confirm it is already vendored.** If `src/lib/ui/<name>/` does not exist,
+   stop and use [`add-component/angular.md`](../add-component/angular.md).
+
+2. **See what is installed:**
+
+   ```bash
+   cd packages/angular
+   pnpm exec ng g @spartan-ng/cli:info --json
+   ```
+
+3. **Working tree must be clean** for the helm dirs you are about to
+   regenerate (commit or stash Curve work first). You need `HEAD` as “ours.”
+
+4. **Regenerate, then immediately inspect — do not commit the dump:**
+
+   ```bash
+   cd packages/angular
+   pnpm exec ng g @spartan-ng/cli:ui <name> --defaults
+   git diff -- packages/angular/src/lib/ui/<name>/
+   ```
+
+   `git diff` is **ours (HEAD, Curve) vs theirs (new helm)**. Dependent
+   components the generator also copied show up in the same diff — merge those
+   too, or restore them with `git checkout -- <path>` if they were collateral.
+
+5. **Restore ours and merge by hand** (do not leave the generator output as
+   the new source):
+
+   ```bash
+   # keep a copy of theirs, then restore Curve
+   cp -R src/lib/ui/<name> /tmp/curve-helm-<name>-theirs
+   git checkout -- src/lib/ui/<name>
+   ```
+
+   Apply upstream hunks from `/tmp/curve-helm-<name>-theirs` onto the restored
+   Curve files. Keep every `CURVE:` hunk, contract `satisfies` / typed inputs,
+   story files, and Phosphor / `NgIcon` conventions.
+
+6. **Always re-run import rewrite** after any generator write:
+
+   ```bash
+   pnpm --filter @surfnet/curve-angular fix-helm-imports
+   ```
+
+   Confirm the published bundle will not leak the alias:
+
+   ```bash
+   pnpm --filter @surfnet/curve-angular build
+   grep -r "@spartan-ng/helm" packages/angular/dist
+   ```
+
+   (`grep` must print nothing.)
+
+7. **Re-apply Curve scaffolding** the generator does not know about:
+
+   - Contract import + `satisfies Record<*Name, string>` (or typed inputs).
+   - Export from `src/public-api.ts`.
+   - New runtime deps in `ng-package.json` → `allowedNonPeerDependencies`.
+   - Stories still source docs from the contract. Do not let the generator
+     delete `*.stories.ts`.
+
+8. **Accessibility pass** — see [SKILL.md](SKILL.md#accessibility). Check
+   `@storybook/addon-a11y`. Update `a11y-gap` / `a11y-minor` tags if the merge
+   fixed, confirmed, or reintroduced an issue. Put back any dropped
+   `CURVE: a11y` hunks.
+
+There is no approved `--overwrite` equivalent. If the user wants stock Spartan
+helm back, say that explicitly, take the generator output, then still run
+`fix-helm-imports` and re-apply contract wiring / stories / a11y markers.
+
+## Verify
+
+```bash
+pnpm --filter @surfnet/curve-contracts lint
+pnpm --filter @surfnet/curve-angular build
+pnpm format
+```
+
+Rebuild Storybook if stories changed:
+`pnpm --filter @surfnet/curve-angular build-storybook`.
+
+## Notes
+
+- Do not re-vendor `hlm-icon`. Phosphor + `NgIcon` sizing is a Curve
+  convention; see [add-component/angular.md](../add-component/angular.md).
+- Theme CSS lives in `@surfnet/curve-tokens`, not in a `ui-theme` regenerate.
+  Do not run `ui-theme` as part of a component update.

.agents/skills/update-component/react.md

@@ -0,0 +1,84 @@
+# Update a React component (`@surfnet/curve-react`)
+
+Part of the **update-component** skill — see [`SKILL.md`](SKILL.md) for shared
+rules, `CURVE:` markers, and accessibility.
+
+Components are vendored with the shadcn CLI into
+`packages/react/src/components/ui/<name>/`. Updating means a **3-way-style
+merge** of upstream registry source into that folder, not a re-install.
+
+Use the CLI from `packages/react` so `components.json` (Base UI, Phosphor,
+`--path` layout) applies. **Never fetch raw files from GitHub** — the CLI
+resolves the registry and CSS.
+
+## Steps
+
+1. **Confirm it is already vendored.** If `src/components/ui/<name>/` does not
+   exist, stop and use [`add-component/react.md`](../add-component/react.md).
+
+2. **List what the CLI would touch** (no writes):
+
+   ```bash
+   cd packages/react
+   pnpm dlx shadcn@latest add <name> --dry-run
+   ```
+
+   Note sibling files (the CLI may want to update dependencies of this
+   component). Each already-vendored sibling needs the same merge treatment —
+   do not overwrite them as collateral.
+
+3. **Diff each affected file against the local copy:**
+
+   ```bash
+   pnpm dlx shadcn@latest add <name> --diff
+   pnpm dlx shadcn@latest add <name> --diff <file>
+   ```
+
+   `--diff` implies `--dry-run`. Prefer `--diff` on a specific file when the
+   combined output is truncated.
+
+4. **Merge per file:**
+
+   | Diff | Action |
+   | --- | --- |
+   | No local Curve edits (file matches a stock vendor copy aside from standard scaffolding) | Safe to take upstream, then **re-apply** contract `satisfies` / `*Name` typing, the barrel, and story docs sourcing. |
+   | Has `CURVE:` markers or other local edits | Keep those hunks. Apply upstream hunks around them by editing the local file. |
+   | User explicitly wants to discard Curve customizations | Only then `pnpm dlx shadcn@latest add <name> --overwrite`, and say so. Re-apply contract wiring, barrel, and stories afterwards. |
+
+   **Never pass `--overwrite` without explicit approval.**
+
+5. **Re-apply Curve scaffolding the CLI does not know about:**
+
+   - Contract import + `satisfies Record<*Name, string>` (or typed inline-union
+     props) from `@surfnet/curve-contracts`.
+   - `index.ts` barrel and `src/index.ts` export (do not flatten the directory).
+   - Story still sources description / axes from the contract object.
+   - Phosphor icons (`*Icon` from `@phosphor-icons/react`), not whatever
+     upstream defaulted to.
+
+6. **Accessibility pass** — see [SKILL.md](SKILL.md#accessibility). Check
+   `@storybook/addon-a11y` on the component stories. Update `a11y-gap` /
+   `a11y-minor` tags if the merge fixed, confirmed, or reintroduced an issue.
+   If upstream dropped a `CURVE: a11y` hunk, put it back.
+
+## Verify
+
+```bash
+pnpm --filter @surfnet/curve-contracts lint
+pnpm --filter @surfnet/curve-react lint
+pnpm --filter @surfnet/curve-react build
+pnpm format
+```
+
+Rebuild Storybook if stories changed:
+`pnpm --filter @surfnet/curve-react build-storybook`.
+
+## Notes
+
+- The published `styles.css` is compiled Tailwind. Consumers do not need to
+  re-run shadcn; only this package's source merge changes what they get after
+  the next Curve release.
+- CSS entry updates (`src/index.css`, `@theme`) from `--diff globals.css` /
+  the dry-run CSS section: take token mappings only when they are new Curve
+  needs. **Do not** paste shadcn's `:root` / `.dark` blocks — tokens come from
+  `@surfnet/curve-tokens`.

.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.