@mohammadhprp/system-prompt 0.11.2 → 0.12.1

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.

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

@@ -0,0 +1,79 @@
+# Contrast
+
+Contrast is measured between a **foreground color**, meaning text, an icon, or a UI element, and the **background color** it actually renders against, usually the nearest ancestor that paints one. Identify that background first. Measuring against the page background when the element sits on a card gives the wrong answer.
+
+**Report, don't repaint.** When a check fails, report the pair, its measured value and the threshold it misses, and leave the colors unchanged. They are a design decision. Apply the fix below only when asked.
+
+`better-accessibility` decides when contrast is required and whether a given pair must pass. This file covers measuring the pair and, on request, changing it.
+
+## APCA thresholds (recommended)
+
+APCA (Accessible Perceptual Contrast Algorithm) models perceived contrast more accurately than WCAG 2 and is the better default for design decisions. Lc (Lightness Contrast) measures perceived contrast between foreground and background. These levels simplify APCA's full font-size and weight lookup table:
+
+| Content type | Minimum | Preferred |
+| --- | --- | --- |
+| Body text (columns or blocks of text) | Lc 75 | Lc 90 |
+| Non-body text (labels, headlines) | Lc 60 | Lc 75 |
+| Large text (≥36px) | Lc 45 | Lc 60 |
+| UI components | Lc 30 | n/a |
+
+Lc 30 is also APCA's minimum for disabled and placeholder text. The floor for a non-text element to be discernible at all is Lc 15.
+
+Lc is signed: positive means dark text on a light background, negative means light text on a dark background. Compare the absolute value against the threshold.
+
+## WCAG 2 thresholds (for legal compliance)
+
+WCAG 2 is still required for formal WCAG 2.x conformance claims. Its luminance ratio is both too strict and too lenient depending on the pair, but it has the legal standing.
+
+| Content type | AA | AAA |
+| --- | --- | --- |
+| Normal text (<24px / <18.5px bold) | 4.5:1 | 7:1 |
+| Large text (≥24px / ≥18.5px bold) | 3:1 | 4.5:1 |
+| UI components and graphical objects | 3:1 | n/a |
+
+WCAG defines large text in points: 18pt ≈ `24px`, 14pt bold ≈ `18.5px`.
+
+When a project must claim WCAG conformance, WCAG is the gate and APCA is the tiebreaker for anything above it.
+
+## Fixing a failing pair (on request)
+
+**Change lightness first.** It is the channel contrast responds to. Hue and saturation move the measured value far less, so fixing contrast by changing hue is wasted effort.
+
+Move the foreground away from the background in perceived lightness, holding hue and saturation, then remeasure. Keeping hue fixed is what stops a contrast fix becoming a palette change.
+
+```css
+/* Failing: text too close to its background in lightness (Lc ≈ 50) */
+color: #7d93b0;
+background: #eef2f7;
+
+/* Fixed: darker text, same hue (Lc ≈ 90) */
+color: #2b3a4f;
+background: #eef2f7;
+```
+
+Two constraints on the fix:
+
+- **Mid-lightness backgrounds cap what is achievable.** On a background near 75% perceived lightness, even pure black text reaches only about Lc 60. Body text needs a background near one extreme, so a mid-range background is the thing that has to change.
+- **Pushing lightness can push the color out of gamut.** Reduce saturation as needed to keep it renderable. See [color-formats.md](color-formats.md).
+
+Always remeasure after changing a value. Do not assume a fix landed.
+
+## Quick approximations
+
+Useful for a first pass and approximations. Verify by measuring before reporting a result.
+
+For body text targeting |Lc| ≥ 75:
+
+- **Light background (above ~90% perceived lightness):** foreground below ~35%.
+- **Dark background (below ~25% perceived lightness):** foreground above ~90%.
+
+The gap is asymmetric because APCA is polarity-aware. Mirrored pairs do not score identically, which is why a pair passing in light mode can fail in dark.
+
+**Light or dark background?** The crossover is around 73% perceived lightness. Above it use dark text; at or below it light text scores higher. That is higher than intuition suggests. Between roughly 60% and 73% the background already looks light, yet white text still measures meaningfully better than black.
+
+## What to check
+
+- **Every pair, in every appearance.** A pair passing in light mode can fail in dark. The palettes are not mirror images.
+- **Translucent surfaces.** A color on a `backdrop-filter` header or an overlay shifts with whatever scrolls behind it. Test against the lightest and darkest content it can sit over, or make the surface opaque enough that the shift cannot break the pair.
+- **Computed colors.** `color-mix()`, relative color syntax and opacity modifiers resolve at render time; measure the rendered result, not the declaration.
+- **Text over images.** There is no single background color. Measure the worst region, or guarantee one with a scrim.

