@pugi/cli 1.0.0-alpha.25 → 1.0.0-alpha.250

package/skills/od-craft/NOTICE.md

@@ -0,0 +1,126 @@
+# Third-party skills vendored into the Pugi designer pack
+
+These skills are part of Sofia's (designer) skill pack. They help her go from a
+brief to a design system to the clickable HTML prototype that the customer
+approves at the plan gate (`.pugi/artifacts/prototype.html`, BACKLOG AO), and,
+since 2026-10-17, carry the craft rules every build turn is held to.
+
+The skill pack generator copies this file and `LICENSE-APACHE-2.0` into every
+vendored skill directory, so each one carries its attribution wherever it is
+baked.
+
+Both upstream projects are licensed under the Apache License, Version 2.0. The
+full licence text is in `LICENSE-APACHE-2.0` next to this file. The LICENSE file
+of each repository was checked before anything was copied (2026-10-04 and
+2026-10-17). Neither repository ships a NOTICE file, so this file is the
+attribution.
+
+## nexu-io/open-design
+
+- Source: https://github.com/nexu-io/open-design
+- Licence: Apache-2.0, "Copyright 2026 Open Design contributors"
+- The upstream `skills/README.md` says skills are Apache-2.0 unless their own
+  `LICENSE` says otherwise. No directory copied here has its own licence.
+- Commit 53231d40b778d88eba23f35547bf99485d3ae9fc (2026-09-30) for the two
+  prototype skills (re-checked unchanged at 3b0df90f and re-stamped);
+  commit 78d5637cb49da07e81314d1544b5fc6d37c95084 (v0.25.1, 2026-10-16) for
+  the craft rules and the two ports below; commit
+  3b0df90f305c8279e748c292accf336d02b924ef (2026-10-20) for the design
+  templates and design skills added 2026-10-21 (CEO: "Open Design inside
+  Pugi"). The LICENSE file of the repository was checked again on 2026-10-21.
+
+| Pugi skill | Upstream path | Files copied |
+|---|---|---|
+| `od-web-prototype` | `design-templates/web-prototype/` | `SKILL.md`, `assets/template.html`, `references/layouts.md`, `references/checklist.md` |
+| `od-reference-design-contract` | `skills/reference-design-contract/` | `SKILL.md`, `references/checklist.md` |
+| `od-craft` | `craft/` | all twelve documents, as `references/<name>.md`: `README.md`, `accessibility-baseline.md`, `animation-discipline.md`, `anti-ai-slop.md`, `color.md`, `form-validation.md`, `laws-of-ux.md`, `rtl-and-bidi.md`, `state-coverage.md`, `typography-hierarchy-editorial.md`, `typography-hierarchy.md`, `typography.md` |
+
+### Design templates (added 2026-10-21, commit 3b0df90f) — the "Start from" catalogue
+
+Each is `design-templates/<name>/` → `od-<name>/`, `SKILL.md` only unless noted.
+Apache-2.0, nexu-io/open-design contributors, except where a row says otherwise.
+
+| Pugi skill | Upstream path | Files copied / licence |
+|---|---|---|
+| `od-saas-landing`, `od-dashboard`, `od-mobile-onboarding`, `od-pricing-page`, `od-blog-post`, `od-docs-page`, `od-kanban-board`, `od-invoice`, `od-meeting-notes`, `od-contact-widget`, `od-email-marketing`, `od-social-carousel`, `od-wireframe-annotated`, `od-wireframe-greybox`, `od-wireframe-mobile-flow`, `od-wireframe-sketch`, `od-pm-spec`, `od-team-okrs`, `od-eng-runbook`, `od-finance-report`, `od-hr-onboarding`, `od-magazine-poster`, `od-webgl-experience` | `design-templates/<name>/` | `SKILL.md` |
+| `od-mobile-app` | `design-templates/mobile-app/` | `SKILL.md`, `assets/template.html`, `references/layouts.md`, `references/checklist.md` |
+| `od-waitlist-page` | `design-templates/waitlist-page/` | `SKILL.md`, `assets/template.html`, `references/checklist.md` |
+| `od-web-prototype-taste-soft`, `-editorial`, `-brutalist` | `design-templates/web-prototype-taste-*/` | `SKILL.md`; distilled by open-design from Leonxlnx/taste-skill (MIT, © 2026 Leonxlnx) — that MIT text is carried as `LICENSE-MIT-Leonxlnx` in each directory |
+| `od-login-flow` | `skills/login-flow/` | `SKILL.md`, `references/checklist.md` |
+| `od-faq-page` | `skills/faq-page/` | `SKILL.md` |
+
+### Design skills (added 2026-10-21, commit 3b0df90f)
+
+| Pugi skill | Upstream path | Files copied / licence |
+|---|---|---|
+| `od-design-brief` | `skills/design-brief/` | `SKILL.md` (Apache-2.0, nexu-io) |
+| `od-critique` | `design-templates/critique/` | `SKILL.md` (Apache-2.0, nexu-io) |
+| `od-frontend-design` | `skills/frontend-design/` | `SKILL.md`, `LICENSE.txt` (Apache-2.0; the skill is Anthropic's `frontend-design` as open-design redistributes it) |
+| `od-redesign-skill` | `skills/redesign-skill/` | `SKILL.md`, `LICENSE` (MIT, © 2026 Leonxlnx; upstream frontmatter name `redesign-existing-projects`) |
+| `od-web-design-guidelines` | `skills/web-design-guidelines/` | `SKILL.md`, `LICENSE`, `references/guidelines.md` (MIT, vercel-labs/web-interface-guidelines, as open-design redistributes it) |
+
+Looked at and left out on 2026-10-21 (no licence file in the open-design
+directory although the upstream is MIT/Apache; take later with the upstream
+text): `design-md`, `enhance-prompt` (google-labs-code/skills),
+`design-consultation`, `plan-design-review` (garrytan/gstack, MIT),
+`copywriting` (coreyhaines31/marketingskills, MIT), `impeccable-design-polish`
+(pbakaus/impeccable, Apache-2.0), `ui-skills` (ibelick/ui-skills, MIT),
+`emil-design-eng`, `animate`, `review-animations`, `stitch-skill`. Decks,
+video, live-artifact and `tweaks` templates are not Pugi surfaces.
+
+Upstream attributions kept inside those files: `craft/` is adapted from
+referodesign/refero_skill (MIT, © Refero Design); the "Adapted from" lines
+stay where upstream put them.
+
+### Ports (derivative works, Apache-2.0 §4), not copies
+
+| Pugi file | Upstream source | What changed |
+|---|---|---|
+| `packages/opencode/src/session/design-lint.ts` | `apps/daemon/src/lint-artifact.ts` | The seven P0 checks and the external-image advisory are kept; the finding shape is local; it runs over a workspace (source and `dist/`) rather than one artifact body; Tailwind utility-class forms of each sin are added; the deck, `data-od-id`, all-caps tracking and raw-hex checks are dropped; the sans-display check fires only when a serif display token is bound. The daemon's analytics were never in this file. |
+| `packages/opencode/src/scaffold/design-direction.ts` | `apps/daemon/src/prompts/directions.ts` | The five schools are kept as postures; labels no longer name other brands; palettes are hex; faces are the Google fonts the starters link; two directions added; no question form (the direction is decided by the model, never asked of the customer). |
+| `packages/plugin-pugi-personas/src/craft-digest.ts` | `craft/*.md` | A condensed summary written by Pugi from the twelve documents. |
+
+Nothing ported touches the network: open-design's PostHog / Langfuse telemetry
+lives in its apps, none of which were taken.
+
+## nexu-io/html-anything
+
+- Source: https://github.com/nexu-io/html-anything
+- Commit: 553ed98c283f9c0f489902d035416a972d6a9699 (2026-09-15)
+- Licence: Apache-2.0. The upstream copyright line is the unfilled template
+  ("Copyright [yyyy] [name of copyright owner]"), so the copyright belongs to
+  the html-anything contributors.
+
+| Pugi skill | Upstream path | Files copied |
+|---|---|---|
+| `ha-prototype-web` | `next/src/lib/templates/skills/prototype-web/` | `SKILL.md` |
+
+## Changes made by Pugi (Apache-2.0 §4(b))
+
+- The frontmatter `name` of every `SKILL.md` was prefixed (`od-`, `ha-`). Skill
+  names are permission patterns in Pugi, and upstream names such as
+  `web-prototype` would collide across the two sources.
+- One HTML comment was added under each frontmatter block. It names the source,
+  the commit and these changes.
+- `od-craft/SKILL.md` is written by Pugi (upstream has no skill wrapper for
+  `craft/`; its daemon injects the files per `od.craft.requires`). Each
+  `references/*.md` begins with one added HTML comment naming the source
+  commit and stating that the rest is verbatim; the text below it is
+  unchanged, including upstream's references to its own paths
+  (`apps/daemon/src/lint-artifact.ts`, `pnpm lint:craft`).
+- Example files (`example.html`, `example.md`) were not copied (the sanitised
+  example pages live under `scaffold/seeds/` with their own NOTICE).
+- The three `od-web-prototype-taste-*` directories and `od-redesign-skill`
+  carry the MIT licence of Leonxlnx next to the Apache-2.0 text, because the
+  upstream `skills/README.md` says a skill's own LICENSE prevails.
+- Every other byte of the copied files is unchanged.
+
+Where an upstream rule conflicts with the Pugi plan-gate prototype contract in
+Sofia's persona prompt, the Pugi contract wins.
+Two upstream rules conflict on purpose. The output file is
+`.pugi/artifacts/prototype.html`, not `index.html`. Photos are Pexels CDN URLs
+taken from Anvil `/v1/images`, not copies in the project, because the console
+renders the prototype from a single document.
+Where a craft rule names open-design's tokens (`var(--accent)`), the starter's
+own token scheme (`src/globals.css` bare HSL components, `src/theme.css`
+typefaces) wins.

package/skills/od-craft/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: od-craft
+description: |
+  Brand-agnostic craft rules for any screen the build emits: typography
+  (tracking, leading, scale), colour (accent budget, contrast), the seven
+  AI-slop tells the design lint blocks, state coverage, motion, accessibility,
+  forms, RTL and the laws of UX. Load one reference when a rule's exact
+  threshold matters; the condensed digest in the system prompt is the summary.
+triggers:
+  - "craft"
+  - "typography"
+  - "letter-spacing"
+  - "accent"
+  - "contrast"
+  - "ai slop"
+  - "design lint"
+  - "empty state"
+  - "reduced motion"
+  - "accessibility"
+  - "form validation"
+  - "rtl"
+---
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/), Apache-2.0, Copyright 2026 Open Design contributors. This SKILL.md is written by Pugi: upstream keeps these rules as loose files its daemon injects per skill (`od.craft.requires`), Pugi ships them as one skill with the full text under references/. Each reference carries its own provenance header. See NOTICE.md in this directory. -->
+
+# Craft rules (open-design `craft/`)
+
+Twelve dense rulebooks, one per dimension of professional UI craft. They are
+true regardless of brand: the design system says WHICH fonts and colours, these
+say HOW they behave. The engine already injects a condensed digest of them
+(`<design-craft>`) into every build turn; load a reference here only when you
+need the exact rule, table or threshold.
+
+## Resource map
+
+| Reference | Load it when |
+|---|---|
+| `references/anti-ai-slop.md` | the design lint reported a finding, or before a hero / landing section. The seven cardinal sins it lists are what `design-lint` blocks at P0 |
+| `references/typography.md` | setting any `letter-spacing`, `line-height`, scale or font pairing; CJK text |
+| `references/typography-hierarchy.md` | one element must dominate above the fold; headings read flat or noisy |
+| `references/typography-hierarchy-editorial.md` | a sustained reading surface: blog, docs, long article |
+| `references/color.md` | palette layers, the two-uses-per-screen accent cap, contrast minimums, dark themes |
+| `references/state-coverage.md` | anything that fetches or accepts data: loading / empty / error / edge states |
+| `references/animation-discipline.md` | any transition or micro-interaction; durations, springs, `prefers-reduced-motion` |
+| `references/accessibility-baseline.md` | focus, labels, targets, keyboard paths; WCAG 2.2 AA numbers |
+| `references/form-validation.md` | an interactive form: timing, `:user-invalid`, error wiring, schema |
+| `references/laws-of-ux.md` | composition decisions: pricing (Hick's), dashboards (working memory), onboarding |
+| `references/rtl-and-bidi.md` | Arabic / Hebrew / Persian text or layout; logical CSS properties |
+| `references/README.md` | upstream's own index and attribution |
+
+## How Pugi applies them
+
+- The condensed digest is always in the prompt; it is the summary, not the rule.
+- `design-lint` (engine, deterministic) checks the built site for the seven
+  sins and a few soft tells at the Ready gate; findings come back once as a fix
+  round, then the site ships and the findings are logged.
+- Where a rule conflicts with the starter's token scheme (`src/globals.css`
+  holds bare HSL components, `src/theme.css` the typefaces), the starter's
+  scheme wins: express the rule in those tokens.

package/skills/od-craft/references/README.md

@@ -0,0 +1,108 @@
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/README.md), Apache-2.0, Copyright 2026 Open Design contributors. Modified by Pugi: this header line added; the text below is otherwise verbatim. Paths it names (apps/daemon/src/lint-artifact.ts, pnpm lint:craft, od.craft.requires) are upstream's, not Pugi's: the Pugi port of the linter is packages/opencode/src/session/design-lint.ts. See NOTICE.md in the skill root. -->
+
+# 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/skills/od-craft/references/accessibility-baseline.md

@@ -0,0 +1,203 @@
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/accessibility-baseline.md), Apache-2.0, Copyright 2026 Open Design contributors. Modified by Pugi: this header line added; the text below is otherwise verbatim. Paths it names (apps/daemon/src/lint-artifact.ts, pnpm lint:craft, od.craft.requires) are upstream's, not Pugi's: the Pugi port of the linter is packages/opencode/src/session/design-lint.ts. See NOTICE.md in the skill root. -->
+
+# 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.