@mohammadhprp/system-prompt 0.12.0 → 0.12.2

package/framework/skills/great-interface/references/better-typography.md

@@ -0,0 +1,157 @@
+# Typography
+
+Typography is mostly restraint: a sensible scale, comfortable spacing, enough contrast. A label, a table cell, a marketing headline and an article paragraph do not share one set of rules.
+
+When reviewing, read the rendered page instead of scanning the code. Bad wrapping, widows and truncation only show up at real content lengths.
+
+Write every fix in the project's styling system, and use the exact values below rather than familiar-looking equivalents. The [cheat sheet]() maps each declaration to its Tailwind equivalent.
+
+The words themselves belong to `better-writing`. Semantic heading structure belongs to `better-accessibility`. Spatial RTL layout and logical properties belong to `better-layout`. Contrast measurement belongs to `better-colors`. This skill owns how text renders, wraps and behaves in mixed-direction content.
+
+## Serve the right format
+
+Use `.woff2` on the web, for Brotli compression and broad support. `.woff` is a fallback for very old browsers. `.ttf` and `.otf` are desktop formats with no web compression. How the files load is the project's concern.
+
+## Properties over raw tags
+
+When a CSS property exists, use it. `font-weight: 650` instead of `font-variation-settings: "wght" 650`. `font-optical-sizing: auto` instead of `"opsz"`. `font-variant-numeric: tabular-nums` instead of `font-feature-settings: "tnum" 1`.
+
+Properties keep working when a non-variable fallback renders. Reserve raw tags for custom axes (`"GRAD" 80`) and niche features (`"ss01" 1`) with no property of their own. Axes and feature tags are listed in [variable-fonts-and-opentype.md]().
+
+## Load intended weights and styles
+
+Browsers synthesize a weight or style the active family doesn't provide, distorting the real face. Load the faces the design uses.
+
+`font-synthesis: none` turns synthesis off, but it erases emphasis rather than reporting it. Set it only after checking every required bold, italic, small-cap, superscript and subscript form stays distinct across the fallback stack.
+
+## Fewer fonts, sizes and weights
+
+Rarely use more than three fonts. Weight and size define hierarchy; overusing them hurts readability fast. Pair for contrast, not similarity: a serif headline over a sans body reads as deliberate, two near-identical sans-serifs read as a mistake.
+
+Below `18px`, stay at weight `400` or heavier. Weights under `300` are display-only at `28px`+; they disappear at text sizes. Pairing guidance is in [choosing-fonts.md]().
+
+## Use a type scale with semantic names
+
+Define a small set of sizes and deviate from it as little as possible. Hard-coded sizes with no system behind them break down at scale.
+
+Solo, default names like `text-sm` are fine when the usage rules are clear. On a team, name sizes by use (`text-body-sm`) so the rules survive other people. Scale construction is in [spacing-and-sizing.md]().
+
+## Heading sizes descend with level
+
+Map heading levels to descending steps of the type scale, so a visually subordinate heading never overpowers its parent. Adjacent levels may share a size toward the small end of the scale, as long as weight or spacing keeps them distinct. The semantic element is `better-accessibility`'s; this skill sets only the visual treatment.
+
+## Line-height by role
+
+Headings tighter, around `1.1`. Body copy `1.5` to `1.6`. Prefer unitless values, so line-height scales with the font size; a fixed `24px` does not.
+
+Tight line-height is for short text. Anything that wraps to three or more lines needs at least `1.4`, even in a height-constrained row.
+
+## Letter-spacing by size
+
+Large headings often look better with slightly negative letter-spacing. Small uppercase labels need a little positive letter-spacing, or the letters feel crowded. Body copy at reading sizes needs neither.
+
+## Cap the measure
+
+Long lines make it hard for the eye to find the next one. Cap long-form text around 60–75 characters per line. Any unit works, as long as a cap exists and the line length lands in range. See [unit choices and the pixel equivalents]().
+
+## Wrap deliberately
+
+Four declarations, four jobs:
+
+- `text-wrap: balance` distributes text evenly across lines. Use it on headings.
+- `text-wrap: pretty` stops a single short word landing on the final line. Use it on descriptions.
+- `overflow-wrap: break-word` where a long word, link, or ID could escape the container.
+- `white-space: nowrap` on labels and badges where a line break looks broken.
+
+Skip `balance` and `pretty` in long-form text.
+
+## Tabular numbers on changing values
+
+Digits have different widths by default, so timers, counters and prices shift the layout as they update. Apply `font-variant-numeric: tabular-nums` to any value that changes.
+
+## Truncate without losing content
+
+For a single line, `text-overflow: ellipsis` with `overflow: hidden` and `white-space: nowrap`. For several, `line-clamp`. Truncation hides content. When the missing text matters, keep the full value reachable in a tooltip or an expanded view.
+
+## Write copy naturally, style with CSS
+
+Store text in natural case and control presentation with `text-transform`, so a redesign never means rewriting copy.
+
+Use smart punctuation in rendered text:
+
+- Curly quotes in prose, straight quotes in code.
+- An en dash for ranges: `2010–2020`.
+- The single ellipsis character, not three periods.
+- ` ` to hold `16 px` together across a line break.
+- `­` to say where a long word may break.
+
+## Underlines from the font
+
+Default underlines sit wherever the browser decides. Pull position and thickness from the font's own metrics with `text-underline-position: from-font` and `text-decoration-thickness: from-font`. Tune by hand with `text-decoration-thickness`, `text-underline-offset` and `text-decoration-skip-ink`.
+
+`text-decoration-style` draws the line dotted, dashed, or wavy. A dotted underline is a common hint that a word carries extra information, such as an abbreviation or a defined term.
+
+Color is the only part of a real underline that animates reliably. So unless the only thing animating is the color, build the underline as a separate element rather than using `text-decoration`.
+
+## Inputs at 16px on mobile
+
+iOS Safari zooms the whole page when an input's text is smaller than `16px`. Two fixes hold the size at `16px` and look different, so ask which one the design wants:
+
+- Size the input up on mobile (`text-base sm:text-sm`). Changes how it looks on small screens.
+- Keep `font-size: 16px` and render the intended size with `transform: scale()`, compensating width and `line-height`. Identical at every viewport, more code to maintain.
+
+Both recipes are in [details-and-accessibility.md]().
+
+## Size and contrast floors
+
+Start long-form body text at `16px`, the browser default. Move off it only for a reason you can name: the typeface runs small, the measure is narrow, or the product is a dense professional tool.
+
+UI text can go smaller. `14px` is a useful starting point for inputs and menus, `13px` for captions and rarely below `12px`. Inputs still need `16px` on mobile.
+
+When text looks low-contrast, use `better-colors` to measure the rendered pair and `better-accessibility` to classify the requirement. Leave the colors alone unless asked.
+
+## Font smoothing on the root
+
+On macOS, text renders heavier than intended. Apply `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` once on the root layout, never per component. Tailwind's `antialiased` covers both.
+
+## Language and bidi behavior
+
+Set `lang` so browsers and assistive technology pick the right pronunciation, quotes and hyphenation. Set `dir` at the document or at the content boundary where direction changes. Preserve digit order, and use `<bdi>` to isolate a mixed-direction value. Spatial mirroring and logical CSS properties belong to `better-layout`.
+
+## Keep useful text selectable
+
+Keep text selectable by default. `::selection` can carry brand into the reading experience, as long as the selected combination stays legible.
+
+`user-select: none` belongs on a draggable or gesture-driven surface where accidental selection interferes. Never across the interface and never because a button label can be highlighted.
+
+## Before you finish
+
+| Mistake | Fix |
+| --- | --- |
+| Synthesized face differs from the design | Load the real face; disable only the verified synthesis mode |
+| Child heading visually overpowers its parent | Map that section's hierarchy to descending scale steps |
+| Heading element picked for its default size | Choose semantics first, then set the size in CSS |
+| Orphan on the last line of a paragraph | `text-wrap: pretty` |
+| Lopsided two-line heading | `text-wrap: balance` |
+| Justified text in an interface | `text-align: start`; reserve justify for specific editorial layouts |
+| Underline cuts through descenders | `text-decoration-skip-ink: auto`, `from-font` metrics |
+| Mixed-direction value renders in the wrong order | Correct `lang`/`dir`; isolate the value with `<bdi>` |
+| Selection disabled across application chrome | Restore it; suppress only where it conflicts with a drag or gesture |
+| Extra-info hint with no visual cue | Dotted underline via `text-decoration-style: dotted` |
+| Thin/Light weight on `14px` UI text | Weight `400`+ below `18px`; thin weights are display-only |
+| `leading-none` on a three-line card description | At least `1.4` on any text that wraps to 3+ lines |
+
+## Reporting
+
+**Severity.** `HIGH` makes text unreadable or truncates content with no way to recover it. `MEDIUM` breaks the type system or the heading hierarchy. `LOW` is isolated polish.
+
+**Verification.** Without a browser: computed size and weight for each heading level, checked descending; declared line-height and measure; truncation rules against realistic string lengths. With one: resize the viewport to catch wrapping, widows and truncation at real content lengths. Report every check you could not run as `Not verified`.
+
+**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
+
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+
+`Location` is `path/to/file:line`. `Why` names the principle and the user impact.
+
+End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable typography findings" and report verification.

