monomind 2.5.1 → 2.5.3

package/packages/@monomind/cli/.claude/skills/monodesign/init.md

@@ -0,0 +1,30 @@
+---
+name: monodesign-init
+description: Set up a project for monodesign — one codebase crawl plus a short interview produces PRODUCT.md (strategic context), optionally DESIGN.md (visual system), and pre-configures live mode. The required first step that anchors all other monodesign commands.
+type: design-sub-command
+argument-hint: "[project path or description]"
+user-invocable: true
+---
+
+# Monodesign: Init
+
+Set up a project for monodesign. Read `reference/init.md` from the monodesign skill directory for the full flow — it is the authoritative protocol. (`/monodesign teach` is the historical alias; it behaves identically.)
+
+## What init produces
+
+- **PRODUCT.md** (strategic): register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual, offered via `/monodesign document`): visual theme, color palette, typography, components, layout. Answers "how it looks".
+- **`.monodesign/live/config.json`**: pre-configured live mode so `/monodesign live` boots straight into variant mode.
+
+## Flow summary (the reference is authoritative)
+
+1. **Load current state**: check for existing PRODUCT.md / DESIGN.md (project root, `.agents/context/`, `docs/`). Never silently overwrite — confirm which file to refresh. A legacy `.monodesign.md` is auto-renamed to PRODUCT.md by the loader.
+2. **Explore the codebase**: one thorough crawl — README/docs, package.json and framework detection, existing components, brand assets, design tokens. Form a register hypothesis (brand vs product vs both) and a platform hypothesis (`web` / `ios` / `android` / `adaptive`).
+3. **Interview**: ask strategic questions to fill PRODUCT.md — register and platform confirmation, users, purpose, positioning, brand personality, anti-references, accessibility needs (plus conversion & proof for the brand register). Never synthesize PRODUCT.md from the task prompt alone; the user confirms before you write.
+4. **Write PRODUCT.md** with only what the user confirmed.
+5. **Offer DESIGN.md** via `/monodesign document` — scan mode when code exists, seed mode for empty projects.
+6. **Pre-configure live mode** when the project has HTML entries and a dev server.
+
+## Blocker behavior
+
+If init was invoked as a setup blocker by another command (e.g. `/monodesign craft` with no PRODUCT.md), complete init, then resume the original command with the fresh context.

package/packages/@monomind/cli/.claude/skills/monodesign/layout.md

