freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.3

package/dist/assets/design/craft/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Open Design contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/assets/design/craft/PROVENANCE.md

@@ -0,0 +1,77 @@
+# OpenDesign craft provenance
+
+The Markdown under this directory is vendored third-party prose from
+[nexu-io/open-design](https://github.com/nexu-io/open-design). It is not covered by this package's
+AGPL-3.0-only license; this directory's `LICENSE` carries the upstream terms,
+and two of the sections carry a second, nested attribution they state
+themselves (`color.md`, `anti-ai-slop.md`: adapted from `refero_skill`, MIT).
+
+## Source and snapshot
+
+| | |
+|---|---|
+| Project | OpenDesign |
+| Repository | https://github.com/nexu-io/open-design |
+| Upstream version | 0.23.1 |
+| Snapshot commit | unrecorded (source tree carries no .git) |
+| Snapshot date | 2026-09-26 |
+| License | Apache-2.0 (no NOTICE file upstream) |
+| Vendored files | 13 |
+| Craft sections | 11 |
+
+## What was adapted, and why
+
+The text is upstream. One adaptation is applied by
+`scripts/vendor-craft.mjs` as a rule, so a re-sync replays it rather than
+requiring anyone to remember it:
+
+- **Six glyphs are named rather than drawn.** `anti-ai-slop.md` forbids
+  emoji as feature icons and therefore writes six of them down. Those are
+  replaced by their code point and Unicode name, so the rule still says
+  which glyphs it means while no emoji-presentation glyph ships. No other
+  change was made to any file; the substitution is listed below.
+
+| Glyph as named | In |
+|---|---|
+| `U+2728 SPARKLES` | `anti-ai-slop.md` |
+| `U+1F680 ROCKET` | `anti-ai-slop.md` |
+| `U+1F3AF DIRECT HIT` | `anti-ai-slop.md` |
+| `U+26A1 HIGH VOLTAGE` | `anti-ai-slop.md` |
+| `U+1F525 FIRE` | `anti-ai-slop.md` |
+| `U+1F4A1 LIGHT BULB` | `anti-ai-slop.md` |
+
+## References to upstream paths
+
+Several sections cite upstream's own repository where a rule is auto-checked or a
+sibling layer is described — `apps/daemon/src/lint-artifact.ts` for the rules the
+linter enforces, `design-systems/` for the brand packages craft sits on top of.
+Those paths do not exist in this package: they are kept because they say *where*
+upstream enforces a rule, which is the difference between a hard rule and guidance
+— and rewriting upstream prose to hide its own layout is the kind of edit that
+makes a notice untrue.
+
+## Forward references
+
+FUTURE_SECTIONS.md lists slugs upstream has referenced but not yet shipped. The tool
+reads that file rather than a copy of it, so an unknown slug and a *planned*
+slug give different answers. Registered at this snapshot:
+
+- `motion-discipline`
+- `pixel-discipline`
+- `typographic-rhythm`
+
+| Vendored file | Bytes | SHA-256 |
+|---|---|---|
+| `accessibility-baseline.md` | 12894 | `ef6c5f670d114ceb4c347681bcf3be8637e5d1186165a9c79ca265f316c72d11` |
+| `animation-discipline.md` | 9114 | `075273e8404f7931adfe196d508461efdd303b54e0d9a9ef3f642a682c12a760` |
+| `anti-ai-slop.md` | 4004 | `9b4e07fff77c95e581719b5bd0c9658f637847b4591a7bc2ba0c8c8bbc6544f2` |
+| `color.md` | 3117 | `fb45b59fa3055f13d6549f45ae52e88cd09d3facd0e5aaab63600e7fb024db6d` |
+| `form-validation.md` | 17186 | `a31410ce6ba8b7a762c2975386f2e93ae97b59a8bc85169aa58457927b0a88e6` |
+| `FUTURE_SECTIONS.md` | 291 | `e95ccf61e166cfc3dc7266bfaaabb3e8cec1dc9c8d134eb63ad064343aa7d9bc` |
+| `laws-of-ux.md` | 17339 | `9a4db0fe294a240920921111d43a6af5ea0c4df1bf979f6e780610a36a9c6d1c` |
+| `README.md` | 6309 | `7b18e690c995226706c7f8f50229a9f9e170ad3b6675bd031c8d8751682c3c46` |
+| `rtl-and-bidi.md` | 12159 | `713abc3707eb056ed1d40ca8f3e91c04afc4003251b9ed266650fd267cbf4391` |
+| `state-coverage.md` | 7084 | `79bda732b55b0f0e4a366ba934f4a01518d3576091422047690e269222f2b682` |
+| `typography-hierarchy-editorial.md` | 8748 | `df5beddb8cd3c2b8f15e74f57ada607f7a89ce9112aaa8f8fad22d89e452bea4` |
+| `typography-hierarchy.md` | 7414 | `e247ca0358dcbdc3921f2148cc44c6ddcc325429b8082f6ad033792b79e39e06` |
+| `typography.md` | 4781 | `5f8e634b35c6b27a5e86f748825da17efe6a0d2e96f68dc35f57f406420049a6` |

package/dist/assets/design/craft/README.md

@@ -0,0 +1,106 @@
+# Craft references
+
+Brand-agnostic craft knowledge. Each file is a small, dense rulebook on one
+dimension of professional UI craft (typography, color, motion, …). Skills
+opt into the references they need; the daemon injects only the requested
+ones into the system prompt above the active skill body.
+
+## Why a fourth axis next to skills, templates, and design systems
+
+| Axis | Scope | Example |
+|---|---|---|
+| `skills/` | Functional capabilities invoked while doing work | `design-brief`, `brand-extract`, `imagegen` |
+| `design-templates/` | Packaged artifact shapes | `saas-landing`, `dashboard`, `pricing-page` |
+| `design-systems/` | Brand package: prose, token contract, and optional rich resources | `linear-app`, `apple`, `notion` |
+| `craft/` | **Universal** craft knowledge — true regardless of brand | letter-spacing rules, accent-overuse caps, anti-AI-slop |
+
+`DESIGN.md` tells the agent which colors and fonts a brand uses. `craft/`
+tells the agent the universal rules a competent designer applies on top —
+e.g. ALL CAPS always needs ≥0.06em tracking, regardless of the brand.
+
+## How a skill opts in
+
+Add an `od.craft.requires` array to the skill's front-matter. Only the
+listed sections are injected, so a skill that needs only typography pays
+no token cost for color/motion content.
+
+```yaml
+od:
+  craft:
+    requires: [typography, color, anti-ai-slop]
+```
+
+Use the layered stack for editorial skills that require authored hierarchy
+and sustained reading behavior:
+
+```yaml
+od:
+  craft:
+    requires: [typography, typography-hierarchy, typography-hierarchy-editorial]
+```
+
+Allowed shipped values match the file names in this directory minus the `.md`
+extension. The runtime skips an absent file for compatibility, but repository
+authoring does not silently accept arbitrary values.
+
+Run `pnpm lint:craft` after adding or changing `od.craft.requires`. The
+repository guard reports unresolved slugs with their manifest paths, so typos
+cannot silently drop a craft section from the runtime prompt. If a slug is an
+intentional forward reference, list it in `craft/FUTURE_SECTIONS.md` until the
+matching `craft/<slug>.md` file ships.
+
+### Runtime compatibility and authoring failures
+
+The loader remains tolerant because externally installed or older bundles may
+reference a section that is unavailable in the current resource set. A missing
+optional paragraph must not make an otherwise usable runtime bundle fail.
+
+Checked-in content has a stronger contract: `pnpm lint:craft` and
+`pnpm guard` fail on malformed slugs and unresolved references. A deliberate
+forward reference is valid only when it is listed in
+`craft/FUTURE_SECTIONS.md`; this makes planned work explicit while preserving
+the runtime compatibility behavior.
+
+Note for skill authors arriving from older guidance: an earlier draft
+used `motion` as the future-slug placeholder. The shipped equivalent
+today is `animation-discipline`. Use that one if your skill emits
+motion.
+
+### Enforcement levels
+
+Craft files mix auto-checked rules and guidance.
+
+- **Auto-checked.** Rules wired into `apps/daemon/src/lint-artifact.ts` — currently the P0 list in `anti-ai-slop.md` (Tailwind-indigo accent, two-stop hero gradients, emoji-as-icons, etc.). The linter reports these as findings back to the UI (for P0/P1 badges) and to the agent (as a system reminder for self-correction). Artifact persistence is not currently hard-blocked on P0 hits.
+- **Guidance.** The rest. The agent reads the rules, reviewers apply them, the linter doesn't check them.
+
+A purely behavioral craft file (state-coverage, animation-discipline) is guidance unless a specific rule is later promoted into `lint-artifact.ts`.
+
+## Files
+
+| File | Section name | When to require |
+|---|---|---|
+| `typography.md` | `typography` | Any skill that emits typed content (~all skills) |
+| `typography-hierarchy.md` | `typography-hierarchy` | Any skill that emits typed content where hierarchy must feel authored, not assembled — especially surfaces with a strong entry point, varied levels, or intentional rhythm. Compose with `typography`. |
+| `typography-hierarchy-editorial.md` | `typography-hierarchy-editorial` | Skills whose primary artifact is a sustained reading surface: `blog-post`, `docs-page`, `digital-eguide`. Requires `typography` + `typography-hierarchy`. |
+| `color.md` | `color` | Any skill that emits styled output (~all skills) |
+| `anti-ai-slop.md` | `anti-ai-slop` | Marketing pages, landing pages, decks |
+| `state-coverage.md` | `state-coverage` | Any skill with stateful UI (dashboards, mobile apps, forms, list/table views) |
+| `animation-discipline.md` | `animation-discipline` | Any skill that ships motion: mobile apps, multi-screen flows, gamified UI, transitions, microinteractions |
+| `accessibility-baseline.md` | `accessibility-baseline` | Any skill that ships interactive UI: dashboards, forms, mobile flows, anything with focus/labels/keyboard paths |
+| `rtl-and-bidi.md` | `rtl-and-bidi` | Any skill that ships localized text or layout: blogs, docs, financial tables, mobile apps, anything that may render Arabic / Hebrew / Persian |
+| `form-validation.md` | `form-validation` | Any skill whose primary artifact contains an interactive form: lead capture, sign-in, signup, settings, multi-step intake |
+| `laws-of-ux.md` | `laws-of-ux` | Any skill whose composition decisions hit named cognitive limits: pricing pages (Hick's, Choice Overload, Von Restorff), dashboards (Pareto, Selective Attention, Working Memory), onboarding (Goal-Gradient, Zeigarnik, Peak-End), modals (Fitts's, Tesler's). Sibling axis to the rendering-rule files above — covers what to compose, not how to render. |
+
+**Partial-stateful skills.** A skill that's mostly static but contains an embedded form, data table, or query surface should opt in. State-coverage rules apply to the stateful component, not the whole page.
+
+Planned-but-unshipped slugs are recorded in
+[`FUTURE_SECTIONS.md`](FUTURE_SECTIONS.md); do not hard-code a second future
+list here.
+
+## Attribution
+
+Craft content is adapted from the MIT-licensed
+[refero_skill](https://github.com/referodesign/refero_skill) project
+(© Refero Design), with edits to fit OpenDesign's house style and link
+back to OD's design tokens (`var(--accent)` etc.) instead of generic
+Tailwind hex values.

package/dist/assets/design/craft/accessibility-baseline.md

@@ -0,0 +1,201 @@
+# Accessibility baseline craft rules
+
+Universal rules for the legal floor of accessibility plus the craft
+commitments that go beyond it. The active `DESIGN.md` decides brand
+appearance; this file decides which rules an artifact has to clear
+before it ships.
+
+> Grounded in primary sources: WCAG 2.2 Understanding pages,
+> ISO/IEC 40500:2025, ADA Title II 2024 + 2026 IFR, EN 301 549 v3.2.1,
+> WAI-ARIA 1.3 + AccName 1.2 + Core AAM 1.2, WebAIM Million 2026
+> (February 2026 crawl), A11yn (arXiv 2510.13914), APCA W3C silver
+> branch.
+
+## Prior art and scope
+
+Existing OSS a11y guidance for AI agents (`fecarrico/A11Y.md`,
+`awesome-copilot agents/accessibility.agent.md`,
+`Community-Access/accessibility-agents`) tends to inline a checklist of
+WCAG SCs without versioning the legal floor or specifying which
+constraints survive on iOS / Android / Flutter. This file scopes
+narrower: the compliance floor an OD artifact must clear, with
+jurisdiction notes and native-mobile parity. Heuristic rules and
+linter-checked items live in sibling craft files
+(`anti-ai-slop.md`, `state-coverage.md`); WCAG SC numbers map to
+specific rules below rather than being re-listed.
+
+## The legal floor changes by jurisdiction
+
+- **EU (EAA, enforcement live 2025-06-28):** EN 301 549 v3.2.1 is the OJ-cited harmonised standard; it references **WCAG 2.1 AA**. EN 301 549 v4.1.1 (which incorporates WCAG 2.2's nine new SCs) is OJ-citation-targeted late 2026 / 2027. Until then, EAA references WCAG 2.1. The Web Accessibility Directive (WAD, EU 2016/2102) covers public-sector bodies separately and also points at EN 301 549.
+- **US public sector — ADA Title II 2024 final rule:** **WCAG 2.1 AA**. The 2026-04-20 IFR slipped deadlines: 2027-04-26 for jurisdictions with population ≥ 50,000; 2028-04-26 for sub-50,000 and special districts.
+- **US federal procurement — Section 508 (Revised 508 Standards):** harmonised with EN 301 549 → references **WCAG 2.0 AA** in the current published rev. The Access Board has WCAG 2.x updates in flight; until they ship, federal IT procurement floor is WCAG 2.0.
+- **US private sector — ADA Title III:** no federal regulation specifies a technical standard. Settlements and DOJ guidance routinely cite **WCAG 2.1 AA** as the de-facto target, but the legal mechanism is case-by-case, not rule-based.
+- **ISO/IEC 40500:2025** (October 2025) ratified WCAG 2.2 verbatim. Does not by itself change EU or US legal floors.
+
+**Practical rule for craft:** target **WCAG 2.2 AA** as the working
+ceiling. It clears the WCAG 2.1 AA legal floor in both jurisdictions
+and prepares for v4.1.1. Anything below 2.2 AA is craft debt.
+
+## Color contrast
+
+| Pair | WCAG 2.x AA minimum |
+|---|---|
+| Normal text below 18 pt regular / 14 pt bold (covers most body and UI text) | 4.5:1 |
+| Large text (≥18 *pt* regular ≈24 px, or ≥14 *pt* bold ≈18.5 px) | 3:1 |
+| Non-text UI components and graphical objects | 3:1 |
+| Focus indicator vs adjacent and unfocused state | 3:1 |
+
+Thresholds are **inclusive** — exactly 4.5:1 or 3:1 passes. Don't round
+up: 2.999:1 fails because rounding is not a permitted mechanism.
+
+"Large text" means **18 pt** regular, not 18 px. 18 px regular needs
+4.5:1; 14 pt bold (≈18.5 px) qualifies for 3:1, 14 px bold does not.
+
+**APCA as a parallel design check.** APCA's Lc value catches font-weight
+and stem-thickness effects that WCAG 2.x luminance ratios miss. Body
+copy at Lc ≥60 is a reasonable parallel pass; APCA's actual lookup
+table is size- and weight-dependent (heavier weights at larger sizes
+clear at lower Lc, thin small text needs Lc ≥75+). APCA is not part
+of WCAG, EN 301 549, ADA, or Section 508 compliance as of 2026-05 —
+keep WCAG 2.2 AA as the compliance floor and treat APCA as
+design-review only. If you ship APCA tooling, use the `apca-w3`
+package; the SAPC repo is non-commercial.
+
+## Touch targets
+
+| Bar | SC | Size |
+|---|---|---|
+| AA (legal floor) | 2.5.8 Target Size (Minimum) | **24×24 CSS px** |
+| AAA (craft commitment) | 2.5.5 Target Size (Enhanced) | 44×44 CSS px |
+| iOS HIG | — | 44×44 pt |
+| Material 3 | — | 48×48 dp |
+
+WCAG 2.5.8 lists five exceptions where the 24×24 minimum doesn't
+apply: **Spacing** (a 24-CSS-px exclusion circle around the target
+doesn't intersect adjacent ones), **Equivalent** (an alternative
+control of sufficient size achieves the same function), **Inline**
+(target sits inside a sentence, e.g. links in body copy), **User
+agent control** (browser default like a native scrollbar), and
+**Essential** (the smaller size is required to convey information,
+e.g. a map pin). The Spacing exception is the one icon-button
+toolbars rely on; the others are narrower than they read and
+shouldn't be used to justify undersized primary actions.
+
+## Focus visibility
+
+Removing the focus outline via CSS is a **triple failure**: 1.4.11
+Non-text Contrast, 2.4.7 Focus Visible, and 2.4.13 Focus Appearance
+(AAA). Use `:focus-visible` for keyboard users; suppress the outline
+for mouse clicks only when an alternative non-color affordance exists.
+
+For AAA (2.4.13): indicator area must equal at least a 2 CSS px
+perimeter of the component, contrast ≥3:1 between focused and
+unfocused states. A 1-px outline at 3:1 doesn't qualify.
+
+## Form input labels
+
+WebAIM Million 2026 (which uses WAVE, not axe-core): **51% of top 1M
+home pages have at least one missing form-input label; 33.1% of all
+6.9M inputs are unlabeled**. The page-level rate moved from 48.2%
+(2025) to 51% (2026) — missing-label prevalence is one of the few
+categories WebAIM explicitly calls out as rising in 2026, against an
+overall errors-per-page count of 56.1.
+
+Default form-error wiring (WCAG 2.2 + ARIA APG):
+
+```html
+<label for="email">Email</label>
+<input id="email" type="email" required
+       aria-describedby="email-hint email-error"
+       aria-invalid="true">
+<span id="email-hint">Used for receipts only.</span>
+<span id="email-error" role="alert">Email must include @ and a domain.</span>
+```
+
+`aria-describedby` is the production default; `aria-errormessage` has
+incomplete screen-reader support as of 2026-05 (full on NVDA, partial
+on JAWS / VoiceOver / TalkBack) — treat as progressive enhancement.
+
+WCAG 3.3.7 Redundant Entry is **Level A** (legal floor). Re-asking for
+data the user already entered "in the same process" fails unless the
+site auto-populates or offers a selectable shortcut. Browser autofill
+does not satisfy it.
+
+## Keyboard operability and semantic structure
+
+Visual contrast and labelled inputs don't matter if a keyboard or
+screen-reader user can't reach the control or parse the page. The
+bullets below are Level A / AA WCAG essentials plus a small set of
+structural conventions OD treats as craft commitments. WCAG levels
+are noted per item.
+
+- **Tab reachability** (2.1.1 Keyboard, Level A): every interactive element must be reachable and operable via keyboard. `tabindex="-1"` removes from the tab order; `tabindex` values >0 break document order and should not be used. (2.1.3 No Exception extends 2.1.1 to AAA by removing the underlying-function exception.)
+- **Activation keys** (2.1.1, Level A): `<button>` activates on Enter and Space; `<a href="…">` activates on Enter. A bare `<a>` without `href` is not a link, not focusable, and not keyboard-operable — use `<a href="…">` for navigation or `<button>` for actions, never a placeholder anchor. Custom controls must implement the matching key handlers and `role`.
+- **No keyboard trap** (2.1.2, Level A): focus must be able to leave any component via the same standard keys it entered with. Modal dialogs are a focus-trap *by design*, not a violation — they trap until dismissed by Escape or the close button.
+- **Focus order** (2.4.3, Level A): tab order must follow the meaningful reading order. Don't rely on positive `tabindex` to fix DOM that's out of order; fix the DOM.
+- **Native control first** (craft convention, anchored on 4.1.2 Name/Role/Value Level A): a `<button>` is keyboard-operable, focusable, name-resolvable, and announced as a button by every AT for free. `<div role="button" tabindex="0">` requires you to re-implement all of that and most reimplementations miss `aria-pressed`, disabled state, or Space-on-keyup. Reach for ARIA only when no native element fits.
+- **Document language** (3.1.1, Level A): `<html lang="...">` is required. Sub-tree language switches use `lang` on the inner element.
+- **Heading hierarchy** (1.3.1 Info and Relationships Level A; 2.4.6 Headings and Labels Level AA): WCAG requires programmatically-determined structure and descriptive headings, not a specific outline shape. OD craft convention layers on: prefer one `<h1>` per page and don't skip levels (`<h1>` → `<h3>` without `<h2>`). Visual size and heading level are independent.
+- **Landmarks** (1.3.1, 2.4.1 Bypass Blocks Level A): use `<header>` `<nav>` `<main>` `<aside>` `<footer>` rather than `<div role="banner">` etc. AT users navigate by landmark; a page with no landmarks is a wall of divs.
+- **Text alternatives** (1.1.1 Non-text Content, Level A): `<img alt="...">` for content images, `alt=""` for decorative; `aria-label` on icon-only buttons; long-form description for charts and SVG data viz. A chart without a text alternative is unreadable to a screen reader.
+
+## ARIA discipline
+
+WebAIM Million 2026 shows ARIA pages average **59.1 errors** vs
+**42** on non-ARIA pages — about 17 extra errors on the ARIA side.
+The gap was 30 in 2025 (57 vs 27) and 15 in 2024; YoY direction is
+noisy, but ARIA usage is up (82.7% of home pages in 2026 vs 79.4% in
+2025) while correctness lags. ARIA deployment outpaces ARIA
+correctness.
+
+Decision order, per ARIA APG:
+
+1. Native HTML element with the right semantics.
+2. Native element under custom visuals if restyling is required.
+3. APG pattern verbatim if neither fits.
+4. Closest APG pattern + documented deviation. Last resort.
+
+Never invent ARIA.
+
+## Reduced motion and flashing
+
+See `animation-discipline.md` for the full rule set. The non-negotiable
+that anchors here: WCAG 2.3.1 (Level A) — flashing more than three
+times per one-second period is non-conformant unless the flash area
+stays below the general and red flash thresholds. Photosensitive
+epilepsy is the protected concern.
+
+## Native mobile parity
+
+Web ARIA does not auto-translate. Each platform has its own labelling API.
+
+| Platform | Label | Role |
+|---|---|---|
+| iOS UIKit | `accessibilityLabel` | `accessibilityTraits` |
+| iOS SwiftUI | `.accessibilityLabel(…)` | `.accessibilityAddTraits(.isButton)` |
+| Android Compose | `Modifier.semantics { contentDescription = … }` | `Modifier.semantics { role = Role.Button }` |
+| Flutter | `Semantics(label: …)` | `Semantics(button: true, …)` |
+| React Native | `accessibilityLabel` | `accessibilityRole` |
+
+Use the platform API for each target. AI-generated mobile UI that
+mirrors web ARIA verbatim usually misses the platform-native screen
+reader path.
+
+## Common mistakes (lint these)
+
+- "Target Size 44×44" cited as the AA bar. 44×44 is **AAA** (2.5.5). AA is **24×24** (2.5.8).
+- "18 px = large text" — wrong. Threshold is 18 *pt* regular (~24 px) or 14 pt bold (~18.5 px).
+- "EAA = WCAG 2.2 AA" — wrong. EN 301 549 v3.2.1 is anchored to WCAG 2.1.
+- "Section 508 = WCAG 2.1 AA" — wrong as of 2026-05. Revised 508 still references WCAG 2.0 AA; the Access Board update is in flight, not shipped.
+- "Tabindex fixes focus order" — `tabindex` >0 reorders against DOM and almost always makes it worse. Fix the DOM.
+- "Modal traps focus → keyboard trap" — confusing 2.1.2. A modal trapping focus until Escape / close is correct behaviour, not a violation.
+- "Heading size = heading level" — visual hierarchy and `<h1>`/`<h2>`/`<h3>` are independent. Style the level you mean.
+- "WebAIM Million uses axe-core" — uses WAVE.
+- "WCAG 3 will use APCA" — APCA was dropped from WCAG 3 in July 2023.
+- "Adding ARIA improves accessibility" — empirically the opposite. WebAIM Million 2026: ARIA pages average 59.1 errors, non-ARIA pages 42.
+- "Bare `<a>` with click handler is a link" — wrong. `<a>` without `href` is not focusable, not keyboard-operable, and not a link. Use `<a href="…">` for navigation, `<button>` for actions.
+- Removing the focus outline via `outline: none` without a replacement. Triple failure: 1.4.11, 2.4.7, 2.4.13.
+- Placeholder text as the only label for a form input. Fails 1.3.1 and 3.3.2; placeholder disappears on input.
+- Using `aria-description` as the sole state-carrier on `role="row"`. JAWS 2025/2026 silently drops it ([FreedomScientific standards-support #927](https://github.com/FreedomScientific/standards-support/issues/927)).
+- Native HTML `<button>` reimplemented as `<div role="button">` without keyboard handling, focus, or `aria-pressed`.
+- A11y treated as web-only. Flutter / iOS / Android have their own labelling APIs that web ARIA doesn't reach.