@mohammadhprp/system-prompt 0.12.0 → 0.12.2

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

@@ -0,0 +1,88 @@
+# Performance
+
+Transition specificity and GPU compositing hints.
+
+## Transition only what changes
+
+Never use `transition: all` or Tailwind's `transition-all`. Always name the exact properties that change. Tailwind's bare `transition` maps to a curated list of colors, opacity, shadow and transforms rather than `all`, and naming what changes is still better.
+
+### Why
+
+- `transition: all` forces the browser to watch every property for changes
+- Causes unexpected transitions on properties you didn't intend to animate (colors, padding, shadows)
+- Prevents browser optimizations
+
+### CSS example
+
+```css
+/* Good: only transition what changes */
+.button {
+  transition-property: scale, background-color;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+/* Bad: transition everything */
+.button {
+  transition: all 150ms ease-out;
+}
+```
+
+### Tailwind
+
+```tsx
+// Good: explicit properties
+<button className="transition-[scale,background-color] duration-150 ease-out">
+
+// Bad: transition all
+<button className="transition-all duration-150 ease-out">
+```
+
+### Tailwind `transition-transform` note
+
+`transition-transform` in Tailwind maps to `transition-property: transform, translate, scale, rotate`, covering every transform-related property rather than only `transform`. Use it when animating transforms alone. For several non-transform properties, use the bracket syntax `transition-[scale,opacity,filter]`.
+
+## Use `will-change` sparingly
+
+`will-change` hints the browser to pre-promote an element to its own GPU compositing layer. Without it the browser promotes only when the animation starts, and that one-time promotion can cause a micro-stutter on the first frame.
+
+It helps most for `scale`, `rotation` and movement through `transform`. For other properties it does little, because the browser cannot composite them on the GPU anyway.
+
+### Rules
+
+```css
+/* Good: specific property that benefits from GPU compositing */
+.animated-card {
+  will-change: transform;
+}
+
+/* Good: multiple compositor-friendly properties */
+.animated-card {
+  will-change: transform, opacity;
+}
+
+/* Bad: never use will-change: all */
+.animated-card {
+  will-change: all;
+}
+
+/* Bad: properties that can't be GPU-composited anyway */
+.animated-card {
+  will-change: background-color, padding;
+}
+```
+
+### Useful properties
+
+| Property | GPU-compositable | Worth using `will-change` |
+| --- | --- | --- |
+| `transform` | Yes | Yes |
+| `opacity` | Yes | Yes |
+| `filter` (blur, brightness) | Yes | Yes |
+| `clip-path` | Newer Chromium only | Rarely; not reliable cross-browser |
+| `top`, `left`, `width`, `height` | No | No |
+| `background`, `border`, `color` | No | No |
+
+### When to skip
+
+Modern browsers optimize well on their own. Add `will-change` only when you see first-frame stutter, which Safari benefits from most. Never add it preemptively to every animated element, since each extra compositing layer costs memory.

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