package/framework/skills/great-interface/references/better-ui.md

@@ -0,0 +1,107 @@
+# UI polish
+
+Polish comes from a pile of small details that compound. This skill is the reference for which are worth having and what values they take.
+
+When reviewing, slow the interface down. What feels off at 10% speed is what is subtly wrong at full speed.
+
+Keep the project's component library, tokens and density, and match its motion language except where a rule below prescribes an exact interaction.
+
+Every duration, curve, scale and blur below is a specific value, not a range to approximate. `cubic-bezier(0.2, 0, 0, 1)` is not `cubic-bezier(0.4, 0, 0.2, 1)`, and `0.96` is not `0.95`. Use what is written.
+
+Text wrapping, font rendering, tabular numbers and text spacing belong to `better-typography`. Hit areas, focus, keyboard support, ARIA and reduced motion belong to `better-accessibility`. Grouping, section spacing, breakpoints and spatial RTL belong to `better-layout`.
+
+## Concentric border radius
+
+Outer radius = inner radius + padding. Mismatched radii on nested elements is the most common thing that makes an interface feel off. Radius, shadow and outline recipes are in [surfaces.md]().
+
+## Optical over geometric alignment
+
+When geometric centering looks off, align optically. Buttons with icons, play triangles and asymmetric icons all need a manual nudge.
+
+## Shadows for elevation, borders for structure
+
+Where a border exists only to create depth, prefer layered transparent `box-shadow` values. Keep borders that communicate structure or state: dividers, separators and selected or focus states.
+
+## Interruptible animations
+
+Use CSS transitions for interactive state changes, because they can be interrupted mid-animation. Reserve keyframes for staged sequences that run once.
+
+## Split and stagger enter animations
+
+For an infrequent staged entrance where sequence communicates hierarchy, break the content into semantic chunks and stagger them by ~100ms. Animating one container gets you less for the same cost. Leave high-frequency interactions unstaggered. See [enter-exit.md]().
+
+## Subtle exit animations
+
+Use a small fixed `translateY` rather than full height. Exits should be softer than enters. Use `ease-out` for both directions.
+
+## Contextual icon animations
+
+Animate icons with `opacity`, `scale` and `blur` rather than toggling visibility. Use exactly these values: scale `0.25` to `1`, opacity `0` to `1`, blur `4px` to `0px`.
+
+With a motion library (`motion` or `framer-motion` in `package.json`), match that package's import path, or nearby imports where both exist. Use `transition: { type: "spring", duration: 0.3, bounce: 0 }`. Bounce is always `0`.
+
+Without one, keep both icons in the DOM with one absolutely positioned, and cross-fade with `cubic-bezier(0.2, 0, 0, 1)`. That gives you enter and exit with no dependency. Both recipes are in [icon-transitions.md]().
+
+## Image outlines
+
+Give images a `1px` outline at low opacity for consistent depth. Pure black in light mode (`oklch(0 0 0 / 0.1)`), pure white in dark (`oklch(1 0 0 / 0.1)`). Never a near-black like slate or zinc and never a tinted neutral. A tinted outline picks up the surface underneath and reads as dirt on the image edge.
+
+## Scale on press
+
+A `scale(0.96)` on click gives a button tactile feedback. Always `0.96`; anything below `0.95` feels exaggerated. Add a `static` prop to switch it off where motion would distract. See [recipes for CSS, Tailwind and Motion]().
+
+## Skip animation on page load
+
+Use `initial={false}` on `AnimatePresence` to keep enter animations off the first render. Check that it leaves intentional page entrances intact.
+
+## Suppress transitions on theme switch
+
+A theme flip changes color, background, border and shadow on nearly every element at once. Every transition on those properties fires together and the switch smears instead of snapping. Inject `*,*::before,*::after{transition:none !important}`, force a reflow, then remove it on the next frame. See the [recipe]().
+
+## Transition only what changes
+
+Always name the exact properties: `transition-property: scale, opacity`. Tailwind's `transition-transform` covers `transform, translate, scale, rotate`.
+
+## Use `will-change` sparingly
+
+Only for `transform`, `opacity` and `filter`, which the GPU can composite. Never `will-change: all`. Add it when you see first-frame stutter, not before. See [performance.md]().
+
+## Match icon stroke to text weight
+
+An icon next to text carries the text's optical weight: `1.5px` stroke beside regular (400) text, `2px` beside semibold (600). One stroke weight per icon set and one icon library per surface. Sizing and RTL flipping are in [icons.md]().
+
+## One SVG, recolored per state
+
+Icons use `currentColor` and take hover, selected and disabled states from CSS color and opacity, never from separate assets. Outline is the default variant; fill marks the active state.
+
+## Motion restraint
+
+Give high-frequency interactions instant feedback, or a transition of `150ms` or less on opacity and color. A custom animation there charges its attention cost on every trigger.
+
+Every animated state change also needs a static cue: color, an icon, or a label. Motion is never the only feedback channel.
+
+## Before you finish
+
+| Mistake | Fix |
+| --- | --- |
+| Icons look off-center | Nudge optically with padding, or fix the SVG |
+| Jarring staged entrance or exit | Stagger infrequent entrances; keep exits subtle |
+| Theme toggle crossfades the whole page | Disable transitions for the swap, force a reflow, restore on the next frame |
+| `transition: all` on elements | Specify exact properties |
+| First-frame animation stutter | Add `will-change: transform` (sparingly) |
+| Hairline icon beside bold text | Match the stroke width to the text weight |
+
+## Reporting
+
+**Severity.** `HIGH` breaks an interaction, makes motion unusable, or leaves a state change visible only while the animation runs. `MEDIUM` is a visible inconsistency in surfaces, icons, or motion. `LOW` is isolated polish.
+
+**Verification.** Without a browser: every state the component defines, meaning hover, focus, active, loading and empty, plus motion durations and easings read from the code. With one: walk each state, and replay motion at 10% speed in the browser's Animations panel. Report every check you could not run as `Not verified`.
+
+**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
+
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+
+`Location` is `path/to/file:line`. `Why` names the principle and the user impact.
+
+End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable UI-polish findings" and report verification.

