@mohammadhprp/system-prompt 0.11.2 → 0.12.1

package/framework/skills/great-interface/references/grouping-and-alignment.md

@@ -0,0 +1,123 @@
+# Grouping and alignment
+
+How spacing, shapes, shared edges and ordering communicate what belongs together and what matters most.
+
+## Group with space, not lines
+
+Three tools create grouping, in order of preference:
+
+1. **Negative space**, the default. Related items sit close, unrelated ones far apart.
+2. **Background shapes**, a card or filled container, where a group must read as one unit such as a selectable row or a draggable card.
+3. **Separator lines**, a last resort for dense data where space costs too much, such as tables and long settings lists.
+
+The structural rule is that the gap between groups is at least 2× the gap within one. At `8px` inside a group, groups need `16px`+ between them, or the eye can't tell where one ends.
+
+```css
+/* Good: spacing alone communicates the grouping */
+.field-group { display: flex; flex-direction: column; gap: 8px; }
+.form { display: flex; flex-direction: column; gap: 24px; }
+
+/* Bad: uniform spacing plus lines to compensate */
+.form > * { margin-bottom: 12px; border-bottom: 1px solid var(--separator); }
+```
+
+```html
+<!-- Good: Tailwind -->
+<div class="space-y-6">
+  <div class="space-y-2">…field group…</div>
+  <div class="space-y-2">…field group…</div>
+</div>
+```
+
+Where a separator is genuinely needed, keep it quiet: hairline width, low contrast, never combined with a large gap that already did the job.
+
+## Keep controls distinct from content
+
+Interactive elements need a visual signal: a background, a border, an underline, or placement in a consistent control zone such as a toolbar or footer row. A control styled identically to static text is invisible.
+
+```html
+<!-- Bad: action looks exactly like the description text next to it -->
+<p class="text-zinc-600">Your trial ends soon. Upgrade now</p>
+
+<!-- Good: the action reads as an action -->
+<p class="text-zinc-600">Your trial ends soon.</p>
+<button class="font-medium text-blue-600">Upgrade now</button>
+```
+
+The inverse holds too. A non-clickable badge shaped exactly like the buttons beside it collects dead clicks.
+
+## Align to shared edges
+
+Pick a small set of alignment edges and put everything on them, because the eye tracks straight edges to scan content.
+
+- Every stray edge reads as noise even when nobody can name it: an icon 2px off the text edge, a card padded unlike its neighbor.
+- Use one project spacing step to express hierarchy. `16px` is a useful default where no scale exists, and deeper nesting repeats the same step.
+- Numbers in tables align to the trailing edge, text to the leading edge. Tabular figures are `better-typography`'s.
+
+```css
+/* Good: one shared leading edge, one indent step */
+.section { padding-inline: 24px; }
+.section .child { margin-inline-start: 16px; }
+
+/* Bad: three unrelated leading edges in one column */
+.header { padding-inline-start: 20px; }
+.list-item { padding-inline-start: 14px; }
+.footer { padding-inline-start: 24px; }
+```
+
+## Logical properties, not physical
+
+Express direction-dependent horizontal position as leading/trailing so the layout mirrors automatically under `dir="rtl"`:
+
+| Physical (avoid) | Logical (use) |
+| --- | --- |
+| `margin-left` | `margin-inline-start` |
+| `padding-right` | `padding-inline-end` |
+| `left: 0` | `inset-inline-start: 0` |
+| `text-align: left` | `text-align: start` |
+| `border-right` | `border-inline-end` |
+
+```html
+<!-- Good: Tailwind logical utilities -->
+<div class="ms-4 pe-6 text-start">…</div>
+
+<!-- Bad: breaks in RTL -->
+<div class="ml-4 pr-6 text-left">…</div>
+```
+
+Reserve physical properties for things that refer to physical screen sides whatever the language, such as positioning against a device notch or matching a gesture direction.
+
+Where arrangement encodes progression, as in star ratings, step indicators and progress bars, the sequence mirrors in RTL and stars fill from the trailing side. Flexbox and grid with logical properties mirror automatically; hand-positioned elements do not. Digit order inside numbers never reverses, which with other bidi rules belongs to `better-typography`.
+
+## Order by importance
+
+Readers scan top-to-bottom and leading-to-trailing. Place content accordingly:
+
+- The most important information sits near the top and the leading edge. The further down and trailing something sits, the less attention it gets.
+- Give essential information room. Never bury the one number the user came for under rows of secondary detail. Push that into collapsed sections, tabs, or detail views.
+- Within a row, identifying content leads and metadata and actions trail.
+
+```html
+<!-- Good: primary fact first, detail demoted -->
+<div>
+  <p class="text-2xl font-semibold">$4,320.00</p>
+  <p class="text-sm text-zinc-500">Available balance</p>
+</div>
+
+<!-- Bad: the key fact is buried below the fold of the card -->
+<div>
+  <p class="text-sm">Account 4402 · Opened 2019 · Standard tier</p>
+  <p class="text-sm">Last statement: June 30</p>
+  <p class="text-sm">Balance: $4,320.00</p>
+</div>
+```
+
+With logical properties, the same hierarchy mirrors correctly in RTL locales.
+
+## Don't overload the entry point
+
+The first screenful is a table of contents, not the whole book. If everything is prominent, nothing is:
+
+- One primary action per view. `better-colors` owns how color enforces it.
+- Group secondary actions behind a menu once they exceed two or three.
+- Prefer a short view that links deeper over a long view that shows everything at level one.