@@ -0,0 +1,76 @@
+# The picker
+
+The control that switches variants. Its appearance is not a design decision, because it sits on top of the thing being judged. Build the spec below and leave it alone.
+
+## Deliberately outside the design system
+
+Never style the picker with the project's tokens, fonts, or colors. One that looks native to the product becomes part of what you are looking at, and then you are judging the harness.
+
+One dark neutral surface, the system font stack and no project variables. Dark reads as chrome over both light and dark pages, which is why it does not follow the theme.
+
+## Behavior
+
+- It sets a `variant` search param and reads the active variant back from it, so the URL is the source of truth and every variant a link.
+- Left and right arrows step through the set. Number keys jump to one directly.
+- The active item carries `aria-current="true"`, and the container carries a label.
+- Switching is instant. Flipping is the run's highest-frequency action, so `better-ui`'s motion restraint gives it no transition.
+- It survives a resize, so you can hold a variant and drag the window rather than reloading per width.
+
+## Structure
+
+One button per variant, in the order they were named. Add a replay button only where a variant has an entrance worth re-triggering.
+
+```html
+<nav class="variant-picker" aria-label="Variants">
+  <button type="button" data-variant="quiet" aria-current="true">Quiet</button>
+  <button type="button" data-variant="editorial">Editorial</button>
+  <button type="button" data-variant="dense">Dense</button>
+</nav>
+```
+
+## Placement and styling
+
+Fixed, bottom centre, above everything the page can stack. Keep it clear of the piece under judgement. Where the variants live at the bottom of the viewport, move the picker to top centre and say so.
+
+```css
+.variant-picker {
+  position: fixed;
+  bottom: 24px;
+  left: 50%;
+  translate: -50% 0;
+  z-index: 2147483647;
+  display: flex;
+  gap: 2px;
+  padding: 4px;
+  border-radius: 999px;
+  background: rgb(20 20 20 / 0.9);
+  box-shadow: inset 0 0 0 1px rgb(255 255 255 / 0.1), 0 8px 24px rgb(0 0 0 / 0.25);
+  font: 13px/1 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  user-select: none;
+}
+
+.variant-picker button {
+  padding: 7px 14px;
+  border: 0;
+  border-radius: 999px;
+  background: none;
+  color: rgb(255 255 255 / 0.6);
+  cursor: pointer;
+}
+
+.variant-picker button:hover {
+  color: rgb(255 255 255 / 0.85);
+}
+
+.variant-picker button[aria-current="true"] {
+  background: rgb(255 255 255 / 0.14);
+  color: rgb(255 255 255);
+}
+
+.variant-picker button:focus-visible {
+  outline: 2px solid rgb(255 255 255 / 0.7);
+  outline-offset: 2px;
+}
+```
+
+In a framework, keep the class names and the structure and change only the rendering syntax.

package/framework/skills/great-interface/references/read-the-system.md