package/framework/skills/great-interface/references/better-writing.md

@@ -0,0 +1,109 @@
+# Interface writing
+
+Clear and brief beats clever; consistent beats varied. The best error message is the interaction redesigned so the error cannot happen.
+
+How copy renders (capitalization via `text-transform`, truncation, smart punctuation) belongs to `better-typography`. Error markup and announcements (`aria-invalid`, live regions) belong to `better-accessibility`. Room for translated strings belongs to `better-layout`.
+
+## Recon the existing voice
+
+Before writing or reviewing, read the copy nearby. Note the product's terminology, its localization conventions and any voice or content style guide.
+
+A deliberate brand voice is not a defect. Raise a departure from plain language only when it creates inconsistency, ambiguity, translation risk, or a tone the stakes don't support.
+
+## One voice, flexible tone
+
+The product has one voice and its existing copy establishes it. A local edit does not get to invent a new one. Keep terms consistent: if it's "Archive" in the menu, it isn't "Move to storage" in the toast. Tone flexes with the stakes:
+
+| Context | Tone |
+| --- | --- |
+| Success, onboarding, empty states | Warm, can be light |
+| Routine actions, settings | Neutral, minimal |
+| Errors, destructive confirmations | Calm, plain, zero playfulness |
+| Data loss, security | Serious, explicit |
+
+## Address the reader directly
+
+In instructional copy, write "you", not "the user". In errors, "we" invites ambiguity and reads as deflection, so prefer "Unable to load content" over "We're having trouble loading this content". An established first-person voice can stay in low-stakes copy where it still reads clearly.
+
+Use possessives sparingly: "Favorites" beats "Your Favorites". Hold one perspective throughout a flow.
+
+## Plain words over clever ones
+
+Choose words a tired reader gets on the first pass, and delete every word that does no work. No idioms, no colloquialisms, no humor that won't translate.
+
+Skip unnecessary gender: "Subscribers can post recipes", not "each subscriber can post his or her recipes". Match the input device: "tap" on touch, "click" with a pointer, "select" when both are possible.
+
+Never assemble a sentence from fragments around a variable (`"You have " + n + " new messages"`), because word order changes per language. Use a full templated string with proper pluralization.
+
+## Verb-first buttons
+
+A button label starts with a verb naming the action: "Send", "Save draft", "Delete project". Never "OK!", "Let's go!", or a bare "Yes" and "No" on a consequential action.
+
+A confirmation button repeats the consequence, so the dialog is answerable without reading the body. "Delete this project?" offers `Delete project` and `Cancel`.
+
+## Consistent flow vocabulary
+
+A multi-step flow uses one vocabulary throughout: "Get started" to enter, "Continue" or "Next" (pick one) to advance, "Done" to finish. Alternating synonyms makes users wonder whether the buttons do different things.
+
+## Links describe their destination
+
+Link text has to make sense out of context, because screen-reader users navigate by a list of the page's links. Write "Read the billing docs". "Click here" fails this and the device-verb rule at once.
+
+A bare "Learn more" breaks down as soon as two appear on one page. Suffix each one: "Learn more about exports".
+
+## One capitalization policy
+
+Pick title case or sentence case per element type, then apply it to every instance of that type. Sentence case is the safer default. It is calmer, has no per-word rules to remember and localizes cleanly. "Save Changes" beside "Discard changes" reads as sloppiness.
+
+## Settings describe the ON state
+
+Label a toggle for what happens when it is on. "Send read receipts" lets users infer the off state; the negative ("Don't send read receipts") turns the toggle into a double negative.
+
+Link straight to a referenced setting rather than describing the path to it: a "Notification settings" link, not "Go to Settings > Notifications > Email".
+
+## Errors say how to fix, next to where it broke
+
+An error is an instruction, and it belongs beside the field that failed:
+
+| Bad | Good |
+| --- | --- |
+| That password is too short | Choose a password with at least 8 characters |
+| Invalid name | Use only letters for your name |
+| Oops! Something went wrong. | Unable to save. Check your connection and try again. |
+
+No blame, no "oops", no exclamation marks. Phrase hints positively ("Use only letters", not "Don't use numbers or symbols") and show them before the mistake, not after. When the same error keeps firing, redesign the interaction instead of rewording it.
+
+## Empty states point forward
+
+An empty state says what this place is, how to fill it and offers one clear next action:
+
+```html
+<!-- Bad: a shrug -->
+<p>No results.</p>
+
+<!-- Good: orientation plus a next step -->
+<p class="font-medium">No projects yet</p>
+<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
+<button class="mt-4">Create a project</button>
+```
+
+A search or filter empty state names the query and offers an exit: "No results for 'quarterly'. Clear filters". Never park persistent information in an empty state. It disappears the moment content exists.
+
+## Placeholders are examples, not labels
+
+A placeholder shows the expected format: `name@example.com`, `DD/MM/YYYY`. It vanishes on input, so it is never the only label. Every field keeps a visible one.
+
+## Reporting
+
+**Severity.** `HIGH` misleads the user or hides how to recover from an error. `MEDIUM` breaks voice, terminology, or capitalization consistency. `LOW` is isolated wording polish.
+
+**Verification.** Source alone is enough here. Check every label against the action it invokes, every error for a stated fix and terminology against the copy around it. No browser check is required.
+
+**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
+
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+
+`Location` is `path/to/file:line`. `Why` names the principle and the user impact.
+
+End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable writing findings" and report verification.

