opencastle 0.32.4 → 0.32.6

package/src/orchestrator/prompts/implement-feature.prompt.md

@@ -15,22 +15,16 @@ You are the Team Lead. Implement the roadmap task described below following this
 
 ---
 
-> **Canonical workflow:** `.github/agent-workflows/feature-implementation.md` defines the phase structure. This prompt adds tracker traceability, validation gate references, and completion criteria.
-
 ## Workflow
 
 > **HARD GATE:** Steps 1→2 are **blocking prerequisites**. Do NOT write, edit, or delegate any code until tracker issues exist for every subtask. If you catch yourself writing code before issues are created, STOP immediately, create the issues, then resume.
 
 ### 1. Research & Context Gathering
 
-Before writing any code, gather all relevant context:
-
-1. **Read the roadmap** — Open `.opencastle/project/roadmap.md` and find the full scope, status, and acceptance criteria for this task
-2. **Read known issues** — Check `.opencastle/KNOWN-ISSUES.md` for blockers or workarounds that affect this task
-3. **Read architecture docs** — Check `.opencastle/project.instructions.md` and `.opencastle/project/decisions.md` for constraints and prior decisions
-4. **Read lessons learned** — Check `.opencastle/LESSONS-LEARNED.md` for pitfalls relevant to this feature area
-5. **Search existing code** — Find all files, components, queries, and tests related to this feature area
-6. **Identify reusable code** — Before creating anything new, check if similar logic, components, or utilities already exist in the codebase that can be reused or extended
+1. **Read the roadmap** — Confirm scope, status, and acceptance criteria in `.opencastle/project/roadmap.md`
+2. **Check blockers** — Read `.opencastle/KNOWN-ISSUES.md` and `.opencastle/LESSONS-LEARNED.md` for pitfalls and workarounds
+3. **Read architecture docs** — Check `.opencastle/project.instructions.md` and `.opencastle/project/decisions.md` for constraints
+4. **Search existing code** — Find related files, components, queries, and tests; check for reusable implementations before creating anything new
 
 ### 2. Task Board Setup (BLOCKING — must complete before Step 3)
 
@@ -39,52 +33,37 @@ Every subtask must be tracked. **No issue = no implementation.** This step produ
 1. **Check existing issues** — Search the board for any in-progress or completed work related to this task
 2. **Decompose into issues** — Create one tracker issue per subtask using `[Area] Short description` naming
 3. **Set metadata** — Assign labels (agent name), priority, dependencies, and file partitions
-4. **Write descriptions** — Each issue must include:
-   - **Objective:** One sentence
-   - **Files (partition):** Exact paths this agent may modify
-   - **Acceptance criteria:** Verifiable checklist
-   - **Dependencies:** Links to prerequisite issues
+4. **Write descriptions** — Objective (1 sentence), files (partition paths), acceptance criteria (checklist), dependencies (links)
 5. **Link to roadmap** — Reference the roadmap section in the issue description so context is never lost
 6. **Verify issues exist** — List all created issue IDs. If count is 0, do NOT proceed to Step 2.5
 
 ### 2.5 Generate Convoy Spec (BLOCKING — decides how Step 3 proceeds)
 
-All project-related work is executed via the convoy engine — regardless of subtask count. This ensures consistent observability, crash recovery, and live progress.
+All project-related work is executed via the convoy engine — regardless of subtask count.
 
-1. **Generate the spec** — use the `generate-convoy` prompt with the decomposed task list as context. The spec IS the implementation plan — no manual per-task delegation is needed. Even single-task fixes go through convoy for observability.
+1. **Generate the spec** — use the `generate-convoy` prompt with the decomposed task list. The spec IS the implementation plan; even single-task fixes go through convoy for observability.
 2. **Hand the spec to the user** — tell them to run: `npx opencastle run -f .opencastle/convoys/<name>.convoy.yml`
 3. **The convoy engine handles** isolated git worktrees, parallel execution, merge queue ordering, crash recovery, and structured logging automatically.
-4. **After convoy completes** — proceed to Step 4 (validation) and Step 5 (delivery/PR). The convoy engine will have created its own commits on the configured branch.
-
-> **Why always convoy?** Convoy execution is the only path that guarantees observability logging, crash recovery, gate validation, and live progress. Direct sub-agent delegation produces no structured logs and cannot be resumed if interrupted.
+4. **After convoy completes** — proceed to Step 4 (validation) and Step 5 (delivery/PR).
 
 ### 3. Implementation Rules
 
