|
| 1 | +; SPDX-License-Identifier: PMPL-1.0-or-later |
| 2 | +; ADJUST.contractile — Accessibility invariants for boj-server |
| 3 | +; "ADJUST" = Accessibility & Digital Justice for Universal Software & Technology |
| 4 | +; |
| 5 | +; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST |
| 6 | +; This file is machine-readable. LLM/SLM agents MUST NOT violate these invariants. |
| 7 | + |
| 8 | +; ── Definitions ────────────────────────────────────────────────── |
| 9 | +; |
| 10 | +; ADJUST (noun/verb) |
| 11 | +; The accessibility contractile. Defines how software must adapt to serve |
| 12 | +; all users regardless of ability, device, or context. Named for the verb |
| 13 | +; "adjust" — to make suitable, to adapt, to accommodate — which is the |
| 14 | +; core action of accessible design. |
| 15 | +; |
| 16 | +; Scope: |
| 17 | +; ADJUST governs all user-facing interfaces: GUI, TUI, CLI, web, mobile, |
| 18 | +; documentation, error messages, and installation flows. It applies to |
| 19 | +; both human users and assistive technologies (screen readers, switch |
| 20 | +; devices, braille displays, voice control). |
| 21 | +; |
| 22 | +; Relationship to other contractiles: |
| 23 | +; - MUST: ADJUST invariants are a subset of MUST — violating ADJUST |
| 24 | +; is a MUST violation. ADJUST exists separately because accessibility |
| 25 | +; rules are numerous enough to warrant their own file, and because |
| 26 | +; LLMs frequently forget accessibility unless explicitly reminded. |
| 27 | +; - TRUST: ADJUST does not affect trust levels. All trust tiers must |
| 28 | +; respect ADJUST invariants equally. |
| 29 | +; - DUST: Deprecating a feature does not exempt it from ADJUST until |
| 30 | +; it is fully removed. Deprecated UI must remain accessible. |
| 31 | +; - INTENT: ADJUST supports the anti-purpose "this software is NOT |
| 32 | +; only for able-bodied users with modern hardware." |
| 33 | +; |
| 34 | +; Standard: WCAG 2.2 Level AA (minimum) |
| 35 | +; https://www.w3.org/WAI/WCAG22/quickref/?levels=aaa |
| 36 | +; |
| 37 | +; Why a separate file: |
| 38 | +; Experience shows LLMs and developers alike treat accessibility as an |
| 39 | +; afterthought. By placing invariants in a contractile that is loaded |
| 40 | +; at session start, we make it structurally impossible to forget. |
| 41 | +; |
| 42 | +; ── End Definitions ────────────────────────────────────────────── |
| 43 | + |
| 44 | +(adjust-contractile |
| 45 | + (version "1.0.0") |
| 46 | + (full-name "Accessibility & Digital Justice for Universal Software & Technology") |
| 47 | + (standard "WCAG-2.2-AA") |
| 48 | + (repo "boj-server") |
| 49 | + |
| 50 | + (invariants |
| 51 | + ; ── Visual ── |
| 52 | + (adjust "colour-contrast-ratio >= 4.5:1 for normal text") |
| 53 | + (adjust "colour-contrast-ratio >= 3:1 for large text (18pt+ or 14pt+ bold)") |
| 54 | + (adjust "no information conveyed by colour alone") |
| 55 | + (adjust "no flashing or strobing content (3 flashes/second max)") |
| 56 | + (adjust "text resizable to 200% without loss of content or function") |
| 57 | + (adjust "focus indicators visible on all interactive elements") |
| 58 | + |
| 59 | + ; ── Keyboard ── |
| 60 | + (adjust "all interactive elements reachable via keyboard (Tab/Shift+Tab)") |
| 61 | + (adjust "no keyboard traps — user can always Tab away") |
| 62 | + (adjust "skip navigation link present on pages with repeated blocks") |
| 63 | + (adjust "logical focus order follows visual reading order") |
| 64 | + |
| 65 | + ; ── Screen reader ── |
| 66 | + (adjust "all images have meaningful alt text (or alt='' if decorative)") |
| 67 | + (adjust "all form inputs have associated labels") |
| 68 | + (adjust "ARIA landmarks used for page regions (main, nav, banner, etc.)") |
| 69 | + (adjust "dynamic content updates announced via aria-live regions") |
| 70 | + (adjust "semantic HTML used (headings, lists, tables) — not div soup") |
| 71 | + |
| 72 | + ; ── Interactive ── |
| 73 | + (adjust "touch targets minimum 44x44px on mobile/touch interfaces") |
| 74 | + (adjust "error messages identify the field and describe the error") |
| 75 | + (adjust "error messages not conveyed by colour or position alone") |
| 76 | + (adjust "form validation provides suggestions for correction") |
| 77 | + |
| 78 | + ; ── Media ── |
| 79 | + (adjust "video has captions (closed or open)") |
| 80 | + (adjust "audio-only content has text transcript") |
| 81 | + (adjust "no autoplay of media with sound") |
| 82 | + |
| 83 | + ; ── Motion ── |
| 84 | + (adjust "animations respect prefers-reduced-motion media query") |
| 85 | + (adjust "no content depends on motion to convey meaning") |
| 86 | + |
| 87 | + ; ── CLI/TUI ── |
| 88 | + (adjust "CLI output must not rely solely on colour (use symbols: [OK] [FAIL])") |
| 89 | + (adjust "TUI must support high-contrast mode") |
| 90 | + (adjust "all CLI commands support --help with plain-text output") |
| 91 | + (adjust "error messages written in plain language, not jargon or codes alone") |
| 92 | + |
| 93 | + ; ── Documentation ── |
| 94 | + (adjust "docs use clear language, short sentences, logical structure") |
| 95 | + (adjust "code examples include comments explaining non-obvious steps") |
| 96 | + (adjust "diagrams have text descriptions or alt text") |
| 97 | + ) |
| 98 | + |
| 99 | + (enforcement |
| 100 | + (ci "accessibility linting in quality.yml workflow") |
| 101 | + (pr-block "PR blocked if accessibility regression detected") |
| 102 | + (tool "axe-core or pa11y for automated checks on web UI") |
| 103 | + (tool "CLI output inspected for colour-only signalling") |
| 104 | + (manual "manual screen reader test before major releases") |
| 105 | + ) |
| 106 | + |
| 107 | + (notes |
| 108 | + "These are MINIMUM requirements. Exceeding them (AAA) is encouraged." |
| 109 | + "When in doubt about an accessibility decision, ask — don't guess." |
| 110 | + "Accessibility is not optional polish — it is a structural requirement." |
| 111 | + ) |
| 112 | +) |
0 commit comments