package/framework/skills/great-interface/references/choosing-fonts.md

@@ -0,0 +1,64 @@
+# Choosing fonts
+
+Choosing a typeface, the right file format and why fonts look the way they do.
+
+## Choosing a typeface
+
+Font families set the tone before the specific font does.
+
+| Category | Traits | Use for |
+| --- | --- | --- |
+| Serif | Small strokes at the ends of letters guide the eye along a line | Long passages, editorial reading |
+| Sans-serif | Clean, even shapes that stay crisp at small sizes | Default for most interfaces (Helvetica, Inter, Geist) |
+| Monospace | Every glyph the same width so columns line up | Code, tables, tabular data |
+| Display | Drawn for large headlines | Marketing headlines, hero text |
+| Script | Mimics handwriting | Rare, decorative moments |
+
+CSS exposes `cursive` and `fantasy` keywords for the last two categories.
+
+"Display" in a font's name does not make it a display font. SF Pro and Heldane ship a `Display` variant for large sizes and a `Text` variant for small ones. Use the variant matching the size you are setting.
+
+### Rules
+
+- Fewer fonts is usually better. Rarely use more than three. Marketing pages can be more expressive than apps.
+- The same applies to sizes and weights. They define hierarchy, and overusing them hurts readability fast.
+- Pair for contrast, not similarity. A serif headline over a sans body reads as a deliberate display and reading split; two near-identical sans-serifs read as a mistake.
+- Thin weights are display-only. Below `18px` stay at weight `400`+, because Ultralight, Thin and Light (`100`–`300`) strokes disappear at text sizes and on low-DPI screens. Reserve them for `28px`+ display text, and check even there that they hold against the background.
+
+## Font family scope
+
+Applying or reviewing typography never requires a new typeface. Use the product's type system unless the task asks for a type change, and never introduce a paid or proprietary face to satisfy a checklist. Rendering details such as font smoothing, wrapping and tabular numbers do not override the project's font family.
+
+When a type change is asked for, two routes. The system stack gives a native macOS and iOS feel. A commercial face such as Helvetica Now is a brand decision and still needs a fallback stack.
+
+```css
+/* System-native macOS/iOS feel */
+html {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+/* Commercial brand face with safe fallbacks */
+html {
+  font-family: "Helvetica Now", "Helvetica Neue", Arial, sans-serif;
+}
+```
+
+## Formats
+
+| Format | Notes |
+| --- | --- |
+| `.woff2` | Brotli compression, broadly supported. Use this on the web. |
+| `.woff` | Older compression. Fallback only for very old browsers. |
+| `.ttf` / `.otf` | Raw formats, no web compression, larger files. Desktop only unless there is no other option. |
+
+## Anatomy of a typeface
+
+| Term | Meaning |
+| --- | --- |
+| x-height | Height of a lowercase `x` |
+| Cap height | Height of uppercase letters |
+| Baseline | The invisible line letters sit on |
+| Ascender | Part of a letter rising above the x-height |
+| Descender | Part dropping below the baseline |
+
+These measurements are why two fonts at the same `font-size` look like different sizes. A large x-height looks bigger.

