@mohammadhprp/system-prompt 0.11.2 → 0.12.1

package/framework/skills/effective-html/references/html-prototype.md

@@ -0,0 +1,97 @@
+# HTML Prototype
+
+Build a credible model of a product decision. Match the artifact to the user's context instead of applying a recurring house style. The goal is not to make every possible screen. The goal is to make the important visual or behavioral question testable.
+
+## Choose the fidelity mode
+
+Use one of two modes:
+
+- **Mockup:** Create a polished, responsive, mostly static artifact when the open question is visual hierarchy, layout, typography, color, or product fit.
+- **Prototype:** Create a working flow when the open question is navigation, input, state change, feedback, recovery, or transition.
+
+Do not create a separate `html-mockup` skill. Do not add behavior merely to make a mockup seem more complete. If a user asks for both modes, preserve the same content and structure so changes in fidelity remain easy to compare.
+
+## Derive the direction from context
+
+Inspect the conversation, supplied references, and project before designing. Look for design-system documentation, tokens, existing components, product screenshots, and nearby artifacts.
+
+Authority runs in this order:
+
+1. The user's explicit visual and functional instructions.
+2. The project's established design language and interaction conventions.
+3. The product, audience, content, and scenario.
+4. Your own design judgment.
+
+Before coding, settle:
+
+- the user and critical job;
+- the bounded scenario under review;
+- mockup or prototype mode;
+- the source of the visual direction;
+- the relevant state model;
+- the point where the real product would take over.
+
+When no design system exists, create a specific direction from the subject and use case. Do not default to a gradient, a dark dashboard, interchangeable cards, or decorative metrics. A prototype for a field tool, an editorial workflow, and a financial approval should not feel like the same product.
+
+When [`design-artifact`](design-artifact.md) is available and the visual
+direction remains open, read and compose it with this skill. Use it to choose
+the register, palette, type, and composition; keep this skill authoritative for
+fidelity, state, and interaction completeness.
+
+## Scope one credible experience
+
+Choose the smallest flow that can answer the review question. Use realistic, internally consistent names, dates, statuses, quantities, and copy.
+
+- Make navigation work for the modeled scope.
+- Implement forms with labels, validation, submission feedback, and sensible defaults.
+- Use dialogs only when interruption or confirmation is part of the scenario.
+- Use transitions to clarify continuity or state change, not as decoration.
+- Remove dead buttons. If an action belongs to the real system, explain the boundary instead of pretending it completed.
+
+## Model relevant states
+
+List the states before building. Include the states that the chosen scenario can actually reach:
+
+- loading;
+- empty;
+- error;
+- success;
+- disabled;
+- mobile;
+- domain-specific states from the brief.
+
+An asynchronous-looking prototype action should normally show loading, success, and failure or recovery. A collection should normally consider empty state. A gated action should show why it is disabled. Do not force irrelevant states into the main flow just to satisfy a checklist. Make omitted states explicit in the handoff.
+
+## Make interaction complete
+
+- Use native elements when they provide the right semantics.
+- Support the entire modeled flow with a keyboard.
+- Keep focus visible and place it deliberately after meaningful transitions.
+- Give dialogs an accessible name, contain focus, close on `Escape`, and restore focus to the trigger.
+- Associate form errors with their controls and announce important status changes.
+- Do not hide essential behavior behind hover.
+- Respect `prefers-reduced-motion` while preserving state feedback.
+- Make touch targets usable and prevent accidental page-level horizontal overflow.
+
+In mockup mode, preserve semantic structure and visible focus styles even if the controls are not wired. Make the static review boundary clear.
+
+## Build contract
+
+- Deliver one self-contained `.html` file with essential CSS and JavaScript inline.
+- Require no build tooling, authentication, live API, or external service.
+- Use a responsive composition rather than shrinking a desktop canvas.
+- Keep design tokens small and specific to the chosen direction.
+- Use accessible contrast and more than color alone to communicate state.
+- Prefer depth and correctness in one flow over breadth across a fake product.
+
+## Verify and hand off
+
+Test the artifact at wide desktop and narrow mobile widths. Exercise every modeled state and control. Test `Tab`, `Shift+Tab`, `Enter`, `Space`, arrow keys where appropriate, and `Escape` for dialogs. Check the console, page overflow, long content, disabled behavior, focus restoration, and reduced-motion mode.
+
+Inspect computed foreground and background colors on every distinct surface, especially text that may inherit the body color inside a dark or tinted region. If browser tooling is unavailable, say which visual and interaction checks remain unverified instead of treating source inspection as a substitute.
+
+Return the absolute file path, the fidelity mode, the scenario modeled, the states implemented, and the production behavior deliberately left out.
+
+## Further reading
+
+Read Plannotator's [HTML wireframes and prototypes for coding agents](https://docs.plannotator.ai/learn/code-context/html-wireframes-and-prototypes-for-coding-agents) for guidance on moving from an approved structure to a mockup or working prototype.

