@mohammadhprp/system-prompt 0.12.2 → 0.12.4

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

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

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

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

package/framework/skills/great-interface/references/no-browser.md

@@ -1,73 +0,0 @@
-# Reading a site without a browser
-
-Fetch the HTML, then the stylesheets it links, then grep. That answers most questions a scriptable browser answers and a few it cannot.
-
-Do not use a markdown-converting fetch for this. It strips exactly what you came for. Fetch the raw bytes.
-
-```bash
-curl -sL --max-time 25 "$URL" -o page.html
-wc -c page.html
-grep -oE 'href="[^"]*\.css[^"]*"' page.html | sed 's/href="//;s/"$//' | sort -u
-```
-
-Pull each stylesheet the same way, resolving protocol-relative and root-relative hrefs against the page's origin first.
-
-## Utility CSS is self-describing
-
-Where the site uses utility classes, the markup already contains the declarations and no stylesheet lookup is needed. Grep the class attribute for the effect:
-
-```bash
-grep -oE '(backdrop-)?blur-\[[^]]*\]|(backdrop-)?blur-[a-z0-9]+' page.html | sort | uniq -c | sort -rn
-grep -oE 'class="[^"]*(gradient|blur|mask|mix-blend)[^"]*"' page.html | head -20
-```
-
-This is where the fetch method beats a browser. A class list carries every responsive and state variant at once, so `blur-[50px] md:h-214 md:-translate-x-1/2` says the element changes shape at the `md` breakpoint. Computed styles read at one width cannot.
-
-Semantic CSS gives you a hashed class name instead (`Hero_glow__a1b2c`). Take that name to the stylesheet and grep it there.
-
-## Inline styles carry the values utilities cannot express
-
-A multi-stop gradient is usually too specific for a utility, so it lands in a `style` attribute:
-
-```bash
-grep -oE 'linear-gradient\([^)]*\)' page.html | sort -u | head
-grep -oE 'radial-gradient\([^)]*\)' page.html | sort -u | head
-grep -oE 'style="[^"]*(transform|filter|mask)[^"]*"' page.html | head
-```
-
-## The stylesheet, for tokens and generated utilities
-
-```bash
-grep -oE ':root\{[^}]*\}' style.css | head -1 | tr ';' '\n'      # the token layer
-grep -oE '@layer [a-z]+' style.css | sort -u                      # Tailwind v4 emits theme/base/components/utilities
-grep -oE '@media[^{]*\(m(in|ax)-width:[^)]*\)' style.css | sort -u # real breakpoints
-grep -oE '@font-face\{[^}]*\}' style.css | head                    # families, weights, formats
-grep -oE '@keyframes [a-zA-Z-]+' style.css | sort -u               # named animations
-```
-
-To understand a custom utility, grep its class name in the stylesheet and read the declaration whole. That is how `gradient-ease-in-out` turns into its mechanism, a generated stop list built with `color-mix()` and relative color syntax rather than twelve hand-written stops.
-
-## Stack fingerprints from the HTML alone
-
-```bash
-grep -ocE '__NEXT_DATA__|/_next/static' page.html          # Next.js
-grep -oc 'self.__next_f' page.html                          # App Router with RSC payload
-grep -ocE '__NUXT__|/_nuxt/' page.html                      # Nuxt
-grep -ocE '__remixContext|___gatsby|astro-island' page.html  # Remix, Gatsby, Astro
-grep -oc 'class="[^"]*svelte-' page.html                     # Svelte
-grep -oc 'data-radix-' page.html                             # Radix primitives
-grep -oc 'bg-linear-to' page.html                            # Tailwind v4 (v3 wrote bg-gradient-to)
-grep -oE '<meta name="generator"[^>]*>' page.html
-```
-
-Report these as fingerprints with the evidence that produced them, never as facts. `/_next/static` in an asset path is strong; a utility-looking class name alone is weak.
-
-## What this method cannot tell you
-
-Say so rather than guessing past it:
-
-- **Which rule won.** Nine rules may match one element; only a browser resolves the cascade.
-- **Anything injected at runtime.** CSS-in-JS, a theme applied by script, styles added on interaction.
-- **Paint order and what is actually visible.** A declaration in the CSS may be overridden or never rendered.
-- **Live animation state.** Whether an effect moves at all.
-- **Computed values.** A `rem` stays a `rem`, and you never learn the resolved pixel size.

package/framework/skills/great-interface/references/palette-generation.md

