@mohammadhprp/system-prompt 0.12.2 → 0.12.4

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

@@ -1,178 +0,0 @@
-# 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

@@ -1,38 +0,0 @@
-# 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

@@ -1,46 +0,0 @@
-# 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

@@ -1,88 +0,0 @@
-# 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

@@ -1,101 +0,0 @@
-# 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.

package/framework/skills/great-interface/references/semantics-and-aria.md

@@ -1,84 +0,0 @@
-# Semantics and ARIA
-
-Native elements first, landmarks, accessible names and the ARIA rules that keep custom widgets honest.
-
-## The rules of ARIA
-
-1. If a native HTML element with the semantics and behavior you need exists, use it instead of repurposing another element with ARIA.
-2. Don't change native semantics unless you really have to.
-3. Every interactive ARIA control must be keyboard-operable; a role is a promise of the full keyboard model, states and behavior.
-4. Never put `role="presentation"` or `aria-hidden="true"` on a focusable element.
-5. All interactive elements must have an accessible name.
-
-No ARIA is better than bad ARIA. A screen reader trusts your roles, so a wrong one is worse than none.
-
-## Button vs link vs div
-
-| Element | Use for | Why |
-| --- | --- | --- |
-| `<a href>` | Navigation: anything that goes somewhere or changes the URL | Free Cmd/Ctrl/middle-click, right-click → copy link, Enter activation |
-| `<button>` | Actions: submit, toggle, open, delete | Free focus, Enter *and* Space activation, form semantics |
-| `<div onClick>` | Nothing | No role, no focus, no keyboard; screen readers see plain text |
-
-```tsx
-// Bad: invisible to keyboard and screen readers
-<div onClick={openSettings}>Settings</div>
-
-// Good: focus, Enter/Space activation and semantics for free
-<button onClick={openSettings}>Settings</button>
-```
-
-If it looks clickable it must be clickable, and if it's clickable it must be a real interactive element. Rebuilding a link as a button, or the reverse, breaks user expectations. A "button" that navigates is a styled `<a>`.
-
-Where a native element is truly impossible, the full polyfill is `role="button"` plus `tabindex="0"` plus Enter and Space handlers, which is why the native element is always less code.
-
-## Landmarks and headings
-
-- Expose one visible primary `<main>` landmark. `<header>`, `<nav>`, `<aside>`, `<footer>` map to landmarks screen-reader users jump between.
-- Multiple landmarks of the same type need distinguishing labels: `<nav aria-label="Primary">`, `<nav aria-label="Breadcrumbs">`.
-- Do not report the one-`<h1>` or the no-skipped-levels convention as a standalone WCAG failure without a concrete navigation or comprehension impact. Headings are structure, not styling; style a heading level with CSS instead of picking the tag by size.
-- `<title>` matches the current context, most specific first: `Billing · Settings · Acme`.
-
-## Accessible names
-
-Name precedence: `aria-labelledby` > `aria-label` > native label (`<label>`, text content, `alt`) > `title` attribute.
-
-- Prefer visible text or `aria-labelledby` over `aria-label`, which is invisible, drifts out of sync with the UI and is handled inconsistently by translation tools.
-- Icon-only buttons always need a name: `<button aria-label="Close">` with the icon `aria-hidden="true"`.
-- WCAG 2.5.3 Label in Name: a button showing "Send" with `aria-label="Submit message"` breaks voice control users who say "click Send".
-- Accessible names must exist even when the design omits visible labels.
-
-```tsx
-// Good: name from visible text, icon hidden
-<button>
-  <TrashIcon aria-hidden="true" /> Delete
-</button>
-
-// Good: icon-only, explicit name
-<button aria-label="Delete">
-  <TrashIcon aria-hidden="true" />
-</button>
-```
-
-Add `translate="no"` to brand names, code tokens and identifiers so auto-translation doesn't garble them.
-
-## Common ARIA mistakes
-
-| Mistake | Why it fails |
-| --- | --- |
-| `aria-label` on a plain `<div>` or `<span>` | Most screen readers ignore names on non-interactive, role-less elements |
-| `<button role="button">` | Redundant role; adds noise, no benefit |
-| `aria-hidden="true"` on or above a focusable element | Creates elements you can Tab to but that don't exist for screen readers |
-| `aria-labelledby`/`aria-describedby` pointing at a missing ID | Silently produces no name or description |
-| `role="menu"` on a nav list | `menu` promises app-style arrow-key behavior; site navigation is `<nav>` with a list |
-
-## Disabled states
-
-Native `disabled` supplies the platform's complete disabled behavior. It removes the control from the tab order, suppresses activation, applies `:disabled` and excludes form controls from submission. Use it when a native control is genuinely unavailable. `aria-disabled="true"` only announces the state, changing neither focusability, nor behavior, nor styling.
-
-- Never disable submit buttons. Keep them enabled, validate on submit and focus the first error ([forms.md](forms.md)).
-- A natively `disabled` control suppresses pointer events and leaves the tab order, so a tooltip on it never opens for keyboard or touch users and is unreliable for mouse users. Put the reason in visible text beside the control, or switch to `aria-disabled="true"`, which keeps it focusable and hoverable and can carry a tooltip.
-- Use `aria-disabled="true"` where keeping a control discoverable in the tab order is intentional, or where a custom control cannot use native `disabled`.
-- With `aria-disabled="true"`, block pointer and keyboard activation in the handler, prevent form submission where applicable, add explicit styling including forced-colors support and explain nearby why the action is unavailable.
-- Never set both `disabled` and `aria-disabled` on the same element.
-- Disabled controls are exempt from contrast minimums. Keep them legible anyway.