@@ -0,0 +1,178 @@
+# Reading the whole system
+
+Use this where no specific effect was named and the question is how the interface is built in general. For one named thing, use [find-the-effect.md](find-the-effect.md).
+
+Every snippet runs in the page context, through whatever browser tooling is available: `evaluate_script` in the Chrome DevTools MCP, the console, a Playwright `page.evaluate`. Each returns data rather than printing, so the result comes back whole.
+
+Run them in this order. Tokens first, because a page that hands you its custom properties has already told you most of the answer.
+
+## The gotcha that costs you the run
+
+`sheet.cssRules` throws on a cross-origin stylesheet. Every snippet that walks stylesheets wraps the access and reports what it could not read. An explanation that silently skipped the main stylesheet describes a page nobody is looking at.
+
+## The stack first
+
+"How was this site built" wants the frontend named before a type scale. Run this, then report each hit with its evidence, never as a bare claim:
+
+```js
+const html = document.documentElement;
+const res = performance.getEntriesByType('resource').map(r => r.name);
+const any = re => res.some(n => re.test(n));
+const attr = sel => !!document.querySelector(sel);
+({
+  framework: {
+    next: !!window.__NEXT_DATA__ || any(/\/_next\/static/),
+    nextAppRouter: typeof self.__next_f !== 'undefined',
+    nuxt: !!window.__NUXT__ || any(/\/_nuxt\//),
+    remix: !!window.__remixContext,
+    gatsby: !!window.___gatsby,
+    astro: attr('astro-island, [data-astro-cid]'),
+    svelte: attr('[class*="svelte-"]') || any(/\/_app\/immutable\//),
+    angular: attr('[ng-version]'),
+    reactFiber: Object.keys(document.body.firstElementChild ?? {}).some(k => k.startsWith('__react')),
+  },
+  styling: {
+    tailwind: getComputedStyle(html).getPropertyValue('--tw-ring-offset-width') !== ''
+              || !!document.querySelector('[class*="bg-linear-to"], [class*="bg-gradient-to"]'),
+    tailwindV4: !!document.querySelector('[class*="bg-linear-to"]'),
+    cssModules: attr('[class*="_"][class*="__"]'),
+    styledComponents: attr('[class^="sc-"]') || attr('style[data-styled]'),
+    emotion: attr('[class^="css-"]'),
+  },
+  components: {
+    radix: attr('[data-radix-popper-content-wrapper], [data-radix-scroll-area-viewport]')
+           || !!document.querySelector('[data-slot], [data-state][data-side]'),
+    baseUi: attr('[data-base-ui-portal], [class*="base-ui"]'),
+    headlessUi: attr('[data-headlessui-state]'),
+    mui: attr('[class*="Mui"]'),
+    arkOrChakra: attr('[data-scope][data-part]'),
+  },
+  motion: { animationsRunning: document.getAnimations().length, gsap: !!window.gsap },
+  images: { nextImage: any(/\/_next\/image\?/), modernFormats: [...document.images].some(i => /\.(avif|webp)/.test(i.currentSrc)), srcset: [...document.images].filter(i => i.srcset).length },
+  fonts: { count: document.fonts.size, variable: [...document.fonts].some(f => String(f.weight).includes(' ')), selfHosted: !any(/fonts\.g(oogleapis|static)\.com/) },
+});
+```
+
+Two rules. A fingerprint is not a fact, so give the evidence: `/_next/static` in an asset path is strong, a utility-looking class name alone is weak. And a `false` is not an absence, only a fingerprint that did not fire.
+
+## Tokens
+
+```js
+const tokens = {}; const unreadable = [];
+for (const sheet of document.styleSheets) {
+  let rules; try { rules = sheet.cssRules } catch { unreadable.push(sheet.href); continue }
+  for (const r of rules ?? []) {
+    if (r.selectorText === ':root' || r.selectorText === 'html') {
+      for (const prop of r.style) {
+        if (prop.startsWith('--')) tokens[prop] = r.style.getPropertyValue(prop).trim();
+      }
+    }
+  }
+}
+({ tokens, unreadable, count: Object.keys(tokens).length });
+```
+
+Group the result by prefix. The prefixes are the system's own layer names, and a two-tier structure, `--blue-500` feeding `--color-text-primary`, is the seam `better-colors` calls the semantic tier.
+
+## The type scale
+
+Leaf text nodes only, so a wrapper's inherited size is not counted as its own step.
+
+```js
+const seen = new Map();
+for (const el of document.querySelectorAll('*')) {
+  if (el.children.length || !el.textContent?.trim()) continue;
+  const s = getComputedStyle(el);
+  const key = `${parseFloat(s.fontSize)}px  w${s.fontWeight}  lh ${s.lineHeight}  ls ${s.letterSpacing}`;
+  seen.set(key, (seen.get(key) ?? 0) + 1);
+}
+[...seen].sort((a, b) => b[1] - a[1]);
+```
+
+Sorted by usage, so the body size is first and the one-offs last. Derive the ratio between adjacent sizes. A consistent ratio means a scale; scattered values mean hard-coded sizes.
+
+## The spacing rhythm
+
+```js
+const vals = new Map();
+for (const el of document.querySelectorAll('*')) {
+  const s = getComputedStyle(el);
+  for (const p of ['paddingTop', 'paddingLeft', 'marginTop', 'marginLeft', 'gap', 'rowGap']) {
+    const v = parseFloat(s[p]);
+    if (v > 0) vals.set(v, (vals.get(v) ?? 0) + 1);
+  }
+}
+[...vals].sort((a, b) => a[0] - b[0]);
+```
+
+Look for the base unit that divides most values, then check `better-layout`'s grouping rule. Is the gap between groups at least 2× the gap within one?
+
+## Radii, shadows, borders
+
+```js
+const grab = (prop, skip) => {
+  const m = new Map();
+  for (const el of document.querySelectorAll('*')) {
+    const v = getComputedStyle(el)[prop];
+    if (v && v !== skip) m.set(v, (m.get(v) ?? 0) + 1);
+  }
+  return [...m].sort((a, b) => b[1] - a[1]);
+};
+({ radius: grab('borderRadius', '0px'), shadow: grab('boxShadow', 'none') });
+```
+
+Count the distinct shadows. One or two recipes is a system; nine is a page where everyone invented their own elevation.
+
+## Motion
+
+```js
+const t = new Map();
+for (const el of document.querySelectorAll('*')) {
+  const s = getComputedStyle(el);
+  if (s.transitionDuration === '0s') continue;
+  const key = `${s.transitionProperty}  ${s.transitionDuration}  ${s.transitionTimingFunction}`;
+  t.set(key, (t.get(key) ?? 0) + 1);
+}
+[...t].sort((a, b) => b[1] - a[1]);
+```
+
+`transition: all` shows up here as `all`. Custom curves arrive as `cubic-bezier(...)`, and the built-in keywords tell you nobody tuned them.
+
+## Breakpoints
+
+```js
+const bp = new Set(); const unreadable = [];
+for (const sheet of document.styleSheets) {
+  let rules; try { rules = sheet.cssRules } catch { unreadable.push(sheet.href); continue }
+  const walk = list => { for (const r of list ?? []) {
+    if (r.media) { for (const m of r.media) { const hit = m.match(/(min|max)-width:\s*([\d.]+)(px|r?em)/); if (hit) bp.add(hit[0]) } }
+    if (r.cssRules) walk(r.cssRules);
+  }};
+  walk(rules);
+}
+({ breakpoints: [...bp].sort(), unreadable });
+```
+
+Compare against the framework defaults. Breakpoints at exactly `640/768/1024/1280` are Tailwind's out of the box, which tells you they were never chosen.
+
+## Fonts and theming
+
+```js
+({
+  loaded: [...document.fonts].map(f => `${f.family} ${f.weight} ${f.style} ${f.status}`),
+  bodyStack: getComputedStyle(document.body).fontFamily,
+  variable: [...document.fonts].some(f => String(f.weight).includes(' ')),
+  themeClass: document.documentElement.className || '(none)',
+  colorScheme: getComputedStyle(document.documentElement).colorScheme,
+});
+```
+
+`variable: true` means one file covers a weight range. A class on `<html>` beside a `prefers-color-scheme` query means a toggle that can override the system, the mechanism `better-colors` describes.
+
+## Reading a second state
+
+Everything above reads one state at one width. Before writing the explanation, at minimum:
+
+- Resize to 375px and re-run the spacing and breakpoint snippets. The values that change are what is fluid.
+- Toggle the theme and re-run the token snippet. The tokens that change are the themed layer, the ones that do not are the primitives.
+- Tab to the first interactive control and read its `:focus-visible` styles, since a focus ring is one of the most common absences.

