@mohammadhprp/system-prompt 0.11.2 → 0.12.1

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.

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

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

package/framework/skills/great-interface/references/spacing-and-adaptivity.md

@@ -0,0 +1,159 @@
+# Spacing and adaptivity
+
+Space between controls, margins against the viewport, hints at off-screen content and layouts that survive resizing and translation.
+
+## Breathing room between targets
+
+Controls placed too close get mis-tapped and read as one unit. Where the project has no density scale, start here:
+
+| Between | Starting point |
+| --- | --- |
+| Adjacent bordered/filled controls (buttons, inputs) | `12px` |
+| Around borderless controls (text buttons, icon buttons) | `24px` |
+| Unrelated control groups | `24px`+ (2× the intra-group gap) |
+
+Borderless controls need more clearance, because nothing marks where one target ends and the next begins. The space is the boundary. Compact professional tools may use less where hit areas stay distinct and never overlap. Preserve an established, usable density rather than expanding controls to match these values.
+
+```html
+<!-- Good: bordered buttons at 12px, icon buttons given room -->
+<div class="flex gap-3">
+  <button class="rounded-lg border px-4 py-2">Cancel</button>
+  <button class="rounded-lg bg-blue-600 px-4 py-2 text-white">Save</button>
+</div>
+
+<!-- Bad: three borderless icon buttons packed at 4px -->
+<div class="flex gap-1">
+  <button><TrashIcon /></button>
+  <button><ArchiveIcon /></button>
+  <button><ShareIcon /></button>
+</div>
+```
+
+WCAG target-size requirements, larger usability targets and pseudo-element expansion belong to `better-accessibility`; these clearances are in addition, so expanded hit areas never overlap.
+
+## Inset buttons from the edges
+
+In content layouts, buttons pressed against the viewport look like system chrome and clip against curved corners or gesture zones. Keep them inside the layout margins. Edge-to-edge actions stay valid where they are deliberately platform chrome and account for safe areas:
+
+```css
+/* Good: inset action bar */
+.action-bar {
+  padding-inline: 16px;
+  padding-bottom: calc(16px + env(safe-area-inset-bottom));
+}
+.action-bar button { width: 100%; border-radius: 12px; }
+
+/* Bad: button glued to all three edges */
+.action-bar button {
+  width: 100vw;
+  border-radius: 0;
+  position: fixed;
+  bottom: 0;
+}
+```
+
+Start near `16px` inline margin on mobile where the project has no layout token. The button can still span the full content width inside them.
+
+## Progressive disclosure needs an affordance
+
+Hiding complexity is good; hiding it without a cue is a trap. Every piece of off-screen or collapsed content needs a visible hint that it exists. Keep the product's established scroll indicator or disclosure pattern, and use the recipes below only where no cue exists:
+
+- **Peeking items.** In a horizontal scroller or carousel, size items so the next one peeks `16–32px` past the container edge. A row of cards that ends exactly at the edge looks complete, and nobody scrolls it.
+- **Disclosure controls.** Collapsed sections get a chevron or "Show more", labelled with what is hidden: "Show 12 more results", not "More".
+- **Truncation cues.** Clamped text shows an ellipsis and a way to expand. Truncation mechanics are `better-typography`'s.
+
+In the peeking-scroller recipe, the container's padding creates the peek and snap points stay on the content edge.
+
+```css
+.scroller {
+  display: flex;
+  gap: 12px;
+  overflow-x: auto;
+  padding-inline: 24px;
+  scroll-padding-inline: 24px;
+  scroll-snap-type: x mandatory;
+}
+.scroller > * {
+  flex: 0 0 calc(100% - 48px - 24px); /* container minus margins minus peek */
+  scroll-snap-align: start;
+}
+```
+
+```html
+<!-- Tailwind: the 80% width keeps the next card's leading 16-32px visible -->
+<div class="flex gap-3 overflow-x-auto px-6 [scroll-padding-inline:1.5rem] snap-x snap-mandatory">
+  <div class="w-[80%] shrink-0 snap-start">…</div>
+  <div class="w-[80%] shrink-0 snap-start">…</div>
+</div>
+```
+
+## Content bleeds, controls float
+
+The two layers behave differently at the edges:
+
+- **Content layer**: backgrounds, hero media and scrollable lists extend to the viewport edges.
+- **Control layer**: text and controls stay inside the layout margins and safe areas, floating above the content.
+
+```css
+/* Good: full-bleed media inside a constrained article */
+.article {
+  display: grid;
+  grid-template-columns: 1fr min(65ch, calc(100% - 48px)) 1fr;
+}
+.article > * { grid-column: 2; }
+.article > .full-bleed { grid-column: 1 / -1; }
+```
+
+Sticky headers and floating action buttons account for safe areas:
+
+```css
+.fab {
+  position: fixed;
+  inset-inline-end: calc(16px + env(safe-area-inset-right));
+  bottom: calc(16px + env(safe-area-inset-bottom));
+}
+```
+
+## Hold structure until it breaks
+
+Breakpoints belong to the content, not the device catalog:
+
+- Break where the layout actually stops fitting, not at `768px` because a preset says so. That is where the sidebar squeezes content below its minimum measure, or the card grid drops below a usable column width.
+- Collapse late. A layout keeping its expanded structure as long as it genuinely fits stays stable and familiar. Premature collapsing throws away space users paid for.
+- Prefer **container queries** for components. A card adapts to the column it is in, not to the viewport.
+
+```css
+/* Good: component adapts to its container */
+.card-list { container-type: inline-size; }
+@container (max-width: 400px) {
+  .card { grid-template-columns: 1fr; }
+}
+
+/* Bad: viewport media query breaks the card inside a narrow sidebar */
+@media (max-width: 768px) {
+  .card { grid-template-columns: 1fr; }
+}
+```
+
+Test the smallest and largest supported sizes first, since those break first, then the sizes between.
+
+## Plan for growth and clipping
+
+Layouts fail in two directions. Content grows, and viewports shrink.
+
+**String expansion varies by language and by source-string length.** Never rely on one universal percentage.
+
+- No fixed widths sized to English labels. Use `max-width` plus wrapping.
+- No fixed heights on text containers. Use `min-height` where a floor is needed.
+- Buttons size themselves from their label (`padding-inline`), never a hardcoded width.
+- Test with pseudo-localization or a long-string locale before shipping.
+
+```css
+/* Good: label defines the size */
+.button { padding-inline: 16px; white-space: nowrap; }
+
+/* Bad: German will overflow or truncate */
+.button { width: 96px; overflow: hidden; }
+```
+
+**Clipping.** Never park a critical action where it can be cut off: the bottom edge of a resizable pane, below the fold of a fixed-height modal, behind an expanding keyboard. Keep primary actions in stable chrome, a sticky footer with safe-area padding or the top of the view. Where a modal's content scrolls, its action row does not.

