claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/frontend-ui/rules/motion-and-animation.md

@@ -0,0 +1,283 @@
+---
+name: motion-and-animation
+description: "UI motion rules — the 4-question animation framework, easing curves, duration tables, springs, reduced motion. Auto-loaded when editing UI files."
+tokens: 2655
+alwaysApply: false
+applyWhenPaths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.ts"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/tailwind.config.*"
+  - "**/*.tokens.*"
+---
+
+# Motion & Animation
+
+Correct motion in aggregate is why an interface feels "right"; animation
+for its own sake is worse than none.
+
+## Hard rules
+
+1. Ask the 4 questions below, in order, before writing any animation.
+2. **Scope:** this rule governs 2D UI element transitions.
+   3D/scroll-scrub contexts are governed by gsap-conventions
+   (frontend-3d package), which allows `power2.in` for viewport-exit
+   animations.
+3. Easing in 2D UI: `ease-out` for enter/exit, `ease-in-out` for
+   on-screen morphing, `linear` for constant motion. No `ease-in` in
+   this scope (3D exception in rule 2).
+4. Keep UI animations under 300ms unless genuinely explanatory.
+5. Animate `transform` and `opacity` by default; never animate layout
+   properties (`width`, `height`, `top`, `left`, `margin`). Name exact
+   properties — never `transition: all`.
+6. Honor `prefers-reduced-motion` (blocks below); skipping it is an
+   accessibility bug.
+7. Bounce/elastic: none in standard UI transitions; a subtle bounce
+   (0.1–0.3) is allowed only for drag-release and playful gestures.
+
+## The 4-question framework (ask in order, before writing any animation)
+
+### Question 1 — Should this animate at all?
+
+Decide by frequency of exposure:
+
+| User exposure | Default |
+|---------------|---------|
+| 100+ times per day (keyboard shortcuts, command palette toggle, every list navigation) | **No animation.** |
+| Tens of times per day (hover effects, tab switches, simple toggles) | Remove or drastically reduce — aim for ≤100ms or none. |
+| Occasional (modals, drawers, toasts, navigating between sections) | Standard animation — the meat of UI motion. |
+| Rare or first-time (onboarding, celebratory moments, form submission success) | Can be expressive and expansive. |
+
+**Keyboard-initiated actions get no animation** (<kbd>⌘K</kbd> palette
+open, shortcut navigation): power users trigger them hundreds of times
+daily, and animation delays the exact moment they are trying to be
+fast. Raycast's command palette opens with no animation by design.
+
+An animation a user sees 50 times today has to earn its keep — if you
+cannot state its purpose (Question 2), remove it.
+
+### Question 2 — What is the purpose?
+
+Every animation must answer "why does this animate?" with one of these
+five purposes:
+
+1. **Spatial consistency.** A toast slides in from the right; when the
+   user swipes it away to the right, they intuit where it went because
+   it entered from there. Entry direction = exit direction.
+2. **State indication.** A button morphs shape to signal the state
+   change (idle → loading → success). Without motion, the state change
+   feels invisible.
+3. **Explanation.** A marketing animation that demonstrates a feature's
+   workflow in 3 seconds.
+4. **Feedback.** A button scales 0.97 on `:active`, confirming the
+   interface registered the press before the action completes.
+5. **Preventing jarring change.** An element suddenly appearing or
+   disappearing without transition reads as a bug. Fade + slight
+   scale-from-0.95 avoids that.
+
+If the answer is "it looks cool" and the user sees it often, remove the
+animation.
+
+### Question 3 — What easing should it use?
+
+Decision flow:
+
+```
+Is the element entering or exiting the screen?
+  Yes → ease-out   (starts fast; feels responsive; user sees immediate motion)
+
+  No →
+    Is it moving or morphing on-screen (not entering/exiting)?
+      Yes → ease-in-out   (natural accel/decel; movement feels organic)
+
+    Is it a hover, color change, or opacity-only transition?
+      Yes → ease   (gentle; the default cubic is fine here)
+
+    Is it constant motion (marquee, progress bar, spinner)?
+      Yes → linear
+
+    Default fallback → ease-out
+```
+
+**Entries and exits both use `ease-out` in 2D UI.** `ease-out` starts
+fast, so the user sees immediate motion; `ease-in` starts slow, so a
+300ms dropdown with `ease-in` feels more sluggish than the identical
+dropdown with `ease-out`. Do not use `ease-in` for 2D UI element
+transitions. 3D/scroll-scrub contexts are governed by gsap-conventions
+(frontend-3d package), which allows `power2.in` for viewport-exit
+animations — that exception never applies to the UI transitions covered
+here.
+
+#### Custom curves (stronger than the CSS defaults)
+
+CSS's built-in `ease-out` / `ease-in-out` are too weak to feel
+intentional. Use these four custom `cubic-bezier()` curves by default —
+curves built from scratch are almost never better:
+
+```css
+:root {
+  /* Strong ease-out for UI element entry */
+  --ease-out:    cubic-bezier(0.23, 1, 0.32, 1);
+
+  /* Strong ease-in-out for on-screen morphing/moving */
+  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
+
+  /* iOS-style drawer curve */
+  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
+
+  /* Snappy / responsive — for tiny UI transitions (hovers, buttons) */
+  --ease-snappy: cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+```
+
+### Question 4 — How long should it take?
+
+| Element | Duration |
+|---------|----------|
+| Button press feedback (`:active` scale) | 100–160ms |
+| Tooltip / small popover open | 125–200ms |
+| Dropdown / select open | 150–250ms |
+| Tab / section transition | 180–300ms |
+| Modal / drawer open-close | 200–500ms |
+| Toast slide in-out | 200–350ms |
+| Page transition (SPA) | 300–500ms |
+| Marketing explainer / onboarding demo | Can be 500–2000ms+ |
+
+**Keep UI animations under 300ms** unless they are genuinely
+explanatory — a 180ms dropdown feels more responsive than a 400ms one.
+Perceived-performance nuance: a faster-spinning spinner makes the app
+feel faster even when actual load time is identical.
+
+## Springs vs duration-based
+
+Springs simulate physics — no fixed duration; they settle from
+stiffness/damping/mass parameters. Use them for:
+
+- **Drag-with-momentum gestures** — swipe-to-dismiss a sheet, flick a
+  card. Springs maintain velocity across release.
+- **Decorative mouse-tracking interactions** — a subtle parallax on a
+  hero element. Binding visuals directly to mouse position (no spring)
+  feels artificial and computery; `useSpring` gives it life.
+- **"Alive"-feeling UI elements** — Apple's Dynamic Island, responsive
+  icons that subtly settle.
+- **Gestures interruptible mid-animation** — springs preserve velocity
+  when interrupted; CSS animations restart from zero.
+
+Do not use springs for:
+
+- Simple state transitions (open/close, in/out) — duration-based
+  `ease-out` is more predictable and easier to tune.
+- Functional contexts where predictability matters more than
+  naturalness (trading interface, banking, medical).
+
+### Spring configuration patterns
+
+```js
+// Apple-style (easy to reason about):
+{ type: "spring", duration: 0.5, bounce: 0.2 }
+
+// Traditional physics:
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
+```
+
+Standard UI transitions use no bounce. When the interaction is a
+drag-release or playful gesture (drag-to-dismiss, playful
+notification), a subtle `bounce` of 0.1–0.3 is allowed — never higher.
+
+### Mouse-tracking springs — example
+
+```jsx
+// Without spring — feels artificial, instant, computery
+const rotation = mouseX * 0.1;
+
+// With spring — feels natural, has settle
+import { useSpring } from 'framer-motion'; // or 'motion/react'
+const rotation = useSpring(mouseX * 0.1, {
+  stiffness: 100,
+  damping: 10,
+});
+```
+
+## Reduced motion — required, not optional
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+This blanket rule is the safe default. For JS-driven motion, check
+`window.matchMedia('(prefers-reduced-motion: reduce)')` and
+short-circuit the animation. Users with vestibular disorders need this;
+skipping it is an accessibility bug.
+
+## Motion rules of execution
+
+**DO:**
+- Ask the 4 questions in order before writing any animation.
+- Use the four custom `cubic-bezier` curves above (stronger than CSS
+  defaults).
+- Use `ease-out` for entry/exit, `ease-in-out` for on-screen morph.
+- Keep UI animations under 300ms by default.
+- Specify exact properties in transitions (`transition: transform
+  200ms ease-out`).
+- Animate `transform` and `opacity` — they're compositor-accelerated.
+  Other properties trigger layout/paint and can stutter.
+- Use springs for drag/momentum/interruptible gestures.
+- Honor `prefers-reduced-motion`.
+- Scale `from 0.95` and fade for entry, not `from 0`. Nothing in the
+  real world appears from true zero size.
+
+**DO NOT:**
+- Animate keyboard-initiated actions (⌘K open, etc.).
+- Use `ease-in` for 2D UI transitions (3D/scroll-scrub viewport exits
+  follow gsap-conventions, which allows `power2.in`).
+- Use `transition: all` — name exact properties.
+- Ship bounce/elastic in standard UI transitions — a subtle bounce
+  (0.1–0.3) is allowed only for drag-release/playful gestures.
+- Animate for decoration alone if the user sees it 50×/day.
+- Animate `width`, `height`, `top`, `left`, `margin` — use `transform`.
+- Skip reduced motion.
+- Use `scale(0)` as entry — `scale(0.95)` reads as natural.
+- Use the same duration everywhere. Duration is a property, not a
+  constant.
+
+## Output format for motion review
+
+When reviewing UI motion code, output exactly this markdown table — one
+row per issue found, the "Why" column carrying the reasoning. Bulleted
+lists with "Before:" and "After:" on separate lines are not accepted.
+
+```markdown
+| Before | After | Why |
+| --- | --- | --- |
+| `<offending code>` | `<replacement code>` | <one-line reason> |
+```
+
+Filled example:
+
+| Before | After | Why |
+| --- | --- | --- |
+| `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; `all` animates layout props that cause stutter. |
+| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing appears from true zero. |
+| `ease-in` on dropdown | `ease-out` with `--ease-snappy` | `ease-in` delays the initial motion, making it feel sluggish. |
+| No `:active` state on button | `transform: scale(0.97)` for 100ms | Buttons must confirm the press. |
+| `transform-origin: center` on popover | `transform-origin: var(--radix-popover-content-transform-origin)` | Popovers should scale from their trigger point (modals stay centered). |
+
+---
+
+Attribution: duration tables, easing `cubic-bezier` constants, spring
+configurations, and the 4-question framework structure are adapted from
+Emil Kowalski's design-engineering skill (https://emilkowal.ski/skill).
+Prose has been written independently for this package. Remaining
+material draws from Impeccable's `reference/motion-design.md` (Apache-
+2.0). See `../NOTICE.md`.

package/packages/frontend-ui/rules/spatial-and-layout.md

@@ -0,0 +1,212 @@
+---
+name: spatial-and-layout
+description: "Spacing, layout, grids, responsive design — 4pt scale, rhythm over uniformity, container queries for components, viewport queries for pages. Auto-loaded when editing UI files."
+tokens: 1717
+alwaysApply: false
+applyWhenPaths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.ts"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/tailwind.config.*"
+  - "**/*.tokens.*"
+---
+
+# Spatial Design & Layout
+
+## Hard rules (always apply)
+
+1. **Use the canonical spacing scale with semantic token names.** Canonical
+   steps in px: **2, 4, 8, 12, 16, 24, 32, 48, 64, 96, 128** — 4pt multiples
+   plus a single 2px hairline step (`--space-3xs`, for hairline gaps and icon
+   nudges). This list and the token block below are the SAME set — use no
+   spacing value outside it. Name tokens by size role (`--space-xs`,
+   `--space-md`), never by pixel value (`--spacing-8`, `--p-12`) — pixel names
+   break the moment the scale changes. 8pt-only is too coarse; 12px between
+   two values is common.
+2. **Use `gap`, not margins, for sibling spacing** inside flex/grid
+   containers — `gap` cannot margin-collapse. Reserve margins for the outside
+   of a component.
+3. **Vary spacing to create hierarchy.** Different relationships get
+   different values — use the mapping in "Visual rhythm" below. A heading
+   with extra space above it reads as more important.
+4. **Self-adjusting grids over media queries for card content.**
+   `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` reflows
+   without breakpoints. Add media queries only when the layout must genuinely
+   rearrange, not when a grid needs to reflow.
+5. **Container queries for components, viewport queries for pages.** A card
+   inside a sidebar reacts to the sidebar's width via `@container`; use
+   `@media` for page-level layout changes only.
+
+## The spacing scale (canonical)
+
+```css
+:root {
+  --space-3xs: 0.125rem;  /*  2px */
+  --space-2xs: 0.25rem;   /*  4px */
+  --space-xs:  0.5rem;    /*  8px */
+  --space-sm:  0.75rem;   /* 12px */
+  --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 */
+  --space-5xl: 8rem;      /* 128px */
+}
+```
+
+Fluid spacing variants for responsive marketing pages:
+
+```css
+--space-section: clamp(3rem, 8vw, 8rem);
+--space-gutter:  clamp(1rem, 4vw, 3rem);
+```
+
+Rule of thumb: **fluid spacing for sections, fixed spacing inside
+components.** A `Card` gets predictable `--space-md` padding; the gap between
+one `Card` and the next can breathe with the viewport.
+
+## Visual rhythm
+
+Rhythm comes from VARIATION, not from uniform application of a single value.
+Relationship → token:
+
+- Tight groupings (related items) → `--space-xs` to `--space-sm`
+- Heading-to-body gap (related) → `--space-sm`
+- Body-to-next-heading gap (transitional) → `--space-xl`
+- Section separation → `--space-xl` or `--space-2xl`
+- Major breaks → `--space-3xl` or fluid `clamp()` values
+
+## Grid patterns
+
+### The breakpoint-free card grid
+
+```css
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: var(--space-md);
+}
+```
+
+Reflows from 4 columns at desktop to 1 at mobile with zero media queries.
+Use for homogeneous card collections.
+
+### The broken grid (for emphasis)
+
+Intentionally break the grid for hero content, featured items, or visual
+punctuation:
+
+```css
+.feature-grid {
+  display: grid;
+  grid-template-columns: 2fr 1fr 1fr;
+  grid-auto-rows: auto;
+  gap: var(--space-lg);
+}
+.feature-grid > :first-child {
+  grid-row: span 2;  /* The first cell takes double height */
+}
+```
+
+Uniform 3-up card grids feel templated; a 2-1-1 pattern with one spanning
+cell feels designed.
+
+### The asymmetric hero
+
+Left-aligned text + asymmetric image placement reads as "designed". Centered
+text + centered image reads as "template". Default to asymmetric unless
+there is a specific reason not to.
+
+## Container queries
+
+For components that appear in multiple layouts (sidebar, main, modal):
+
+```css
+.card {
+  container-type: inline-size;
+  container-name: card;
+}
+
+@container card (min-width: 320px) {
+  .card .header { flex-direction: row; }
+}
+
+@container card (min-width: 480px) {
+  .card .header { font-size: var(--text-lg); }
+}
+```
+
+The card adapts to its container's width, not the viewport's: a 320px card
+in a narrow sidebar stays stacked even on a 1920px viewport.
+
+## Fluid vs fixed — when to choose which
+
+| Context | Strategy |
+|---------|----------|
+| Marketing page sections | Fluid (`clamp()`) |
+| App shell (header, sidebar, footer) | Fixed — predictable interactions |
+| Card / component internals | Fixed — consistency matters |
+| Text sizes on marketing | Fluid headings, fixed body |
+| Text sizes in product UI | Fixed throughout (see `typography-guidelines.md`) |
+| Column widths in dashboards | Fixed with `minmax()` and explicit breakpoints |
+
+Rule of thumb: **fluid where the content naturally expands, fixed where
+users expect repeatable hit targets and interaction patterns.**
+
+## Breakpoints (when you must use media queries)
+
+Default set — mobile-first:
+
+```css
+/* Default: <640px (mobile) */
+
+@media (min-width: 640px)  { /* small tablet */ }
+@media (min-width: 768px)  { /* tablet / small laptop */ }
+@media (min-width: 1024px) { /* desktop */ }
+@media (min-width: 1280px) { /* wide desktop */ }
+@media (min-width: 1536px) { /* max-out */ }
+```
+
+Prefer **`min-width`** (mobile-first) over `max-width` (desktop-first): each
+breakpoint adds features rather than removing them.
+
+## Spatial rules of execution
+
+**DO:**
+- Use the canonical spacing scale (2px hairline + 4pt steps) with semantic
+  token names.
+- Use `gap` for sibling spacing inside flex/grid containers.
+- Vary spacing for hierarchy — different values between different
+  relationships.
+- Use `repeat(auto-fit, minmax(X, 1fr))` for breakpoint-free card grids.
+- Use container queries for component-level responsiveness.
+- Use viewport queries for page-level layout changes only.
+- Use fluid `clamp()` spacing on marketing page sections.
+- Break the grid intentionally for hero or featured content.
+- Cap body text blocks at `max-width: 65ch`–`75ch` — the same 65–75ch limit
+  as `typography-guidelines.md`.
+
+**DO NOT:**
+- Wrap everything in cards. Not every section needs a container.
+- Nest cards inside cards. Visual noise; flatten.
+- Ship the "3 identical cards with icon + heading + body" template. Use a
+  broken grid, a single hero card, or a list with visual hierarchy — do
+  something more considered.
+- Ship the "big number / small label / stat row / gradient accent"
+  hero-metrics template. It is the default for AI dashboards. Break it.
+- Use identical spacing between every element. Monotony — nothing is
+  emphasised when everything sits at the same weight.
+- Center everything. Asymmetric left-aligned typically feels more designed.
+- Use fluid typography/spacing inside dense product UI. Predictability >
+  fluidity when users repeat the same action 100× a day.
+- Let body text run wider than 75ch (see the DO cap above).
+
+---
+
+Attribution: adapted from Impeccable's `reference/spatial-design.md` and
+`reference/responsive-design.md` (Apache-2.0). See `../NOTICE.md`.

package/packages/frontend-ui/rules/typography-guidelines.md

@@ -0,0 +1,185 @@
+---
+name: typography-guidelines
+description: "Typography rules — modular scales, fluid sizing, pairing, line-height, tracking, font-selection procedure, and the reflex_fonts_to_reject list. Auto-loaded when editing UI files."
+tokens: 1775
+alwaysApply: false
+applyWhenPaths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.ts"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/tailwind.config.*"
+  - "**/*.tokens.*"
+---
+
+# Typography Guidelines
+
+## Principles (hard rules — apply to every UI edit)
+
+1. **Fluid type on content, fixed type in product UI.** Marketing pages
+   and long-form content: size headings with `clamp()` so they flow with
+   the viewport. App UIs, dashboards, forms, and dense tables: fixed
+   `rem` scales — no major design system uses fluid type in product UI,
+   and fluid type inside dense tables is chaos.
+2. **Fewer sizes, more contrast.** Use a 5-step scale with a **1.25×
+   minimum ratio** between steps. Eight sizes at 1.1× apart produce a
+   flat hierarchy that reads as undesigned.
+3. **Line-height scales inversely with line length.** Narrow columns:
+   1.2–1.35. Wide columns: 1.5–1.6. For light text on dark backgrounds,
+   **add 0.05–0.1 to your normal line-height** — light type reads as
+   lighter weight and needs more breathing room.
+4. **Cap body line-length at 65–75ch.** Put `max-width: 65ch` (up to
+   `75ch`) on text blocks. Wider body text is fatiguing.
+5. **Pair a distinctive display font with a refined body font.** Never
+   use a single font family for an entire page — you lose hierarchy
+   tools.
+
+## The font-selection procedure (4 steps, in order)
+
+This procedure exists to break one reflex: "I was told not to use
+Inter, so I will pick my next favorite font" — which becomes the new
+monoculture.
+
+### Step 1 — Write the brief in 3 concrete words
+
+Stop and write down three concrete brand-voice words. Not "modern" and
+not "elegant" — those are dead categories that do not help you decide.
+Concrete examples:
+
+- "warm and mechanical and opinionated"
+- "calm and clinical and careful"
+- "fast and dense and unimpressed"
+- "handmade and a little weird"
+- "expensive and quiet and precise"
+- "loud and angular and young"
+
+The three words will produce mutually exclusive type choices, which is
+the point.
+
+### Step 2 — List your reflex picks, then reject them
+
+Write down the 3 fonts you would normally pick given those words. Check
+every one against the canonical `reflex_fonts_to_reject` list — it
+lives in `ui-anti-patterns.md`, section "The reflex_fonts_to_reject
+list" (Inter, Fraunces, Playfair and Playfair Display, Space Grotesk,
+and all system defaults are on it; read the full list there — this file
+deliberately does not carry a second copy). Most of what you wrote down
+will be on it. Reject every font on that list for this project,
+including the one you were about to pick.
+
+### Step 3 — Pick candidates from a catalog, brief words in mind
+
+Ordered branches — use the first one that applies:
+
+1. **Web access available (WebFetch/WebSearch):** browse these catalogs
+   with the three words held in mind:
+   - Google Fonts (filter aggressively — avoid the top 20)
+   - Pangram Pangram
+   - Future Fonts
+   - Adobe Fonts
+   - ABC Dinamo
+   - Klim Type Foundry
+   - Velvetyne
+   - OH no Type Co
+   - Uncut
+2. **No web access:** propose 5–8 candidates recalled from those same
+   foundries' catalogs. Verify each candidate is absent from the
+   `reflex_fonts_to_reject` list before shortlisting it.
+3. **Project cannot load web fonts at all** (offline target, no font
+   pipeline): choose the most distinctive face already bundled with the
+   project, or compose a deliberate system-safe stack — and state
+   explicitly in your summary that the reject list was relaxed for this
+   reason only.
+
+In every branch, look for something that fits the brand **as a physical
+object**: a museum exhibit caption, a hand-painted shop sign, a 1970s
+mainframe terminal manual, a fabric label sewn inside a coat, a
+children's book printed on cheap newsprint, a laminated menu from a
+highway diner. Reject the first thing that "looks designy" — that is
+the trained reflex too. Keep looking.
+
+### Step 4 — Cross-check against reflex
+
+Check your final pick against the type of brief:
+
+- The right font for an **"elegant"** brief is NOT necessarily a serif.
+- The right font for a **"technical"** brief is NOT necessarily a sans.
+- The right font for a **"warm"** brief is NOT Fraunces.
+- The right font for a **"premium"** brief is NOT Playfair.
+
+If your final pick lines up with the reflex pattern (warm → Fraunces,
+technical → Space Mono, elegant → Playfair), go back to Step 3.
+
+## Web font loading
+
+- Use `font-display: swap` for body text, `font-display: optional` for
+  display headings that should render with the system fallback if the
+  web font is late. Never use `font-display: block`.
+- Preload only the one or two critical faces; preloading everything
+  defeats the point.
+- Subset aggressively. A display font used for a 3-word hero text should
+  not ship the full 5000-glyph payload.
+- Variable fonts save one HTTP request and allow a wider range of
+  weights/widths — prefer them when available.
+- For icon fonts: don't. Use SVG icons. Icon fonts lose accessibility
+  context and scale inconsistently at small sizes.
+
+## OpenType features worth turning on
+
+- `ss01`, `ss02`, … — stylistic sets. Check the type foundry's showings;
+  many fonts ship alternate character forms hidden behind these.
+- `onum` — old-style figures for body text; `tnum` — tabular figures for
+  tables and numeric columns.
+- `kern` — usually on by default, confirm.
+- `liga`, `calt` — ligatures; confirm appropriate for your audience.
+- `case` — case-sensitive forms; turn on for all-caps tracking.
+
+Example:
+```css
+.body { font-feature-settings: "onum", "kern", "liga"; }
+.table-num { font-feature-settings: "tnum", "lnum"; }
+```
+
+## Tracking (letter-spacing)
+
+- Display type (large headings, 40px+) often wants **slightly negative**
+  tracking (`-0.01em` to `-0.03em`). The optical default at large sizes
+  is too loose.
+- Body type wants **0** tracking (rely on the type designer).
+- Small caps and all-caps labels at <12px want **positive** tracking
+  (`+0.05em` to `+0.12em`) for readability.
+- Never apply the same tracking value across the whole scale. Tracking
+  is optical and must vary with size.
+
+## Typography rules of execution
+
+**DO:**
+- Vary font weights and sizes to create clear visual hierarchy.
+- Vary font choices across projects. If your last project was a serif
+  display with sans body, look at sans display / monospace / slab for
+  the next one.
+- Pair a distinctive display font with a refined body font.
+
+**DO NOT:**
+- Use any font on the canonical `reflex_fonts_to_reject` list
+  (`ui-anti-patterns.md`, section "The reflex_fonts_to_reject list") —
+  Inter, Roboto, Playfair, system defaults, all of them. Run the 4-step
+  procedure above instead.
+- Use monospace typography as lazy shorthand for "technical/developer
+  vibes".
+- Place large rounded-corner icons above every heading. They rarely add
+  value and make sites look templated.
+- Use one font family for the entire page.
+- Let the type scale collapse — step ratios below 1.25× read as flat.
+- Set long body passages in all-caps. Reserve all-caps for short labels
+  and headings, ≤6 words.
+- Use fluid type in product UI (forms, tables, dashboards) — Principle 1:
+  fixed `rem` scales there.
+
+---
+
+Attribution: adapted from Impeccable's `reference/typography.md`
+(Apache-2.0). See `../NOTICE.md`.