package/framework/skills/great-interface/references/removed-signals.md

@@ -0,0 +1,38 @@
+# Removed signals
+
+What to look for on the `-` side of a hunk and which skill owns the judgement. A row here is a lead, never a finding. Route the removal to its owner and report it only once that skill confirms the interface got worse.
+
+| Removed from the `-` side | Owner | What to check |
+| --- | --- | --- |
+| `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-live`, `role=` | `better-accessibility` | The control or region lost its accessible name, description, or announcement |
+| `alt=`, `<label`, `for=`, `scope=` | `better-accessibility` | Image, field, or table cell lost its programmatic association |
+| `<button>`, `<a>`, `<nav>`, `<main>`, `<ul>` replaced by `div` or `span` | `better-accessibility` | Keyboard and assistive-technology behavior was traded for styling |
+| `:focus-visible`, `:focus`, `outline`, `tabindex` | `better-accessibility` | Keyboard users lost the focus indicator or the element left the tab order |
+| `prefers-reduced-motion`, `prefers-contrast` | `better-accessibility` | Motion or contrast now ignores the user's system preference |
+| Logical properties swapped for `left` / `right` | `better-layout` | Direction-aware layout was dropped |
+| `lang=`, `dir=` | `better-typography` | Language metadata or text direction was dropped |
+| `text-wrap`, `line-clamp`, `overflow-wrap`, `tabular-nums`, `font-feature-settings` | `better-typography` | Text rendering, wrapping, or numeral alignment silently changed |
+| A color token swapped for a literal, or a token swapped for a lighter one | `better-colors` | The rendered contrast pair may now fail; measure it |
+| A user-facing string deleted or shortened | `better-writing` | A label, error, or empty state lost the information it carried |
+
+## Equivalent replacements
+
+These clear the signal. Check for them before routing anything, or the report fills with refactors reported as regressions:
+
+- `aria-label` giving way to `aria-labelledby` pointing at visible text.
+- An explicit `role` dropped because the element became the native equivalent, `role="button"` going as a `div` becomes a `<button>`.
+- `outline` replaced by a `box-shadow` focus ring that still meets the focus-indicator rule.
+- `tabindex="0"` dropped from an element that is now natively focusable.
+- A color literal replaced by a token that measures the same rendered pair.
+- A physical property replaced by its logical counterpart, which is the fix rather than the regression.
+- A string moved into the translation catalogue rather than deleted.
+
+## Searching the removed side
+
+Restrict the search to deleted lines so additions do not mask a removal:
+
+```bash
+git diff -U0 "$BASE"...HEAD -- '*.tsx' '*.css' | grep -E '^-[^-]' | grep -E 'aria-|role=|alt=|focus|tabindex|prefers-'
+```
+
+Read the surrounding hunk before deciding. A removed attribute is meaningless without the element it came from, and `-U0` deliberately hides that context.

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