@@ -1,104 +0,0 @@
-# Palette generation
-
-Producing the values once the structure is decided. For which ramps to build and what each step is for, see [palette-structure.md](palette-structure.md).
-
-## Start from the brand color
-
-A brand color arrives as one value, usually a hex. Two decisions come before any ramp exists:
-
-**Which step does it occupy?** A brand color meant for buttons and links belongs on the solid-fill step: `500` in Tailwind, `9` in Radix. Then `bg-brand-500` renders the actual brand color, not an approximation.
-
-**Is it pinned or snapped?** Pin a contractually fixed brand color. It stays exact, the ramp builds outward from it and that one step spaces slightly unevenly. Otherwise snap it onto the ramp so every step spaces evenly. That looks better almost always, and nobody notices without a swatch held to the screen.
-
-A brand color that fails contrast behind white text is still the brand color, just not the solid-fill step. Put it where it lands and use a darker step for interactive fills. Never quietly darken the brand.
-
-## What a correct ramp looks like
-
-Properties of the finished ramp, checkable against any output in any notation:
-
-- **Steps are evenly spaced in perceived lightness.** Not in the number your format calls "lightness". HSL's is not perceptual, and evenly spaced HSL values bunch at one end.
-- **Hue is constant end to end.** Every step is recognisably the same color. A wandering hue reads as two colors blended and will not sit correctly against a neutral built on a different hue.
-- **Vividness peaks in the middle and falls off at both ends.** The lightest and darkest steps are nearly neutral; the middle carries the color. Holding full vividness into the extremes gives a `50` that glows and a `950` like ink spilled on the brand.
-- **Steps are denser at the light end.** Light backgrounds need finer distinctions than dark ones. Keep `50` to `200` close together and `800` to `950` further apart. Even spacing across the whole range makes the pale end unusable, because `50` and `100` stop reading as two surfaces.
-- **No two adjacent steps are indistinguishable.** If `200` and `300` look identical on a calibrated screen, the ramp has more steps than decisions. Drop one.
-- **Both ends stop short of pure black and white.** A ramp that reaches them loses its identity exactly where the page background lives.
-
-## Use a color library
-
-Never compute these by hand or by eye. `culori`, `colorjs.io` and `chroma.js` all convert between notations, measure perceived lightness and interpolate perceptually. Read the brand color in whatever format it arrives, do the math in a perceptual space and emit the project's notation:
-
-```js
-import { formatHex, interpolate, samples } from 'culori'
-
-// Perceptual interpolation, hex in and hex out.
-const ramp = interpolate(['#eff6ff', '#3b82f6', '#172554'], 'lab')
-const steps = samples(11).map((t) => formatHex(ramp(t)))
-```
-
-The output format is the project's choice. For a ramp the interpolation space is not, because the steps have to land evenly in perceived lightness and sRGB interpolation produces muddy mid-steps. Decorative gradients are the opposite case, where the space is a deliberate look ([color-usage.md](color-usage.md)).
-
-```css
-:root {
-  --brand-50: #eff6ff;
-  --brand-100: #dbeafe;
-  --brand-200: #bfdbfe;
-  --brand-300: #93c5fd;
-  --brand-400: #60a5fa;
-  --brand-500: #3b82f6;
-  --brand-600: #2563eb;
-  --brand-700: #1d4ed8;
-  --brand-800: #1e40af;
-  --brand-900: #1e3a8a;
-  --brand-950: #172554;
-}
-```
-
-## Several hues at once
-
-With an accent plus status ramps, the ramps must agree step for step. `danger-500` and `brand-500` should read as equally bright and vivid, or a red button looks heavier than a blue one at the same step.
-
-- **Match perceived lightness exactly.** Same step, same brightness, across every hue.
-- **Match vividness relatively, not absolutely.** Hues do not share a maximum vividness. A saturated yellow and a saturated blue are not equally far from gray, and no format makes them so. Set each ramp to the same *proportion* of what its own hue reaches. Copying a saturation number across hues leaves one washed out.
-
-Yellows and cyans are the usual casualties, peaking much lower than reds and blues. Copy the numbers across and the warning color looks weak beside the danger one.
-
-## Dark mode
-
-A dark palette is not the light one reversed. Reversal is the starting point, not the output.
-
-Swap the semantic roles first, then tune the values:
-
-```css
-:root {
-  --color-bg: var(--brand-50);
-  --color-text: var(--brand-950);
-}
-
-.dark {
-  --color-bg: var(--brand-950);
-  --color-text: var(--brand-50);
-}
-```
-
-Three things almost always need hand-tuning after the swap:
-
-- **Vividness comes down.** A color that reads as confident on white reads as neon on near-black. Dark appearances need the accent a step or two less vivid.
-- **The dark end needs more separation.** Steps distinguishable as pale backgrounds collapse into each other as dark surfaces.
-- **Contrast does not survive the mirror.** A pair passing in light mode can fail reversed, because contrast is not symmetric. Recheck every foreground against its real background in both appearances ([contrast.md](contrast.md)).
-
-### Choosing the switching mechanism
-
-Pick one and use it throughout:
-
-- **`prefers-color-scheme` alone** is correct with no theme toggle. Nothing to persist, nothing to hydrate.
-- **A `.dark` class** is required as soon as users can override the system setting. The media query then sets only the initial value.
-- **`light-dark()`** collapses both values into one declaration, the least code when the project also sets `color-scheme`. It reads that property rather than a class, so a class-based toggle must set `color-scheme` too.
-
-```css
-:root {
-  color-scheme: light dark;
-  --color-bg: light-dark(#ffffff, #172554);
-}
-```
-
-Mixing mechanisms is the common failure. A media query setting some tokens and a class setting others gives a half-themed interface the moment a user overrides their system preference.