package/framework/skills/effective-html/references/html-wireframe.md

@@ -0,0 +1,81 @@
+# HTML Wireframe
+
+Turn a product question into a low-fidelity HTML artifact that is easy to inspect, change, and discuss. The wireframe should help reviewers decide what belongs on the screen and how the task should work. It should not look like a finished product.
+
+## Establish the review question
+
+Read the conversation, supplied brief, and nearby project material before choosing a layout. Reuse the project's vocabulary, content model, and known product constraints.
+
+Authority runs in this order:
+
+1. The user's explicit instructions and accepted decisions.
+2. The product's existing structure and terminology.
+3. The user, task, and content being modeled.
+4. Your own layout judgment.
+
+Before coding, identify:
+
+- the user and the job they need to complete;
+- the screen or bounded flow under review;
+- the information and actions the artifact must contain;
+- the assumptions that can be made safely;
+- the structural questions the wireframe should help answer.
+
+Use real labels and representative content. Low fidelity is not permission to use anonymous boxes or lorem ipsum where wording affects the layout.
+
+## Explore structure before style
+
+When [`design-artifact`](design-artifact.md) is available, read it for
+subject-specific composition and hierarchy guidance without importing editorial
+polish. This skill's low-fidelity contract remains authoritative.
+
+When the layout is still unsettled, create two or three meaningfully different directions. Vary product decisions such as:
+
+- navigation model;
+- grouping and order;
+- primary-action placement;
+- content density;
+- overview versus step-by-step flow;
+- desktop-to-mobile reflow.
+
+Do not call color changes or minor card rearrangements separate directions. Give each direction a short descriptive name and one sentence about its tradeoff.
+
+Keep the directions in one HTML file when practical. Use a small, keyboard-operable selector so reviewers can compare them without opening several files. Preserve the same core content and task across directions. If the user has already chosen a structure, build that direction only.
+
+## Keep the artifact intentionally unfinished
+
+- Use a restrained grayscale palette, system type, plain borders, and simple blocks.
+- Avoid brand colors, gradients, shadows, illustrations, decorative imagery, and polished component styling.
+- Use limited radius and spacing. Enough order should be present to judge hierarchy, but not enough polish to invite a brand review.
+- Show images or rich media as labeled placeholders unless the asset changes a structural decision.
+- Add annotations only when they expose an assumption, open question, or behavior that cannot be shown directly.
+
+The wireframe may still be well composed. Intentional unfinishedness is different from careless spacing, illegible type, or broken responsive behavior.
+
+## Add only useful behavior
+
+Use basic click-through behavior when it helps test navigation, disclosure, or a short task flow. Keep it immediate and plain.
+
+- Make links, tabs, and next or back actions work when they are part of the review.
+- Use native controls and visible keyboard focus.
+- Do not build elaborate animation, persistence, simulated APIs, or production state management.
+- Remove controls that have no review purpose, or label them clearly as out of scope.
+
+## Build contract
+
+- Deliver one self-contained `.html` file with essential CSS and JavaScript inline.
+- Require no build tooling or external service.
+- Use semantic landmarks, headings, lists, forms, and buttons.
+- Make the layout useful at wide desktop and narrow mobile widths.
+- Keep the page free of accidental horizontal overflow.
+- Respect the source material. Do not invent extra product scope to fill space.
+
+## Verify and hand off
+
+Open the result at desktop and mobile widths. Check reading order, wrapping, overflow, focus visibility, and every implemented click path. Confirm that the directions remain structurally distinct at both sizes.
+
+Return the absolute file path, the names and tradeoffs of the directions, and the visual decisions deliberately deferred to a later mockup or prototype.
+
+## Further reading
+
+Read Plannotator's [HTML wireframes and prototypes for coding agents](https://docs.plannotator.ai/learn/code-context/html-wireframes-and-prototypes-for-coding-agents) for guidance on what to decide at the wireframe stage.

