Merge pull request Pulsefy#993 from zhero-o/feat/766-frontend-a11y-ci-checks

feat(frontend): add automated a11y checks to CI (Pulsefy#766)

Author: Cedarich

.github/workflows/frontend-ci.yml

@@ -52,10 +52,17 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      # Node 22, not 20: jsdom@30 bundles undici@8, whose CacheStorage
+      # constructor calls the node:worker_threads `markAsUncloneable` builtin
+      # unconditionally (no feature-detection/fallback). That builtin only
+      # landed in Node 20.13.0/21.7.0, and CI's Node 20 install predates it,
+      # so any jsdom-environment test (e.g. the a11y suite below) crashed
+      # with "webidl.util.markAsUncloneable is not a function" the moment
+      # jsdom instantiated its Cache API. Node 22 carries it.
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
           cache-dependency-path: app/frontend/package-lock.json
 
@@ -93,6 +100,14 @@ jobs:
         working-directory: ./app/frontend
         run: npm test || npx vitest run
 
+      # #766: automated axe-core a11y audit of the QR/payment components
+      # (generator, pay page, payment states, QR preview). Run as its own
+      # step, like the i18n parity check above, so it isn't silently skipped
+      # by the wider unit test suite.
+      - name: Run accessibility (a11y) checks
+        working-directory: ./app/frontend
+        run: npx vitest run __tests__/a11y-payment-flow.test.tsx
+
   build:
     name: Build Frontend
     runs-on: ubuntu-latest

.github/workflows/frontend-e2e.yml

@@ -53,6 +53,8 @@ jobs:
         working-directory: ./e2e
         run: npx playwright install --with-deps chromium
 
+      # Runs every spec under e2e/tests, including a11y-pay-flow.spec.ts
+      # (#766: axe-core audit of the generator and pay pages).
       - name: Run pay → receipt E2E
         if: steps.preview.outputs.configured == 'true'
         working-directory: ./e2e

CONTRIBUTING.md

@@ -66,6 +66,14 @@ If you prefer to set up the environment manually on your host machine:
 - Follow the [Conventional Commits](https://www.conventionalcommits.org/) style.
 - Add/Update documentation as needed.
 
+## Accessibility
+
+The frontend is checked in CI with `eslint-plugin-jsx-a11y` (errors on the
+QR/payment flow, warnings elsewhere) and `jest-axe`/`axe-core` audits of the
+payment link generator, pay page, and payment-state components — see
+[app/frontend/CONTRIBUTING.md](app/frontend/CONTRIBUTING.md#accessibility)
+for the checklist to follow when touching UI.
+
 ## 8-Week MVP Roadmap & Feature Prioritization
 
 See [docs/MVP-ROADMAP.md](docs/MVP-ROADMAP.md) for the full roadmap and priorities.

app/frontend/CONTRIBUTING.md

@@ -23,3 +23,37 @@ Thank you for your interest in contributing to the QuickEx frontend!
 - Follow the **vibrant dark theme** (neutral-950 background, indigo-500 accents).
 - Ensure all interactive elements have hover and focus states.
 - Maintain a **premium, clean aesthetic** with consistent spacing and typography.
+
+## Accessibility
+
+Payments and QR flows are how money moves, so a user relying on a screen
+reader or keyboard must be able to complete them. When you touch UI code:
+
+- Every interactive element (buttons, links, form controls) needs an
+  accessible name — visible text, `aria-label`, or a `<label>` properly
+  associated with its control (`htmlFor`/`id`, or nesting where the control
+  is directly inside the `<label>`).
+- Decorative icons/SVGs get `aria-hidden="true"`; icons that convey meaning
+  on their own need an accessible label.
+- Custom interactive elements (a `<div>` with `onClick`) need a real
+  `role`, `tabIndex`, and keyboard handlers, or — preferably — should just
+  be a `<button>`.
+- Don't rely on color alone to convey state (error/success/expired); pair
+  it with text or an icon.
+- Preserve `focus-visible` ring styles on interactive elements; don't
+  suppress the browser's default focus outline without replacing it.
+
+**Enforcement**: `eslint-plugin-jsx-a11y` runs in CI. It's a hard error
+(`--max-warnings 0`) for the QR/payment flow — `src/app/generator/**`,
+`src/app/pay/**`, `src/components/payment-states/**`,
+`src/components/QRPreview.tsx`, `src/components/SigningSummary.tsx` — see
+`eslint.config.mjs`. It's a warning elsewhere while the rest of the app
+catches up; please still fix what you touch. `__tests__/a11y-payment-flow.test.tsx`
+runs a `jest-axe` audit over the same components, and
+`e2e/tests/a11y-pay-flow.spec.ts` runs an `axe-core` audit against the live
+generator and pay pages (gated on `PREVIEW_BASE_URL`, same as the
+pay-to-receipt E2E). Run them locally with:
+
+```bash
+npx vitest run __tests__/a11y-payment-flow.test.tsx
+```

app/frontend/__tests__/a11y-payment-flow.test.tsx

@@ -0,0 +1,102 @@
+// @vitest-environment jsdom
+//
+// Automated accessibility checks for the QR/payment flow (#766). These
+// components render the pay-to-receipt path exercised by
+// e2e/tests/pay-to-receipt.spec.ts, so an axe violation here means a real
+// user relying on a screen reader or keyboard could get stuck paying or
+// receiving a payment.
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import { axe, toHaveNoViolations } from "jest-axe";
+import { QRPreview } from "@/components/QRPreview";
+import { SigningSummary } from "@/components/SigningSummary";
+import { ActivePaymentState } from "@/components/payment-states/ActivePaymentState";
+import { PaidPaymentState } from "@/components/payment-states/PaidPaymentState";
+import { ExpiredPaymentState } from "@/components/payment-states/ExpiredPaymentState";
+import { RefundedPaymentState } from "@/components/payment-states/RefundedPaymentState";
+
+expect.extend(toHaveNoViolations);
+
+const activeStatus = {
+  username: "alice",
+  amount: "100",
+  asset: "USDC",
+  memo: null,
+  destinationPublicKey: "GABC1234567890",
+  expiresAt: null,
+  swapOptions: null,
+  acceptsMultipleAssets: false,
+  acceptedAssets: null,
+  userMessage: "Complete this payment to alice.",
+  availableActions: ["pay"],
+};
+
+const paidStatus = {
+  username: "alice",
+  amount: "100",
+  asset: "USDC",
+  memo: null,
+  transactionHash: "abc123",
+  paidAt: new Date().toISOString(),
+  userMessage: "Payment received.",
+};
+
+const expiredStatus = {
+  username: "alice",
+  amount: "100",
+  asset: "USDC",
+  memo: null,
+  expiresAt: new Date().toISOString(),
+  userMessage: "This link has expired.",
+};
+
+describe("QR/payment flow accessibility", () => {
+  it("QRPreview with a value has no axe violations", async () => {
+    const { container } = render(<QRPreview value="stellar:GABC?amount=100" />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("QRPreview placeholder (no value) has no axe violations", async () => {
+    const { container } = render(<QRPreview />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("SigningSummary has no axe violations", async () => {
+    const { container } = render(
+      <SigningSummary
+        action="purchase"
+        amount={{ value: 100, asset: "USDC" }}
+        details={[{ label: "Recipient", value: "alice" }]}
+        expiry={new Date(Date.now() + 60_000)}
+        fee={{ value: 1, asset: "USDC", percentage: 1 }}
+      />,
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("ActivePaymentState has no axe violations", async () => {
+    const { container } = render(
+      <ActivePaymentState
+        status={activeStatus}
+        onPaymentInitiated={() => {}}
+        onPaymentCompleted={() => {}}
+      />,
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("PaidPaymentState has no axe violations", async () => {
+    const { container } = render(<PaidPaymentState status={paidStatus} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("ExpiredPaymentState has no axe violations", async () => {
+    const { container } = render(<ExpiredPaymentState status={expiredStatus} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("RefundedPaymentState has no axe violations", async () => {
+    const { container } = render(<RefundedPaymentState status={paidStatus} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

app/frontend/eslint.config.mjs

@@ -1,6 +1,7 @@
 import { dirname } from "path";
 import { fileURLToPath } from "url";
 import { FlatCompat } from "@eslint/eslintrc";
+import jsxA11y from "eslint-plugin-jsx-a11y";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -9,8 +10,27 @@ const compat = new FlatCompat({
   baseDirectory: __dirname,
 });
 
+// Payment/QR flows carry real deployment and money-movement risk (#766), so
+// a11y rules are enforced there first as CI-breaking errors. The rest of the
+// app isn't covered yet — enabling jsx-a11y repo-wide under the existing
+// `--max-warnings 0` gate would fail CI on unrelated pre-existing findings;
+// widen this list as those get addressed.
+const paymentFlowGlobs = [
+  "src/app/generator/**/*.{ts,tsx}",
+  "src/app/pay/**/*.{ts,tsx}",
+  "src/components/payment-states/**/*.{ts,tsx}",
+  "src/components/QRPreview.tsx",
+  "src/components/SigningSummary.tsx",
+];
+
 const eslintConfig = [
   ...compat.extends("next/core-web-vitals", "next/typescript"),
+  {
+    // next/core-web-vitals already registers the jsx-a11y plugin, so this
+    // override only sets rule severities and must not redeclare `plugins`.
+    files: paymentFlowGlobs,
+    rules: jsxA11y.flatConfigs.recommended.rules,
+  },
   {
     ignores: [
       "node_modules/**",