@design-ai/cli 4.55.0

package/knowledge/illustration/svg-optimization.md

@@ -0,0 +1,308 @@
+<!-- hand-written -->
+---
+title: SVG optimization (file size, performance, accessibility)
+applies_to: [svg, illustration, performance, optimization]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# SVG optimization
+
+SVGs are usually the right format for illustration. They scale, theme, and animate. But raw exports from Figma / Illustrator are bloated — 5-10× larger than they need to be, and they break theming.
+
+This file is the production checklist for shipping a clean SVG.
+
+## Why optimize
+
+A typical Figma SVG export of a medium-detail spot illustration:
+- **Raw**: 80kB
+- **After optimization**: 8-15kB
+
+10× reduction is normal. For 100 illustrations across a site, that's 7MB → 1MB.
+
+Beyond size: optimized SVGs theme correctly, render faster, and are easier to inline in React.
+
+## The bloat sources
+
+Raw SVG exports include:
+1. **Editor metadata** — Figma / Sketch / Illustrator editor tags (10-30% of file).
+2. **Default styles** — `fill="#000"`, `stroke-width="1"` on every element even when it's the default.
+3. **Decimal precision** — `M123.4567890123` instead of `M123.46`.
+4. **Empty groups** — `<g></g>` wrappers with no purpose.
+5. **Unused attributes** — `id` on every element, even when unused.
+6. **Embedded fonts** — text rendered as font (not paths) carrying entire font subsets.
+7. **Embedded raster** — images embedded as base64 inside the SVG.
+
+Cleaning these is mechanical (run a tool) plus judgmental (preserve structure for theming / animation).
+
+## SVGO — the standard tool
+
+**SVGO** (svgo on npm) is the de-facto SVG optimizer. Run on every SVG before shipping.
+
+```bash
+npm install -g svgo
+svgo input.svg -o output.svg
+```
+
+Or batch:
+
+```bash
+svgo --folder=src/illustrations --output=dist/illustrations
+```
+
+### Recommended SVGO config
+
+```js
+// svgo.config.js
+module.exports = {
+  plugins: [
+    {
+      name: "preset-default",
+      params: {
+        overrides: {
+          removeViewBox: false,        // KEEP viewBox — required for responsive scaling
+          cleanupIds: false,           // KEEP ids if you reference them in CSS / JS
+          removeUselessDefs: false,    // KEEP defs if used by clipPath / filter / linearGradient
+        },
+      },
+    },
+    "removeXMLNS",                     // Remove if you inline; keep if standalone <img src>
+    "convertStyleToAttrs",
+    "removeDimensions",                // Use viewBox + CSS sizing
+    {
+      name: "convertPathData",
+      params: { floatPrecision: 2 },
+    },
+    "removeMetadata",
+    "removeEditorsNSData",
+    "removeEmptyContainers",
+    "convertColors",                   // Hex → shorter forms / named
+  ],
+};
+```
+
+`removeViewBox: false` is critical. Without viewBox, SVG can't scale responsively.
+
+`cleanupIds: false` if you have any `<use>`, `clipPath`, or CSS targeting by id.
+
+## Theming with currentColor
+
+To make SVGs theme-aware, use `currentColor`:
+
+```svg
+<!-- Bad: hardcoded brand color -->
+<svg viewBox="0 0 24 24"><path d="..." fill="#0064FF"/></svg>
+
+<!-- Good: themeable -->
+<svg viewBox="0 0 24 24"><path d="..." fill="currentColor"/></svg>
+```
+
+```css
+.icon { color: var(--color-brand-default); }
+```
+
+Now the SVG inherits color from CSS. Dark mode? Just change the variable.
+
+For multi-color illustrations, use CSS variables in the SVG (requires inline SVG or CSS-aware loader):
+
+```svg
+<svg viewBox="0 0 240 240">
+  <circle cx="120" cy="120" r="100" fill="var(--color-bg-illo, #E0F2FF)" />
+  <path d="..." fill="var(--color-brand-default, #0064FF)" />
+</svg>
+```
+
+The fallback after the comma is the static value — used if CSS variables aren't applied.
+
+## Inline vs `<img src>` vs `<object>`
+
+| Method | When | Pros | Cons |
+| --- | --- | --- | --- |
+| **Inline `<svg>`** in HTML / JSX | Theming, animation, SVG you control | Full theming, full animation | Bigger HTML, no caching of SVG itself |
+| **`<img src="...svg">`** | Decorative, no theming needed | Cacheable, simple | No CSS targeting from outside |
+| **`<object>` / `<iframe>`** | Rare | SVG can have its own CSS | Layout edge cases |
+| **CSS `background-image: url(...svg)`** | Decorative backgrounds | Cacheable | No theming, no animation |
+
+Default: **inline** for icons / themed illustrations; **`<img>`** for static illustrations.
+
+For React, popular pattern is inline-as-component:
+
+```tsx
+// SearchEmpty.tsx
+export function SearchEmptyIllustration({ className, ...props }: SVGProps) {
+  return (
+    <svg viewBox="0 0 240 240" className={className} {...props}>
+      <path d="..." fill="currentColor" />
+    </svg>
+  );
+}
+```
+
+Build tool (vite-svg-loader, SVGR, esbuild-plugin-svgr) auto-converts SVG files to React components.
+
+## Avoiding common pitfalls
+
+### 1. Don't lose theming during optimization
+
+SVGO can replace `currentColor` with the value if it's not careful. Whitelist `currentColor`:
+
+```js
+// In svgo config
+{
+  name: "convertColors",
+  params: { currentColor: false },  // Don't replace currentColor
+}
+```
+
+### 2. Don't strip ids you reference
+
+If your CSS or JS targets `#illo-bg` inside SVG, `cleanupIds: false` and explicit preservation needed.
+
+### 3. Don't strip viewBox
+
+Without viewBox, SVG renders at intrinsic size and won't respond to `width` / `height` CSS.
+
+### 4. Don't inline raster
+
+Some Figma exports embed PNGs as base64 inside SVG. This defeats the point — you have an SVG wrapper around a PNG. Identify with:
+
+```bash
+grep "data:image" myfile.svg
+```
+
+If found: re-export with the raster as a separate file, OR redraw the part as vector.
+
+### 5. Don't keep editor metadata
+
+```bash
+# Check size before / after
+ls -la myfile.svg          # 80kB
+svgo myfile.svg
+ls -la myfile.svg          # 8kB
+```
+
+If your "after" is still 30kB+, something didn't strip — open and check.
+
+## Accessibility
+
+### Decorative SVG
+
+```html
+<svg aria-hidden="true" focusable="false">...</svg>
+```
+
+`aria-hidden` removes from a11y tree. `focusable="false"` prevents keyboard focus on the SVG element (important for IE/legacy; defensive in modern browsers).
+
+### Meaningful SVG (conveys information)
+
+```html
+<svg role="img" aria-label="결제 완료">
+  <title>결제 완료</title>
+  ...
+</svg>
+```
+
+`role="img"` + `aria-label` is the cleanest. `<title>` element inside SVG is also read by some screen readers — defense in depth.
+
+### Interactive SVG (button, link)
+
+```html
+<svg role="button" aria-label="닫기" tabindex="0" onclick="..." onkeydown="...">
+  ...
+</svg>
+```
+
+Better: wrap the SVG in a real `<button>` and let the SVG be decorative. Avoids handling keyboard manually.
+
+## Performance
+
+| Metric | Target |
+| --- | --- |
+| Inline SVG (icon-sized, < 32px) | < 1kB |
+| Inline SVG (spot illustration, 100-200px) | < 10kB |
+| Hero SVG | < 100kB; ideal < 50kB |
+| Path count per SVG | < 200 (above this, consider raster) |
+| Distinct gradients | < 5 (browsers de-dupe; > 10 hurts paint) |
+| Filters (blur, drop-shadow) | Use sparingly; expensive |
+
+For SVG with > 500 paths (very detailed): seriously consider a WebP / AVIF instead. Browsers paint thousands of paths slowly on mobile.
+
+## Animation in SVG
+
+SVG can animate via:
+
+| Method | Use |
+| --- | --- |
+| **CSS animation on SVG elements** | Hover effects, simple loops |
+| **SMIL** (`<animate>`, `<animateTransform>`) | Legacy; deprecated in some browsers; avoid for new |
+| **JavaScript (GSAP, Framer Motion)** | Complex animation, scroll-triggered |
+| **Lottie** | Designer-led; bypasses SVG animation entirely |
+
+For most cases: CSS animation on inline SVG is the best balance. SMIL is dead. Lottie when designer makes it in After Effects.
+
+```css
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+.spinner svg {
+  animation: spin 1s linear infinite;
+}
+```
+
+`prefers-reduced-motion` rules apply — pause / freeze on reduce.
+
+## Sprite vs separate files
+
+| Approach | Use |
+| --- | --- |
+| **One SVG sprite** (one file, many `<symbol>` IDs, referenced via `<use>`) | Many icons, want HTTP single-fetch |
+| **Separate SVG files** | Treeshaking with build tools, modern HTTP/2/3 |
+| **React component per SVG** (most common modern) | React apps, full type-safety, easy theming |
+
+With HTTP/2/3 multiplexing, separate files are usually fine. Sprites add build complexity. For most projects: separate files / per-component is simpler.
+
+## Workflow checklist
+
+For each new illustration:
+
+- [ ] Created at canvas size matching display (don't scale up small canvas)
+- [ ] Strokes converted to fills (or kept as strokes — pick one and stay consistent)
+- [ ] Text either converted to paths OR uses Pretendard / system fonts (safe for cross-platform)
+- [ ] Brand colors replaced with `currentColor` or CSS variables
+- [ ] Run through SVGO with config above
+- [ ] viewBox preserved
+- [ ] No embedded raster (`grep "data:image"`)
+- [ ] No editor metadata (`grep -E "sodipodi|inkscape|sketch:"`)
+- [ ] File size < target for category (1kB icon, 10kB spot, 50kB hero)
+- [ ] Accessibility: `aria-hidden` for decorative, `role="img"` + `aria-label` for meaningful
+- [ ] Tested in light + dark modes
+- [ ] Tested at 1×, 2×, 3× device pixel ratio (cribs / blur check)
+
+## Tools
+
+| Tool | Use |
+| --- | --- |
+| **SVGO** | CLI optimizer; mandatory |
+| **SVGOMG** (svgomg.net) | Web UI for SVGO; preview before/after |
+| **vite-plugin-svgr / SVGR** | SVG → React component build |
+| **Figma → "Copy as SVG"** | Fast extraction; still needs SVGO |
+| **Adobe Illustrator → "Save for Web"** | Slightly cleaner output than Figma |
+| **PurgeCSS / unused style sweep** | After build, ensure unused SVG IDs / classes purged |
+
+## Don't
+
+- Don't ship raw Figma exports — always SVGO.
+- Don't keep `width` / `height` attributes on the `<svg>` if you want it responsive — use viewBox + CSS sizing.
+- Don't embed raster inside SVG. Defeats the format.
+- Don't bake brand color as raw hex — use `currentColor` or CSS variables.
+- Don't make 100 separate SVG components when an inline icon font / sprite would do (icons specifically).
+- Don't ignore reduced-motion when SVG animates.
+
+## Cross-reference
+
+- [`knowledge/illustration/illustration-systems.md`](illustration-systems.md) — system foundation
+- [`knowledge/illustration/spot-illustrations.md`](spot-illustrations.md) — production rules
+- [`knowledge/illustration/hero-illustrations.md`](hero-illustrations.md) — performance targets
+- [`knowledge/icons/curated-sets.md`](../icons/curated-sets.md) — icon system
+- [`knowledge/motion/motion-tools.md`](../motion/motion-tools.md) — Lottie alternative

package/knowledge/layout/spacing-and-grid.md

@@ -0,0 +1,119 @@
+<!-- hand-written -->
+---
+title: Spacing, grid, and responsive layout
+applies_to: [web, mobile, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Spacing, grid, and responsive layout
+
+## The 4-or-8 rule
+
+Pick one base unit and use **only multiples**. Most systems pick **4 px** (with 8 px subset). Tailwind defaults to 4. Material defaults to 4. Ant Design's `sizeUnit` is 4.
+
+**Why 4 not 8?** 4 lets you express tight component padding (e.g., 12 px, 20 px) without breaking grid. 8-only is simpler but produces blocky UIs.
+
+The canonical scale derived from base 4:
+
+```
+4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128
+```
+
+**Skip 28, 36, 44, 52, 56**: they are intermediate steps that should be expressed as `+8` from neighbors when truly needed, not added to the scale.
+
+## Spacing tokens
+
+Name spacing tokens by **role**, not value:
+
+```
+✗ space-12
+✓ space-md           OR    component-padding-y
+```
+
+Two-axis naming is the cleanest:
+- **`space-2xs / xs / sm / md / lg / xl / 2xl / 3xl`** for layout (4, 8, 12, 16, 24, 32, 48, 64).
+- **`gap-x` / `gap-y`** for component-internal spacing.
+- **`inset`** vs **`stack`** vs **`inline`** (Braid/Mirage style) — fancier but disambiguates "padding inside" vs "vertical rhythm" vs "horizontal flow".
+
+## Grid systems
+
+| System | Columns | Gutter | Margin |
+| --- | --- | --- | --- |
+| 12-column (Bootstrap, Ant) | 12 | 16–24 px | 24 px (mobile) → 80+ px (desktop) |
+| 8-point grid | flexible | 8 multiples | aligns to 8 |
+| Material | 4-column (mobile), 8 (tablet), 12 (desktop) | 16/24/24 | 16/24/24 |
+| Editorial | 6-column or asymmetric | wide | wide |
+
+For most product UIs: **12 columns, 24 px gutter, 24 px outer margin on mobile, scaling**.
+
+## Breakpoints
+
+The pragmatic set, ordered by frequency of use:
+
+| Name | Min width | Usage |
+| --- | --- | --- |
+| `xs` | 0 | Mobile portrait. Single column, full-width buttons. |
+| `sm` | 640 px | Large mobile / phablet. |
+| `md` | 768 px | Tablet portrait, foldables. |
+| `lg` | 1024 px | Tablet landscape, small laptops. |
+| `xl` | 1280 px | Desktop. |
+| `2xl` | 1536 px | Large desktop. |
+
+Tailwind v4 defaults match exactly (mobile-first). Ant Design uses 576/768/992/1200/1600 — slightly different, less aligned with modern devices.
+
+**Mobile-first**: write base styles for mobile, use `min-width` queries to add desktop adjustments. Don't author for desktop and shrink down.
+
+## Container queries vs media queries
+
+Use container queries when:
+- A component reused at multiple sizes (a card in a grid AND in a sidebar).
+- Layout depends on its own width, not the viewport.
+
+Use media queries when:
+- Page-level layout shifts (sidebar collapses, navigation opens).
+- Typography scale changes globally.
+
+```css
+@container card (min-width: 320px) {
+  .card { display: grid; grid-template-columns: 1fr 2fr; }
+}
+```
+
+Browser support: 2023+ all major browsers.
+
+## Density modes
+
+Many products need at least two density modes:
+
+| Mode | Use | Adjustments |
+| --- | --- | --- |
+| **Comfortable** (default) | Consumer apps, marketing | Standard padding, 16 px body |
+| **Compact** | Power users, data tables, IDE-like UIs | -25% vertical padding, 14 px body, smaller controls (28 px height vs 32) |
+| **Spacious** | First-time-user, accessibility mode | +25% padding, 16+ px body |
+
+Implement as a CSS variable scale that all components consume:
+
+```css
+:root[data-density="compact"] {
+  --space-md: 12px;     /* normally 16 */
+  --control-height: 28px; /* normally 32 */
+}
+```
+
+## Responsive type
+
+Three approaches, pick one:
+
+1. **Stepped**: Different `font-size` at each breakpoint. Predictable, easy to QA. _Default for most projects._
+2. **Fluid (clamp)**: `font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem)`. Smooth, harder to QA. Good for editorial.
+3. **Combined**: Stepped at small/medium, fluid above to fill wide screens. Most expressive, most work.
+
+## Common layout failures
+
+- **No max-width on text content**: lines exceeding 75 chars hurt readability. Cap with `max-w-prose` (Tailwind) or `max-width: 65ch`.
+- **Form fields full-width on desktop**: a 1200 px-wide email input looks broken. Cap at 480 px.
+- **Card grids without min/max width**: pure `repeat(auto-fit, 1fr)` produces 50 px cards on tiny screens. Use `repeat(auto-fit, minmax(280px, 1fr))`.
+- **Mobile drawer that scrolls behind backdrop**: scroll-locking the body is required.
+- **No safe-area handling on iOS**: notch/home-bar overlap. `padding-top: env(safe-area-inset-top)`.

package/knowledge/motion/app-loading-sequences.md

@@ -0,0 +1,277 @@
+<!-- hand-written -->
+---
+title: App loading sequences
+applies_to: [splash, app-launch, route-transitions, progressive-load]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# App loading sequences
+
+The first 3 seconds of an app launch decide whether users feel the app is fast or slow. **Perceived performance** > actual performance. Design the loading sequence intentionally.
+
+## Three loading moments
+
+| Moment | Duration | UX goal |
+| --- | --- | --- |
+| **Cold launch** (app first opens) | 0–3s | Make waiting feel intentional |
+| **Warm launch** (app already in memory) | 0–500ms | Hide the load entirely |
+| **Route change** (user navigates within app) | 0–500ms | Smooth transition |
+
+Each needs different patterns.
+
+## Cold launch — splash + first paint
+
+Native apps (iOS / Android) show a splash screen during launch. Web / PWA does similar via service worker + first paint.
+
+### Splash screen rules
+
+- **Brand-led** — logo + brand color. No spinner.
+- **Static or minimal motion**. Looping spinner reads as loading-stuck.
+- **Match the first screen** — splash's bg color = first screen's bg color, so transition is seamless.
+- **iOS / Android handle splash automatically** in many cases (LaunchScreen.storyboard / SplashScreen API).
+
+### iOS splash strategy
+
+Use LaunchScreen.storyboard:
+- Centered logo on brand background.
+- No spinner (Apple HIG explicitly says no).
+- Disappears as soon as React Native / web view is ready.
+
+### Android splash (API 31+)
+
+Native SplashScreen API:
+- Animated icon support
+- Brand background color
+- Auto-handles transition to app
+
+For older Android: simple solid-color screen with logo.
+
+## Warm launch — invisible
+
+When app is already in memory, launch should feel instant. < 500ms.
+
+If you can't hit < 500ms:
+- Show **same splash** (consistency).
+- Or: snapshot of last app state (iOS does this automatically).
+
+## Route changes within app
+
+Web / SPA / native apps: navigating between screens.
+
+### Three transition patterns
+
+| Pattern | Use |
+| --- | --- |
+| **Cross-fade** | Default for content-led transitions. 200ms opacity. Calm. |
+| **Slide-in** | Native iOS pattern. New screen slides from right; old slides left. |
+| **Hero / shared element** | Element from old screen "transforms" into element on new screen (Material's shared transitions). |
+
+### Cross-fade (web default)
+
+```css
+.page-transition-enter {
+  opacity: 0;
+}
+.page-transition-enter-active {
+  opacity: 1;
+  transition: opacity 200ms;
+}
+.page-transition-exit {
+  opacity: 1;
+}
+.page-transition-exit-active {
+  opacity: 0;
+  transition: opacity 200ms;
+}
+```
+
+For React Router with Framer Motion or React Transition Group: 5 lines.
+
+For modern web: **View Transitions API** (browser-native, 2024+):
+
+```js
+document.startViewTransition(() => {
+  // Update DOM
+});
+```
+
+Browser handles the cross-fade. Cleanest path for modern Chrome / Edge / Safari.
+
+### Slide-in (native pattern)
+
+iOS native: `pushViewController` slides new screen from right. Back swipe slides it back.
+
+For web: use Framer Motion `<AnimatePresence>` with `x` translation.
+
+For React Native: `@react-navigation/native` handles it automatically.
+
+### Shared element / hero transitions
+
+Most sophisticated. Element from screen A morphs into element on screen B.
+
+```
+Screen A: [Card with image]
+              ↓ tap
+Screen B: [Image full-bleed, card details below]
+
+The image element animates (FLIP technique) from card position → full-bleed
+```
+
+Tools:
+- **Material You shared transitions** (Android native)
+- **Framer Motion `layoutId`** (React)
+- **View Transitions API** (web, with named transitions)
+- **react-native-shared-element** (RN)
+
+When to use:
+- Photo gallery → detail view
+- Card-grid → card-detail
+- Logo persistence across pages
+
+When to skip:
+- Simple route changes (overkill)
+- Rapid-tap navigation (animation can't keep up)
+
+## Progressive content loading
+
+Once app is rendered, content arrives async. Three patterns:
+
+### 1. Skeleton coordination
+
+Multiple skeletons load simultaneously. **Stagger the resolve** to avoid simultaneous flash:
+
+```
+Fetch 3 sections in parallel:
+  - Header data: arrives at 200ms
+  - Body data: arrives at 350ms
+  - Footer data: arrives at 500ms
+
+Don't replace each skeleton instantly. Coordinate:
+  - At 500ms (when slowest is ready), reveal all three with 50ms stagger.
+  - Total settle: 650ms with smooth orchestrated reveal.
+```
+
+Or simpler: replace each skeleton as data arrives. Less coordinated but faster to ship.
+
+### 2. Pull-to-refresh
+
+Mobile-native pattern. User pulls down → refresh indicator → data fetched → indicator hides.
+
+| Phase | Behavior |
+| --- | --- |
+| Pull (1–80px) | List moves with finger |
+| Past threshold (80px+) | Indicator appears |
+| Release | List bounces back; indicator stays during fetch (typical 1–3s) |
+| Done | Indicator fades; new content (if any) at top |
+
+Cite [`knowledge/patterns/list-and-feed.md`](../patterns/list-and-feed.md).
+
+### 3. Infinite scroll triggers
+
+User scrolls near bottom → next page loads.
+
+```
+Scroll position 80% of total → trigger fetch
+Spinner at bottom while loading
+New items append (with 50ms entrance stagger)
+```
+
+Don't:
+- Reset scroll on append.
+- Auto-scroll to new items (user is reading something).
+
+## Page state transitions
+
+Beyond just loading: empty → loading → content → error states all need motion-aware transitions.
+
+```
+Empty state visible
+  ↓ user adds item
+  ↓ list animates with new item entering
+Content visible
+  ↓ user filters to nothing
+  ↓ items fade out
+Empty state slides in (filtered variant)
+```
+
+Each state-to-state transition is ~200ms. Cross-fade is the safe default.
+
+## Korean fintech app launch convention
+
+Korean fintech apps (Toss, KakaoBank) often have:
+- **Solid brand color splash** — yellow (Kakao) / blue (Toss).
+- **No logo animation** — stays clean.
+- **Biometric gate** appears immediately on launch (Face ID / Fingerprint).
+- **After auth**: cross-fade to dashboard.
+
+Total cold launch experience: 1.5–3s. The biometric gate is the bulk; actual app load hides under it.
+
+Cite [`examples/component-biometric-gate.md`](../../examples/component-biometric-gate.md).
+
+## Reduced motion
+
+For loading sequences:
+- Splash: still show (brand recognition matters more than "no motion").
+- Route transitions: instant cross-fade, no slide.
+- Skeleton entrance: still show skeleton, but no shimmer animation.
+- Hero / shared element: skip the morph, just instant layout change.
+
+## Performance — perceived vs actual
+
+| Strategy | Perceived speed |
+| --- | --- |
+| Show app chrome (header, nav) immediately, content later | Faster |
+| Show skeleton matching final layout | Faster |
+| Animate progress (even fake) | Feels active |
+| Optimistic UI (act on click before server confirms) | Instant |
+| Keep stale data visible during refresh | Faster |
+
+vs:
+
+| Strategy | Slower perceived speed |
+| --- | --- |
+| Blank screen during load | Slowest |
+| Spinner with no context | Slow |
+| Block all interaction until loaded | Slow |
+
+## Code example — page transition wrapper (Framer Motion)
+
+```tsx
+import { motion, AnimatePresence } from "framer-motion";
+
+function PageTransition({ children, route }: Props) {
+  return (
+    <AnimatePresence mode="wait">
+      <motion.div
+        key={route}
+        initial={{ opacity: 0, y: 8 }}
+        animate={{ opacity: 1, y: 0 }}
+        exit={{ opacity: 0, y: -8 }}
+        transition={{ duration: 0.2, ease: "easeOut" }}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  );
+}
+```
+
+## Don't
+
+- Don't show looping spinner on splash. Brand-led is calmer.
+- Don't animate route changes longer than 300ms.
+- Don't transition every state change with motion. Only meaningful ones.
+- Don't auto-replay splash on every cold launch — user has seen it.
+- Don't ignore `prefers-reduced-motion` in transitions.
+- Don't block interactivity during transitions (button clicks during fade should still work).
+
+## Cross-reference
+
+- [`knowledge/motion/principles.md`](principles.md) — duration / easing fundamentals
+- [`knowledge/motion/marketing-motion.md`](marketing-motion.md) — hero entrances
+- [`knowledge/motion/choreography-depth.md`](choreography-depth.md) — multi-element coordination
+- [`knowledge/motion/motion-tools.md`](motion-tools.md) — tool comparison
+- [`knowledge/patterns/list-and-feed.md`](../patterns/list-and-feed.md) — pull-to-refresh + infinite scroll
+- [`examples/component-biometric-gate.md`](../../examples/component-biometric-gate.md) — Korean launch gate