package/framework/skills/great-interface/references/hit-areas.md

@@ -0,0 +1,94 @@
+# Hit areas
+
+Target sizes, expanding hit areas without changing visual size and collision rules.
+
+## Target sizes
+
+Separate the conformance baseline from larger usability targets:
+
+| Standard | Minimum |
+| --- | --- |
+| WCAG 2.5.8 (AA) | 24×24px, the hard floor |
+| WCAG 2.5.5 (AAA) | 44×44px |
+| Apple HIG | 44×44pt |
+| Material Design | 48×48dp |
+
+WCAG 2.5.8 Level AA requires a 24×24 CSS-pixel target or one of its exceptions. Treat 44px as the recommended touch target for primary controls and 40px as a useful desktop target where density permits. Smaller controls are not automatic failures. Check the spacing, equivalent-control, inline, user-agent and essential exceptions before reporting one.
+
+Under the spacing exception, an undersized target passes when a 24px circle centered on its bounding box intersects no other target and no other undersized target's circle. In the simple case, 20px targets need a 4px gap.
+
+The visible element can stay small; the hit area is what must be big. Anything that looks clickable must be clickable across its whole visual extent, with no dead zones. A checkbox and its label share one hit target.
+
+## Expanding the hit area
+
+Where the visible element is smaller, say a 20×20 checkbox, extend the hit area with a pseudo-element. Put it on the wrapping `<label>` or `<button>`, never on the `<input>`, because replaced elements don't render `::before`/`::after` reliably.
+
+### CSS example
+
+```css
+/* Small checkbox with expanded 44px hit area, on the wrapping label */
+.checkbox-label {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.checkbox-label::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%; /* physical centering: direction-independent */
+  transform: translate(-50%, -50%);
+  width: 44px;
+  height: 44px;
+}
+```
+
+### Tailwind example
+
+```tsx
+<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-11 after:-translate-1/2">
+  <CheckIcon />
+</button>
+```
+
+### Layout alternative
+
+Where the element can afford real box size, skip the pseudo-element and let the box be the target. That hands the browser real geometry for scrolling and gestures:
+
+```css
+.icon-button {
+  min-width: 44px;
+  min-height: 44px;
+  display: inline-grid;
+  place-items: center;
+}
+```
+
+## Collision rule
+
+Where the extended hit area overlaps another interactive element, shrink the pseudo-element to the largest size that does not collide. Two interactive elements never have overlapping hit areas.
+
+## Decorative layers
+
+A decorative layer painted over interactive content absorbs every pointer event its box covers: a gradient scrim, a glow, a blurred sheen, a full-bleed `::after`. The control underneath looks live and does nothing, and no hit-area sizing fixes it.
+
+Give each one `pointer-events: none` (Tailwind `pointer-events-none`) so events reach the control below, plus `aria-hidden="true"` to keep it out of the accessibility tree:
+
+```css
+.card-glow {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+```
+
+Keep pointer events on any layer the user is meant to hit: a modal scrim that dismisses on click is a control, not decoration.
+
+## Touch behavior
+
+- Add `touch-action: manipulation` to interactive elements to remove the double-tap-to-zoom delay on mobile.
+- Set `touch-action: none` on a surface implementing its own pan, zoom, or drag gestures, so the browser stops claiming them for scrolling and pinch-zoom. Scope it to that surface; at page level it removes scrolling.
+- Set `-webkit-tap-highlight-color` to match the design instead of the default gray flash.
+- Put hover-only styling behind `@media (hover: hover)`. On touch, `:hover` latches after a tap and holds until the user taps elsewhere, so it reads as a stuck selected state. Tailwind 4's `hover:` variant already compiles under this query.
+- Prefer generous targets and clear affordances over finicky interactions such as tiny drag handles and precise hover zones.