@@ -0,0 +1,46 @@
+# Review output format
+
+This is the format for a review `better-interface` orchestrates. A domain skill reporting on its own carries its own smaller format, in its `## Reporting` section.
+
+## Scope and coverage
+
+State the exact scope, stack and styling conventions, the project convention documents found in recon and any review boundary. Then show coverage:
+
+| Domain | Evidence inspected | Result |
+| --- | --- | --- |
+| Accessibility | Files, components, states, or checks | Findings count or `Clear` |
+
+Include every domain listed under `better-interface`'s **Use domain skills as the sources of truth**. `Clear` means inspected with no actionable finding; `Not reviewed` must explain why.
+
+## Findings
+
+One table, ordered by severity, then by reach:
+
+| Severity | Domain | Location | Before | After | Why |
+| --- | --- | --- | --- | --- | --- |
+| HIGH | Accessibility | `src/Dialog.tsx:42` | `<button><XIcon /></button>` | Add `aria-label="Close"` and hide the icon from the accessibility tree | The icon-only control has no accessible name |
+
+- **Severity** comes from `better-interface`'s **Rank by user impact**.
+- **Location** cites `path/to/file:line`. Cite the exact screen and component when the artifact has no source files.
+- **Before / After** show the current implementation and an actionable replacement. Never split them into separate "Before:" and "After:" lines.
+- **Why** names the violated principle and its user impact.
+- **Domain** is the owning skill without the `better-` prefix.
+
+Each row is one root cause. Consolidate a repeated systemic issue into one row and list every affected location. Respect the finding cap. With no findings, omit the table and state "No actionable interface findings."
+
+## Verification
+
+List each check or interaction, the exact command or steps and the observed result. Separate checks that passed from checks marked **Not verified**.
+
+## Verdict
+
+End with one of two:
+
+- `Block`: one or more `HIGH` findings remain. Do not ship until they are fixed.
+- `Approve`: no `HIGH` findings remain. Any `MEDIUM` and `LOW` findings stay in the table as work to do.
+
+`Approve` claims the coverage you reported, so never issue it for a domain you did not inspect.
+
+## Change-scoped reviews
+
+When `interface-review` resolved the scope from version control, it supplies the scope block, a status on every finding and the change-scoped format, which its `## Review output format` holds. Severity, ranking, the cap and the verdict are the ones above, and all four cover `Introduced` and `Regression` only.

package/framework/skills/great-interface/references/scope-resolution.md