-> **Convoy execution:** The convoy spec file IS the implementation plan — skip the manual delegation workflow below and jump to Step 4 after the user runs the convoy. The convoy engine delegates tasks internally using the agents and prompts defined in the spec.
+> **Convoy execution:** The convoy spec IS the implementation plan — skip manual delegation and jump to Step 4 after the user runs the convoy.
 
 #### Issue Traceability
 
-- **Pass issue ID to every agent** — When delegating a subtask (sub-agent or background), include the tracker issue ID and title in the prompt so the agent knows which tracked task it is completing
-- **Reference in commits** — Include the issue ID (e.g., `TAS-42`) in commit messages when possible
-- **Update issue status** — Move issues to In Progress before starting, Done after verification passes
+- Include the tracker issue ID and title in every delegation prompt
+- Reference issue IDs (e.g., `TAS-42`) in commit messages; move issues In Progress → Done as work progresses
 
 #### DRY Code
 
-- **Search before creating** — Before writing any new component, hook, utility, query, or type, search the codebase for existing implementations
-- **Extract shared logic** — If two agents need similar functionality, extract it to a shared library (`libs/`) first
-- **No copy-paste across apps** — Shared code belongs in shared libraries, not duplicated between apps
-- **Refactor on discovery** — If you find duplicated code during implementation, create a subtask to consolidate it
-
-#### Self-Improvement
-
-Include the self-improvement reminder in every delegation prompt (see the **self-improvement** skill).
+- Search before creating — check for existing components, hooks, utilities, and queries first
+- Extract shared logic to `libs/`; no copy-paste across apps. Refactor duplicates when discovered
 
 #### Visual Consistency
 
-- **Reuse existing components** — Use the shared component library; never re-implement a component that already exists
-- **Follow the design system** — Match spacing, typography, colors, and interaction patterns from existing pages
-- **Cross-app consistency** — Changes must look correct in all apps that share the codebase
-- **Browser verification required** — Every UI change must be visually confirmed in Chrome (see Testing below)
+- Use the shared component library; never re-implement existing components
+- Match spacing, typography, and colors from existing pages; verify in all affected apps
 
 ### 4. Validation & Testing
 
@@ -92,39 +71,26 @@ Include the self-improvement reminder in every delegation prompt (see the **self
 
 Every subtask must pass ALL gates before being marked Done:
 
-1. **Gate 1: Secret Scanning** — scan diff for API keys, tokens, passwords, connection strings — block immediately if found
-2. **Gate 2: Deterministic Checks** — run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands) — all zero errors
-3. **Gate 3: Blast Radius Check** — verify scope is expected (≤200 lines, ≤5 files normal; escalate if >500 lines or >10 files)
-4. **Gate 4: Dependency Audit** (when `package.json` changes) — vulnerability scan, license check, bundle size, duplicates
-5. **Gate 5: Fast Review** (MANDATORY) — single reviewer sub-agent validates every delegation output. No auto-PASS for sensitive files
-6. **Gate 6: Browser Testing** (MANDATORY for UI changes) — clear cache, start server, verify features + responsive + screenshots
-7. **Gate 7: Regression Testing** — full test suite for affected projects, browser-test adjacent pages if shared components changed
-8. **Gate 8: Panel Review** (for high-stakes changes) — use **panel-majority-vote** skill for security, DB migrations, architecture
-9. **Gate 9: Final Smoke Test** — after all tasks Done, verify the complete feature end-to-end as a cohesive unit
+1. **Secret Scanning** — block if API keys/tokens/passwords found in diff
+2. **Deterministic Checks** — lint, test, build — zero errors (see **codebase-tool** skill)
+3. **Blast Radius** — ≤200 lines / ≤5 files normal; escalate if >500 lines or >10 files
+4. **Dependency Audit** — when `package.json` changes
+5. **Fast Review** (MANDATORY) — single reviewer sub-agent
+6. **Browser Testing** (MANDATORY for UI) — clear cache, verify features + responsive + screenshots
+7. **Regression Testing** — full suite for affected projects
+8. **Panel Review** — for security, DB migrations, architecture (use **panel-majority-vote** skill)
+9. **Final Smoke Test** — end-to-end verification of complete feature
 
 ### 5. Delivery
 
-Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
-
-> The convoy engine creates commits on the configured `branch` directly. After validation passes, open the PR from that branch. No additional commits from the Team Lead are needed unless gates failed and required manual fixes.
+Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker. The convoy engine creates commits on the configured `branch` directly; open the PR from that branch after validation passes.
 
 ### 6. Documentation & Traceability
 
-Keep documentation current so future sessions have full context:
-
-1. **Update roadmap** — Mark completed items in `.opencastle/project/roadmap.md` with ✅ and the completion date. **Include tracker issue IDs and links** next to each scope item so progress is traceable across sessions. Format:
-   ```
-   **Tracker Issues:**
-   - [PREFIX-6](<tracker-url>/PREFIX-6) — [Search] Description ✅ Done
-   - [PREFIX-7](<tracker-url>/PREFIX-7) — [UI] Description 📋 Todo
-   ```
-   > Replace `PREFIX` with the project's issue prefix (see `tracker-config.md`).
-2. **Update known issues** — If new limitations are discovered, add them to `.opencastle/KNOWN-ISSUES.md`
-3. **Update architecture docs** — If architectural decisions were made, add an ADR to `.opencastle/project/decisions.md`
-4. **Link tracker issues** — Every issue description should reference:
-   - Related roadmap section
-   - Files modified (the partition)
-   - Related issues (dependencies and follow-ups)
+1. **Update roadmap** — Mark completed items with ✅ and date; include tracker issue IDs next to each scope item (e.g., `[PREFIX-6](<url>) — Description ✅ Done`)
+2. **Update known issues** — Add new limitations to `.opencastle/KNOWN-ISSUES.md`
+3. **Update architecture docs** — Add ADRs for architectural decisions to `.opencastle/project/decisions.md`
+4. **Link tracker issues** — Reference roadmap section, partition files, and related issues in each description
 5. **Close issues properly** — Move to Done only after independent verification passes all gates
 
 ### 7. Completion Criteria
@@ -132,11 +98,8 @@ Keep documentation current so future sessions have full context:
 The roadmap task is complete when:
 
 - [ ] All tracker subtask issues are Done
-- [ ] All deterministic checks pass (lint, test, build) for affected projects
-- [ ] **Dev server started with CLEAN cache** (clear framework + task runner caches before serving — see the **codebase-tool** skill)
 - [ ] **All UI changes verified in Chrome browser via MCP with screenshots taken as proof**
 - [ ] **Every feature in the acceptance criteria visually confirmed** — not just "page loads"
-- [ ] Regression tests confirm no existing functionality is broken
 - [ ] No duplicated code — shared logic extracted to libraries
 - [ ] Visual consistency maintained across all affected pages and apps
 - [ ] Documentation updated (roadmap, known issues, decisions)

package/src/orchestrator/prompts/quick-refinement.prompt.md

@@ -31,68 +31,45 @@ You are the Team Lead. Handle the follow-up refinement described below. This is
 
 ### 1. Triage: Decide Tracking Level
 
-Before doing anything, decide whether this follow-up needs issue tracking:
-
 **Create a tracker issue if ANY of these are true:**
-- The change affects user-visible behavior (not just cosmetic)
-- It touches more than 2–3 files
-- It modifies shared library code (`libs/`)
-- It changes data queries, API routes, or Server Actions
-- It could introduce regressions in other features
-- You want a record for future reference (e.g., "why was this changed?")
+- Affects user-visible behavior, touches >2–3 files, or modifies `libs/`, queries, API routes, or Server Actions
+- Could introduce regressions in other features
+- You want a record for future reference
 
 **Skip tracking if ALL of these are true:**
-- Pure cosmetic/spacing/copy tweak
+- Pure cosmetic/spacing/copy change with no behavioral impact
 - Isolated to a single component or page
-- No behavioral change
 - Trivial to verify visually
 
-If creating a tracker issue, use:
-- **Title**: `[Follow-up] Short description`
-- **Label**: agent name + `follow-up`
-- **Priority**: Low or Medium
-- **Description**: What changed, why, and which files
+If creating: title `[Follow-up] Short description`, label `follow-up`, priority Low/Medium, description: what changed, why, files
 
 ### 2. Understand the Request
 