package/framework/skills/effective-html/references/html.md

@@ -0,0 +1,72 @@
+# HTML
+
+Build one self-contained HTML file that makes the subject clearer, easier to use, or easier to understand. The standard is consistent care, not a consistent look. Do not reproduce a house palette, typography stack, card system, or layout from prior runs.
+
+## Route the request first
+
+Use the narrowest skill that owns the main review question:
+
+- Read and compose [`design-artifact`](design-artifact.md) with the
+  chosen workflow when palette, type, composition, theming, or overall visual
+  register remain open. It provides creative direction; it does not replace the
+  specialist that owns fidelity, structure, or behavior.
+- Read and follow [`html-wireframe`](html-wireframe.md) when structure, information hierarchy, navigation, or task flow is still unsettled. It should remain visibly low fidelity and may compare two or three layout directions.
+- Read and follow [`html-prototype`](html-prototype.md) when the user needs a polished mockup or a working interactive flow. A mockup is the static fidelity mode inside that skill.
+- Read and follow [`html-plan`](html-plan.md) when the artifact is primarily a plan, roadmap, implementation sequence, or rollout document whose source commitments must remain easy to verify.
+- Read and follow [`html-diagram`](html-diagram.md) when relationships, sequence, topology, state, hierarchy, or system behavior are the main content.
+- Continue with `html` for reports, explainers, presentations, landing pages, data stories, tools, and mixed artifacts that do not have a clearer owner.
+
+These sibling links are the nesting mechanism when the collection is installed together. If a specialized skill is unavailable, continue here and load the closest reference below. Do not make the user install another skill before completing the request.
+
+## Read the room before designing
+
+Inspect the user's request and any material they supplied. When working in a repository, look for its design language in `AGENTS.md`, `CLAUDE.md`, design-system documentation, tokens, existing components, and nearby artifacts.
+
+Authority runs in this order:
+
+1. The user's explicit visual and functional instructions.
+2. The project's established design system and conventions.
+3. The subject matter, audience, and purpose of this artifact.
+4. Your own design judgment.
+
+Before coding, settle five things in working notes:
+
+- **Audience and job:** who will use this, and what should they understand or do?
+- **Form:** document, presentation, interface, diagram, or data visualization.
+- **Register:** quiet and workmanlike, polished and editorial, or intentionally expressive.
+- **Fidelity:** whether to preserve the user's structure and wording or synthesize more freely.
+- **Interaction:** what benefits from exploration, sequencing, filtering, or motion, if anything.
+
+If the project already answers the visual questions, follow it. Otherwise read
+and compose [`design-artifact`](design-artifact.md) when it is
+available. If the collection was installed without that sibling skill, read
+   [`creative-direction.md`](creative-direction.md) before
+choosing the palette, type, composition, or motion.
+
+## Load only the guidance the artifact needs
+
+- For reports, briefs, plans, explainers, and decks, read [`documents-and-presentations.md`](documents-and-presentations.md).
+- For interfaces, calculators, and other tools that remain in this broad skill, read [`interfaces.md`](interfaces.md).
+- For architecture, process, sequence, state, hierarchy, or concept diagrams, read [`diagrams.md`](diagrams.md).
+- For quantitative charts, tables, metrics, or data stories, read [`charts-and-data.md`](charts-and-data.md).
+
+Requests can span forms. Read every reference that materially applies, then give the artifact one coherent direction.
+
+## Build contract
+
+- Produce one `.html` file with its essential CSS and JavaScript inline. It should work when opened directly, without a build step. Do not require a network connection unless the user permits external dependencies.
+- Use real content. Do not fill prominent space with placeholder copy, decorative statistics, or controls that do nothing.
+- Let content determine structure. A sequence should read in order; a comparison should make differences easy to scan; an interface should expose state and actions; a diagram should make relationships legible.
+- Use semantic HTML, responsive layout, accessible contrast, visible keyboard focus, and reduced-motion handling. Make interactive elements work with a keyboard.
+- Keep the page body free of accidental horizontal overflow. Put intentionally broad content in a contained scrolling or pannable region.
+- Define a small set of CSS tokens for the chosen direction and use them consistently. Tokens are an implementation tool, not a predetermined palette.
+- Treat motion as explanation or feedback. If removing an animation loses no meaning or useful feedback, remove it.
+- Follow the user's or project's theme policy. When none exists, give durable utility artifacts considered light and dark themes if that improves their use. A deliberate single-theme concept is valid.
+
+## Finish the work
+
+Write the file to the requested location, or choose a clear filename in the current workspace. When browser tooling is available, open it and inspect a wide and narrow viewport. Exercise its controls, check the console, and fix clipping, overlap, illegible text, broken states, and accidental overflow.
+
+Before delivery, run one originality check: if the subject were swapped for a neighboring topic, would the same visual concept still make just as much sense? If yes, the direction is too generic; revise the composition, type, color, imagery, or interaction so it belongs to this subject.
+
+Return the absolute path and a short description of the artifact's visual and interaction choices.