package/framework/skills/great-interface/references/icon-transitions.md

@@ -0,0 +1,102 @@
+# Icon transitions
+
+Cross-fading an icon when it changes contextually or by state, with and without a motion library. Icon weight, color and direction live in [icons.md](icons.md).
+
+## Contextual icon animations
+
+When icons appear or disappear contextually, on hover or a state change, animate them with `opacity`, `scale` and `blur` rather than toggling visibility.
+
+### Motion example
+
+This uses the `motion` package. Where the project has `framer-motion`, import the same APIs from `"framer-motion"`. Never mix an installed package with the other's import path.
+
+```tsx
+import { AnimatePresence, motion } from "motion/react";
+
+function IconButton({ isActive, icon: Icon }) {
+  return (
+    <button>
+      <AnimatePresence 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)" }}
+          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
+        >
+          <Icon />
+        </motion.span>
+      </AnimatePresence>
+    </button>
+  );
+}
+```
+
+### CSS transition approach (no Motion)
+
+Without Motion or Framer Motion, keep both icons in the DOM and cross-fade with CSS transitions. Neither unmounts, so enter and exit both animate smoothly.
+
+One icon is absolutely positioned on top of the other. Toggling state cross-fades them, the entering icon scaling up from `0.25` while the exiting one scales down to `0.25`, both with opacity and blur.
+
+```tsx
+function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
+  return (
+    <button>
+      <div className="relative">
+        <div
+          className={cn(
+            "absolute inset-0 flex items-center justify-center",
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-100 opacity-100 blur-0"
+              : "scale-[0.25] opacity-0 blur-[4px]"
+          )}
+        >
+          <ActiveIcon />
+        </div>
+        <div
+          className={cn(
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-[0.25] opacity-0 blur-[4px]"
+              : "scale-100 opacity-100 blur-0"
+          )}
+        >
+          <InactiveIcon />
+        </div>
+      </div>
+    </button>
+  );
+}
+```
+
+The non-absolute icon, `InactiveIcon`, defines the layout size. The absolute one, `ActiveIcon`, overlays it without affecting flow.
+
+### Choosing between Motion and CSS
+
+| | Motion (Framer Motion) | CSS transitions (both icons in DOM) |
+| --- | --- | --- |
+| **Enter animation** | Yes | Yes |
+| **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade, icon never unmounts) |
+| **Spring physics** | Yes | No, use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
+| **When to use** | Project already uses `motion` or `framer-motion` | No motion dependency, or keeping bundle small |
+
+Check the project's `package.json`. Import from `"motion/react"` when `motion` is installed, or `"framer-motion"` when that is. Where both exist, follow the imports the component or its nearest peers already use. Where neither is present, use the CSS cross-fade and never add a dependency just for icon transitions.
+
+### When to animate icons
+
+| Animate | Don't animate |
+| --- | --- |
+| Icons that appear on hover (action buttons) | Static navigation icons |
+| State change icons (play → pause, like → liked) | Decorative icons |
+| Icons in contextual toolbars | Icons that are always visible |
+| Loading/success state indicators | Icon labels (text next to icon) |
+
+Use exactly these values for contextual icon animations. Do not deviate:
+- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
+- `opacity`: `0` → `1`
+- `filter`: `"blur(4px)"` → `"blur(0px)"`
+- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }`; **bounce must always be `0`**, never `0.1` or any other value
+

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

@@ -0,0 +1,110 @@
+# Icons
+
+Icon weight, states, sizing and direction, the details that make icons sit naturally in an interface.
+
+## Match icon stroke to text weight
+
+A hairline icon beside semibold text reads as broken; a heavy icon beside regular text shouts.
+
+| Adjacent text | Icon stroke width (24px grid) |
+| --- | --- |
+| Regular (400), 14–16px | `1.5px` |
+| Medium/Semibold (500–600) | `2px` |
+| Bold (700), or emphasized standalone | `2.5px` |
+
+```html
+<!-- Good: stroke tuned to the label weight -->
+<button class="flex items-center gap-2 font-semibold">
+  <PlusIcon stroke-width="2" class="size-4" />
+  New project
+</button>
+
+<!-- Bad: default 1.5px stroke against a bold label -->
+<button class="flex items-center gap-2 font-bold">
+  <PlusIcon stroke-width="1.5" class="size-4" />
+  New project
+</button>
+```
+
+Two related consistency rules:
+
+- **One optical strategy per surface.** Never mix icon libraries with incompatible stroke conventions on one toolbar. Where the library supports stroke variants, match them to adjacent text as above; otherwise keep the set's native stroke and use size or color for emphasis.
+- **Size icons relative to the text's cap height**, typically `1em`–`1.25em` when inline with text, so the pair scales together.
+
+## One SVG, recolored per state
+
+Never ship separate assets for default, hover, selected and disabled states. Use one SVG drawn with `currentColor` and let CSS state drive the color:
+
+```html
+<!-- Good: one asset, states are CSS -->
+<svg fill="none" stroke="currentColor" stroke-width="2">…</svg>
+```
+
+```css
+.icon-button { color: oklch(0.552 0.016 285.938); }
+.icon-button:hover { color: oklch(0.21 0.006 285.885); }
+.icon-button[aria-pressed="true"] { color: oklch(0.623 0.188 259.815); }
+.icon-button:disabled { opacity: 0.4; }
+```
+
+```html
+<!-- Tailwind -->
+<button class="text-zinc-500 hover:text-zinc-900 aria-pressed:text-blue-600 disabled:opacity-40">
+  <BookmarkIcon />
+</button>
+```
+
+Hardcoded fills inside the SVG, such as `fill="#666"`, break this. Strip them to `currentColor` when importing icons.
+
+## Outline default, fill active
+
+Where an icon set offers outline and filled variants, use them as a state pair, never interchangeably:
+
+| Variant | Use for |
+| --- | --- |
+| Outline | Default state: toolbars, list rows, inline with text |
+| Fill | Selected/active state: the active tab, a toggled bookmark, a liked heart |
+
+```tsx
+// Good: variant communicates state
+<TabIcon variant={isActive ? "solid" : "outline"} />
+
+// Bad: filled icons everywhere, so the active tab has no state signal
+<TabIcon variant="solid" />
+```
+
+The swap between variants is a contextual icon animation. Use the exact cross-fade values in [icon-transitions.md](icon-transitions.md).
+
+## Design at render size
+
+An icon that looks great at 48px collapses into mush at 16px. Thin interior lines, tight counters and fine texture all blur or alias when small.
+
+- Test every icon at the smallest size it will render, often `16px`. It must stay recognizable there.
+- Prefer simplified glyphs for small contexts over scaling down detailed artwork.
+- Keep icons on the pixel grid at their render size. A 16px icon drawn on a 24px grid with fractional scaling renders soft, so use the set's native grid sizes (`16`, `20`, `24`) rather than arbitrary scales.
+- Always SVG, never raster, so the same asset stays crisp at every density.
+
+## Icons in RTL
+
+Under `dir="rtl"`, flip icons whose meaning is tied to reading direction, and leave the rest alone:
+
+| Flip | Don't flip |
+| --- | --- |
+| Back/forward arrows, chevrons in navigation | Logos and brand marks |
+| Text-block glyphs (alignment, lists, indent) | Checkmarks |
+| Speaker/volume waves (emanate in reading direction) | Physical objects: clocks, cups, pencils |
+| "Send" style directional glyphs | Media playback (play/rewind refer to tape direction, convention keeps them LTR) |
+
+```css
+/* Good: mirror only direction-dependent icons */
+[dir="rtl"] .icon-directional {
+  scale: -1 1;
+}
+```
+
+```html
+<!-- Tailwind -->
+<ChevronRightIcon class="icon-directional rtl:-scale-x-100" />
+```
+
+Analyze composite icons part by part. A badge or slash overlay may keep its position even when the base glyph flips. Accessible names for icon-only buttons belong to `better-accessibility`.

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

@@ -0,0 +1,148 @@
+# Change review
+
+This skill reviews a change rather than a screen. It resolves the scope, expands the changed files to the surfaces they affect, reads both sides of the diff and classifies every finding.
+
+Scope is all it owns. Domain rules belong to the `better-*` skills. Severity, consolidation, coverage, the cap and the verdict belong to `better-interface`, which this skill hands the review to.
+
+Correctness, tests, security and performance belong to the project's general code review. Name the concern once and move on.
+
+## The change, not the codebase
+
+The author is asking "did I make this worse?". Report what the change caused and stay mostly quiet about what it merely touched. Three pre-existing findings is a courtesy; thirty is a different review and one nobody asked for.
+
+Read the change before forming an opinion of it. The stated intent decides what counts as incomplete, and a skimmed diff produces findings about code the next hunk already fixed.
+
+## Core principles
+
+### 1. Resolve the change scope first
+
+The whole invocation is the target, so `/interface-review pr 482` reviews pull request 482. [Scope resolution]() holds the accepted targets and how each resolves.
+
+With no target supplied, resolve in this order and stop at the first match:
+
+1. `HEAD` is ahead of `git merge-base origin/<default-branch> HEAD`: that range **plus** any uncommitted changes, with the commit count and the uncommitted file count stated separately.
+2. The working tree is dirty: the uncommitted changes.
+3. Neither: there is no change to review. Stop and ask, per **With no change, ask rather than invent one**.
+
+Order matters. Check the working tree first and one stray formatting edit shadows a twelve-commit branch, with the report still claiming full coverage.
+
+Exclude lockfiles, snapshots, generated output, vendored code and binaries, and name what you excluded. An empty scope after exclusions reaches the same place by a different route.
+
+### 2. With no change, ask rather than invent one
+
+A clean tree with nothing ahead of the merge base means the user asked to review a change that does not exist. Never fall back to `HEAD~1..HEAD` on your own. The last commit is whatever happened to land, often a merge, often someone else's work, and a report on it is indistinguishable from a report on what the user meant.
+
+State the repository facts you found, then offer the routes and wait. [Nothing to review]() holds the facts to gather:
+
+- **The last commit**, `HEAD~1..HEAD`, named by short SHA and subject, so the user sees what they would get before choosing it.
+- **A target they name**: `pr <n>`, a branch, a ref, or a range, resolved per **Resolve the change scope first**.
+- **A whole-repository interface audit**, which is not a change review. Hand it to `better-interface` as a repository-scope review, without this skill's scope block, statuses, or pre-existing section. With no change, every finding is pre-existing and the classification says nothing.
+
+Check for an open pull request on the current branch before asking, and offer it first. A branch whose commits already landed resolves to no change, while its pull request is still exactly what the user meant.
+
+Where the scope emptied out after exclusions, say which files were excluded and ask the same way. Never report a review of nothing as `Approve`.
+
+### 3. A diff is not a surface
+
+A changed file is evidence, not the review subject. Its **blast radius** is the set of surfaces it renders in; review those.
+
+Expand the blast radius one hop by default: the direct importers and callers. Expand a second hop only for design tokens, theme values and shared primitives, where one line reaches the whole product.
+
+Review at most five consumers, ordered by [the rule in Scope resolution](), then state how many you did not expand. A sweep with no bound cannot support the coverage it claims, and an unstated cutoff reads as completeness.
+
+### 4. Read the removed lines
+
+Regressions are invisible in the post-change state. Read the `-` side of every hunk against [Removed signals]().
+
+A signal is a lead, not a finding. A removal is only a regression when nothing in the change replaces it, and the domain skill owns that judgement. Route each unmatched removal to its owner, report only what that skill confirms and status it `Regression`. That tells the author they broke something that worked rather than made a new mistake.
+
+### 5. Classify every finding
+
+Give every finding one status:
+
+- `Introduced`: the change created it.
+- `Regression`: the change weakened something previously correct.
+- `Pre-existing`: present in the touched code but not caused by this change.
+
+Status by what the diff touched, not by which file it sits in: a line the change never touched is `Pre-existing` even three lines from a hunk. Confirm against the base ref when it matters:
+
+```bash
+git blame -L <line>,<line> "$BASE" -- path/to/file
+```
+
+Hand every finding up with its status attached and let `better-interface` apply its cap and verdict rules.
+
+### 6. Hold the change to its stated intent
+
+Read the pull request title and body, the linked issue and the commit messages, then review whether the interface delivers what they claim.
+
+This is what surfaces the **incomplete** change. A surface review cannot see it, because it inspects the states that are present, and here the point is the ones that are absent:
+
+- A new variant, size, or theme applied to some states but not all: hover, focus, active, disabled, loading, selected.
+- A new user-facing string with no entry in the translation catalogue the project maintains.
+- A new component with no empty, loading, error, disabled, or narrow-width state.
+- A control added to one surface but not to the siblings that already carry its peers.
+
+Do not report scope creep. Whether a change does too much is a process question, not an interface one.
+
+### 7. Hand the review to `better-interface`
+
+Hand `better-interface` the scope block, the affected surfaces and a status on every finding. It routes to the domain skills, applies severity, consolidates, enforces the cap and issues the verdict.
+
+If `better-interface` is unavailable, report the resolved scope and the file inventory, name it as the missing skill and stop. Do not invent a severity scale, a cap, or a verdict.
+
+### 8. Never mutate the working tree
+
+A change review is read-only, including the checkout. Fetch pull request refs; never check them out. `git fetch` writes only to `.git` and is permitted. `gh pr checkout`, `git checkout`, `git switch` and `git stash` rewrite the files the author has open. They fail against local edits or discard them, so they are never permitted.
+
+Rendered verification is opt-in. Mark visual and runtime claims **Not verified** unless the project exposes a cheap preview or the user asks for a rendered review. When they do, use an isolated worktree (`git worktree add /tmp/review-<n> refs/remotes/pr/<n>`) and remove it when done.
+
+## Before you finish
+
+| Mistake | Fix |
+| --- | --- |
+| One stray edit reviewed instead of the branch | Check `merge-base` before the working tree, and report both counts |
+| The last commit reviewed because there was no change | State the facts and offer the last commit, a named target, or a repository audit |
+| Hunks reviewed without their consumers | Expand one hop, two for tokens and primitives, and name what you skipped |
+| Only the `+` side of the diff read | Search the `-` side for removed accessibility, focus, motion and text signals |
+| An equivalent replacement reported as a regression | Route the removal to its owner; report only what it confirms |
+| A removal reported as a new mistake | Status it `Regression` so the author knows it used to work |
+| A line near a hunk statused `Introduced` | Status by what the diff touched, confirmed with `git blame` against the base ref |
+| A pull request checked out to review it | Fetch the ref and review it in place |
+| Line numbers cited that do not exist on the reviewed ref | Cite against the head ref named in the scope block |
+| The severity scale or the finding cap restated here | Defer to `better-interface` |
+| Correctness, test, or security findings in the report | Name the concern once, point at the project's code review and drop it |
+
+## Review output format
+
+Open with the scope block:
+
+| Field | Value |
+| --- | --- |
+| Target | `branch`, `working`, `staged`, `pr 482`, or the range as entered |
+| Base ref | `origin/main` at `a1b2c3d` |
+| Head ref | `refs/remotes/pr/482` at `e4f5g6h` |
+| Commits | 7 committed, 2 files uncommitted |
+| Files in scope | 12 after exclusions |
+| Excluded | `pnpm-lock.yaml`, `src/__snapshots__/`: lockfile and snapshots |
+| Surfaces expanded | `CheckoutPage`, `SettingsPanel`; 3 further `Button` consumers not expanded |
+
+The coverage table follows it unchanged. A domain with no evidence in the change scope is `Not reviewed: no evidence in the change scope`, which is a coverage statement rather than a gap.
+
+Then the findings, with a `Status` column per **Classify every finding**:
+
+| Severity | Domain | Status | Location | Before | After | Why |
+| --- | --- | --- | --- | --- | --- | --- |
+| HIGH | Accessibility | Regression | `src/Dialog.tsx:42` | `aria-label="Close"` removed in this change | Restore `aria-label="Close"` on the icon-only control | The close control had an accessible name before this change and no longer does |
+
+With no `Introduced` or `Regression` findings, omit the table and state "No actionable interface findings in this change."
+
+Then `Pre-existing` findings, at most three, highest severity first, stated plainly as not this change's responsibility. Omit the section when there are none.
+
+| Severity | Domain | Location | Issue |
+| --- | --- | --- | --- |
+| MEDIUM | Typography | `src/Toolbar.tsx:7` | Numeric badges use proportional figures; predates this change |
+
+The cap and the verdict cover `Introduced` and `Regression` only. `Pre-existing` findings sit outside the cap, so touching a legacy file cannot turn into a full-file audit. They sit outside the verdict too, so a change whose only findings are pre-existing is an `Approve`.
+
+End with `Block` when any `HIGH` remains and `Approve` otherwise, leaving the remaining findings in the table as work to do. When `better-interface` is available, the severity scale and the cap come from it.

package/framework/skills/great-interface/references/motion-and-zoom.md

@@ -0,0 +1,79 @@
+# Motion and zoom
+
+`prefers-reduced-motion`, zoom and reflow, and unit choices that respect user settings.
+
+## prefers-reduced-motion
+
+Make motion opt-in. Wrap animations in `@media (prefers-reduced-motion: no-preference)` so users who asked for reduced motion get the static version by default, rather than you chasing every animation with an override.
+
+```css
+/* Good: motion is opt-in */
+.card {
+  /* static styles */
+}
+@media (prefers-reduced-motion: no-preference) {
+  .card {
+    transition: transform 200ms ease-out;
+  }
+}
+```
+
+```tsx
+// Tailwind: motion-safe / motion-reduce variants
+<div className="motion-safe:transition-transform motion-safe:hover:-translate-y-1" />
+```
+
+For an existing codebase where opt-in isn't feasible, the global kill switch is the fallback:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+`0.01ms` rather than `none`, so `animationend` and `transitionend` still fire and JS waiting on them doesn't hang.
+
+### What to disable vs reduce
+
+Reduced motion means reduced, not eliminated. It targets vestibular triggers, not feedback.
+
+| Disable entirely | Replace | Keep |
+| --- | --- | --- |
+| Parallax scrolling | Slide/scale/zoom transitions → opacity crossfade | Loading spinners and progress |
+| Autoplaying video, GIFs, looping decoration | Smooth scrolling → instant jump | Instant state changes (hover color, focus ring) |
+| Spinning, large-scale movement across the screen | Auto-rotating carousels → start paused | Brief functional feedback (button press) |
+
+Animations are interruptible and driven by user input. Nothing autoplays or refuses to stop, and under reduced motion carousels start paused.
+
+## Autoplay and timed UI
+
+Motion the user didn't ask for and UI acting on its own schedule:
+
+- **No autoplaying media without visible controls** (WCAG 2.2.2). Anything moving, blinking, or updating on its own for more than 5 seconds needs a visible pause or stop control, muted looping hero videos included.
+- **Prefer explicit dismissal over timers.** Auto-dismissal suits low-stakes confirmations and nothing else. A toast carrying an action, an error, or information the user may need stays until dismissed. Where one must time out, 5 seconds is the floor, and hovering or focusing it pauses the timer.
+- **Never put critical information only in a timed element.** A vanished toast with the only link to an undo action is data loss on a schedule.
+
+## Zoom and reflow
+
+- **200% zoom** (WCAG 1.4.4). All content and functionality survives text scaled to 200%, and the viewport leaves the reader able to zoom.
+- **Reflow at 320px** (WCAG 1.4.10). At 400% zoom on a 1280px viewport, equivalent to a 320px one, the page must work with vertical scrolling alone. Genuinely 2D content is the exception: tables, maps and code blocks scroll inside their own container.
+
+Fixed heights are what break under zoom. Use `min-height` on anything containing text and let containers grow.
+
+### rem vs px
+
+Respect how the codebase is set up. Where the project sizes in `px`, or on an established Tailwind scale, stay consistent and never introduce mixed units into someone else's system. Where you do have the choice, in new code or a codebase already on `rem`, `rem` respects the user's base font size and `px` ignores it:
+
+| Use `rem` | Use `px` |
+| --- | --- |
+| `font-size` | Borders and hairlines |
+| `max-width` of text containers | Focus outline width and offset |
+| Media-query breakpoints (`@media (min-width: 48rem)`) | `box-shadow` details |
+| Spacing that should scale with text | Fixed-size decorations |
+
+Breakpoints are where the choice matters most. At a larger base font size an `em` or `rem` query switches to the mobile layout when the text needs it, and a `px` query does not.