package/framework/skills/great-interface/references/color-formats.md

@@ -0,0 +1,90 @@
+# Color formats
+
+Which notation to write colors in, how to convert between them and what happens at the edges of a display's gamut. Every other rule in this skill is stated perceptually and holds whatever notation you write.
+
+## Choosing a notation
+
+| Notation | Good for | Weakness |
+| --- | --- | --- |
+| Hex | Universal support, compact, what design tools hand you | Opaque. No channel is readable or editable by hand |
+| `rgb()` | Same reach as hex, readable alpha | Channels do not correspond to anything a designer thinks about |
+| `hsl()` | Channels look like design controls | Its lightness is not perceptual and its hue drifts; a ramp built by varying lightness bunches at one end and shifts hue |
+| `oklch()` | Perceptually uniform lightness, stable hue, predictable ramps | Baseline 2023, so very old browser matrices need a fallback |
+
+**Match whatever the project already uses.** Notation is not a defect: a project on hex is not doing it wrong.
+
+**For a genuinely new color system, `oklch()` is the best default.** Even lightness steps stay even, and a fixed hue stays fixed. See [palette-generation.md](palette-generation.md).
+
+```css
+oklch(L C H)          /* lightness 0–1, chroma 0–~0.4, hue 0–360 */
+oklch(L C H / alpha)  /* alpha uses a slash, never a comma */
+```
+
+## Converting
+
+Convert when the user asks, when an agreed migration is in scope, or when the project is standardizing on a notation and this value is the straggler. Never convert an isolated value in a project that deliberately uses something else and never because this skill happened to load.
+
+When conversion is in scope, change the values and nothing else:
+
+- Leave CSS keywords alone: `currentColor`, `inherit`, `transparent`, `initial`, `unset`.
+- Leave gradient functions alone. Convert the color stops inside them; do not touch the interpolation method.
+- Leave colors in third-party configs that expect a specific format.
+- Preserve comments and formatting.
+
+```css
+/* Before */
+color: #3b82f6;
+border: 1px solid rgba(0, 0, 0, 0.1);
+
+/* After */
+color: oklch(0.623 0.188 259.815);
+border: 1px solid oklch(0 0 0 / 0.1);
+```
+
+Bulk conversion is a migration, not cleanup. It shifts every rendered color by a rounding margin and touches files nobody asked about, so it has to be the task rather than a side effect.
+
+## Gamut
+
+Every sRGB color exists in Display P3, but not the reverse. P3 covers roughly 50% more colors, which matters only for the most saturated values. A color at 60% of maximum vividness looks the same on both.
+
+A color more vivid than its display can render gets clipped, and clipping is not graceful. It flattens neighbouring steps into one rendered color, so the top of a ramp can lose its distinctions on an sRGB screen. Maximum vividness varies by hue and lightness. Cyans top out far lower than reds and purples, so a clipping ramp clips at some steps and not others.
+
+The fix is to reduce vividness while holding hue and lightness. Generate ramps against sRGB unless the product is display-restricted, and add P3 as an enhancement:
+
+```css
+.accent {
+  background: #3b82f6;
+}
+
+@media (color-gamut: p3) {
+  .accent {
+    background: oklch(0.62 0.24 259);
+  }
+}
+```
+
+Order matters. The sRGB value comes first so every display gets something, and the P3 rule overrides only where it will render. A P3 color with no fallback is a `HIGH` finding; it does not degrade, it fails.
+
+For browser matrices predating `oklch()` support, the same layering works with `@supports`:
+
+```css
+.accent {
+  background: #3b82f6;
+}
+
+@supports (color: oklch(0 0 0)) {
+  .accent {
+    background: oklch(0.62 0.19 259);
+  }
+}
+```
+
+Check the project's actual browser matrix before adding this. On a modern baseline it is dead weight.
+
+## Modern CSS worth knowing
+
+- **`color-mix()`** derives one color from another, as in `color-mix(in oklab, var(--color-accent-solid) 15%, white)` for a tinted background. Useful for states, but keep generated values out of the token layer, since a mixed color cannot be inspected in a design tool.
+- **Relative color syntax** adjusts one channel of an existing color. `oklch(from var(--color-accent-solid) calc(l - 0.1) c h)` darkens the accent by hand. Powerful and easy to overuse, since a token defined by three chained derivations is unreadable.
+- **`light-dark()`** puts both appearances in one declaration. See [palette-generation.md](palette-generation.md).
+
+All three compute at render time, so their output cannot be contrast-checked statically. Measure the rendered result.

