agemon 0.1.0 → 6.3.0

package/assets/skills/design/agemon-design/references/tokens.md

@@ -0,0 +1,350 @@
+# Token Spine
+
+Every design decision in a project references a three-layer token system established before any component is written. The layers are: **primitive** (raw values named for what they are), **semantic** (contextual meaning, switches between themes), and **component** (specific usage, created on demand). The scope is projects: throwaway prototypes and single standalone components may run on primitives alone — but the moment a second surface appears, build the spine.
+
+This 3-layer contract and the off-system-value definition (any color, radius, or spacing value not drawn from the token system) are the evaluation source for the `token-consistency` loop preset (see `../SKILL.md` → loops.md).
+
+---
+
+## The Three Layers
+
+### Layer 1: Primitive tokens
+
+Raw values. Named for what they ARE, not how they're used. Reusable across themes.
+
+**Color — neutral ramp + accent ramp + semantic bases.**
+Use OKLCH for perceptually uniform steps. See `color.md` for palette strategy and tinted-neutral rationale.
+
+```css
+/* Neutral ramp — warm tint, not pure gray */
+--gray-50:  oklch(98%  0.008 60);
+--gray-100: oklch(95%  0.010 60);
+--gray-200: oklch(90%  0.012 60);
+--gray-300: oklch(82%  0.014 60);
+--gray-400: oklch(70%  0.016 60);
+--gray-500: oklch(58%  0.016 60);
+--gray-600: oklch(46%  0.015 60);
+--gray-700: oklch(36%  0.013 60);
+--gray-800: oklch(26%  0.010 60);
+--gray-900: oklch(18%  0.008 60);
+--gray-950: oklch(12%  0.006 60);
+
+/* Accent ramp — replace hue with your brand value */
+--accent-50:  oklch(97%  0.03 var(--accent-hue));
+--accent-100: oklch(93%  0.06 var(--accent-hue));
+--accent-200: oklch(86%  0.10 var(--accent-hue));
+--accent-300: oklch(78%  0.14 var(--accent-hue));
+--accent-400: oklch(68%  0.18 var(--accent-hue));
+--accent-500: oklch(58%  0.20 var(--accent-hue));
+--accent-600: oklch(48%  0.19 var(--accent-hue));
+--accent-700: oklch(38%  0.16 var(--accent-hue));
+--accent-800: oklch(28%  0.12 var(--accent-hue));
+--accent-900: oklch(20%  0.08 var(--accent-hue));
+--accent-950: oklch(13%  0.05 var(--accent-hue));
+
+/* Semantic color bases — for success / warning / error / info */
+--green-400:  oklch(72%  0.18 145);
+--green-600:  oklch(52%  0.18 145);
+--amber-400:  oklch(78%  0.16 70);
+--amber-600:  oklch(58%  0.16 70);
+--red-400:    oklch(65%  0.20 25);
+--red-600:    oklch(48%  0.20 25);
+--blue-400:   oklch(66%  0.16 250);
+--blue-600:   oklch(50%  0.16 250);
+```
+
+**Spacing — 8pt scale.** Full rhythm rules and when to compress → see `layout.md`.
+
+```css
+--space-xs:  0.25rem;  /* 4px */
+--space-sm:  0.5rem;   /* 8px */
+--space-md:  1rem;     /* 16px */
+--space-lg:  1.5rem;   /* 24px */
+--space-xl:  2rem;     /* 32px */
+--space-2xl: 3rem;     /* 48px */
+--space-3xl: 4rem;     /* 64px */
+--space-4xl: 6rem;     /* 96px */
+```
+
+**Type — size, weight, line-height, letter-spacing.** Full scale and font selection → see `typography.md`.
+
+```css
+--text-xs:   0.75rem;   /* 12px */
+--text-sm:   0.875rem;  /* 14px */
+--text-base: 1rem;      /* 16px */
+--text-lg:   1.125rem;  /* 18px */
+--text-xl:   1.25rem;   /* 20px */
+--text-2xl:  1.5rem;    /* 24px */
+--text-3xl:  1.875rem;  /* 30px */
+--text-4xl:  2.25rem;   /* 36px */
+--text-5xl:  3rem;      /* 48px */
+
+--font-light:   300;
+--font-regular: 400;
+--font-medium:  500;
+--font-semibold: 600;
+--font-bold:    700;
+
+--leading-none:   1;
+--leading-tight:  1.1;
+--leading-snug:   1.3;
+--leading-normal: 1.5;
+--leading-relaxed: 1.65;
+
+--tracking-tight: -0.03em;
+--tracking-normal: 0;
+--tracking-wide:  0.01em;
+--tracking-wider: 0.05em;
+```
+
+**Radii.**
+
+```css
+--radius-none: 0;
+--radius-sm:   0.125rem;  /* 2px — minimal, sharp */
+--radius-md:   0.375rem;  /* 6px — inputs, badges */
+--radius-lg:   0.625rem;  /* 10px — cards */
+--radius-xl:   0.875rem;  /* 14px — modals, large panels */
+--radius-2xl:  1.25rem;   /* 20px — expressive cards, popovers */
+--radius-full: 9999px;    /* pills, avatars */
+```
+
+**Shadows — layered ambient + direct.** Always stack two layers minimum. See `layout.md` for the scale and the "never flat" rule.
+
+```css
+--shadow-sm: 0 1px 2px oklch(0% 0 0 / 0.05);
+--shadow-md: 0 4px 6px oklch(0% 0 0 / 0.07),
+             0 1px 3px oklch(0% 0 0 / 0.06);
+--shadow-lg: 0 10px 15px oklch(0% 0 0 / 0.09),
+             0 4px  6px  oklch(0% 0 0 / 0.05);
+--shadow-xl: 0 20px 25px oklch(0% 0 0 / 0.10),
+             0 8px  10px oklch(0% 0 0 / 0.04);
+```
+
+**Motion — durations and easings.** Perceptual bands and choreography rules → see `motion.md`.
+
+```css
+--duration-instant: 80ms;
+--duration-fast:    150ms;
+--duration-normal:  250ms;
+--duration-slow:    400ms;
+
+--ease-out:    cubic-bezier(0.16, 1, 0.3, 1);
+--ease-in:     cubic-bezier(0.4, 0, 1, 1);
+--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+```
+
+**Z-index — semantic layers, never arbitrary numbers.**
+
+```css
+--z-base:           0;
+--z-raised:         1;
+--z-dropdown:       10;
+--z-sticky:         20;
+--z-modal-backdrop: 30;
+--z-modal:          40;
+--z-toast:          50;
+--z-tooltip:        60;
+```
+
+> **The naming rule:** primitives are nouns about the value — `--gray-500`, `--space-md`, `--radius-lg`. Never role-named at this layer. `--button-bg` is a component token. `--text-primary` is a semantic token. Both are wrong here.
+
+---
+
+### Layer 2: Semantic tokens
+
+Contextual meaning. References primitives. This is the layer that switches between light and dark mode — primitives never change; semantics remap.
+
+```css
+:root {
+  /* Surface stack — 5 levels of elevation */
+  --surface-canvas:  var(--gray-50);   /* page background */
+  --surface-raised:  var(--gray-100);  /* cards, panels */
+  --surface-overlay: #fff;             /* modals, sheets */
+  --surface-sunken:  var(--gray-200);  /* inset areas, code blocks */
+  --surface-inverse: var(--gray-900);  /* inverted blocks, tooltips */
+
+  /* Text */
+  --text-primary:    var(--gray-900);
+  --text-secondary:  var(--gray-600);
+  --text-tertiary:   var(--gray-400);
+  --text-on-accent:  #fff;
+  --text-on-inverse: var(--gray-50);
+  --text-link:       var(--accent-600);
+  --text-success:    var(--green-600);
+  --text-warning:    var(--amber-600);
+  --text-error:      var(--red-600);
+
+  /* Border */
+  --border-subtle:  oklch(0% 0 0 / 0.06);
+  --border-default: oklch(0% 0 0 / 0.12);
+  --border-strong:  oklch(0% 0 0 / 0.24);
+  --border-focus:   var(--accent-500);
+  --border-error:   var(--red-400);
+
+  /* Accent */
+  --accent-bg:        var(--accent-500);
+  --accent-bg-hover:  var(--accent-600);
+  --accent-bg-active: var(--accent-700);
+  --accent-text:      #fff;
+  --accent-border:    var(--accent-400);
+
+  /* Status — bg / text / border per state */
+  --success-bg:     oklch(96% 0.04 145);
+  --success-text:   var(--green-600);
+  --success-border: var(--green-400);
+
+  --warning-bg:     oklch(97% 0.04 70);
+  --warning-text:   var(--amber-600);
+  --warning-border: var(--amber-400);
+
+  --error-bg:       oklch(97% 0.04 25);
+  --error-text:     var(--red-600);
+  --error-border:   var(--red-400);
+
+  --info-bg:        oklch(96% 0.04 250);
+  --info-text:      var(--blue-600);
+  --info-border:    var(--blue-400);
+}
+```
+
+Dark mode remaps semantics only — primitives are untouched:
+
+```css
+[data-theme="dark"] {
+  --surface-canvas:  var(--gray-950);
+  --surface-raised:  var(--gray-900);
+  --surface-overlay: var(--gray-800);
+  --surface-sunken:  oklch(9% 0.008 60);  /* darker than canvas */
+  --surface-inverse: var(--gray-50);
+
+  --text-primary:    var(--gray-50);
+  --text-secondary:  var(--gray-400);
+  --text-tertiary:   var(--gray-600);
+  --text-on-inverse: var(--gray-900);
+
+  --border-subtle:  oklch(100% 0 0 / 0.06);
+  --border-default: oklch(100% 0 0 / 0.12);
+  --border-strong:  oklch(100% 0 0 / 0.24);
+
+  /* Accent desaturates ~12% in dark to prevent burn */
+  --accent-bg:        oklch(58% 0.18 var(--accent-hue));
+  --accent-bg-hover:  oklch(65% 0.18 var(--accent-hue));
+  --accent-bg-active: oklch(70% 0.18 var(--accent-hue));
+}
+```
+
+---
+
+### Layer 3: Component tokens
+
+Specific usage. References semantics. Created on demand per component — not pre-built as a blanket catalog.
+
+```css
+/* Example: button */
+--button-primary-bg:            var(--accent-bg);
+--button-primary-bg-hover:      var(--accent-bg-hover);
+--button-primary-bg-active:     var(--accent-bg-active);
+--button-primary-text:          var(--accent-text);
+--button-primary-border-radius: var(--radius-md);
+--button-primary-padding-x:     var(--space-md);
+--button-primary-padding-y:     var(--space-sm);
+
+/* Example: input */
+--input-bg:            var(--surface-canvas);
+--input-border:        var(--border-default);
+--input-border-focus:  var(--border-focus);
+--input-border-error:  var(--border-error);
+--input-text:          var(--text-primary);
+--input-placeholder:   var(--text-tertiary);
+--input-border-radius: var(--radius-md);
+```
+
+> **When to create component tokens:** only when a component has multiple states or themes. A simple component referencing semantic tokens directly is fine — don't add a layer to prove you understand the system.
+
+---
+
+## Light + Dark: Both Intentional
+
+Dark mode is not the negation of light mode. Both are designed; neither is a fallback.
+
+> **The intentional-dark test:** if your dark mode maps `--text-primary` from `gray-900` to `gray-100` and stops there, you inverted — you didn't design. Real dark mode rebalances the entire surface stack.
+
+**The canvas rule.** `--surface-canvas` in dark sits between `gray-950` and `gray-900` with a slight hue tint. Pure `#000` reads as broken on any monitor with backlight bleed — it's also a cold dead black that strips warmth from everything above it.
+
+**The accent rule.** Saturated accent colors burn on dark surfaces. Drop chroma 10-15% in OKLCH when switching to dark. The hue stays constant; only `C` shifts. This preserves brand recognition while reducing visual strain.
+
+**The shadow rule.** Shadows are invisible on dark surfaces — black-on-near-black has no contrast. In dark mode: replace `box-shadow` depth with a `1px` border ring using `--border-default`, or a subtle top-edge highlight (`inset 0 1px 0 oklch(100% 0 0 / 0.08)`). Reserve box-shadow for colored glows only.
+
+**The text rule.** Pure white (`#fff`) on dark backgrounds creates excessive halation on OLED screens. Use `--gray-50` or a warmer `oklch(97% 0.01 60)` as your lightest text value.
+
+**The transition rule.** Always declare `color-scheme: light dark` for native form controls to adopt the right system rendering. Provide `prefers-color-scheme` for users without a toggle; respect the user's explicit toggle when present — never override it with system preference once the user has made a choice.
+
+```css
+/* Both modes in one block */
+:root {
+  color-scheme: light dark;
+
+  /* Light defaults above */
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    /* Paste dark remaps here — same keys as light */
+  }
+}
+
+[data-theme="dark"] {
+  /* Explicit toggle — overrides media query */
+}
+```
+
+---
+
+## Token Categories Required
+
+Every non-trivial UI needs all seven. Missing categories produce ad-hoc inline values that break theming.
+
+| Category | Primitive examples | Semantic examples | Notes |
+|---|---|---|---|
+| Color | `--gray-50` → `--gray-950`, `--accent-50` → `--accent-950` | `--text-primary`, `--surface-raised`, `--accent-bg` | Light + dark both required |
+| Spacing | `--space-xs` → `--space-4xl` | (typically used directly) | See `layout.md` for scale and rhythm rules |
+| Type | `--text-xs` → `--text-5xl`, `--leading-tight`, `--font-medium` | `--font-display`, `--font-body`, `--font-mono` | See `typography.md` for scale and letter-spacing rules |
+| Radii | `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-full` | `--radius-card`, `--radius-button`, `--radius-input` | Vary by element — uniform radius is the AI tell |
+| Shadows | `--shadow-sm` → `--shadow-xl` | `--elevation-raised`, `--elevation-overlay`, `--elevation-modal` | Stack 2+ layers per shadow; dark mode requires border-ring replacement |
+| Motion | `--duration-instant` → `--duration-slow`, `--ease-out`, `--ease-spring` | `--motion-hover`, `--motion-modal-in` | See `motion.md` for perceptual bands and choreography |
+| Z-index | `--z-dropdown`, `--z-modal`, `--z-toast` | (typically used directly) | Semantic labels, never arbitrary numbers |
+
+---
+
+## When to Extend vs. Replace
+
+**If the project has a token system:**
+- **Extend** — add the missing layer or category. The most common gap is missing semantics: primitives exist, but nothing switches for dark mode and no surface stack is defined.
+- **Audit** — check dark mode is intentional (run the test above), semantic naming exists, all 7 categories are present.
+- **Don't replace** unless the user explicitly asks. Token replacement is a multi-week refactor. Propose additions as patches, not rewrites.
+
+**If the project has nothing:**
+- **Establish primitives first** — color (neutral ramp + one accent), spacing (8pt scale), type (5 sizes + 3 weights). These three cover the majority of any UI.
+- **Add semantics on demand** as components get built. Surface stack + text roles are almost always next.
+- **Defer component tokens** until variant explosion — more than 2-3 states or themes — forces them.
+
+---
+
+## When the Token Spine Doesn't Apply
+
+- **Single-page experiences** (landing pages, one-off campaign pages) — primitives + inline use is fine when nothing will be themed or reused. Semantics add no value if there's one theme and no components.
+- **Adopted upstream systems** (Material, shadcn, Ant Design) — use the upstream tokens wholesale. Don't reinvent a parallel system alongside an existing one; that's two token systems to maintain.
+- **Native iOS / Android** — platform tokens (`systemBackground`, `label`, `tint`) govern rendering. Custom tokens run parallel and cause drift.
+
+---
+
+## Cross-References
+
+- Spacing scale: see `layout.md` for the full table and spacing rhythm rule.
+- Type scale: see `typography.md` for sizes, weights, scoped letter-spacing, and line-height by script.
+- Color strategy: see `color.md` for OKLCH rationale, tinted neutrals, accent budget, and semantic palette structure.
+- Motion durations: see `motion.md` for the duration scale, perceptual bands, and reduced-motion contract.
+
+The spine ties these together. Each scale is its own discipline; the spine defines how they layer.