-Before touching any code:
-
 1. **Clarify scope** — Identify exactly which pages, components, or behaviors need to change
 2. **Find affected files** — Search the codebase for the relevant components, styles, queries, and tests
 3. **Check known issues** — Scan `.opencastle/KNOWN-ISSUES.md` in case this is a documented limitation
 4. **Read lessons learned** — Check `.opencastle/LESSONS-LEARNED.md` for relevant pitfalls before starting
-5. **Assess complexity** — If the request turns out to be larger than expected (touches >5 files, needs a migration, or affects auth/security), escalate it:
-   - Inform the user that this should be a tracked task
-   - Create a tracker issue (if not already created in triage) and switch to the `implement-feature` workflow
+5. **Assess complexity** — If larger than expected (>5 files, migration, or auth/security), inform the user, create a tracker issue, and switch to the `implement-feature` workflow
 
 ### 3. Plan the Fix
 
-Think before you act:
-
-1. **Identify root cause** — For bugs, find why it happens, not just where. For UI tweaks, understand the current styling/layout chain
-2. **Check for shared impact** — Will the fix affect other pages or apps? Check component usage across the codebase
-3. **Determine the minimal change** — Follow the principle of least surprise. Change only what's necessary
-4. **Reuse existing patterns** — Use components, utilities, and styles that already exist in the codebase. Never introduce a new pattern for a one-off fix
+1. **Identify root cause** — For bugs, find why; for UI tweaks, understand the styling/layout chain
+2. **Assess shared impact** — Will the fix affect other pages or apps? Check component usage across the codebase
+3. **Minimal change** — Reuse existing components, utilities, and styles. Never introduce a new pattern for a one-off fix
 
 ### 4. Implement
 
-Delegate to the appropriate specialist agent(s). Since follow-ups are scoped and focused, prefer **sub-agents** (inline) over background agents.
-
 #### Delegation Prompt Must Include
 
-- **What to fix** — clear description of the problem and desired outcome
-- **Where** — exact file paths to read and modify
-- **How to verify** — what the result should look like or how to test it
-- **Boundaries** — "Only modify files listed above. Do not refactor unrelated code."
-- **Self-improvement reminder** — include per the **self-improvement** skill
+- What to fix, exact file paths, and how to verify the result
+- Boundaries: "Only modify files listed above. Do not refactor unrelated code."
+- Self-improvement reminder (see **self-improvement** skill)
 
 #### Implementation Rules
 
-- **No scope creep** — Fix what was asked. If you notice other issues, note them but don't fix them in this pass
-- **DRY** — Search before creating. Reuse existing components and utilities
-- **Visual consistency** — Match the existing design system (spacing, colors, typography)
-- **Cross-app check** — If the change is in shared code (`libs/`), verify it works for both apps
-- **Accessibility** — Don't regress keyboard navigation, screen reader support, or contrast ratios
+- **No scope creep** — Fix only what was asked; note but don't fix adjacent issues
+- **DRY + Visual consistency** — Reuse existing components, utilities, and design system patterns
+- **Cross-app + Accessibility** — Verify `libs/` changes across apps; don't regress keyboard nav/contrast
 
 ### 5. Validate
 
@@ -100,46 +77,34 @@ Delegate to the appropriate specialist agent(s). Since follow-ups are scoped and
 
 Every follow-up, no matter how small, must pass these gates:
 
-1. **Gate 1: Secret Scanning** — scan diff for API keys, tokens, passwords, connection strings — block immediately if found
-2. **Gate 2: Deterministic Checks** — run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands) — all zero errors
-3. **Gate 3: Blast Radius Check** — verify scope matches the "small follow-up" expectation (≤100 lines, ≤3 files normal; if larger, escalate to `implement-feature` workflow)
-4. **Gate 4: Dependency Audit** (when `package.json` or lockfiles change) — vulnerability scan, license check, bundle size, duplicates
-5. **Gate 5: Fast Review** (MANDATORY) — single reviewer sub-agent validates the change. No auto-PASS for sensitive files
-6. **Gate 6: Browser Testing** (MANDATORY for any visual change) — clear cache, start server, verify scenario + responsive + screenshot evidence
-7. **Gate 7: Regression Testing** — if shared component/library modified, run tests for all consuming projects and browser-test at least one page per affected app
+1. **Secret Scanning** — block if API keys/tokens/passwords found in diff
+2. **Deterministic Checks** — lint, test, build — zero errors (see **codebase-tool** skill)
+3. **Blast Radius** — ≤100 lines / ≤3 files for follow-ups; if larger, escalate to `implement-feature`
+4. **Dependency Audit** — when `package.json` or lockfiles change
+5. **Fast Review** (MANDATORY) — single reviewer sub-agent
+6. **Browser Testing** (MANDATORY for visual changes) — clear cache, verify + responsive + screenshots
+7. **Regression Testing** — if shared component/library modified, test all consuming projects
 
 ### 6. Delivery
 