package/framework/skills/great-interface/references/palette-structure.md

@@ -1,76 +0,0 @@
-# Palette structure
-
-What a color system is made of, before any values exist. For computing the values see [palette-generation.md](palette-generation.md); for what to call them see [token-naming.md](token-naming.md).
-
-## What a system needs
-
-Most products need three kinds of ramp and nothing else:
-
-| Ramp | How many | Notes |
-| --- | --- | --- |
-| Neutral | 1 | Carries 80–90% of the interface: backgrounds, borders, body text |
-| Accent | 1 | The brand hue. Interactive and selected states |
-| Status | 0–4 | `danger`, `warning`, `success`, `info`. Add one only when the product shows that state |
-
-A second accent hue must also never sit adjacent to the first. Where it would, the accent ramp's own steps provide the range.
-
-## Every step has a job
-
-Each step maps to a role. Generate the steps the roles below call for and skip the rest.
-
-| Role | Tailwind | Radix |
-| --- | --- | --- |
-| Page background | `50` | `1` |
-| Subtle background | `50` | `2` |
-| Component background | `100` | `3` |
-| Component hover | `200` | `4` |
-| Component active / selected | `200` | `5` |
-| Subtle border | `200` | `6` |
-| Border, separator | `300` | `7` |
-| Strong border, focus ring | `400` | `8` |
-| Solid fill | `500` | `9` |
-| Solid fill hover | `600` | `10` |
-| Low-contrast text | `700` | `11` |
-| High-contrast text | `900` | `12` |
-
-The two conventions differ in kind, not only in numbering:
-
-- **Radix defines its 12 steps by role.** Step 9 is "the solid fill" in every ramp and appearance. The dark scale is a separate ramp reusing the same numbers, so `--accent-9` is the fill in both and component CSS never changes.
-- **Tailwind defines its 11 steps by lightness.** `50` is light, `950` is dark. The mapping above therefore holds in light mode and inverts in dark, with the page background at `950` and high-contrast text at `50`. Components either swap step numbers per appearance or read a semantic token that swaps once.
-
-Match whichever the project uses. For a new system prefer Radix's model, because a role-defined step survives a theme change that a lightness-defined step does not. On Tailwind, keep `50`–`950` and put the role mapping in the semantic tier.
-
-Tailwind's 11 steps cover 12 roles, so some do double duty. Where the table repeats a step, the two roles are adjacent in practice and the collision is real. A design needing a subtle border and a component hover to be distinguishable needs a 12-step ramp.
-
-## Neutrals
-
-A pure gray ramp is a perfectly good default. It sits under any accent hue without competing and never needs revisiting when the brand color changes.
-
-Tinting the neutral toward the accent hue is a stylistic option, not a correction. A trace of the accent, a few percent of its vividness, puts the greys in the same family as the accent rather than merely coexisting with it. Enough to measure, not enough to name. Neither choice reads as a mistake.
-
-Warm neutrals, hue toward orange, read approachable and editorial; cool ones, toward blue, read technical and precise. Whichever you pick, including none, hold it across the whole ramp. A warm gray border on a cool gray background is visible even when neither color is nameable alone.
-
-Neutrals carry the most roles, so they need the most steps. Never generate fewer neutral steps than accent steps.
-
-## Status colors
-
-Convention constrains status hues before taste does. Red reads as danger, amber as warning, green as success. See the cultural exceptions in [color-usage.md](color-usage.md).
-
-Two rules govern them:
-
-- **Keep every status hue distinct from the accent.** If the brand is red, the danger ramp cannot also be red. Move danger toward a deeper crimson and check the two side by side, or the destructive and primary actions are the same button.
-- **Status ramps need fewer steps than the accent.** Most render four roles: a background, a border, a solid fill and text. Generate the full ramp only where the product styles status components across the whole range.
-
-Status color is never the only signal of a state change; pair it with an icon or text. `better-accessibility` owns that requirement.
-
-## Auditing an existing palette
-
-Before restructuring a system, inventory it. Most codebases hold several times more colors than the design has decisions.
-
-1. **Collect every literal.** Grep for hex, `rgb(`, `hsl(`, `oklch(` and the project's utility-class prefixes. Include SVG `fill`/`stroke`, chart configs and email templates. Colors hide outside stylesheets.
-2. **Sort by perceived lightness within each hue family.** Duplicates surface immediately as near-identical neighbors.
-3. **Collapse near-duplicates.** Two colors closer than about one ramp step are one color that drifted. Keep the one used most and retire the others. Never average them.
-4. **Assign each survivor a role** from the table above. A color matching no role is a missing token or a mistake. Decide which, and say so in the finding.
-5. **Count what is left.** More than one ramp per role above means the palette outgrew its structure, not that the product needs more color.
-
-Report the inventory before changing anything. Consolidating a palette changes rendered output on screens nobody asked you to touch, so it stays a proposal until the user accepts it.

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

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

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