package/framework/skills/great-interface/references/spacing-and-sizing.md

@@ -0,0 +1,121 @@
+# Spacing and sizing
+
+A sensible scale and comfortable spacing do more for typography than any effect.
+
+## Units
+
+| Unit | Behavior |
+| --- | --- |
+| `px` | Fixed |
+| `em` | Scales with the current font size |
+| `rem` | Scales with the root font size |
+| `%` on `font-size` | Relative to the parent's font size, behaves like `em` |
+
+## Type scale
+
+A small set of sizes used across a product, deviated from as little as possible. Hard-coding sizes with no system behind them breaks down at scale.
+
+```css
+:root {
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.5rem;
+  --text-2xl: 2rem;
+}
+```
+
+Pick an existing scale or define one. Tailwind's (`text-xs` through `text-9xl`, each class pairing a size with a matching line height) is a solid ready-made choice.
+
+Solo, the default names work fine given clear rules for where each size is used. On a team, name sizes semantically. `text-sm` tells you the size but not the use, where `text-body-sm` carries both.
+
+A role-based scale pairs each size with its line-height and weight, making a role one decision instead of three. A starting point for a product interface:
+
+| Role | Size | Line-height | Weight |
+| --- | --- | --- | --- |
+| Display | `2.25rem` (36px) | `1.1` | `600` |
+| Title | `1.5rem` (24px) | `1.2` | `600` |
+| Heading | `1.125rem` (18px) | `1.3` | `600` |
+| Body | `1rem` (16px) | `1.5` | `400` |
+| Caption | `0.8125rem` (13px) | `1.4` | `400` |
+
+Emphasis within a role is one weight step up (`400` → `500`), not a size change.
+
+## Heading hierarchy
+
+Assign each heading level to a descending step of the scale, so hierarchy comes from the scale instead of one-off sizes:
+
+```css
+h1 { font-size: var(--text-2xl); }
+h2 { font-size: var(--text-xl); }
+h3 { font-size: var(--text-lg); }
+```
+
+In Tailwind the same mapping is utility classes per level (`text-2xl`, `text-xl`, `text-lg`), centralized in a component or `@layer base` rather than repeated inline.
+
+When reviewing, compare the computed size of headings within each semantic section. A child rendering more prominently than its parent breaks the hierarchy. Deep levels may share a size where the scale runs out of comfortable steps, as long as weight or letter-spacing keeps them distinct. A heading is never smaller than body text unless it is deliberately a label-style overline.
+
+Heading semantics and outline quality belong to `better-accessibility`. Pick the element from the document structure, then use this skill to make that structure visually legible. Never pick a heading element for its browser-default size.
+
+## Kerning and letter-spacing
+
+- **Kerning** adjusts specific pairs such as `AV` or `Ye`. It is built into the font and applied automatically. Switch it off only deliberately, with `font-kerning: none`.
+- **`letter-spacing`** adds the same space between every character.
+
+```css
+/* Good */
+.display-heading {
+  letter-spacing: -0.02em;
+}
+
+.uppercase-label {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+## Line-height
+
+| Text | Value |
+| --- | --- |
+| Headings | ~`1.1` |
+| Body copy | `1.5`–`1.6` |
+
+Tailwind's `leading-snug`, `leading-normal` and `leading-relaxed` are sensible defaults that rarely need overriding. A tightly-leaded paragraph is harder to read than a taller row is to fit.
+
+```css
+/* Bad: card description at heading leading */
+.card-description { line-height: 1.1; }
+
+/* Good: it wraps to 3 lines, so it reads as body text */
+.card-description { line-height: 1.4; }
+```
+
+## Text trimming with text-box
+
+Fonts reserve space above and below the letters, which is why text sits slightly too low in buttons and badges. `text-box` trims it. Two parts: which edges to trim (`trim-both`, `trim-start`, `trim-end`) and where:
+
+| Keyword | Trims at |
+| --- | --- |
+| `cap` | The cap height (top) |
+| `alphabetic` | The baseline (bottom) |
+| `text` | The font's own text edge, keeping room for descenders |
+
+```css
+/* trim top and bottom */
+.badge {
+  text-box: trim-both cap alphabetic;
+}
+
+/* trim only the top */
+.heading {
+  text-box: trim-start cap;
+}
+
+/* trim only the bottom */
+.label {
+  text-box: trim-end alphabetic;
+}
+```
+
+Supported in Chromium (133+) and Safari (18.2+), not yet Firefox. Treat it as progressive enhancement, where unsupported browsers keep the default leading.