package/framework/skills/effective-html/references/interfaces.md

@@ -0,0 +1,17 @@
+# Interfaces and tools
+
+Read this for editors, calculators, control panels, and other broad HTML artifacts people operate rather than read straight through. Use `html-prototype` for a styled mockup or a bounded product flow when that skill is available.
+
+Lead with the current state and the next useful action. Organize the interface around the user's task, not the shape of the underlying data model.
+
+- Make controls look actionable and label them with the result they produce.
+- Show feedback close to the action: pending, success, empty, validation, and error states should all be designed.
+- Preserve state visibly. Selected filters, active modes, changed values, and unsaved work should never be mysteries.
+- Put summaries before detail when scanning matters, while keeping the path to the underlying evidence obvious.
+- Use status color for status, independently from the artifact's decorative accent.
+- Keep forms keyboard-friendly, labels explicit, targets comfortably sized, and destructive actions difficult to trigger accidentally.
+- Prefer a few strong regions over a uniform grid of interchangeable cards.
+
+Implement the important path when behavior is part of the request. A convincing static shell with dead controls is worse than a simpler interface whose important path works end to end.
+
+On narrow screens, preserve the primary task. Reflow secondary panels, turn dense toolbars into deliberate controls, and contain wide data rather than shrinking it until it is illegible.

package/framework/skills/great-interface/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: great-interface
+description: >-
+  Build, explain, review, and refine product interfaces across accessibility, layout,
+  writing, typography, color, UI polish, holistic review, change review, and design variants.
+  Use when creating frontend interfaces, reviewing interface quality, explaining how an
+  interface works, or comparing UI directions.
+---
+
+# Great Interface
+
+Use the domain references below as the sources of truth. Load the smallest set that covers
+the request, except for a holistic review, which loads every applicable review domain.
+
+## Build and refine
+
+- Accessibility: [better-accessibility.md](references/better-accessibility.md)
+- Layout: [better-layout.md](references/better-layout.md)
+- Writing: [better-writing.md](references/better-writing.md)
+- Typography: [better-typography.md](references/better-typography.md)
+- Colors: [better-colors.md](references/better-colors.md)
+- UI polish and motion: [better-ui.md](references/better-ui.md)
+
+## Review
+
+- Holistic screen or flow review: [better-interface.md](references/better-interface.md)
+- Change, branch, or pull request review: [interface-review.md](references/interface-review.md)
+
+## Explore alternatives
+
+- Explain how an interface or effect was built: [explain-interface.md](references/explain-interface.md)
+- Build and compare multiple UI directions: [variant.md](references/variant.md)
+
+## Ownership
+
+Do not duplicate rules across domains. Accessibility owns keyboard support, focus, ARIA,
+semantic structure, hit areas, announcements, and reduced motion. Layout owns grouping,
+spacing, responsive structure, and spatial RTL. Writing owns interface copy. Typography owns
+how text renders and wraps. Colors owns palette systems and color measurement. UI owns
+surfaces, icons, and visual motion. The review references own orchestration and reporting.
+
+When domains overlap, report or apply the rule in the owning domain and mention secondary
+effects only where useful.

package/framework/skills/great-interface/references/animations.md

