codexkit 1.0.1 → 1.0.3

package/.codex/skills/frontend-design/references/color-system.md

@@ -0,0 +1,125 @@
+# Color System
+
+> Reference for the `frontend-design` skill. Covers OKLCH-first color pipeline, tinted neutrals, dark mode, and accessibility.
+> Adapted from [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache 2.0).
+
+## Color Spaces: Use OKLCH
+
+**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal. In HSL, 50% lightness in yellow looks bright while 50% in blue looks dark.
+
+```css
+/* OKLCH: lightness (0-100%), chroma (0-0.4+), hue (0-360) */
+--color-primary: oklch(60% 0.15 250);       /* Blue */
+--color-primary-light: oklch(85% 0.08 250); /* Same hue, lighter */
+--color-primary-dark: oklch(35% 0.12 250);  /* Same hue, darker */
+```
+
+**Key insight**: As you move toward white or black, reduce chroma (saturation). High chroma at extreme lightness looks garish.
+
+## Tinted Neutrals
+
+**Pure gray is dead.** Add a subtle hint of your brand hue to all neutrals:
+
+```css
+/* Dead grays */
+--gray-100: oklch(95% 0 0);   /* No personality */
+--gray-900: oklch(15% 0 0);
+
+/* Warm-tinted grays (add brand warmth) */
+--gray-100: oklch(95% 0.01 60);
+--gray-900: oklch(15% 0.01 60);
+
+/* Cool-tinted grays (tech, professional) */
+--gray-100: oklch(95% 0.01 250);
+--gray-900: oklch(15% 0.01 250);
+```
+
+The chroma is tiny (0.01) but perceptible. It creates subconscious cohesion between your brand color and your UI.
+
+## Palette Structure
+
+A complete system needs:
+
+| Role | Purpose | Example |
+|------|---------|---------|
+| **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades |
+| **Neutral** | Text, backgrounds, borders | 9-11 shade scale |
+| **Semantic** | Success, error, warning, info | 4 colors, 2-3 shades each |
+| **Surface** | Cards, modals, overlays | 2-3 elevation levels |
+
+**Skip secondary/tertiary unless you need them.** Most apps work fine with one accent color.
+
+## The 60-30-10 Rule
+
+This rule is about **visual weight**, not pixel count:
+
+- **60%**: Neutral backgrounds, white space, base surfaces
+- **30%**: Secondary colors — text, borders, inactive states
+- **10%**: Accent — CTAs, highlights, focus states
+
+The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare.
+
+## Contrast & Accessibility
+
+| Content Type | AA Minimum | AAA Target |
+|--------------|------------|------------|
+| Body text | 4.5:1 | 7:1 |
+| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 |
+| UI components, icons | 3:1 | 4.5:1 |
+| Non-essential decorations | None | None |
+
+**Gotcha**: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere usually fails WCAG.
+
+### Dangerous Color Combinations
+
+- Light gray text on white (the #1 accessibility fail)
+- **Gray text on any colored background** — gray looks washed out on color; use a darker shade of the background color or transparency instead
+- Red text on green background (or vice versa) — 8% of men can't distinguish these
+- Blue text on red background (vibrates visually)
+- Yellow text on white (almost always fails)
+- Thin light text on images (unpredictable contrast)
+
+### Never Use Pure Gray or Pure Black
+
+Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted.
+
+### Testing
+
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- Browser DevTools: Rendering > Emulate vision deficiencies
+- [Polypane](https://polypane.app/) for real-time testing
+
+## Dark Mode
+
+### Dark Mode Is Not Inverted Light Mode
+
+| Light Mode | Dark Mode |
+|------------|-----------|
+| Shadows for depth | Lighter surfaces for depth (no shadows) |
+| Dark text on light | Light text on dark (reduce font weight) |
+| Vibrant accents | Desaturate accents slightly |
+| White backgrounds | Never pure black — use dark gray (oklch 12-18%) |
+
+```css
+/* Dark mode depth via surface color, not shadow */
+:root[data-theme="dark"] {
+  --surface-1: oklch(15% 0.01 250);
+  --surface-2: oklch(20% 0.01 250); /* "Higher" = lighter */
+  --surface-3: oklch(25% 0.01 250);
+
+  /* Reduce text weight slightly */
+  --body-weight: 350; /* Instead of 400 */
+}
+```
+
+### Token Hierarchy
+
+Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer — primitives stay the same.
+
+## Alpha Is A Design Smell
+
+Heavy use of transparency (rgba, hsla) usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency. Define explicit overlay colors for each context instead. Exception: focus rings and interactive states where see-through is needed.
+
+---
+
+**Avoid**: Relying on color alone to convey information. Creating palettes without clear roles for each color. Using pure black (#000) for large areas. Skipping color blindness testing (8% of men affected).

package/.codex/skills/frontend-design/references/interaction.md

@@ -0,0 +1,115 @@
+# Interaction Design
+
+> Reference for the `frontend-design` skill. Covers touch/click targets, feedback, focus management, forms, and loading patterns.
+> Adapted from [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache 2.0).
+
+## The Eight Interactive States
+
+Every interactive element needs these states designed:
+
+| State | When | Visual Treatment |
+|-------|------|------------------|
+| **Default** | At rest | Base styling |
+| **Hover** | Pointer over (not touch) | Subtle lift, color shift |
+| **Focus** | Keyboard/programmatic focus | Visible ring (see below) |
+| **Active** | Being pressed | Pressed in, darker |
+| **Disabled** | Not interactive | Reduced opacity, no pointer |
+| **Loading** | Processing | Spinner, skeleton |
+| **Error** | Invalid state | Red border, icon, message |
+| **Success** | Completed | Green check, confirmation |
+
+**The common miss**: Designing hover without focus, or vice versa. Keyboard users never see hover states.
+
+## Focus Rings: Do Them Right
+
+**Never `outline: none` without replacement.** Use `:focus-visible` to show focus only for keyboard users:
+
+```css
+/* Hide focus ring for mouse/touch */
+button:focus {
+  outline: none;
+}
+
+/* Show focus ring for keyboard */
+button:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}
+```
+
+**Focus ring design**:
+- High contrast (3:1 minimum against adjacent colors)
+- 2-3px thick
+- Offset from element (not inside it)
+- Consistent across all interactive elements
+
+## Form Design
+
+**Placeholders aren't labels** — they disappear on input. Always use visible `<label>` elements. **Validate on blur**, not on every keystroke (exception: password strength). Place errors **below** fields with `aria-describedby` connecting them.
+
+## Loading States
+
+**Optimistic updates**: Show success immediately, rollback on failure. Use for low-stakes actions (likes, follows), not payments or destructive actions. **Skeleton screens > spinners** — they preview content shape and feel faster than generic spinners.
+
+## Modals: The Inert Approach
+
+Use the native `<dialog>` element:
+
+```javascript
+const dialog = document.querySelector('dialog');
+dialog.showModal(); // Opens with focus trap, closes on Escape
+```
+
+Or use the `inert` attribute on the background content when a modal is open.
+
+## The Popover API
+
+For tooltips, dropdowns, and non-modal overlays, use native popovers:
+
+```html
+<button popovertarget="menu">Open menu</button>
+<div id="menu" popover>
+  <button>Option 1</button>
+  <button>Option 2</button>
+</div>
+```
+
+**Benefits**: Light-dismiss (click outside closes), proper stacking, no z-index wars, accessible by default.
+
+## Destructive Actions: Undo > Confirm
+
+**Undo is better than confirmation dialogs** — users click through confirmations mindlessly. Remove from UI immediately, show undo toast, actually delete after toast expires. Use confirmation only for truly irreversible actions (account deletion), high-cost actions, or batch operations.
+
+## Keyboard Navigation Patterns
+
+### Roving Tabindex
+
+For component groups (tabs, menu items, radio groups), one item is tabbable; arrow keys move within:
+
+```html
+<div role="tablist">
+  <button role="tab" tabindex="0">Tab 1</button>
+  <button role="tab" tabindex="-1">Tab 2</button>
+  <button role="tab" tabindex="-1">Tab 3</button>
+</div>
+```
+
+Arrow keys move `tabindex="0"` between items. Tab moves to the next component entirely.
+
+### Skip Links
+
+Provide skip links (`<a href="#main-content" class="sr-only focus:not-sr-only">Skip to main content</a>`) for keyboard users to jump past navigation. Hide off-screen, show on focus.
+
+## Gesture Discoverability
+
+Swipe-to-delete and similar gestures are invisible. Hint at their existence:
+
+- **Partially reveal**: Show delete button peeking from edge
+- **Onboarding**: Coach marks on first use
+- **Alternative**: Always provide a visible fallback (menu with "Delete")
+
+Don't rely on gestures as the only way to perform actions.
+
+---
+
+**Avoid**: Removing focus indicators without alternatives. Using placeholder text as labels. Touch targets <44x44px. Generic error messages. Custom controls without ARIA/keyboard support.

package/.codex/skills/frontend-design/references/motion-core.md

@@ -0,0 +1,102 @@
+# Motion Core
+
+> Reference for the `frontend-design` skill. Covers timing, easing, spring defaults, stagger, reduced motion, and perceived performance.
+> Adapted from [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache 2.0).
+
+## Duration: The 100/300/500 Rule
+
+Timing matters more than easing:
+
+| Duration | Use Case | Examples |
+|----------|----------|----------|
+| **100-150ms** | Instant feedback | Button press, toggle, color change |
+| **200-300ms** | State changes | Menu open, tooltip, hover states |
+| **300-500ms** | Layout changes | Accordion, modal, drawer |
+| **500-800ms** | Entrance animations | Page load, hero reveals |
+
+**Exit animations are faster than entrances** — use ~75% of enter duration.
+
+## Easing: Pick the Right Curve
+
+**Don't use `ease`.** It's a compromise that's rarely optimal.
+
+| Curve | Use For | CSS |
+|-------|---------|-----|
+| **ease-out** | Elements entering | `cubic-bezier(0.16, 1, 0.3, 1)` |
+| **ease-in** | Elements leaving | `cubic-bezier(0.7, 0, 0.84, 0)` |
+| **ease-in-out** | State toggles (there and back) | `cubic-bezier(0.65, 0, 0.35, 1)` |
+
+**For micro-interactions, use exponential curves** — they mimic real physics:
+
+```css
+/* Quart out - smooth, refined (recommended default) */
+--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);
+
+/* Quint out - slightly more dramatic */
+--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);
+
+/* Expo out - snappy, confident */
+--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+```
+
+**Avoid bounce and elastic curves.** They were trendy in 2015 but now feel tacky and amateurish. Real objects don't bounce when they stop — they decelerate smoothly.
+
+## The Only Two Properties You Should Animate
+
+**transform** and **opacity** only — everything else causes layout recalculation. For height animations (accordions), use `grid-template-rows: 0fr -> 1fr` instead of animating `height` directly.
+
+## Staggered Animations
+
+Use CSS custom properties for cleaner stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"` on each item. **Cap total stagger time** — 10 items at 50ms = 500ms total. For many items, reduce per-item delay or cap staggered count.
+
+## Reduced Motion
+
+This is not optional. Vestibular disorders affect ~35% of adults over 40.
+
+```css
+/* Define animations normally */
+.card {
+  animation: slide-up 500ms ease-out;
+}
+
+/* Provide alternative for reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    animation: fade-in 200ms ease-out; /* Crossfade instead of motion */
+  }
+}
+
+/* Or disable entirely */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+**What to preserve**: Functional animations like progress bars, loading spinners (slowed down), and focus indicators should still work — just without spatial movement.
+
+## Perceived Performance
+
+**Nobody cares how fast your site is — just how fast it feels.**
+
+**The 80ms threshold**: Our brains buffer sensory input for ~80ms to synchronize perception. Anything under 80ms feels instant. This is your target for micro-interactions.
+
+**Active vs passive time**: Passive waiting (staring at a spinner) feels longer than active engagement. Strategies:
+
+- **Preemptive start**: Begin transitions immediately while loading (skeleton UI). Users perceive work happening.
+- **Early completion**: Show content progressively — don't wait for everything.
+- **Optimistic UI**: Update the interface immediately, handle failures gracefully. Use for low-stakes actions; avoid for payments or destructive operations.
+
+**Easing affects perceived duration**: Ease-in (accelerating toward completion) makes tasks feel shorter because the peak-end effect weights final moments heavily.
+
+**Caution**: Too-fast responses can decrease perceived value. Users may distrust instant results for complex operations (search, analysis). Sometimes a brief delay signals "real work" is happening.
+
+## Performance
+
+Don't use `will-change` preemptively — only when animation is imminent (`:hover`, `.animating`). For scroll-triggered animations, use Intersection Observer instead of scroll events; unobserve after animating once. Create motion tokens for consistency (durations, easings, common transitions).
+
+---
+
+**Avoid**: Animating everything (animation fatigue is real). Using >500ms for UI feedback. Ignoring `prefers-reduced-motion`. Using animation to hide slow loading.

package/.codex/skills/frontend-design/references/responsive-design.md

@@ -0,0 +1,104 @@
+# Responsive Design
+
+> Reference for the `frontend-design` skill. Covers mobile-first approach, fluid design, input detection, and container queries.
+> Adapted from [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache 2.0).
+
+## Mobile-First: Write It Right
+
+Start with base styles for mobile, use `min-width` queries to layer complexity. Desktop-first (`max-width`) means mobile loads unnecessary styles first.
+
+## Breakpoints: Content-Driven
+
+Don't chase device sizes — let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use `clamp()` for fluid values without breakpoints.
+
+## Detect Input Method, Not Just Screen Size
+
+**Screen size doesn't tell you input method.** A laptop with touchscreen, a tablet with keyboard — use pointer and hover queries:
+
+```css
+/* Fine pointer (mouse, trackpad) */
+@media (pointer: fine) {
+  .button { padding: 8px 16px; }
+}
+
+/* Coarse pointer (touch, stylus) */
+@media (pointer: coarse) {
+  .button { padding: 12px 20px; } /* Larger touch target */
+}
+
+/* Device supports hover */
+@media (hover: hover) {
+  .card:hover { transform: translateY(-2px); }
+}
+
+/* Device doesn't support hover (touch) */
+@media (hover: none) {
+  .card { /* No hover state - use active instead */ }
+}
+```
+
+**Critical**: Don't rely on hover for functionality. Touch users can't hover.
+
+## Safe Areas: Handle the Notch
+
+Modern phones have notches, rounded corners, and home indicators:
+
+```css
+body {
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+
+/* With fallback */
+.footer {
+  padding-bottom: max(1rem, env(safe-area-inset-bottom));
+}
+```
+
+Enable viewport-fit in your meta tag:
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+```
+
+## Responsive Images
+
+### srcset with Width Descriptors
+
+```html
+<img
+  src="hero-800.jpg"
+  srcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1200.jpg 1200w"
+  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
+  alt="Hero image"
+>
+```
+
+- `srcset` lists available images with their actual widths (`w` descriptors)
+- `sizes` tells the browser how wide the image will display
+- Browser picks the best file based on viewport width AND device pixel ratio
+
+### Picture Element for Art Direction
+
+When you need different crops/compositions (not just resolutions), use the `<picture>` element with `<source>` elements for each breakpoint.
+
+## Layout Adaptation Patterns
+
+**Navigation**: Three stages — hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. **Tables**: Transform to cards on mobile using `display: block` and `data-label` attributes. **Progressive disclosure**: Use `<details>/<summary>` for content that can collapse on mobile.
+
+## Testing: Don't Trust DevTools Alone
+
+DevTools device emulation is useful for layout but misses:
+
+- Actual touch interactions
+- Real CPU/memory constraints
+- Network latency patterns
+- Font rendering differences
+- Browser chrome/keyboard appearances
+
+**Test on at least**: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you'll never see on simulators.
+
+---
+
+**Avoid**: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.

package/.codex/skills/frontend-design/references/spatial-design.md

@@ -0,0 +1,103 @@
+# Spatial Design
+
+> Reference for the `frontend-design` skill. Covers spacing systems, grids, visual hierarchy, and container queries.
+> Adapted from [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache 2.0).
+
+## Spacing Systems
+
+### Use 4pt Base, Not 8pt
+
+8pt systems are too coarse — you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
+
+### Name Tokens Semantically
+
+Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing — it eliminates margin collapse and cleanup hacks.
+
+## Grid Systems
+
+### The Self-Adjusting Grid
+
+Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints. Columns are at least 280px, as many as fit per row, leftovers stretch. For complex layouts, use named grid areas (`grid-template-areas`) and redefine them at breakpoints.
+
+## Visual Hierarchy
+
+### The Squint Test
+
+Blur your eyes (or screenshot and blur). Can you still identify:
+- The most important element?
+- The second most important?
+- Clear groupings?
+
+If everything looks the same weight blurred, you have a hierarchy problem.
+
+### Hierarchy Through Multiple Dimensions
+
+Don't rely on size alone. Combine:
+
+| Tool | Strong Hierarchy | Weak Hierarchy |
+|------|------------------|----------------|
+| **Size** | 3:1 ratio or more | <2:1 ratio |
+| **Weight** | Bold vs Regular | Medium vs Regular |
+| **Color** | High contrast | Similar tones |
+| **Position** | Top/left (primary) | Bottom/right |
+| **Space** | Surrounded by white space | Crowded |
+
+**The best hierarchy uses 2-3 dimensions at once**: A heading that's larger, bolder, AND has more space above it.
+
+### Cards Are Not Required
+
+Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when content is truly distinct and actionable, items need visual comparison in a grid, or content needs clear interaction boundaries. **Never nest cards inside cards** — use spacing, typography, and subtle dividers for hierarchy within a card.
+
+## Container Queries
+
+Viewport queries are for page layouts. **Container queries are for components**:
+
+```css
+.card-container {
+  container-type: inline-size;
+}
+
+.card {
+  display: grid;
+  gap: var(--space-md);
+}
+
+/* Card layout changes based on its container, not viewport */
+@container (min-width: 400px) {
+  .card {
+    grid-template-columns: 120px 1fr;
+  }
+}
+```
+
+**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands — automatically, without viewport hacks.
+
+## Optical Adjustments
+
+Text at `margin-left: 0` looks indented due to letterform whitespace — use negative margin (`-0.05em`) to optically align. Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction.
+
+### Touch Targets vs Visual Size
+
+Buttons can look small but need large touch targets (44px minimum). Use padding or pseudo-elements:
+
+```css
+.icon-button {
+  width: 24px;  /* Visual size */
+  height: 24px;
+  position: relative;
+}
+
+.icon-button::before {
+  content: '';
+  position: absolute;
+  inset: -10px; /* Expand tap target to 44px */
+}
+```
+
+## Depth & Elevation
+
+Create semantic z-index scales (dropdown > sticky > modal-backdrop > modal > toast > tooltip) instead of arbitrary numbers. For shadows, create a consistent elevation scale (sm > md > lg > xl). **Key insight**: Shadows should be subtle — if you can clearly see it, it's probably too strong.
+
+---
+
+**Avoid**: Arbitrary spacing values outside your scale. Making all spacing equal (variety creates hierarchy). Creating hierarchy through size alone — combine size, weight, color, and space.

package/.codex/skills/frontend-design/references/typography-rules.md

@@ -0,0 +1,118 @@
+# Typography Rules
+
+> Reference for the `frontend-design` skill. Covers type systems, font pairing, modular scales, and OpenType features.
+> Adapted from [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache 2.0).
+
+## Vertical Rhythm
+
+Line-height is the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px.
+
+## Modular Scale & Hierarchy
+
+Avoid too many font sizes that are too close together (14px, 15px, 16px, 18px). Use fewer sizes with more contrast. A 5-size system covers most needs:
+
+| Role | Typical Ratio | Use Case |
+|------|---------------|----------|
+| xs | 0.75rem | Captions, legal |
+| sm | 0.875rem | Secondary UI, metadata |
+| base | 1rem | Body text |
+| lg | 1.25-1.5rem | Subheadings, lead text |
+| xl+ | 2-4rem | Headlines, hero text |
+
+Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit.
+
+## Readability & Measure
+
+Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length. Increase line-height for light text on dark backgrounds (add 0.05-0.1 to normal line-height).
+
+## Font Selection
+
+**Avoid the invisible defaults**: Inter, Roboto, Open Sans, Lato, Montserrat. They make designs feel generic.
+
+**Better Google Fonts alternatives**:
+- Instead of Inter: **Instrument Sans**, **Plus Jakarta Sans**, **Outfit**
+- Instead of Roboto: **Onest**, **Figtree**, **Urbanist**
+- Instead of Open Sans: **Source Sans 3**, **Nunito Sans**, **DM Sans**
+- For editorial/premium feel: **Fraunces**, **Newsreader**, **Lora**
+
+**System fonts are underrated**: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui` looks native and loads instantly.
+
+## Pairing Principles
+
+You often don't need a second font. One well-chosen family in multiple weights creates cleaner hierarchy. Only add a second font when you need genuine contrast (e.g., display headlines + body serif).
+
+When pairing, contrast on multiple axes:
+- Serif + Sans (structure contrast)
+- Geometric + Humanist (personality contrast)
+- Condensed display + Wide body (proportion contrast)
+
+**Never pair fonts that are similar but not identical** (e.g., two geometric sans-serifs).
+
+## Web Font Loading
+
+```css
+/* 1. Use font-display: swap for visibility */
+@font-face {
+  font-family: 'CustomFont';
+  src: url('font.woff2') format('woff2');
+  font-display: swap;
+}
+
+/* 2. Match fallback metrics to minimize shift */
+@font-face {
+  font-family: 'CustomFont-Fallback';
+  src: local('Arial');
+  size-adjust: 105%;
+  ascent-override: 90%;
+  descent-override: 20%;
+  line-gap-override: 10%;
+}
+
+body {
+  font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif;
+}
+```
+
+Tools like [Fontaine](https://github.com/unjs/fontaine) calculate these overrides automatically.
+
+## Fluid Type
+
+Use `clamp(min, preferred, max)` for fluid typography. The middle value (e.g., `5vw + 1rem`) controls scaling rate. Add a rem offset so it doesn't collapse to 0 on small screens.
+
+**When NOT to use fluid type**: Button text, labels, UI elements (should be consistent), very short text, or when you need precise breakpoint control.
+
+## OpenType Features
+
+```css
+/* Tabular numbers for data alignment */
+.data-table { font-variant-numeric: tabular-nums; }
+
+/* Proper fractions */
+.recipe-amount { font-variant-numeric: diagonal-fractions; }
+
+/* Small caps for abbreviations */
+abbr { font-variant-caps: all-small-caps; }
+
+/* Disable ligatures in code */
+code { font-variant-ligatures: none; }
+
+/* Enable kerning */
+body { font-kerning: normal; }
+```
+
+Check font feature support at [Wakamai Fondue](https://wakamaifondue.com/).
+
+## Token Architecture
+
+Name tokens semantically (`--text-body`, `--text-heading`), not by value (`--font-size-16`). Include font stacks, size scale, weights, line-heights, and letter-spacing in your token system.
+
+## Accessibility
+
+- **Never disable zoom**: `user-scalable=no` breaks accessibility.
+- **Use rem/em for font sizes**: Respects user browser settings.
+- **Minimum 16px body text**: Smaller strains eyes and fails WCAG on mobile.
+- **Adequate touch targets**: Text links need padding or line-height that creates 44px+ tap targets.
+
+---
+
+**Avoid**: More than 2-3 font families per project. Skipping fallback font definitions. Ignoring font loading performance (FOUT/FOIT). Using decorative fonts for body text.