@@ -0,0 +1,88 @@
+# Scope resolution
+
+Turning a review target into a file list. The commands themselves are ordinary git. What follows is the part that is not obvious, plus the traps that fail quietly and leave the scope block claiming a count it never delivered.
+
+## Default branch
+
+Try `refs/remotes/origin/HEAD`, then `gh repo view --json defaultBranchRef`, then `init.defaultBranch`. If the ref is missing, ask the remote with `git remote set-head origin --auto` rather than guessing. It needs the network and writes a ref under `.git`, leaving the working tree untouched, so it is permitted; note it in Verification. With no remote at all, fall back to a local `main` or `master` and state which base you assumed.
+
+## Targets
+
+Accepted targets are `working`, `staged`, `branch`, `pr <n>`, a bare `<ref>` and an explicit `<a>..<b>` or `<a>...<b>` range. Anything else in the invocation is a `<ref>`.
+
+Diff a branch against the **merge base**, three dots. Two dots reports every upstream commit that landed on the base branch as part of the change.
+
+But use the dots the user wrote when they wrote a range. `<a>..<b>` compares the endpoints; `<a>...<b>` compares `merge-base(<a>, <b>)` with `<b>`. Rewriting `release..feature` to three dots drops everything between `release` and the merge base, which is often exactly what was asked for. State the resolved range in the scope block.
+
+`git diff HEAD` reports tracked changes only. Any target including uncommitted work must pair it with `git ls-files --others --exclude-standard`. Otherwise a newly added component is silently dropped from a scope the report claims to cover in full. For `branch` with uncommitted work, report the two counts separately.
+
+## Pull requests
+
+Fetch the head into a remote-tracking ref, `git fetch origin "pull/<n>/head:refs/remotes/pr/<n>"`, and review it in place. This works for forks, which `origin/<branch>` does not.
+
+Read files at that ref with `git show refs/remotes/pr/<n>:path/to/file`. Never open the working-tree copy; on a fork PR it is a different file.
+
+`gh pr diff <n>` is a fine shortcut for the patch text. It gives no way to read unchanged context or expand to consumers, so fetch the ref as well.
+
+**Citations.** `better-interface` requires `path/to/file:line`, and line numbers from a fetched ref need not match the working tree. Cite against the head ref, and declare that ref and its SHA in the scope block so the numbers resolve.
+
+**Intent.** The `title` and `body` from `gh pr view` are the stated intent for **Hold the change to its stated intent**. Add the commit subjects when the body is empty.
+
+## Awkward repository states
+
+Three worth handling. Everything else fails loudly at `merge-base`: no remote, unrelated histories, a repo with no commits, a moved submodule pointer. Say the base is unresolvable and stop. Never review a range you cannot name.
+
+**Detached HEAD.** Use the merge base against the default branch and name the SHA, not a branch, in the scope block.
+
+**Shallow clone**, the CI default, where `merge-base` returns nothing. Fetch `--deepen=50`, retry, then `--deepen=200`, then report the scope as unresolvable. Deepening writes to `.git` and not to the working tree, so it is permitted; note it in Verification.
+
+**Mid-rebase or mid-merge**, the one that does not fail loudly. `git diff` succeeds and returns something that is not the change, so the review looks fine and is wrong. Detect it with `git rev-parse --git-path` against `rebase-merge`, `rebase-apply`, `MERGE_HEAD` and `CHERRY_PICK_HEAD`. Do not test `.git/` paths directly, because they are not directories inside a linked worktree. Stop and say the tree is mid-operation.
+
+## Nothing to review
+
+The tree is clean and `HEAD` is not ahead of the merge base. Gather the facts before asking, so the offer is accurate rather than a guess: the current branch, whether the tree is clean, the count ahead of the base, the last commit's SHA and subject and any open pull request from `gh pr status`.
+
+`gh pr status` succeeds when no pull request is open. It omits `currentBranch`, so an empty result is an answer, not an error. It fails outright without `gh`, without authentication and on a repository with no GitHub remote. Treat any failure as "no pull request found", say so and offer the remaining routes rather than stopping.
+
+Report those facts, then offer the three routes in **With no change, ask rather than invent one**. State the last commit's SHA and subject inside the offer. The user recognises "a1b2c3d Merge pull request #482" as not what they wanted and cannot recognise "the last commit".
+
+A whole-repository audit is a different review, not this one with a wider net. Hand the repository to `better-interface` directly, without a scope block, statuses, or a pre-existing section.
+
+## Renames
+
+Rename detection is on by default for `--name-status`, reporting `R100 old/path new/path`. Raise the window with `--find-renames=40% --find-copies-harder` when a file was moved and edited in the same change.
+
+Review a rename as a move, not a delete plus an add. Everything that survived the move is unchanged code, and only the genuine edits are in scope.
+
+## Excluded paths
+
+Exclude these and name what you excluded in the scope block. They are machine-authored and carry no interface rules.
+
+| Category | Patterns |
+| --- | --- |
+| Lockfiles | `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `bun.lockb`, `Cargo.lock`, `composer.lock`, `Gemfile.lock`, `poetry.lock`, `uv.lock` |
+| Snapshots and fixtures | `__snapshots__/`, `*.snap`, `*.approved.*`, `test-results/`, `playwright-report/` |
+| Generated output | `dist/`, `build/`, `out/`, `.next/`, `.turbo/`, `.svelte-kit/`, `coverage/`, `storybook-static/`, `*.min.js`, `*.min.css`, `*.map` |
+| Generated sources | `*.gen.ts`, `*.generated.*`, `*.d.ts` emitted by a build, GraphQL and Prisma client output |
+| Vendored code | `vendor/`, `third_party/`, `node_modules/` |
+| Binaries and media | `*.png`, `*.jpg`, `*.webp`, `*.avif`, `*.woff2`, `*.mp4`, `*.pdf` |
+
+Two exceptions stay in scope. A **font file** added or swapped is a `better-typography` change. An **image** added to a component is a `better-ui` and `better-accessibility` change, through its `alt` text and its outline. Review the code that references them, not the bytes.
+
+Apply the exclusions as pathspecs so the file count in the scope block is the reviewed count. Two traps under-exclude silently. `*.lock` catches `yarn.lock` and `Cargo.lock` but not `package-lock.json` or `pnpm-lock.yaml`, so cover every suffix in the table. And `**` needs `glob` magic: without it `*` never crosses `/`, so `**/dist/**` excludes `packages/a/dist/` but misses a root-level `dist/`. Run the diff with and without the pathspecs and confirm the count dropped by exactly the files you named.
+
+## Expanding to consumers
+
+**A diff is not a surface** expands one hop, two for tokens and primitives. Use the project's own resolver where one exists, otherwise import paths.
+
+`git grep` searches the working tree by default. Pass the reviewed ref after the pattern, or on a pull request you search a different revision and miss importers the change itself added. Results come back as `<rev>:path/to/file`; read them with `git show`, never the working-tree copy. Pass `-e` when the pattern starts with a dash, such as a `--color-*` token, or git parses it as an option.
+
+For a changed token or theme value, search the token name rather than the file, since consumers reference the name and never import it.
+
+Order the consumers by a rule you can evaluate, so the cutoff is reproducible instead of a guess:
+
+1. **Route and layout entry points first**, whatever the framework treats as a rendered surface: `app/**/page.*`, `app/**/layout.*`, `pages/**`, `routes/**`, `src/views/**`, `*.astro` pages. Everything else only appears inside one.
+2. **Then by importer count**, since a component pulled in by twenty files carries more of the change than one pulled in by two.
+3. **Break ties by proximity**, same package or feature directory first.
+
+Review the first five, state how many you did not expand and say plainly if the ordering was arbitrary past a point.

package/framework/skills/great-interface/references/screen-readers.md

@@ -0,0 +1,101 @@
+# Screen readers
+
+Visually hidden content, live regions, toasts, alt text and SVG.
+
+## Visually hidden content
+
+The canonical `.sr-only` pattern hides content visually while keeping it in the accessibility tree:
+
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+Use `1px` boxes, not `0`, because some screen readers skip zero-sized elements. `white-space: nowrap` stops words being read as one run-together string. Never `display: none` or `visibility: hidden`, which remove the content from assistive tech entirely.
+
+Tailwind ships this as `sr-only`. Skip links add a focus variant that un-hides it, `focus:not-sr-only` or an override on `:focus`.
+
+Use it for context sighted users get visually: `<span class="sr-only">Opens in new tab</span>`, table captions, or an icon-only control's label where `aria-label` isn't an option.
+
+## Choosing how to announce a change
+
+Work down this list and stop at the first match:
+
+1. **Focus moves there anyway**, as with an opened modal or the first invalid field. Nothing extra needed; the focus move is the announcement.
+2. **Tied to a specific control**, such as a field error or character count: `aria-describedby` on the control, announced with the field.
+3. **Non-urgent, not tied to a control**, such as a toast, "Saved", a result count, or a loading state: a polite live region, `role="status"`.
+4. **Urgent and not tied to a control**, such as a form-level failure or session expiry: `role="alert"`.
+
+## Live regions
+
+Live regions announce content that changes without a page load: toasts, validation, search-result counts, loading states.
+
+| Mechanism | Politeness | Use for |
+| --- | --- | --- |
+| `role="status"` (= `aria-live="polite"` + `aria-atomic="true"`) | Waits for a pause | Toasts, "Saved", result counts, loading updates |
+| `role="alert"` (= `aria-live="assertive"` + `aria-atomic="true"`) | Interrupts immediately | Errors and urgent problems only |
+
+Rules for reliable announcements:
+
+- For repeated polite updates, keep a stable empty region in the DOM before changing its text. Inserting a new polite region with its content is announced inconsistently.
+- Dynamically inserted `role="alert"` content is usually announced, but behavior varies. Use it only for urgent errors not tied to a control, and test the target browser and screen-reader combinations.
+- Default to polite. Overusing `assertive` is the most common live-region mistake, because it interrupts whatever the user was reading.
+- Keep messages short and self-contained. `aria-atomic="true"` re-reads the whole region on change.
+- Never move focus to a toast. Announce it and leave focus where the user is working. Give toasts a generous timeout or a dismiss button, and never put the only path to an action inside an auto-dismissing one.
+
+```tsx
+// Region rendered from the start, message injected later
+<div role="status" className="sr-only">
+  {statusMessage}
+</div>
+```
+
+For loading states: set `aria-busy="true"` on the updating region, announce "Loading…" politely, then announce the outcome ("Loaded, 12 results").
+
+## aria-hidden
+
+`aria-hidden="true"` removes an element and its whole subtree from assistive tech. Use it for decorative icons and content duplicated for visual effect. Never put it on or above a focusable element, which creates stops you can Tab to that do not exist for a screen reader. Hiding something interactive means removing it from the tab order too.
+
+## Alt text
+
+Choose by purpose, not by what the image looks like:
+
+| Purpose | Alt | Example |
+| --- | --- | --- |
+| Decorative, or redundant with adjacent text | `alt=""` (empty, but present) | Logo next to the company name in text |
+| Informative | Describe the meaning it adds | `alt="Ticket QR code"` |
+| Functional (image is the link/button) | Describe the action or destination | Search icon → `alt="Search"`, not `alt="magnifying glass"` |
+| Image of text | The exact text (better: use real text) | `alt="50% off everything"` |
+| Complex (chart, diagram) | Short summary in `alt`, full data as a table or text nearby | `alt="Revenue by quarter, described below"` |
+
+A missing `alt` is worse than an empty one, because screen readers fall back to reading the file name.
+
+## SVG
+
+- Decorative SVG: `aria-hidden="true"` and `focusable="false"`, the latter for legacy Edge and IE tabbing. No title needed.
+- Meaningful inline SVG: `role="img"` plus `aria-label="…"`, or a `<title>` as the first child referenced by `aria-labelledby`.
+- Simple cases: `<img src="icon.svg" alt="…">` is the most reliable delivery.
+
+```tsx
+// Decorative icon inside a labeled button
+<button aria-label="Close">
+  <svg aria-hidden="true" focusable="false">…</svg>
+</button>
+
+// Standalone meaningful icon
+<svg role="img" aria-label="Verified account">…</svg>
+```
+
+## Video and audio
+
+Prerecorded video needs captions; provide transcripts for audio. Never autoplay with sound, and always render controls.