package/assets/skills/design/agemon-design/references/typography.md

@@ -0,0 +1,248 @@
+# Typography
+
+Type scale, font selection, readability, and weight systems.
+
+---
+
+## Essentials
+
+Apply these in all standard Latin-script web UI unless a specific context overrides:
+
+- **`text-wrap: balance`** for headings; **`text-wrap: pretty`** for body
+- **`font-variant-numeric: tabular-nums`** for data/numbers
+- **Truncation handling** for dense UI; flex children need `min-w-0`
+- **Smart punctuation**: curly quotes (`“` `”`), apostrophes (`’`), ellipsis (`…`), em-dash (`—`)
+- **Non-breaking spaces**: `10 MB`, `⌘ K`, brand names, `$ 79/month`
+
+**Font recommendations** — pick one family for body, optionally a second for display. In a single product surface, don't mix more than two typefaces; editorial layouts intentionally mix three or more for hierarchy.
+
+Choose by genre and subject. These are examples to show the range, not defaults; use the project's fonts first, and say why when you pick one.
+
+| Genre / subject | Examples |
+|----------|-------------|
+| Dense data and tooling | IBM Plex Sans, Source Sans 3, Atkinson Hyperlegible |
+| Editorial and long-form | Newsreader, Source Serif 4, Literata, Alegreya |
+| Technical or workshop feel | Space Grotesk, Barlow, Archivo |
+| Warm, human, consumer | Nunito Sans, Figtree, Lexend |
+| Monospace for code and IDs | JetBrains Mono, IBM Plex Mono, Commit Mono |
+| No web font wanted | `system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif` |
+
+**A font you would reach for on any project is a default, not a choice.** On landings, portfolios, and brand surfaces the display face carries voice — reaching for the same sans every build produces monoculture. Selection procedure for marketing display type:
+
+1. Write three concrete brand-voice words from the brief ("warm, mechanical, opinionated" — not "modern, clean").
+2. Note the font you'd reach for by reflex; if it's the same face your last marketing build used, reject it and rotate.
+3. Pick for the voice words, then cross-check: "creative brief = serif" is itself a reflex — a distinctive sans display (Cabinet Grotesk, Satoshi, GT Walsheim class) can fit a creative/premium brief; choose by the voice words, not by habit. Serif display only when the brief is genuinely editorial, luxury, or publication-shaped, and rotate which serif.
+4. Emphasize within a headline using italic or bold of the **same family** — never inject a one-word serif into a sans headline for "visual interest".
+
+**Italic descender clearance:** italic display words containing `y g j p q` clip under `line-height: 1`. Use ≥1.1 and reserve bottom padding on the wrapper.
+
+---
+
+## Type Hierarchy
+
+Create a clear scale from most important to least. Two weights (regular + one of
+semibold/bold) cover most products; every added weight is another hierarchy level readers
+must decode. For long-form reading (articles, docs) the body floor is 18px — 14-16px serves
+UI labels and controls, not sustained reading.
+
+### The ladder is what you use, not what you define
+
+A nine-step scale is a palette. The **ladder** is the four to six steps that actually appear
+in the built page, and it is the ladder a reader sees. Emitting most of a modular scale
+produces a gradient of sizes where every step is 1.2x the last — legible, forgettable, and
+the single loudest tell of a surface built by an agent rather than designed.
+
+Measured on four surfaces whose typography is the reason people copy them (a project tool, a
+deploy platform, a voice API, a commerce framework), at 2120x1143:
+
+| | A | B | C | D |
+|---|---|---|---|---|
+| distinct sizes rendered in the fold | 9 | **4** | 5 | **4** |
+| sizes below 14px | 4 | **0** | 2 | 2 |
+| display size | 64 | 64 | 48 | 64 |
+| next size used below it | 20 | 24 | 16 | 16 |
+| **the jump** | **3.2x** | **2.7x** | **3.0x** | **4.0x** |
+| weight of the display type | 510 | 450-500 | 400 | 500 |
+| distinct weights | 3 | 3 | 3 | **2** |
+
+Three rules fall out of that table, and all three are checkable:
+
+1. **Four to six steps, not nine.** One label size, one body size, one intermediate, one
+   section head, one display. Collapse everything else onto the nearest step. Half-pixel
+   neighbours (13px and 13.5px) are never a distinction — they are indecision.
+2. **The display step sits 2.5x to 4x above the step below it, with nothing in between.**
+   Display type is made by the **gap**, not by the size: 56px directly above 44px reads as
+   slightly bigger text, while 76px above 30px reads as a headline. If the jump is small,
+   either raise the display size or delete the step under it.
+3. **Display type is not bold.** None of the four sets its largest type above 510. Big and
+   bold reads cheap — a poster made in a hurry; big and medium reads like the size was
+   already enough. Reserve 600-700 for 13-16px labels and buttons, where weight is the only
+   emphasis available.
+
+Corollary on small type: seven sizes under 14px is how a landing page ends up reading as a
+dashboard. Two is plenty, and one of those should be the mono label size.
+
+### Scale (a palette to choose from, not a set to emit)
+```css
+--text-xs:   0.75rem;   /* 12px - mono labels, captions */
+--text-sm:   0.875rem;  /* 14px - secondary text */
+--text-base: 1rem;      /* 16px - body text */
+--text-lg:   1.25rem;   /* 20px - lead text */
+--text-xl:   1.875rem;  /* 30px - section heads */
+--text-2xl:  2.75rem;   /* 44px - the one big number, on data surfaces */
+--text-3xl:  4.75rem;   /* 76px - display */
+```
+Pick four to six of these per surface and use nothing else. A dense console legitimately
+sits low on the ladder (11 / 13 / 16 / 22 / 64); a restaurant page legitimately skips the
+middle entirely (12 / 15 / 30 / 88). Both are ladders. Twelve evenly-spaced steps is not.
+
+Match the *floor* to the product type — dense apps start at 11-13px, marketing at 13-16px —
+but the jump to display stays large in both. A console with a 2.9x jump to its one headline
+number is right; a console with twelve steps is not.
+
+---
+
+## Font Selection
+
+### Principles
+- **Display fonts** for headlines — distinctive, personality-rich. A font excellent for display (high contrast, tight spacing) is wrong for body text at 16px.
+- **Body fonts** for running text — readable, neutral, well-hinted at small sizes. A workhorse body font (Charter, IBM Plex Sans) often looks bland at hero scale — that's fine, just don't ask it to do both jobs.
+- **UI fonts** for labels and dense interfaces — optimized x-height, open apertures. Inter and Geist are UI fonts first; using them at 48px display is fine, but don't expect typographic personality.
+- **Monospace** as intentional accent — not as lazy "dev tool" default
+- **Variable fonts** for flexibility — one file, many weights
+- **Subset fonts** — ship only code points/scripts you use
+
+### Loading
+```html
+<link rel="preload" href="/fonts/main.woff2" as="font" type="font/woff2" crossorigin>
+```
+```css
+@font-face {
+  font-family: 'Main';
+  src: url('/fonts/main.woff2') format('woff2');
+  font-display: swap;
+  unicode-range: U+0000-007F; /* Basic Latin only */
+}
+```
+
+**`font-synthesis: none`** on any family missing a weight or style file. Without it, the browser fakes bold by smearing the outline and fakes italic by shearing it — synthesized glyphs that ship silently to production. Setting `font-synthesis: none` makes the gap fail visibly in development (regular weight renders where bold was requested) so it gets caught before ship, instead of shipping fake glyphs users never notice as wrong but perceive as slightly off.
+
+### Feature Control: Properties Over Raw Tags
+
+When a high-level CSS property and a raw OpenType feature tag both produce the same visual result, take the property. **Why it matters more than it looks:** a property degrades gracefully — a fallback font that lacks the matching axis or feature just ignores the property and falls back to its own default rendering, no error, nothing visibly broken. A raw feature tag has no such fallback path; it silently stops applying, and the gap stays invisible until someone diffs the rendered output against the design.
+
+Where this shows up in practice: `font-variant-numeric: tabular-nums slashed-zero` instead of a hand-written feature-tag equivalent, for the tabular figures this skill already asks for anywhere numbers stack in a column; `font-weight` instead of `font-variation-settings: 'wght' 600` on variable fonts; `font-variant-caps` instead of a raw `font-feature-settings` string for small caps.
+
+### Letter-Spacing by Size
+
+These rules apply to **Latin script, sans-serif and display faces** unless stated otherwise. Do not adjust tracking on CJK, Arabic, Devanagari, or other non-Latin scripts unless you deeply understand their typographic conventions — the font's built-in metrics handle it. Serif faces are designed with tracking already optimized across sizes; tightening them at display sizes damages their rhythm.
+
+- **Display (≥24px), sans-serif Latin**: tighten to `-0.02em` to `-0.04em` — large sizes optically appear loose at default tracking. `tracking-tight` in Tailwind.
+  > **When it breaks:** serif faces (Playfair, Freight, Garamond) — leave at default. The built-in sidebearings were set for the size.
+- **Body text (14-18px)**: leave `letter-spacing` alone — the font designer optimized it. This holds for all scripts and classifications.
+- **Small text/labels (11-13px), Latin**: slight positive tracking `+0.01em` to `+0.02em` improves readability at tight optical sizes. `tracking-wide` in Tailwind.
+  > **When it breaks:** CJK labels — already have generous inter-glyph spacing; adding more creates uneven color.
+- **ALL CAPS labels, Latin**: `+0.05em` to `+0.1em` — all-caps removes descender space and needs tracking to stay readable. `tracking-widest` in Tailwind.
+  > **When it breaks:** Not a universal Never. ALL CAPS is acceptable for small category labels (10-13px), regulatory text, and utilitarian aesthetics — just always add tracking when you do it.
+
+### Never
+- Use system fonts when personality matters — system stacks are fine for utilitarian UI but they signal "no design intent" in brand-facing contexts
+- Mix more than 2-3 typefaces **in a single product surface** — editorial layouts (magazines, marketing pages) intentionally exceed this for typographic hierarchy
+
+---
+
+## Readability
+
+### Line Length
+- **Prose body text**: 45-75 characters per line (ideal: 66). Use `max-width: 65ch` on text containers.
+  > **When it breaks:** UI labels, buttons, table cells, and dense data layouts tolerate much shorter or longer lines. The 65ch rule is for continuous reading, not UI components.
+
+### Line Height
+
+Line height is script- and x-height-dependent — no single value works universally.
+
+- **Body text (14-18px), Latin**: 1.5 to 1.65. Tall x-height fonts (Inter, Geist) tolerate the lower end; short x-height faces (Garamond, Freight) may need slightly tighter — test visually.
+- **Display headlines (≥24px)**: 1.05 to 1.2. Headlines need to feel tight; a 1.5 line-height on a 48px heading looks airy and unintentional.
+- **UI labels and dense interfaces**: 1.3 to 1.4. Enough air to avoid collision, not so much that the interface feels sparse.
+- **CJK scripts**: 1.7 to 1.85 — CJK glyphs have different vertical metrics and need more inter-line clearance than Latin at the same size.
+  > **When it breaks:** Applying 1.5 body line-height to display text; applying CJK ratios to Latin body text (creates too much vertical space).
+
+### Text Wrapping
+```css
+h1, h2, h3, h4 { text-wrap: balance; }
+p, li, dd      { text-wrap: pretty; }
+```
+
+- **`text-wrap: balance`** — even line lengths for headings
+- **`text-wrap: pretty`** — avoids widows/orphans in body text
+
+---
+
+## Data Typography
+
+```css
+/* Tabular numbers for data alignment */
+.data-value { font-variant-numeric: tabular-nums; }
+
+/* Or use a monospace font for data-heavy tables */
+.data-table { font-family: var(--font-mono, monospace); }
+```
+
+- **`tabular-nums`** for any numbers that align vertically in columns (tables, prices, stats) — this is a near-universal rule for data UI; the exception is decorative numerals in display headings where proportional figures look better
+- **Truncate dense UI**: `truncate` or `line-clamp-*`
+- **Flex children need `min-w-0`** to allow truncation
+
+---
+
+## Text Handling
+
+### Content Overflow
+```css
+/* Single line truncation */
+.truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Multi-line clamp */
+.line-clamp-3 {
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+/* Flex children MUST have min-w-0 */
+.flex-child {
+  min-width: 0; /* allows text to truncate */
+}
+```
+
+### Special Characters
+- **Curly quotes**: " " not " "
+- **Ellipsis character**: … not ...
+- **Non-breaking spaces**: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+- **`scroll-margin-top`** on headings for anchor links
+
+### Resilience
+- Layouts handle short, average, AND very long content
+- Handle empty strings without broken UI
+- Locale-aware: `Intl.DateTimeFormat`, `Intl.NumberFormat`
+
+---
+
+## Cap-Height Trimming & Underlines
+
+- **`text-box: trim-both cap alphabetic`** strips out the half-leading a browser adds above and below the glyph outlines — that reserved sliver is what makes a single-line label inside a pill, chip, or button look like it's drifted below true center instead of sitting on it. Until support is universal, the old manual counter-measure still works: nudge the text node with a small negative margin or padding tuned to the font's own metrics.
+- **`text-underline-position: from-font`** and **`text-decoration-thickness: from-font`** pull the underline's offset and weight from the font file's own metrics instead of the browser's generic guess — closer underlines on script-adjacent faces, correctly-weighted underlines on heavier display fonts.
+- **Reserve dotted underlines for "more info" affordances** — glossary terms, `<abbr>`, inline definitions — not for links. A dotted underline reads as "hover for detail," and putting it on a normal link signals the wrong interaction.
+
+---
+
+## Anti-aliasing
+
+- **Root smoothing (macOS):** apply `-webkit-font-smoothing: antialiased` + `-moz-osx-font-smoothing: grayscale` once on `html` (Tailwind: `antialiased` on the root element). macOS renders text heavier than intended by default; this thins it for crisper text. Set it ONCE at the root — never per-element, or smoothed and unsmoothed text end up with visibly different weights. No-op on other platforms, safe to apply universally.
+- Scaling text via `transform` can change smoothing
+- Prefer animating a wrapper instead of text node directly
+- If artifacts persist: `translateZ(0)` or `will-change: transform` to promote layer