@@ -0,0 +1,36 @@
+---
+name: monodesign-layout
+description: Fix the structure, not the surface — diagnose a layout's actual problem (monotone spacing, weak hierarchy, identical card grids) and restructure spacing, grids, and composition for the project's register.
+type: design-sub-command
+argument-hint: "[target file, route, or component]"
+user-invocable: true
+---
+
+# Monodesign: Layout
+
+Space is the most underused design tool. Find the layout's actual problem and fix the structure, not the surface. Read `reference/layout.md` from the monodesign skill directory for the full protocol.
+
+## Register-aware structure
+
+- **Brand**: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-breaking for emphasis. Rhythm through contrast — tight groupings paired with generous separations.
+- **Product**: predictable grids, consistent densities, familiar navigation patterns. Responsive behavior is structural (collapse sidebar, responsive table), not fluid typography. Consistency IS an affordance.
+- **Native** (`ios` / `android` / `adaptive`): follow the Layout section of `reference/ios.md` / `reference/android.md` — platform navigation, insets, and touch targets, never web CSS tooling.
+
+## Two isolated assessments (required)
+
+Spawn two parallel sub-agents (isolation is the point — neither sees the other's output):
+
+1. **Layout assessment**: works through the full "Assess Current Layout" checklist from the reference, returning per-item findings that cite file, selector, or value.
+2. **Mechanical pre-scan**: runs the bundled detector scoped to layout:
+
+   ```bash
+   node .claude/skills/monodesign/scripts/detect.mjs --json --scope layout [target files or dirs]
+   ```
+
+   When the project documents a spacing scale, also grep arbitrary Tailwind spacing (`gap-[`, `p-[`, `m-[`, `z-[`) and judge those hits against it.
+
+If no sub-agent tool is available, run both yourself — assessment first, pre-scan second, so deterministic findings can't anchor the visual judgment.
+
+## Then
+
+Synthesize both assessments, propose the structural fix (spacing rhythm, grid restructure, hierarchy weight), apply it, and re-run the detector to confirm the layout-scope findings are resolved.

package/packages/@monomind/cli/.claude/skills/monodesign/live.md

@@ -1,59 +1,34 @@
 ---
 name: monodesign-live
-description: Iterate on the UI directly in the browser — screenshot, identify issues, apply targeted CSS fixes, verify, repeat — until the live result matches the design intent.
+description: Interactive live variant mode — select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via the dev server's HMR. Iterate until the live result matches the design intent.
 type: design-sub-command
-argument-hint: "[target URL or component]"
+argument-hint: "[target URL, route, or app path]"
 user-invocable: true
 ---
 
 # Monodesign: Live
 
-Iterate on the UI directly in the browser. Read `reference/live.md` from the monodesign skill directory for the full protocol.
+Interactive live variant mode. This is a fully functional, script-driven flow — not a manual screenshot loop. Read `reference/live.md` from the monodesign skill directory for the full protocol and follow its contract exactly (boot, poll, generate, steer, accept/discard, exit).
 
-## CLAUDE.md Requirement
+## Prerequisites
 
-This command requires browser automation. Before proceeding, verify that `npx monomind browse` is available (`Skill("agent-browser-testing")`). If not, the `/monodesign live` flow falls back to editing CSS files and asking the user to refresh.
+- A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser.
+- Node available on PATH (the flow runs the bundled live helper scripts).
+- If `.monodesign/live/config.json` exists (written by `/monodesign init`), live boots straight into variant mode with no first-time setup detour.
 
-## Live Iteration Loop
+## How it works (summary — the reference is authoritative)
 
-The loop runs until the user confirms the design is right or cancels.
-
-### 1. Screenshot
-Capture the current state of the target URL or component. No assumptions — look at what's actually rendered.
-
-### 2. Diagnose
-Look at the screenshot with fresh eyes. Identify the top 3 issues:
-- Visual hierarchy problems
-- Spacing inconsistencies
-- Color contrast issues
-- Typography rendering
-- Interaction state gaps
-- Alignment problems
-
-State the issues clearly before touching any code.
-
-### 3. Apply targeted fix
-Edit the CSS for the specific issue identified. Keep each fix surgical — change one thing at a time.
-
-```css
-/* Targeted fix: heading weight is too light — can't distinguish from body */
-.hero-heading {
-  font-weight: 800;
-  font-size: clamp(2.5rem, 5vw, 4rem);
-  letter-spacing: -0.03em;
-}
-```
-
-### 4. Screenshot again
-Verify the fix had the intended effect. Check for regressions on neighboring elements.
-
-### 5. Confirm or continue
-If the target issue is resolved, state what was fixed and move to the next. If the fix introduced a regression, roll back and try a different approach.
+1. **Boot**: run `live.mjs` (with `--target <path>` when the request names a specific file, route, or monorepo app). It starts the live helper server and injects the in-page toolbar.
+2. **Open the app URL** that serves the page (the app's own dev-server URL — never the helper's `serverPort`).
+3. **Poll loop**: long-poll with `live-poll.mjs` (default long timeout). The user selects elements in the browser and picks a design action from the toolbar.
+4. **On `generate`**: read the screenshot if present, load the action's reference file, plan three distinct directions, write all variants in one edit, reply done, poll again.
+5. **On `steer`**: handle the user's free-text instruction, reply, poll again.
+6. **On `accept` / `discard`**: the accepted variant is committed to source (carbonize accepts have a cleanup step via `live-complete.mjs`); discards roll back.
+7. **If interrupted**: run `live-status.mjs` or `live-resume.mjs` — the durable journal replays unacknowledged work.
+8. **On `exit`**: run the cleanup steps at the bottom of the reference.
 
 ## Guidelines
 
-- Fix the most visually impactful issue first
-- Don't batch multiple fixes — screenshot after each change
-- State what you're about to change and why before changing it
-- If the same area has been fixed 3+ times without convergence, step back and assess whether the problem is structural (wrong layout approach) vs. cosmetic
-- Deliver final CSS that can be committed, not just live browser overrides
+- Never pass a short poll timeout; restart the poll immediately after every event.
+- Variants are written as real source edits hot-swapped by HMR — deliver code that can be committed, not browser-only overrides.
+- Manual in-browser edits are captured and can be committed or discarded via `live-commit-manual-edits.mjs` / `live-discard-manual-edits.mjs`.

package/packages/@monomind/cli/.claude/skills/monodesign/reference/adapt.md

@@ -2,6 +2,7 @@
 
 Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.
 
+**Web only** (mobile web included). Native platforms (`ios` / `android` / `adaptive`) route to [adapt.native.md](adapt.native.md) instead; if the project is native, switch to it now.
 
 ---
 
@@ -188,3 +189,124 @@ Test thoroughly across contexts:
 - **Slow connections**: Test on throttled network
 
 When the adaptation feels native to each context, hand off to `/monodesign polish` for the final pass.
+
+---
+
+## Reference Material
+
+The sections below were previously `responsive-design.md` and live inline now so the adapt flow has its deep responsive reference in one place.
+
+### Responsive Design
+
+#### 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. Use `env()`:
+
+```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: Get It Right
+
+##### 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: 768px) 100vw, 50vw"
+  alt="Hero image"
+>
+```
+
+**How it works**:
+- `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):
+
+```html
+<picture>
+  <source media="(min-width: 768px)" srcset="wide.jpg">
+  <source media="(max-width: 767px)" srcset="tall.jpg">
+  <img src="fallback.jpg" alt="...">
+</picture>
+```
+
+#### 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/packages/@monomind/cli/.claude/skills/monodesign/reference/adapt.native.md

@@ -0,0 +1,58 @@
+> **Additional context needed**: target platforms/devices and usage contexts.
+
+Adapt an existing **native** design (`ios` / `android` / `adaptive`) to a different context: another device class, orientation, platform, or origin. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context, inside the platform conventions of [ios.md](ios.md) / [android.md](android.md); read the target platform's reference before planning if Setup hasn't already.
+
+## Assess Adaptation Challenge
+
+1. **Source context**: what was it designed for, and what assumptions did it make? (Phone-only? Portrait-only? One platform's idioms? A website?)
+2. **Target context**: which device class (phone, tablet, foldable), orientation, platform, and usage posture (one-handed on the go vs two-handed at rest)?
+3. **What breaks**: navigation that doesn't fit the target, layouts that stretch instead of restructure, gestures or controls that don't exist there?
+
+## Adaptation Strategies
+
+### Phone → Tablet (iPad / large screens)
+
+- **Restructure, don't stretch.** A scaled-up phone UI on a tablet is the failure mode. Use size classes (iOS) / window size classes (Android) to switch structure.
+- **Navigation changes shape**: tab bar stays or becomes a sidebar on iPad; Android navigation bar becomes a rail or drawer on expanded width.
+- **Use the width**: split view / master-detail (list + detail side by side), multi-column grids, popovers where phones used sheets.
+- **Multitasking is a size, not an edge case**: iPad Split View and Android multi-window can hand you a phone-width window on a tablet; size-class-driven layout handles both for free.
+
+### Orientation & foldables
+
+- Landscape restructures (side-by-side panes, repositioned controls); never clip or letterbox. Lock orientation only when the task truly demands it.
+- Foldables (Android): react to posture and hinge via window size classes; test folded, unfolded, and tabletop.
+
+### Platform → platform (iOS ↔ Android)
+
+Translate idioms; never transplant them:
+
+| iOS | Android |
+|---|---|
+| Tab bar | Navigation bar / rail / drawer |
+| Edge-swipe back, back chevron | Predictive Back gesture / button |
+| Switch, segmented control, system pickers | Material switch, chips, Material pickers |
+| Action sheet | Bottom sheet / Material dialog |
+| SF Symbols, SF Pro, Dynamic Type | Material Symbols, Roboto, sp scaling |
+| Semantic system colors, materials | Material color roles, tonal elevation |
+| System push/sheet transitions | Container transform, shared-axis, fade-through |
+
+Rebuild navigation and controls in the target's vocabulary; carry over the brand's expressive layer (palette intent, type accent, motion personality) through the target's theming system.
+
+### Web → native (porting a website or web app)
+
+Reconform, don't reflow. Replace web navigation with the platform's model, HTML-shaped controls with platform controls, hover affordances with touch-first ones, and px-based type with Dynamic Type / sp. Then treat the result to the full platform reference; the slop test there is the acceptance bar.
+
+## Implement & Verify
+
+- Drive structure from **size classes / window size classes**, never from device-model checks.
+- Respect safe areas and window insets in every new configuration (notch, hinge, status bar, keyboard).
+- Test on simulators for breadth, then real hardware for truth: at least one phone and one tablet per shipped platform, both orientations, split-screen where supported.
+
+When the adaptation feels native to each context, hand off to `/monodesign polish` for the final pass.
+
+**NEVER**:
+- Ship a stretched phone layout on a tablet
+- Port one platform's controls or navigation onto the other
+- Hide core functionality on smaller devices (if it matters, make it work)
+- Lock orientation to dodge a layout bug
+- Trust simulators alone (posture, gestures, and performance need hardware)

package/packages/@monomind/cli/.claude/skills/monodesign/reference/android.md

@@ -0,0 +1,40 @@
+# Android platform
+
+For native Android apps: Jetpack Compose, Android Views, React Native, Expo, Flutter shipping to Android hardware.
+
+On native, register narrows. Material Design 3 governs structure, navigation, and interaction whatever the register; brand expresses through Material's theming (color roles, type scale, shape, motion). A Material-everywhere cross-platform app that also ships to iPhone still owes iOS its OS guarantees on that hardware: safe-area insets, Reduce Motion, edge-swipe back.
+
+## The Android slop test
+
+Would a fluent Android user trust this app, or trip on off-spec components? The most common tell is an iOS app wearing Android's skin: a bottom-only navigation copied from iPhone, a back arrow that ignores the system Back gesture, Cupertino-shaped switches and dialogs. Material 3 is the rulebook; follow its components and theme the brand through it.
+
+## Layout & structure
+
+- **Material navigation, matched to size.** Navigation bar (bottom, 3–5 destinations) on compact width; navigation rail or drawer on expanded width. Never ship a phone bottom-bar untouched on a tablet.
+- **System Back always works.** Honor the predictive Back gesture and Back button; never trap the user or hijack the gesture.
+- **Edge-to-edge with window insets.** Apply the status bar, navigation bar, display cutout, and IME insets so content never hides behind system bars or the keyboard.
+- **Top app bar for screen context**; pair with a FAB when the screen has a single primary action.
+
+## Touch targets
+
+- **48×48 dp minimum** for every touch target, with at least 8 dp between them.
+
+## Typography
+
+- **Material type scale.** Display, Headline, Title, Body, Label roles (large/medium/small each). Map text to roles; never hand-pick sizes per screen.
+- **Roboto is the system face**; theme a brand face in through the type scale, keeping body, labels, and controls legible and consistent.
+- **sp units, never fixed px**, so type follows the system font-size setting.
+
+## Color & theming
+
+- **Material color roles** (primary, on-primary, surface, surface-variant, secondary-container, outline, error). Role tokens resolve light/dark and contrast variants automatically; raw hex breaks there.
+- **Dynamic Color (Material You)** where it fits: derive the scheme from the user's wallpaper on Android 12+, with a static fallback.
+- **Dark theme is a first-class scheme.** Design and test it; never a quick invert.
+- **Tonal elevation.** Convey elevation through the standard surface tonal levels (plus shadow where appropriate); no arbitrary drop shadows.
+
+## Components & motion
+
+- **Material components.** Buttons (filled / tonal / outlined / text), FAB, switches, chips, snackbars, bottom sheets, Material dialogs, navigation bar/rail/drawer. Never port iOS controls or invent equivalents.
+- **One FAB, one primary action.** Never stack FABs or spend one on a secondary task.
+- **Snackbars for transient feedback** (actionable when useful, never a toast for that); dialogs only for decisions that must interrupt.
+- **Material motion patterns.** Container transform, shared-axis, fade-through, with standard easing and durations; honor the system Remove animations setting with a crossfade or instant cut.

package/packages/@monomind/cli/.claude/skills/monodesign/reference/animate.md

@@ -6,10 +6,12 @@ Add motion that conveys state, gives feedback, and clarifies hierarchy. Cut moti
 
 ## Register
 
-Brand: orchestrated page-load sequences, staggered reveals, scroll-driven animation. Motion is part of the voice; one well-rehearsed entrance beats scattered micro-interactions.
+Brand: motion is part of the voice; one well-rehearsed entrance beats scattered micro-interactions. The saturated AI default is fade-and-rise reveals on every scrolled section; that's a tell, not a choreography. Reserve scroll-triggered motion for moments that earn it.
 
 Product: 150–250 ms on most transitions. Motion conveys state: feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it.
 
+Native (`ios` / `android` / `adaptive`): implementation follows the Motion section of [ios.md](ios.md) / [android.md](android.md) (read it first if Setup hasn't already): system transitions and OS Reduce Motion, never the web tooling below.
+
 ---
 
 ## Assess Animation Opportunities
@@ -29,7 +31,7 @@ Analyze where motion would improve the experience:
    - Who's the audience? (Motion-sensitive users? Power users who want speed?)
    - What matters most? (One hero animation vs many micro-interactions?)
 
-If any of these are unclear from the codebase, Ask the user for clarification before proceeding.
+If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify.
 
 **CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them.
 
@@ -49,10 +51,11 @@ Create a purposeful animation plan:
 Add motion systematically across these categories:
 
 ### Entrance Animations
-- **Page load choreography**: Stagger element reveals (100-150ms delays), fade + slide combinations
 - **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects)
-- **Content reveals**: Scroll-triggered animations using intersection observer
 - **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management
+- **List rhythm**: Sibling stagger is legitimate for cards-in-a-grid or list-items-appearing. Whole-section fade-on-scroll is not a list and is not legitimate. Cap total stagger time: 10 items at 50ms each = 500ms total. For more items, reduce per-item delay or cap the staggered count.
+
+  Use CSS custom properties for clean stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"`, `style="--i: 1"`, etc. on each item.
 
 ### Micro-interactions
 - **Button feedback**:
@@ -97,11 +100,14 @@ Use appropriate techniques for each animation:
 
 ### Timing & Easing
 
-**Durations by purpose:**
-- **100-150ms**: Instant feedback (button press, toggle)
-- **200-300ms**: State changes (hover, menu open)
-- **300-500ms**: Layout changes (accordion, modal)
-- **500-800ms**: Entrance animations (page load)
+**Duration: the 100/300/500 rule.** Timing matters more than easing for "feels right":
+
+| Duration | Use Case | Examples |
+|----------|----------|----------|
+| **100–150ms** | Instant feedback | Button press, toggle, color change |
+| **200–300ms** | State changes | Menu open, tooltip, hover state |
+| **300–500ms** | Layout changes | Accordion, modal, drawer |
+| **500–800ms** | Entrance animations | Page load, hero reveal |
 
 **Easing curves (use these, not CSS defaults):**
 ```css
@@ -134,13 +140,35 @@ Use appropriate techniques for each animation:
 - GSAP for complex sequences
 ```
 
+### Motion Materials
+
+Transform and opacity are reliable defaults, not the whole palette. Premium interfaces often need atmospheric properties. Match material to effect:
+
+- **Transform / opacity**: movement, press feedback, simple reveals, list choreography
+- **Blur / filter / backdrop-filter**: focus pulls, depth, glass or lens effects, softened entrances
+- **Clip-path / masks**: wipes, reveals, editorial cropping, product-like transitions
+- **Shadow / glow / color filters**: energy, affordance, focus, warmth, active state
+- **Grid-template-rows or FLIP-style transforms**: expanding and reflowing layout without animating `height` directly
+
+The hard rule isn't "transform and opacity only." It's: avoid animating layout-driving properties casually (`width`, `height`, `top`, `left`, margins), keep expensive effects bounded to small or isolated areas, and verify smoothness in-browser on target viewports.
+
 ### Performance
-- **Motion materials**: Use transform/opacity for reliable movement, but use blur, filters, masks, shadows, and color shifts when they materially improve the effect
 - **Layout safety**: Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
-- **will-change**: Add sparingly for known expensive animations
+- **will-change**: Add sparingly for known expensive animations only (e.g. on `:hover` or an `.animating` class), never preemptively across the whole page
+- **Scroll triggers**: Use Intersection Observer instead of scroll event listeners; unobserve after the animation fires once
 - **Bound expensive effects**: Keep blur/filter/shadow areas small or isolated, use `contain` where appropriate
 - **Monitor FPS**: Ensure 60fps on target devices
 
+### Perceived Performance
+
+Nobody cares how fast your site *is*, only how fast it feels. The 80ms threshold: anything under ~80ms feels instant because our brains buffer sensory input for that long to synchronize perception. Target this for micro-interactions.
+
+- **Preemptive start**: Begin transitions immediately while loading (iOS app zoom, skeleton UI). Users perceive work happening.
+- **Early completion**: Show content progressively, don't wait for everything (progressive images, streaming HTML, skeleton fade-ins).
+- **Optimistic UI**: Update the interface immediately, handle failures gracefully. Use for low-stakes actions (likes, follows). 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. Ease-out feels satisfying for entrances.
+- **Caution**: Too-fast responses can decrease perceived value for complex operations (search, analysis). Sometimes a brief delay signals "real work" is happening.
+
 ### Accessibility
 ```css
 @media (prefers-reduced-motion: reduce) {