-If triage determined this follow-up needs tracker tracking, follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
+If tracked: follow the **Delivery Outcome** in the **git-workflow** skill — commit, push, open PR (not merged), tracker linked.
 
-If triage determined no tracker tracking is needed (pure cosmetic/isolated/trivial), commit the changes to the current working branch. A dedicated branch and PR are not required because the Team Lead will include these changes in the parent task's existing PR — the "every change goes through a PR" rule is still satisfied via the parent PR.
+If untracked: commit to the current branch; Team Lead includes in the parent task's existing PR.
 
 ### 7. Escalation Triggers
 
-Stop the follow-up workflow and switch to a full roadmap task if:
-
-- The fix requires a **database migration**
-- The fix involves **authentication or authorization** changes
-- The fix touches **more than 5 files** across multiple libraries
-- The fix introduces a **new dependency** or **new API endpoint**
-- The fix changes **data models** (CMS schemas, database tables)
-- You discover the "small fix" is actually a **systemic issue** requiring architectural changes
-
-When escalating, explain to the user what you found and why it needs proper tracking.
-
-- **Multi-task escalation** — If the refinement decomposes into 3+ subtasks, switch to `implement-feature` (which will use convoy execution for multi-task work)
+- Requires a database migration or data model changes (CMS schemas, tables)
+- Involves auth/authorization changes
+- Touches >5 files across multiple libraries
+- Introduces a new dependency or API endpoint
+- Is a systemic issue requiring architectural changes
+- Decomposes into 3+ subtasks → switch to `implement-feature`
 
 ### 8. Completion
 
-The follow-up is complete when:
-
 - [ ] The specific request is resolved
 - [ ] Tracker issue created and moved to Done (if triage determined tracking was needed)
-- [ ] Lint, test, and build pass for all affected projects
-- [ ] **Dev server started with CLEAN cache** (clear framework + task runner caches before serving — see the **codebase-tool** skill)
 - [ ] **Visual changes verified in Chrome with screenshot taken as proof**
-- [ ] No regressions in adjacent functionality
 - [ ] Shared component changes tested across all consuming apps
 - [ ] Delivery Outcome completed if tracked (see the **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
-- [ ] Lessons learned captured if any retries occurred
-- [ ] Known issues updated if a new limitation was discovered
+- [ ] Lessons learned captured and known issues updated if applicable

package/src/orchestrator/skills/accessibility-standards/SKILL.md

@@ -3,164 +3,109 @@ name: accessibility-standards
 description: "WCAG 2.2 Level AA accessibility patterns for React/HTML/CSS. Use when creating or modifying UI components, forms, navigation, tables, images, or any user-facing elements. Covers keyboard navigation, screen reader semantics, low vision contrast, voice access, and inclusive language."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Accessibility Standards
 
-Code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/). Go beyond minimal conformance wherever possible.
-
-## Workflow
+Code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/).
 
