@afixt/a11y-calc

An accessible calculator React component styled after the macOS built-in calculator, with basic and scientific modes. Built with accessibility as the primary design constraint.

• Basic mode — standard four-function calculator (add, subtract, multiply, divide, percent, sign toggle)
• Scientific mode — trigonometric, logarithmic, exponential, power, root, and factorial functions, parentheses, constants (π, e), degree/radian toggle, and a "2nd" function key
• Fully accessible — screen reader announcements, keyboard support, ARIA attributes, high-contrast and reduced-motion support
• Themeable — all colors and sizes exposed as CSS custom properties and an optional theme prop

npm install @afixt/a11y-calc

import { Calculator } from '@afixt/a11y-calc';
import '@afixt/a11y-calc/style.css';

// Basic usage
<Calculator />

// Start in scientific mode
<Calculator initialMode="scientific" />

// Custom theme
<Calculator theme={{
  'calc-bg': '#1a1a2e',
  'btn-operator-bg': '#e94560',
  'btn-number-bg': '#16213e',
  'btn-number-text': '#eee',
  'display-bg': '#0f3460',
  'display-text': '#ffffff',
}} />

Every visual property is exposed as a CSS custom property. You can override them globally in CSS or per-instance via the theme prop.

.calculator {
  --calc-bg: #1a1a2e;
  --btn-operator-bg: #e94560;
  --btn-number-bg: #16213e;
}

The calculator also responds to prefers-color-scheme: light, prefers-contrast: more, and prefers-reduced-motion: reduce media queries automatically.

The <Calculator> component targets WCAG 2.2 AA. Accessibility is verified at three layers:

1. @afixt/a11y-assert via Vitest against the rendered component
2. @afixt/a11y-assert via Playwright against the running demo
3. A dedicated accessibility GitHub Actions workflow on every PR

See ADR 0009 for the layering rationale. Known limitations are tracked as issues labeled a11y.

• All buttons are native <button type="button"> elements
• The display uses the <output> element
• The calculator container uses role="application" with aria-roledescription="calculator" to allow keyboard passthrough in screen readers

• Every symbolic button has an explicit aria-label (e.g., ÷ is labeled "Divide", √x is "Square root")
• Active operator buttons have aria-pressed="true"
• A live region (aria-live="polite") announces every action in natural language:
  • Digit press: "5"
  • Operator: "plus"
  • Equals: "5 plus 3 equals 8"
  • Scientific: "square root of 9 equals 3"
  • Error: "Error, cannot divide by zero"
  • Clear: "All cleared, 0"

• Minimum 44px touch targets on all calculator buttons
• Visible focus indicators (never suppressed)
• Light/dark mode support (prefers-color-scheme)
• High contrast support (prefers-contrast: more)
• Reduced motion support (prefers-reduced-motion)
• Font sizes use rem units

git clone https://github.com/AFixt/a11y-calc.git
cd a11y-calc
bash scripts/bootstrap.sh    # installs every external scanner used by the hooks
npm ci

The bootstrap script installs trufflehog, lychee, semgrep, osv-scanner, codeql, dependency-check, and zap via Homebrew on macOS (with Linux/WSL release-binary hints for the rest). First run of dependency-check seeds the NVD mirror (~1 GB, 20–40 min — faster with an NVD API key).

npm run dev            # Start demo dev server (vite)
npm run build          # Type-check and build library (dist/)
npm run build:demo     # Build the demo app (dist-demo/)
npm run preview        # Serve the built demo
npm run lint           # ESLint
npm run typecheck      # tsc --noEmit across all project references
npm test               # Unit tests (vitest)
npm run test:watch     # Tests in watch mode
npm run test:coverage  # Tests with coverage report
npm run test:e2e       # Build demo + run Playwright E2E tests
npm run size           # size-limit budgets
npm run ai:context     # Print project summary (for AI sessions / new contribs)

• npm run check — fast: lint + typecheck + stylelint + markdownlint + format check
• npm run check:ci — CI target: adds tests, build, size, dupes, links, fast security scanners, license allowlist
• npm run check:all — pre-push: full gate including CodeQL and OWASP Dependency-Check

npm run check:all runs automatically on git push via Husky.

1. Run bash scripts/bootstrap.sh and npm ci.
2. Create a branch, commit with Conventional Commits (enforced by commitlint on commit-msg).
3. Husky's pre-commit runs lint-staged + type check on staged files
   • TruffleHog secret scan (see ADR 0012). pre-push runs the full check:all.
4. Open a PR targeting main. CI runs check:ci and the a11y workflow. Scheduled workflows (CodeQL, OWASP Dependency-Check, OWASP ZAP, lychee online) run weekly on main.
5. Non-obvious engineering decisions get an ADR in docs/adr/ — see docs/templates/adr-template.md.

• React + TypeScript
• Vite for bundling
• Vitest + Testing Library for unit tests
• Playwright for E2E tests

MIT