package/framework/skills/great-interface/references/css-cheat-sheet.md

@@ -0,0 +1,65 @@
+# CSS cheat sheet
+
+One-line lookup for every typography CSS declaration covered by this skill, with the Tailwind 4 equivalent. Where no utility exists, the arbitrary-value form is shown. Pick the column that matches the project: the declaration in plain CSS, CSS Modules, styled-components or StyleX codebases, the utility in Tailwind codebases.
+
+## Font
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `font-family: sans-serif` | The sans family | `font-sans` |
+| `font-family: serif` | The serif family | `font-serif` |
+| `font-family: monospace` | The monospace family | `font-mono` |
+| `font-size` | Size from the type scale | `text-*` |
+| `font-weight` | Any value from 1 to 1000 | `font-*` |
+| `font-style: italic` | Switch to italic style | `italic` |
+| `-webkit-font-smoothing` + `-moz-osx-font-smoothing` | Smooth macOS font rendering; apply once at the root | `antialiased` |
+| `font-synthesis: none` | Disable all synthesized forms after verifying fallbacks and emphasis | `[font-synthesis:none]` |
+| `font-feature-settings` | Toggle OpenType features | `[font-feature-settings:"ss01"]` |
+| `font-variation-settings` | Tune variable font axes | `[font-variation-settings:"GRAD"_80]` |
+| `font-optical-sizing` | Adjust details per size | `[font-optical-sizing:auto]` |
+| `font-variant-caps` | Real small capitals | `[font-variant-caps:small-caps]` |
+| `font-variant-position` | Real super and subscripts | `[font-variant-position:super]` |
+| `font-variant-numeric: tabular-nums` | Equal-width digits | `tabular-nums` |
+| `font-variant-numeric: slashed-zero` | Tell 0 from O | `slashed-zero` |
+
+## Spacing and layout
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `letter-spacing` | Space between letters | `tracking-*` |
+| `line-height` | Space between lines | `leading-*` |
+| `font-kerning` | Kerning on or off | `[font-kerning:none]` |
+| `text-box: trim-both` | Trim space above and below | `[text-box:trim-both_cap_alphabetic]` |
+| `max-width` on text columns | Cap at ~60–75 characters per line | `max-w-xl` / `max-w-2xl` / `max-w-[65ch]` |
+| `text-align` | Where lines start and end | `text-start` / `text-center` |
+
+## Wrapping and overflow
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `text-wrap: balance` | Even out heading lines | `text-balance` |
+| `text-wrap: pretty` | Avoid orphaned words | `text-pretty` |
+| `text-overflow: ellipsis` | Ellipsis for clipped text | `truncate` |
+| `line-clamp` | Cut off after N lines | `line-clamp-*` |
+| `overflow-wrap: break-word` | Break long strings | `break-words` |
+| `white-space: nowrap` | Stop wrapping | `whitespace-nowrap` |
+| `text-transform` | Change the casing | `uppercase` / `capitalize` |
+
+## Decoration and interaction
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `text-decoration-line: underline` | Draw an underline | `underline` |
+| `text-decoration-color` | Underline color | `decoration-*` |
+| `text-decoration-thickness` | Underline thickness | `decoration-1` / `decoration-2` |
+| `text-underline-offset` | Push the line down | `underline-offset-*` |
+| `text-underline-position: from-font` | Underline position from the font | `[text-underline-position:from-font]` |
+| `text-decoration-style` | Dotted, dashed or wavy | `decoration-dotted` / `decoration-wavy` |
+| `text-decoration-thickness: from-font` | Underline set by the font | `decoration-from-font` |
+| `text-decoration-skip-ink` | Gaps around descenders | `[text-decoration-skip-ink:auto]` |
+| `caret-color` | Tint the text cursor | `caret-*` |
+| `user-select: none` | Suppress selection on a verified drag/gesture conflict only | `select-none` |
+| `text-shadow` | Shadow behind the letters | `text-shadow-*` |
+| `-webkit-text-stroke` | Outline the letters | `[-webkit-text-stroke:1px_black]` |
+| `background-clip: text` | Clip a background to the letters | `bg-clip-text` |
+| `initial-letter` | Size a drop cap | `[initial-letter:3]` |