@@ -0,0 +1,205 @@
+# Animations
+
+Interruptible transitions, press feedback and the restraint that decides whether to animate at all. Staged entrances and exits live in [enter-exit.md](enter-exit.md); icon swaps in [icon-transitions.md](icon-transitions.md).
+
+## Interruptible animations
+
+Users change intent mid-interaction. Animations that cannot be interrupted make the interface feel broken.
+
+### CSS transitions vs. keyframes
+
+| | CSS Transitions | CSS Keyframe Animations |
+| --- | --- | --- |
+| **Behavior** | Interpolate toward latest state | Run on a fixed timeline |
+| **Interruptible** | Yes, retargets mid-animation | No, restarts from beginning |
+| **Use for** | Interactive state changes (hover, toggle, open/close) | Staged sequences that run once (enter animations, loading) |
+| **Duration** | Fixed; retargets the value mid-flight, not the timeline | Fixed timeline, restarts from the beginning |
+
+```css
+/* Good: interruptible transition for a toggle */
+.drawer {
+  transform: translateX(-100%);
+  transition: transform 200ms ease-out;
+}
+.drawer.open {
+  transform: translateX(0);
+}
+
+/* Clicking again mid-animation smoothly reverses, no jank */
+```
+
+```css
+/* Bad: keyframe animation for interactive element */
+.drawer.open {
+  animation: slideIn 200ms ease-out forwards;
+}
+
+/* Closing mid-animation snaps or restarts, feels broken */
+```
+
+Prefer CSS transitions for interactive elements. Reserve keyframes for one-shot sequences.
+
+## Scale on press
+
+A subtle scale-down on click gives buttons tactile feedback. Always `scale(0.96)`, never below `0.95`, which feels exaggerated. Use CSS transitions so a release mid-press returns smoothly.
+
+Not every button needs it. Add a `static` prop that disables the scale where the motion would distract.
+
+### CSS example
+
+```css
+.button {
+  transition-property: scale;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.button:active {
+  scale: 0.96;
+}
+```
+
+### Tailwind example
+
+```tsx
+<button className="transition-transform duration-150 ease-out active:scale-[0.96]">
+  Click me
+</button>
+```
+
+### Motion example
+
+```tsx
+<motion.button whileTap={{ scale: 0.96 }}>
+  Click me
+</motion.button>
+```
+
+### Static prop pattern
+
+Extract the scale class into a variable and apply it conditionally on a `static` prop:
+
+```tsx
+const tapScale = "active:not-disabled:scale-[0.96]";
+
+function Button({ static: isStatic, className, children, ...props }) {
+  return (
+    <button
+      className={cn(
+        "transition-transform duration-150 ease-out",
+        !isStatic && tapScale,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// Usage
+<Button>Click me</Button>           {/* scales on press */}
+<Button static>Submit</Button>       {/* no scale */}
+```
+
+## Skip animation on page load
+
+Use `initial={false}` on `AnimatePresence` to stop enter animations firing on first render. An element already in its default state animates on later state changes, not on page load.
+
+### When it works
+
+```tsx
+// Good: icon doesn't animate in on mount, only on state change
+<AnimatePresence initial={false} mode="popLayout">
+  <motion.span
+    key={isActive ? "active" : "inactive"}
+    initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+    animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+    exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+  >
+    <Icon />
+  </motion.span>
+</AnimatePresence>
+```
+
+Works well for icon swaps, toggles, tabs and segmented controls, anything with a default state on page load.
+
+### When it breaks
+
+Never use `initial={false}` where the component relies on its `initial` prop for a first-time enter animation, such as a staggered page hero or a loading state. Removing it skips the entire entrance.
+
+```tsx
+// Bad: initial={false} would skip the staggered page enter entirely
+<AnimatePresence initial={false}>
+  <motion.div initial="hidden" animate="visible" variants={...}>
+    ...
+  </motion.div>
+</AnimatePresence>
+```
+
+Verify the component still looks right on a full page refresh before applying this.
+
+## Suppress transitions on theme switch
+
+Flipping the theme changes `color`, `background-color`, `border-color` and `box-shadow` on nearly every element at once. Everything carrying a transition on those properties animates together, so the switch reads as a slow smear rather than an instant change. Disable transitions for the swap and restore them right after.
+
+Inject a stylesheet that turns off every transition, force a reflow so the new colors commit while it still applies, then drop it on the next frame:
+
+```tsx
+"use client";
+
+import { useEffect } from "react";
+
+export function DisableThemeTransitions() {
+  useEffect(() => {
+    const mql = window.matchMedia("(prefers-color-scheme: dark)");
+
+    const handleChange = () => {
+      const style = document.createElement("style");
+      style.append(
+        document.createTextNode(
+          "*,*::before,*::after{transition:none !important}"
+        )
+      );
+      document.head.append(style);
+
+      const _flushReflow = document.body.offsetHeight;
+
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => style.remove());
+      });
+    };
+
+    mql.addEventListener("change", handleChange);
+    return () => mql.removeEventListener("change", handleChange);
+  }, []);
+
+  return null;
+}
+```
+
+`document.body.offsetHeight` is read for its side effect, forcing a synchronous style flush so the new theme resolves while the override is still in the document and no transition starts. The nested `requestAnimationFrame` removes the override only after that paint, restoring transitions before the next interaction.
+
+That covers the OS-level change. An in-app toggle needs the same treatment around its own flip: apply the override, change the theme, flush, remove. `next-themes` ships this as `disableTransitionOnChange`.
+
+## Motion restraint
+
+Motion is a budget, not a garnish. Three rules decide whether an animation belongs at all:
+
+- **Give high-frequency interactions instant feedback instead of animation.** Every keystroke, every list-row hover, every tab switch in a work tool. Reserve expressive motion for infrequent moments (first load of a view, success states, empty states); high-frequency interactions get instant feedback or the subtlest possible transition (`opacity`/`background-color` at ≤150ms).
+- **Motion is never the only feedback channel.** Every state change an animation communicates stays visible when it doesn't run: a color change, an icon swap, a label. Users with reduced motion enabled and anyone who blinked still need to see what happened.
+- **Brief and precise beats prominent.** Where a shorter, smaller animation says the same thing, use it. When in doubt cut the duration, not the clarity.
+
+```css
+/* Good: high-frequency hover gets a minimal transition */
+.row:hover {
+  background-color: var(--surface-hover);
+  transition: background-color 100ms ease-out;
+}
+
+/* Bad: every hover replays a full entrance */
+.row:hover .row-icon {
+  animation: bounceIn 500ms;
+}
+```
+