package/framework/skills/great-interface/references/color-usage.md

@@ -0,0 +1,118 @@
+# Color usage
+
+Deploying color once the system exists: meaning, emphasis, gradients and appearance variants. For picking values see [palette-generation.md](palette-generation.md), for naming them [token-naming.md](token-naming.md), for checking pairs [contrast.md](contrast.md).
+
+## One color, one meaning
+
+Users read a near-miss in hue as a slightly different shade, not as a different color.
+
+```css
+/* Bad: the accent means both "link" and "decorative heading" */
+a { color: #3b82f6; }
+.section-title { color: #4f8ef7; }
+
+/* Good: interactive elements own the accent; headings stay neutral */
+a { color: var(--color-accent-text); }
+.section-title { color: var(--color-text-primary); }
+```
+
+The rule runs both ways. A color must not be *absent* where its meaning occurs. If the accent means interactive, an interactive element rendered neutral is just as misleading.
+
+Color is never the only carrier of meaning. Pair it with an icon, a label, or a shape. `better-accessibility` owns that requirement.
+
+## Use tokens in their role
+
+Apply a semantic token only for the role it names. `--color-text-secondary` is muted foreground text. Use it as a background and every future theme change that assumes the role breaks, because a value that happened to work as both stops working as both.
+
+```css
+/* Bad: separator token repurposed as a text color because it looked right */
+.caption { color: var(--color-border); }
+
+/* Bad: text token repurposed as a background */
+.tag { background: var(--color-text-secondary); }
+```
+
+The role inventory in [token-naming.md](token-naming.md) is the list of roles a system needs.
+
+## One colored action per view
+
+Preserve an established component hierarchy that communicates emphasis another way. Do not recolor controls merely to impose this recipe.
+
+```html
+<!-- Good: one filled primary action, neutral secondaries -->
+<button class="bg-accent-solid text-white">Save</button>
+<button class="text-neutral-700">Cancel</button>
+
+<!-- Bad: every action colored, so nothing is primary -->
+<button class="bg-accent-solid text-white">Save</button>
+<button class="bg-accent-solid text-white">Duplicate</button>
+<button class="bg-accent-solid text-white">Export</button>
+```
+
+Selected states may use the accent on the glyph and label. An active tab or a checked segment is state, not emphasis.
+
+## Gradients
+
+**The interpolation space is a look, not a correctness setting.** Three are worth knowing, and the difference between them is most visible in the middle of the gradient:
+
+```css
+/* sRGB: the default and the classic. Midpoint darkens and mutes. */
+background: linear-gradient(#3b82f6, #ec4899);
+
+/* oklab: even brightness across the transition. The best default. */
+background: linear-gradient(in oklab, #3b82f6, #ec4899);
+
+/* oklch: travels around the hue wheel, staying vivid throughout. */
+background: linear-gradient(in oklch, #3b82f6, #ec4899);
+```
+
+`oklab` and sRGB are **rectangular**, interpolating in a straight line through the color space. `oklch` is **polar**, interpolating the hue angle, so it arcs around the wheel through every hue between the stops. That is why it stays saturated and why it can produce hues nobody asked for. A blue-to-pink gradient routes through purple, which is either the look or a surprise.
+
+**The gray dead zone is a rectangular-space problem.** Two hues on opposite sides of the wheel sit either side of the neutral axis. A straight line between them passes near gray, and the middle goes lifeless. Either switch to a polar space, which routes around the axis, or add a third stop between the two and keep the space you have.
+
+With a polar space you also control which way it goes around:
+
+```css
+/* The short way round, usually what you want */
+background: linear-gradient(in oklch shorter hue, #3b82f6, #ec4899);
+
+/* The long way, sweeps most of the spectrum */
+background: linear-gradient(in oklch longer hue, #3b82f6, #ec4899);
+```
+
+**Banding shows up on large areas.** A gradient spanning a hero with little contrast between its stops steps visibly on 8-bit displays. Widen the contrast, shrink the area, or overlay a subtle noise texture.
+
+**Keep text off gradients where you can.** Contrast varies continuously across one, so a single measurement does not describe it. Where text must sit on a gradient, measure the worst region rather than the average, or put a scrim behind it.
+
+## Color across cultures
+
+Color meaning is not universal. Where a color is load-bearing in finance, status, or alerts, verify the meaning holds in every locale you ship to.
+
+| Color | Common Western reading | Elsewhere |
+| --- | --- | --- |
+| Red | Danger, loss, errors | Luck, prosperity; **gains** in Chinese financial UIs |
+| Green | Success, gains, go | Losses in Chinese financial UIs |
+| White | Purity, cleanliness | Mourning in parts of East Asia |
+| Gold | Premium, luxury | Religious significance in some regions |
+
+The classic case is stock tickers, which show gains in green for English locales and red for Chinese ones. Where the product ships to such markets, make gain and loss per-locale tokens rather than hardcoded values.
+
+## Light, dark and increased contrast
+
+Every custom color needs a light and a dark variant, derived per [palette-generation.md](palette-generation.md). Beyond that, users who enable increased contrast expect visibly stronger differentiation:
+
+```css
+:root {
+  --color-accent-solid: #3b82f6;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root { --color-accent-solid: #60a5fa; }
+}
+
+@media (prefers-contrast: more) {
+  :root { --color-accent-solid: #1d4ed8; }
+}
+```
+
+The increased-contrast variant widens the foreground/background gap by at least 15 points of perceived lightness over the default. Re-verify against APCA's preferred thresholds, Lc 90 body and Lc 75 non-body. Widening the gap without remeasuring is not fixing it.