package/framework/skills/great-interface/references/details-and-accessibility.md

@@ -0,0 +1,119 @@
+# Details and accessibility
+
+Underlines, selection, forms, decorative text and the floors that keep everything readable.
+
+## Underlines
+
+Default underline position is browser-determined, sometimes too close, sometimes cutting through descenders, sometimes too thin. Pull position and thickness from the font's own metrics:
+
+```css
+a {
+  text-underline-position: from-font;
+  text-decoration-thickness: from-font;
+}
+```
+
+A dotted underline on an abbreviation:
+
+```css
+abbr {
+  text-decoration: underline dotted;
+}
+```
+
+Or tune manually:
+
+```css
+a {
+  text-decoration-thickness: 1px;
+  text-underline-offset: 3px;
+  text-decoration-skip-ink: auto;
+  text-decoration-color: var(--color-gray-1000);
+  transition: text-decoration-color 200ms ease-out;
+}
+
+a:hover {
+  text-decoration-color: var(--color-gray-1200);
+}
+```
+
+Animate the custom element however the effect requires.
+
+## Selection
+
+- `::target-text` styles the phrase a shared link scrolls to.
+- The Custom Highlight API styles ranges you pick yourself, like search matches, without extra markup.
+
+## Forms and editable text
+
+- `::placeholder` styles the hint in an empty field.
+- `caret-color` colors the blinking insertion bar. Color is about as far as caret styling goes; a fully custom caret is hard to build and rarely worth it.
+
+### iOS input zoom
+
+This is an accessibility feature: `16px` is the web default, and Safari treats smaller as too hard to read while typing.
+
+The two fixes differ in what they do to the design, not in correctness.
+
+**Size up on mobile.** The input renders at `16px` on small screens and drops to the design size from the `sm` breakpoint up. Nothing to compensate, but the mobile input no longer matches the desktop one.
+
+```tsx
+<input className="text-base sm:text-sm" type="email" />
+```
+
+**Scale the text down.** Keep `font-size` at `16px` so Safari never zooms, then render at the intended size with a transform. The design survives at every viewport, at the cost of two compensating calcs. Widen the element by the inverse of the scale so it still fills its container once shrunk, and divide `line-height` by the same factor so the intended leading survives. `origin-left` pins the text to the start edge, `origin-right` under RTL. Above the breakpoint, drop the transform and set the real size.
+
+```tsx
+// 13px rendered from a 16px font-size: 13 / 16 = 0.8125
+<div className="flex h-10 items-center rounded-[10px] bg-gray-300 px-2.5">
+  <input
+    className="h-full w-[calc(100%/0.8125)] origin-left scale-[0.8125] bg-transparent text-base leading-[calc(1.125/0.8125)] outline-none sm:w-full sm:scale-100 sm:text-[13px]"
+    type="email"
+  />
+</div>
+```
+
+The transform shrinks the whole box, not only the glyphs, so let a wrapper draw the field's surface and keep the input transparent. A background, border, or ring on the scaled element shrinks with the text and misses the intended hit area.
+
+## Decorative text
+
+| Property | Effect |
+| --- | --- |
+| `::first-letter` | Drop cap, widely supported |
+| `::first-line` | Styles only the first line |
+| `initial-letter` | Sizes the drop cap; limited support, no Firefox yet |
+| `background-clip: text` | Clips a background or gradient to the letter shapes |
+| `-webkit-text-stroke` | Outlines the letters; works across modern browsers despite the prefix |
+| `text-shadow` | Like `box-shadow` but follows the character shapes |
+
+A text stroke drawing lines inside the letters is the font. The stroke traces every contour, and variable fonts usually keep overlapping shapes unmerged. Static fonts do not have this issue.
+
+## Sizes
+
+Typography must survive the reader changing it: zoom, a larger browser font size, an overridden line height or letter spacing.
+
+| Text | Size |
+| --- | --- |
+| Long-form body starting point | Around `16px`, verified in the actual typeface and measure |
+| Inputs and menus starting point | Around `14px` |
+| Captions | `13px` |
+| Floor | Rarely below `12px` |
+
+## Font smoothing
+
+Tailwind's `antialiased` sets both properties:
+
+```css
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+```tsx
+<html lang="en">
+  <body class="font-sans antialiased">
+    <main>{children}</main>
+  </body>
+</html>
+```