package/framework/skills/great-interface/references/better-accessibility.md

@@ -0,0 +1,106 @@
+# Accessibility
+
+Most accessibility is free if you use the platform. Native elements ship with keyboard support, real labels announce themselves and a visible focus ring is one CSS rule.
+
+Write every fix in the project's styling system, and use the exact values below rather than familiar-looking substitutes.
+
+Reviewing means two walks. Keyboard-only, where every flow completes without a mouse. Then screen-reader, where every control announces a name, a role and its state. When unsure, take the platform default over a custom rebuild, and remove ARIA rather than add it.
+
+Contrast measurement and color fixes belong to `better-colors`. Text sizing and iOS input zoom belong to `better-typography`. Spatial RTL layout belongs to `better-layout`.
+
+## Native elements first
+
+The first rule of ARIA: don't use ARIA when a native element exists. `<button>` for actions, `<a href>` for navigation, never `<div onClick>`. A real link must support Cmd/Ctrl/middle-click. No ARIA is better than bad ARIA. See [semantics-and-aria.md]() for landmarks, button-vs-link and disabled states.
+
+## Visible focus rings
+
+Style `:focus-visible`, not bare `:focus`. Keyboard users get a ring and mouse users usually don't. Prefer the browser's unmodified indicator.
+
+A custom ring needs a project focus token or another explicit color. Verify the whole indicator against every adjacent color it crosses, `currentColor` included. Use at least a `2px` solid perimeter or an equivalent visible area. Never use `outline: none` without a verified replacement, and preserve system colors in forced-colors mode. Recipes are in [focus-and-keyboard.md]().
+
+## Full keyboard support
+
+Every pointer interaction needs a keyboard path. Follow the ARIA APG patterns: Escape closes overlays, arrow keys move within composite widgets, Tab moves between widgets, Enter and Space activate.
+
+Use only `tabindex="0"` to join the natural tab order and `tabindex="-1"` for programmatic focus. Positive values break that order. Composite widgets use roving tabindex, where the active item is `0` and every other is `-1`.
+
+## Trap and restore focus
+
+Modals set `inert` on the background content, move focus inside on open and return focus to the trigger on close. Add `overscroll-behavior: contain` so background content doesn't scroll.
+
+## Minimum hit area
+
+WCAG 2.5.8's Level AA baseline is a 24×24 CSS-pixel target, or one of its spacing, equivalent-control, inline, user-agent and essential exceptions. Aim for 44×44px on touch and 40×40px on desktop where density permits. Extend with a pseudo-element when the visible element should stay smaller.
+
+Never let extended hit areas overlap. Give decorative layers `pointer-events: none`, so a glow never swallows the clicks meant for the control beneath it. Sizes and collision rules are in [hit-areas.md]().
+
+## Label and type every control
+
+Every input gets a `<label for>` or a wrapping `<label>`. A placeholder is never a label. Label and control share one hit target, with no dead zone between a checkbox and its text.
+
+Add `autocomplete` with a meaningful `name`, plus the `type` and `inputmode` that summon the right keyboard. Never block paste; users paste passwords and one-time codes. See [forms.md]().
+
+## Errors that announce
+
+Keep submit enabled until the request starts, then disable with a spinner and the original label. Validate on submit. Mark failing fields `aria-invalid="true"`, point `aria-describedby` at the inline error text and focus the first invalid field.
+
+Use native `disabled` when a control is genuinely unavailable. Reach for `aria-disabled="true"` only when it should stay focusable, then block pointer, keyboard and form behavior in code and style the state explicitly.
+
+## Accessible names everywhere
+
+Icon-only buttons need a descriptive `aria-label`. Visible label text must appear in the accessible name. Decorative elements get `aria-hidden="true"`, never on a focusable element.
+
+## Don't rely on color alone
+
+Status needs a redundant cue: an icon, text, or an underline alongside the color. Work out which WCAG contrast requirement applies, then use `better-colors` to measure the rendered pair. When it fails, report the pair and the requirement it misses, and leave the colors alone unless asked.
+
+## Honor prefers-reduced-motion
+
+Wrap motion in `@media (prefers-reduced-motion: no-preference)` so it is opt-in. Under reduced motion, replace slides and scales with opacity crossfades, and kill parallax and autoplay entirely.
+
+Two rules hold regardless of the preference. Autoplaying media needs a visible pause control, and toasts carrying an action or an error stay until dismissed. See [motion-and-zoom.md]().
+
+## Announce dynamic content
+
+Three mechanisms, three jobs. `aria-describedby` carries field-specific validation. A polite live region (`role="status"`) carries non-urgent updates not tied to a control, such as toasts and result counts. `role="alert"` carries urgent untied errors and nothing else.
+
+Repeated polite announcements need a stable empty region rendered before its text updates. Dynamically inserted alerts vary in support, so test them on the screen readers you target. See [screen-readers.md]().
+
+## Alt text by purpose
+
+Decorative images get `alt=""`. Informative images describe the meaning. Functional images describe the action: a search icon button is `alt="Search"`, not `alt="magnifying glass"`.
+
+## Structure is navigation
+
+Use headings that describe their sections and form a coherent outline. Give the page one `<h1>` and nest the levels below it without skipping. Expose one visible primary `<main>` landmark. When repeated navigation or chrome precedes it, make a "Skip to content" link the first focusable element. Anchored headings get `scroll-margin-top`.
+
+## Survive zoom and text resize
+
+The page must work at 200% zoom and reflow at 320px width without horizontal scrolling. Use `min-height` rather than fixed `height` on text containers. Prefer `rem` breakpoints where they fit the codebase, and never let the viewport meta cap how far the reader can zoom.
+
+## Before you finish
+
+| Mistake | Fix |
+| --- | --- |
+| Custom focus color assumed to work everywhere | Verify it against every adjacent color and in forced-colors mode |
+| Repeated polite update inconsistently announced | Keep a stable empty status region and update its text |
+| `assertive` live region for a routine toast | Use `polite`; reserve `assertive` for errors |
+| `aria-hidden="true"` on a focusable element | Remove it or make the element non-focusable |
+| Submit disabled until the form is valid | Keep it enabled; validate on submit and focus the first error |
+| Hover treatment stuck after a tap on touch | Gate hover styling with `@media (hover: hover)` |
+| Tooltip on a natively `disabled` control | Text beside it, or `aria-disabled` so it stays focusable |
+
+## Reporting
+
+**Severity.** `HIGH` prevents a task, hides content from assistive technology, or creates a systemic failure. `MEDIUM` makes an interaction meaningfully harder. `LOW` is isolated polish.
+
+**Verification.** Without a browser: accessible names on every interactive element, keyboard handlers on non-native controls, focus styles, `prefers-reduced-motion` guards and form labels bound to their inputs. With one: tab the flow in order, read computed names and roles from the accessibility tree, confirm a visible focus indicator at every stop and run an automated audit. Report every check you could not run as `Not verified`.
+
+**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
+
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+
+`Location` is `path/to/file:line`. `Why` names the principle and the user impact.
+
+End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable accessibility findings" and report verification.