-1. Before generating code, plan how to implement it accessibly.
-2. After generating code, review against WCAG 2.2 and these patterns. Iterate until compliant.
-3. Inform the user the code was built with accessibility in mind but may still have issues. Suggest [Accessibility Insights](https://accessibilityinsights.io/) for testing.
+**Workflow:** Plan accessible implementation → generate → review against WCAG 2.2 → iterate. Suggest [Accessibility Insights](https://accessibilityinsights.io/) for testing.
 
-## Inclusive Language
-
-- Use people-first language ("person using a screen reader," not "blind user").
-- Avoid stereotypes or assumptions about ability.
-- Flag uncertain implementations — include reasoning or references to standards.
+**Language:** People-first ("person using a screen reader," not "blind user"). No ability stereotypes. Flag uncertain implementations with reasoning.
 
 ## Cognitive
 
-- Prefer plain language.
-- Use consistent page structure (landmarks) across the application.
-- Keep navigation items in the same order across pages.
-- Keep the interface clean — reduce unnecessary distractions.
+Plain language; consistent landmarks and nav order across pages; minimal distractions.
 
 ## Keyboard
 
-- All interactive elements must be keyboard navigable with predictable focus order (reading order).
-- Focus must be clearly visible at all times.
-- All interactive elements must be operable (buttons, links, dropdowns, etc.).
-- Static (non-interactive) elements should NOT have `tabindex`. Exception: elements receiving programmatic focus (e.g., headings) get `tabindex="-1"`.
-- Hidden elements must not be keyboard focusable.
+- All interactive elements keyboard-navigable with visible focus in reading order.
+- No `tabindex` on static elements; `tabindex="-1"` only for elements receiving programmatic focus.
+- Hidden elements must not be focusable.
 
-### Composite Components (grids, listboxes, menus, tabs, toolbars)
+**Composite components** (grids, listboxes, menus, tabs, toolbars): tab stop on container; arrow keys navigate children via roving tabindex or `aria-activedescendant`; on focus restore last/first child.
 
-- Tab stop on the container with appropriate interactive role.
-- Arrow keys navigate children (roving tabindex or `aria-activedescendant`).
-- On focus: show selected child, or previously focused child, or first interactive child.
+**Roving tabindex:** First child `tabindex="0"`, rest `-1`; on arrow key set prev to `-1`, new to `0`, call `.focus()`.
 
-### Bypass Blocks
+**`aria-activedescendant`:** Container `tabindex="0"` + `aria-activedescendant="IDREF"`; CSS draws outline on referenced element; arrow keys update attribute.
 
-Provide "Skip to main" link as first focusable element:
+**Skip link** (first focusable element):
 
 ```html
-<header>
-  <a href="#maincontent" class="sr-only">Skip to main</a>
-</header>
+<a href="#maincontent" class="sr-only">Skip to main</a>
 <main id="maincontent"></main>
 ```
 
 ```css
-.sr-only:not(:focus):not(:active) {
-  clip: rect(0 0 0 0);
-  clip-path: inset(50%);
-  height: 1px;
-  overflow: hidden;
-  position: absolute;
-  white-space: nowrap;
-  width: 1px;
-}
+.sr-only:not(:focus):not(:active) { clip: rect(0 0 0 0); clip-path: inset(50%); height: 1px; overflow: hidden; position: absolute; white-space: nowrap; width: 1px; }
 ```
 
-### Common Keys
-
 | Key | Action |
 |-----|--------|
 | `Tab` | Next interactive element |
 | `Arrow` | Navigate within composite component |
 | `Enter` | Activate focused control |
-| `Escape` | Close open surfaces (dialogs, menus) |
-
-### Roving Tabindex Pattern
-
-1. Initial: `tabindex="0"` on first focusable child, `tabindex="-1"` on rest.
-2. On arrow key: set previous to `-1`, new target to `0`, call `element.focus()`.
-
-### `aria-activedescendant` Pattern
-
-- Container has `tabindex="0"` and `aria-activedescendant="IDREF"`.
-- CSS draws focus outline on referenced element.
-- Arrow keys update `aria-activedescendant`.
+| `Escape` | Close dialogs/menus |
 
 ## Low Vision
 
-- Dark text on light backgrounds (or vice versa).
-- Text contrast ≥4.5:1 (≥3:1 for large text: 18.5px bold or 24px).
-- Graphics/controls contrast ≥3:1 with adjacent colors.
-- Control state indicators (pressed, focus, checked) ≥3:1 contrast.
-- Color must NOT be the only way to convey information — use text/shapes in addition.
+| Rule | Requirement |
+|------|-------------|
+| Text contrast | ≥4.5:1 (≥3:1 for large text: 18.5px bold / 24px) |
+| Graphics/controls | ≥3:1 with adjacent colors |
+| State indicators (pressed, focus, checked) | ≥3:1 |
+| Color | Never the sole conveyor of information |
 
 ## Screen Reader
 
-- All elements must convey correct semantics (name, role, value, states/properties). Prefer native HTML; use ARIA when necessary.
-- Use landmarks: `<header>`, `<nav>`, `<main>`, `<footer>`.
-- Use headings (`<h1>`–`<h6>`) to introduce sections. One `<h1>` per page. Avoid skipping levels.
+- Correct semantics (name, role, value, states). Prefer native HTML; ARIA only when necessary.
+- Landmarks: `<header>`, `<nav>`, `<main>`, `<footer>`.
+- One `<h1>` per page; `<h1>`–`<h6>` introduce sections; no skipping levels.
 
 ## Voice Access
 
-- Accessible name of interactive elements must contain the visual label (so voice users can say "Click [label]").
-- `aria-label` must contain the visual label text.
+- Interactive element accessible name must contain its visible label text.
+- `aria-label` must include the visible label.
 
 ## Forms
 
-- Labels must accurately describe control purpose.
+- Labels accurately describe control purpose.
 - Required fields: asterisk in label + `aria-required="true"`.
-- Errors: `aria-invalid="true"` on invalid fields. Error messages via `aria-describedby`.
-- Inline errors next to fields (common) or form-level errors at top identifying specific fields.
-- Submit buttons should NOT be disabled — trigger error messages instead.
-- On submit with invalid input, focus the first invalid field.
+- Errors: `aria-invalid="true"` + `aria-describedby` pointing to error message.
+- Don't disable submit — show errors instead; focus first invalid field on submit.
 
-## Graphics and Images
+## Images
 
-- All graphics must have correct role (`<img>` implicit, `<svg>` needs `role="img"`, icon fonts/emojis need `role="img"` on `<span>`).
-- **Informative**: `alt` text conveying meaning/purpose (concise, meaningful). Avoid `title` attribute.
-- **Decorative**: `alt=""` for `<img>`, `aria-hidden="true"` for `role="img"`.
+| Type | Pattern |
+|------|---------|
+| Informative | `alt="[meaning]"` on `<img>`; `role="img"` + `aria-label` on `<svg>` / icon fonts |
+| Decorative | `alt=""` on `<img>`; `aria-hidden="true"` on `role="img"` |
 
 ## Input Labels
 
-- All interactive elements need visual labels.
-- `<label for="id">` for form inputs.
-- Multiple controls with same label (e.g., "Remove"): use `aria-label` for disambiguation.
-- Help text: associate via `aria-describedby`.
+- `<label for="id">` for form inputs; all interactive elements need visible labels.
+- Disambiguate repeated labels (e.g., "Remove") with `aria-label`.
+- Help text via `aria-describedby`.
 
 ## Navigation
 
 ```html
-<nav>
-  <ul>
-    <li>
-      <button aria-expanded="false" tabindex="0">Section 1</button>
-      <ul hidden>
-        <li><a href="..." tabindex="-1">Link 1</a></li>
-      </ul>
-    </li>
-    <li>
-      <button aria-expanded="false" tabindex="-1">Section 2</button>
-      <ul hidden>
-        <li><a href="..." tabindex="-1">Link 1</a></li>
-      </ul>
-    </li>
-  </ul>
-</nav>
+<nav><ul>
+  <li><button aria-expanded="false" tabindex="0">Section 1</button>
+    <ul hidden><li><a href="..." tabindex="-1">Link 1</a></li></ul>
+  </li>
+</ul></nav>
 ```
 
-- Navigation menus use `<nav>` with `<ul>`, NOT `menu`/`menubar` roles.
-- Toggle `aria-expanded` on expand/collapse.
-- Roving tabindex for main items (arrow across), arrow down into sub-menus.
-- `Escape` closes expanded menus.
+- Use `<nav>` + `<ul>`, NOT `menu`/`menubar` roles.
+- Toggle `aria-expanded` on expand/collapse; `Escape` closes menus.
+- Roving tabindex across main items; arrow down into sub-menus.
 
 ## Page Title
 
-- Defined in `<title>` in `<head>`.
-- Describes page purpose, unique per page.
-- Front-load unique information: `"[Page] - [Section] - [Site]"`.
+- `<title>` describes page purpose, unique per page.
+- Front-load unique info: `"[Page] - [Section] - [Site]"`.
 
-## Tables and Grids
+## Tables & Grids
 
-- Column headers via `<th>` in first `<tr>`. Row headers via `<th>` in each row.
-- `role="gridcell"` must be nested within `role="row"`.
-- Prefer simple tables (one set of headers, no spanning cells).
-- Use `<table>` for static data, `role="grid"` for interactive data (date pickers, calendars).
+- Column headers: `<th>` in first `<tr>`; row headers: `<th>` in each row.
+- `role="gridcell"` nested within `role="row"`.
+- `<table>` for static data; `role="grid"` for interactive (date pickers, calendars).