exonous 0.0.0-stage → 2.10.4

package/assets/skills/ui-motion/reference/vocabulary.md

@@ -0,0 +1,130 @@
+# Motion vocabulary (reverse lookup)
+
+Maps vague descriptions to precise terms so prompts and specs use shared language. Naming only — not build (`reference/web.md`) or audit (`reference/review.md`).
+
+## How to answer
+
+User describes what they see or feel. Return:
+
+```
+**Term** — One-line definition.
+```
+
+Best match first; 1–2 alternates if close. Disambiguate (e.g. crossfade vs shared-element vs morph). If no exact match, say so and compose from glossary terms. Keep answers short.
+
+## Glossary
+
+### Entrances & exits
+- **Fade in / Fade out** — Opacity to visible or hidden.
+- **Slide in** — Enters from off-screen edge.
+- **Scale in** — Grows from smaller size, often with fade.
+- **Pop in** — Slight overshoot on arrival.
+- **Reveal** — Gradual uncover via clip or mask.
+- **Enter / Exit** — Motion when node mounts or unmounts.
+
+### Sequencing & timing
+- **Keyframes** — Defined waypoints the engine interpolates between.
+- **Interpolation / Tween** — In-between frames between start and end values.
+- **Stagger** — Sequential starts with small offsets — cascade.
+- **Orchestration** — Multiple motions timed as one beat.
+- **Delay** — Wait before start.
+- **Duration** — Length of motion.
+- **Fill mode** — Styles held before/after (e.g. forwards).
+- **Stepped animation** — Discrete steps, not smooth blend.
+
+### Movement & transforms
+- **Translate** — Shift along X or Y.
+- **Scale** — Resize uniformly.
+- **Rotate** — Spin around a point.
+- **Skew** — Shear from rectangular shape.
+- **3D tilt / Flip** — rotateX/Y depth.
+- **Perspective** — Viewer distance for 3D exaggeration.
+- **Transform origin** — Anchor for scale/rotate.
+- **Origin-aware animation** — Grows from trigger, not box center.
+
+### State transitions
+- **Crossfade** — Overlap fade between two states same place.
+- **Continuity transition** — Same object reads across states (resize, reposition).
+- **Morph** — One shape becomes another.
+- **Shared element transition** — Element travels between layouts.
+- **Layout animation** — Size/position animates to new layout.
+- **Accordion / Collapse** — Height opens/closes for content.
+- **Direction-aware transition** — Forward/back slide opposes by nav direction.
+
+### Scroll & navigation
+- **Scroll reveal** — Enters when entering viewport.
+- **Scroll-driven animation** — Progress tied to scroll offset.
+- **Parallax** — Layers move at different rates.
+- **Page transition** — Motion between routes.
+- **View transition** — Browser morph between document states.
+
+### Feedback & interaction
+- **Hover effect** — Pointer-over change (web).
+- **Press / Tap feedback** — Brief scale on press.
+- **Hold to confirm** — Fill while held for destructive confirm.
+- **Drag** — Direct manipulation with optional momentum.
+- **Drag to reorder** — List reorder with shifting neighbors.
+- **Swipe to dismiss** — Off-screen drag to close.
+- **Rubber-banding** — Resistance and snap at overscroll edge.
+- **Shake / Wiggle** — Error/reject jitter.
+- **Ripple** — Expanding circle from tap point.
+
+### Easing
+- **Easing** — Speed curve over time.
+- **Ease-out** — Fast start, slow end — default for UI response.
+- **Ease-in** — Slow start — usually avoid on UI.
+- **Ease-in-out** — Slow-fast-slow for on-screen travel.
+- **Linear** — Constant speed — spinners, progress.
+- **Cubic-bezier** — Custom curve control points.
+- **Asymmetric easing** — Different accel/decel — livelier than symmetric.
+
+### Springs
+- **Spring** — Physics-driven settle vs fixed duration.
+- **Stiffness / Tension** — Pull toward target — higher = snappier.
+- **Damping** — Oscillation decay — lower = more bounce.
+- **Mass** — Heaviness of moving object.
+- **Bounce** — Overshoot then settle.
+- **Perceptual duration** — When motion *feels* done.
+- **Momentum** — Velocity continues after release.
+- **Velocity** — Speed/direction; springs preserve on interrupt.
+- **Interruptible animation** — Retarget mid-flight smoothly.
+
+### Looping & ambient
+- **Marquee** — Continuous horizontal scroll loop.
+- **Loop** — Repeating cycle.
+- **Alternate (yoyo)** — Forward then reverse each cycle.
+- **Orbit** — Path around anchor.
+- **Pulse** — Rhythmic scale/opacity attention.
+- **Float** — Gentle vertical drift idle motion.
+- **Idle animation** — Subtle motion while waiting.
+
+### Polish & effects
+- **Blur** — Soften or hide transition seams.
+- **Clip-path** — Hard-edge reveal/mask shapes.
+- **Mask** — Soft-edge hide/reveal vs clip-path.
+- **Before / after slider** — Draggable compare wipe.
+- **Line drawing** — SVG stroke draw-on.
+- **Text morph** — Character-wise text change.
+- **Skeleton / Shimmer** — Loading placeholder sheen.
+- **Number ticker** — Rolling digit counter.
+- **Tabular numbers** — Fixed-width digits — stable counters.
+- **Typewriter** — Sequential character reveal.
+
+### Performance
+- **Frame rate (FPS)** — 60 baseline; 120 on high-refresh displays.
+- **Jank** — Visible stutter from missed frames.
+- **Dropped frame** — Missed paint deadline hitch.
+- **Compositing** — GPU layer move/fade without layout.
+- **will-change** — Hint upcoming animation for promotion.
+- **Layout thrashing** — Layout-forcing props animated each frame.
+
+### Principles
+- **Purposeful animation** — Motion serves orientation/feedback, not filler.
+- **Anticipation** — Small wind-up before main move.
+- **Follow-through** — Secondary motion after main stop.
+- **Squash & stretch** — Deform conveys weight/speed.
+- **Perceived performance** — Motion changes felt speed.
+- **Frequency of use** — More exposure → shorter/subtler motion.
+- **Spatial consistency** — Same identity/path across states.
+- **Hardware acceleration** — transform/opacity on GPU.
+- **Reduced motion** — Honor system preference — gentler, not always off.

package/assets/skills/ui-motion/reference/web.md

@@ -0,0 +1,294 @@
+# Web animation — build sequence & recipes
+
+Construction skill: turn a motion request into implementation that passes review. Not for codebase audits (`reference/review.md`) or RN (`reference/expo.md`). For overlays (toast, drawer, menu) consider `reference/ui-libraries.md` before hand-rolling.
+
+## Posture
+
+Make the call; one line of reasoning; ship code. Worst failure: animating what should stay instant. Second: right moment, wrong curve, keyframes on a stack, `scale(0)`.
+
+## Hard rules
+
+1. Run steps 1–2 before tools or curves.
+2. Use table values — no invented beziers.
+3. Extend existing `--ease-*` / duration tokens; do not fork a parallel scale.
+4. Ship reduced-motion and hover gating with the change.
+5. Cheapest tool: CSS fade beats installing Motion.
+
+## Build sequence
+
+### 1–2. Gate & purpose
+
+Same frequency and purpose tables as `SKILL.md`. Keyboard-initiated → stop with instant UI alternative.
+
+### 3. Tool (first fit)
+
+| Need | Tool |
+| --- | --- |
+| Class/attribute toggles | CSS transition |
+| Mount entry, no JS | `@starting-style` |
+| Predetermined motion under load | CSS `@keyframes` / animation |
+| JS control, CSS perf | WAAPI `element.animate()` |
+| Springs, layout, exit, gestures | Motion (`motion.dev`) |
+
+### 4. Properties
+
+- `transform` + `opacity`; `clip-path` when recipe says so; `height` only for accordions.
+- No `scale(0)` entrances.
+- Trigger-anchored surfaces: `transform-origin: var(--transform-origin)`.
+- `translateY(100%)` = one element height — prefer over px.
+- Motion: full `transform` string, not `x`/`y` shorthands under load.
+
+### 5. Easing, duration, springs
+
+Follow `SKILL.md` tokens and duration table.
+
+Springs when: drag momentum, alive feel, interruptible gesture, decorative pointer tracking.
+
+```js
+{ type: "spring", duration: 0.5, bounce: 0.2 }
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
+```
+
+Bounce 0.1–0.3; reserve visible bounce for dismiss/playful cases.
+
+### 6. Interruption & exit
+
+Transitions (or springs) for rapid fire; symmetric enter/exit paths for dismiss surfaces; slow deliberate press, fast release (hold-to-confirm pattern).
+
+### 7. A11y
+
+`prefers-reduced-motion` + `@media (hover: hover) and (pointer: fine)` for hover motion.
+
+## Never ship
+
+| Avoid | Use |
+| --- | --- |
+| `transition: all` | Named properties |
+| `scale(0)` enter | `scale(0.95)` + opacity |
+| `ease-in` on UI | ease-out + strong bezier |
+| Keyframes on toasts/toggles | Transitions |
+| Motion x/y under load | `transform` string |
+| Ungated hover | fine-pointer media query |
+
+## Recipes
+
+Tokens: `--ease-out`, `--ease-in-out`, `--ease-drawer` from sequence above.
+
+### Press feedback
+
+```css
+.tap-target {
+  transition: transform 160ms var(--ease-out);
+}
+.tap-target:active {
+  transform: scale(0.97);
+}
+```
+
+### Popover / menu / select
+
+```css
+.floating-panel {
+  transform-origin: var(--transform-origin);
+  transition:
+    opacity 200ms var(--ease-out),
+    transform 200ms var(--ease-out);
+}
+.floating-panel[data-starting-style],
+.floating-panel[data-ending-style] {
+  opacity: 0;
+  transform: scale(0.95);
+}
+```
+
+### Tooltip
+
+```css
+.hint {
+  transform-origin: var(--transform-origin);
+  transition:
+    transform 125ms var(--ease-out),
+    opacity 125ms var(--ease-out);
+}
+.hint[data-starting-style],
+.hint[data-ending-style] {
+  opacity: 0;
+  transform: scale(0.97);
+}
+.hint[data-instant] {
+  transition-duration: 0ms;
+}
+```
+
+### Modal (centered origin)
+
+```css
+.dialog {
+  transform-origin: center;
+  transition:
+    opacity 250ms var(--ease-out),
+    transform 250ms var(--ease-out);
+}
+.dialog[data-starting-style],
+.dialog[data-ending-style] {
+  opacity: 0;
+  transform: scale(0.96);
+}
+.scrim {
+  transition: opacity 250ms var(--ease-out);
+}
+```
+
+### Drawer
+
+```css
+.sheet {
+  transform: translateY(0);
+  transition: transform 500ms var(--ease-drawer);
+}
+.sheet[data-closed] {
+  transform: translateY(100%);
+}
+```
+
+### Toast
+
+```css
+.notice {
+  opacity: 1;
+  transform: translateY(0);
+  transition:
+    opacity 400ms ease,
+    transform 400ms ease;
+
+  @starting-style {
+    opacity: 0;
+    transform: translateY(100%);
+  }
+}
+```
+
+Fallback mount flag if `@starting-style` unavailable:
+
+```jsx
+useEffect(() => { setVisible(true); }, []);
+// data-visible on root
+```
+
+### Accordion
+
+```css
+.panel-body {
+  overflow: hidden;
+  transition:
+    height 200ms var(--ease-out),
+    opacity 200ms var(--ease-out);
+}
+```
+
+Measure height in JS — do not animate to `auto` blindly.
+
+### Stagger (occasional lists)
+
+```css
+.row {
+  opacity: 0;
+  transform: translateY(8px);
+  animation: rise 300ms var(--ease-out) forwards;
+}
+.row:nth-child(2) { animation-delay: 50ms; }
+.row:nth-child(3) { animation-delay: 100ms; }
+.row:nth-child(4) { animation-delay: 150ms; }
+
+@keyframes rise {
+  to { opacity: 1; transform: translateY(0); }
+}
+```
+
+30–80ms between items; never block interaction.
+
+### Hold to confirm
+
+```css
+.fill-mask {
+  clip-path: inset(0 100% 0 0);
+  transition: clip-path 200ms var(--ease-out);
+}
+.destructive:active .fill-mask {
+  clip-path: inset(0 0 0 0);
+  transition: clip-path 2s linear;
+}
+.destructive:active {
+  transform: scale(0.97);
+}
+```
+
+### Tab color via clip
+
+Duplicate tab row; clip active copy; animate `clip-path` not per-tab color tweens.
+
+```css
+.tabs-active-layer {
+  clip-path: inset(0 60% 0 20%);
+  transition: clip-path 250ms var(--ease-in-out);
+}
+```
+
+### Scroll reveal (marketing only)
+
+```css
+.hero-block {
+  clip-path: inset(0 0 100% 0);
+  transition: clip-path 600ms var(--ease-in-out);
+}
+.hero-block[data-in-view] {
+  clip-path: inset(0 0 0 0);
+}
+```
+
+Once per element (`IntersectionObserver` or Motion `useInView` `{ once: true, margin: "-100px" }`).
+
+### Drag dismiss
+
+```js
+const elapsed = Date.now() - pointerDownAt;
+const speed = Math.abs(deltaY) / elapsed;
+if (Math.abs(deltaY) >= DISMISS_PX || speed > 0.11) close();
+```
+
+```js
+node.style.transform = `translateY(${deltaY}px)`;
+```
+
+Pointer capture; ignore second touch while dragging; rubber-band past edges; spring settle `{ type: "spring", duration: 0.5, bounce: 0.2 }`.
+
+### Crossfade seam blur
+
+```css
+.inner {
+  transition: filter 200ms ease, opacity 200ms ease;
+}
+.inner.is-swapping {
+  filter: blur(2px);
+  opacity: 0.7;
+}
+```
+
+Keep blur < 20px.
+
+### WAAPI clip reveal
+
+```js
+node.animate(
+  [{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }],
+  {
+    duration: 1000,
+    fill: 'forwards',
+    easing: 'cubic-bezier(0.77, 0, 0.175, 1)',
+  }
+);
+```
+
+## Output
+
+Deliver code; then briefly: gate + purpose, tool/properties/curve/duration, what to feel-check (2–5× slow, DevTools frames, device for gestures).

package/assets/skills/ui-patterns/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ui-patterns
+description: SUBORDINATE to the design stack (ui-design, ui-motion, native-ui, ui-mockup). Consult only after the stack has set design direction, and only for four gaps it does not cover - charts and data visualization, form UX patterns, web navigation patterns, and stack implementation guidelines (Vue, Nuxt, React, Next.js, React Native, shadcn/ui, HTML + Tailwind). Never sets visual direction, style, palette, typography or motion.
+---
+
+# ui-patterns
+
+Authority: this skill never sets visual direction. The design stack is the maximum source of truth for design; on any conflict between this file and the stack, the stack wins. Consult it only after the stack has defined direction, and only for the four areas below: charts, forms, web navigation and stack guidelines. Existing project design systems still win for tokens and components.
+
+Not here on purpose (the design stack owns it): aesthetic direction, style and palette selection, typography and font pairing, motion and animation, responsive and native iOS/Android adaptation, performance and Core Web Vitals, accessibility audit and hardening, i18n, empty and error states, copywriting, polish.
+
+## 1. Charts and data visualization
+
+Pick the chart from the data shape, not from looks.
+
+| Data type | Best chart | Avoid when | A11y fallback |
+|-----------|-----------|-----------|---------------|
+| Trend over time | Line | Fewer than 4 points (use a stat card); more than 6 series; no time dimension | Dashed/dotted line per series; toggleable data table with timestamps |
+| Compare categories | Bar (horizontal for long labels) | More than 15 categories (use a table); data has a time axis (use line) | Value labels always visible |
+| Part-to-whole | Donut / pie | More than 5 slices; differences under 5%; precise values needed | Stacked bar + percentage table (mandatory) |
+| Correlation / distribution | Scatter / bubble; box plot for groups | Categorical variables; fewer than 20 points; mobile-primary | Shape marker per group; data table (or min/Q1/median/Q3/max table) |
+| Heatmap / intensity | Heat map | Fewer than 20 cells (use bar); exact values needed; no pattern fallback for colorblind users | Numeric overlay on hover/focus; grid table with row/column labels |
+| Funnel / flow | Funnel; Sankey for branching | Non-sequential stages; values not monotonically decreasing; fewer than 3 stages | List of stage + count + drop-off %; keyboard traversal |
+| Performance vs target | Bullet (grid for several KPIs); gauge for a single KPI | No target or benchmark exists | Value and % of target as visible text; live region for real-time updates |
+| Hierarchical | Treemap | More than 3 levels; precise sibling comparison needed | Collapsible tree table as primary view |
+| Real-time streaming | Streaming area / line | Updates less than once a minute (use periodic refresh) | Pause/resume control; current value as large text; freeze under reduced motion |
+| Geographic | Choropleth / bubble map | Region sizes distort comparison (use bar); mobile-primary | Region labels; sortable table by region; keyboard-navigable regions |
+
+Rules:
+
+- Never encode meaning by color alone: add pattern, shape, line style or direct labels; no red/green-only pairs.
+- Contrast: data marks vs background at least 3:1; data text labels at least 4.5:1.
+- Always show a legend next to the chart; make it toggle series when there are several.
+- Label axes with units and readable, auto-skipped ticks; label time granularity and allow switching when relevant.
+- Direct-label values on small datasets; exact values via tooltip on hover, tap and keyboard focus.
+- Interactive marks (points, bars, slices) are keyboard-focusable and have at least 44pt touch targets.
+- Provide a data table alternative (sortable, with `aria-sort`) and a text summary or `aria-label` stating the key insight.
+- Format numbers, dates and currency with the user's locale.
+- More than 5 categories on a pie becomes a bar; 1000+ points get aggregated or sampled with drill-down.
+- Drill-down keeps a visible back path (breadcrumb of the current level).
+- One question per chart; split dense charts; keep gridlines low-contrast and skip decorative gradients and shadows.
+- Charts reflow on small screens (horizontal bars, fewer ticks) and render readable data immediately; entrance animation respects reduced motion.
+- Every chart has loading (skeleton, not an empty axis frame), empty (message + next step) and error (message + retry) states.
+- Data-heavy products offer CSV export of the underlying data.
+
+## 2. Forms and feedback
+
+Complements `ui-design harden` (validation, sanitization, double-submit, permission states); use both.
+
+- Every input has a visible label; placeholder is never the only label. Group related fields with `fieldset`/`legend`.
+- Mark required fields visibly and with `required` / `aria-required`.
+- Use semantic input types (`email`, `tel`, `number`, `url`) and `autocomplete` tokens so keyboards and autofill work.
+- Password fields have a show/hide toggle.
+- Validate on blur, not on every keystroke; show the error directly below its field, stating cause and fix.
+- Errors are announced: `aria-live` region or `role="alert"`, and the field links to its message via `aria-describedby`.
+- After a failed submit, move focus to the first invalid field. With many errors, add an error summary at the top whose items anchor to each field.
+- Submit shows loading, then success or error; the button stays disabled only while the request is in flight.
+- Toasts never steal focus: announce them with `aria-live="polite"`.
+- Confirm destructive actions and dismissing a modal/sheet with unsaved changes.
+- Offer undo for destructive and bulk actions (for example an "Undo delete" toast) instead of, or in addition to, a confirm.
+- Multi-step flows show a step indicator and allow going back without losing entered data.
+- Read-only is not disabled: read-only stays focusable, selectable and readable; disabled is removed from interaction and carries the semantic attribute.
+
+## 3. Web navigation patterns
+
+Native navigation (tab bars, app bars, gestures) belongs to `ui-design adapt` (native references) and `native-ui`.
+
+- Highlight the current location in every nav (indicator plus weight or color) and set `aria-current="page"`.
+- Back is predictable: restore scroll position, filters and form input; never silently reset the stack or jump home.
+- Key screens and meaningful state (filters, tabs, pagination, selected item) live in the URL so they are deep-linkable and shareable.
+- On client-side route change, move focus to the main content region (or its heading) and update the document title.
+- Use breadcrumbs for hierarchies 3+ levels deep.
+- Do not mix tabs, sidebar and bottom nav at the same hierarchy level; keep nav placement identical across pages.
+- Modals are not for primary navigation flows; if it needs a URL or a back button, it is a page.
+- Keep destructive actions (delete account, logout) visually and spatially separated from normal nav items.
+- When a destination is unavailable, show it disabled with the reason instead of silently hiding it.
+- Adaptive nav: persistent sidebar at 1024px and wider; top bar or bottom nav on small screens; core nav stays reachable from deep pages.
+
+## 4. Stack implementation guidelines
+
+High-severity implementation rules only (correctness, not look). Detect the stack from the project's `package.json` dependencies and read the matching file; read every file that applies (for example Nuxt + Tailwind).
+
+| Stack | Detect in `package.json` | Reference |
+|-------|--------------------------|-----------|
+| Vue | `vue` (without `nuxt`) | `references/stacks/vue.md` |
+| Nuxt / Nuxt UI | `nuxt`, `@nuxt/ui` | `references/stacks/nuxt.md` (also `vue.md`) |
+| React | `react` (without `next` / `react-native`) | `references/stacks/react.md` |
+| Next.js | `next` | `references/stacks/nextjs.md` (also `react.md`) |
+| React Native | `react-native`, `expo` | `references/stacks/react-native.md` |
+| shadcn/ui | `components.json` at the root, `@radix-ui/*` + `class-variance-authority` | `references/stacks/shadcn.md` |
+| HTML + Tailwind | `tailwindcss`, `@tailwindcss/*` | `references/stacks/html-tailwind.md` |
+
+## 5. Pre-delivery add-on
+
+Run after ui-design's own polish/audit pass; these are the items it does not enforce.
+
+- [ ] Clickable elements that are not `<button>`/`<a>` have `cursor: pointer` (and a proper role plus keyboard handler).
+- [ ] Every chart has a visible legend, a non-color encoding, and a table or text-summary fallback.
+- [ ] Forms: visible labels, error below field, errors announced, focus moves to the first invalid field on submit.
+- [ ] Toasts use `aria-live="polite"` and never take focus.
+- [ ] Client-side route changes move focus to main content and update the title; the active nav item is marked.
+- [ ] Meaningful UI state (filters, tabs, pagination) survives reload and back via the URL.
+- [ ] `z-index` values come from a defined scale (tokens), not ad-hoc numbers.
+
+Derived from [ui-ux-pro-max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) (MIT).

package/assets/skills/ui-patterns/references/stacks/html-tailwind.md

@@ -0,0 +1,40 @@
+# HTML + Tailwind — high-severity implementation guidelines
+
+Subordinate to the design stack (ui-design first). Implementation correctness only; never visual direction.
+
+## Animation
+
+- **Limit bounce animations** — Do: Use animate-bounce sparingly on CTAs only · Don't: Multiple bounce animations on page
+
+## Z-Index
+
+- **Fixed elements z-index** — Do: z-50 for nav z-40 for dropdowns · Don't: Relying on DOM order for stacking
+
+## Images
+
+- **Lazy loading** — Do: loading='lazy' on images · Don't: All images eager load
+- **Responsive images** — Do: srcset and sizes attributes · Don't: Same large image all devices
+- **SVG explicit dimensions** — Do: <svg class='size-6' width='24' height='24'> · Don't: SVG without explicit dimensions
+
+## Forms
+
+- **Focus states** — Do: focus:ring-2 focus:ring-blue-500 · Don't: Remove focus outline
+
+## Responsive
+
+- **Breakpoint testing** — Do: 320 375 768 1024 1280 1536 · Don't: Only test on development device
+
+## Buttons
+
+- **Touch targets** — Do: min-h-[44px] on mobile · Don't: Small buttons on mobile
+- **Loading states** — Do: disabled + spinner icon · Don't: Clickable during loading
+- **Icon buttons** — Do: aria-label on icon buttons · Don't: Icon button without label
+
+## Accessibility
+
+- **Screen reader text** — Do: sr-only for hidden labels · Don't: Missing context for icons
+- **Reduced motion** — Do: motion-reduce:animate-none · Don't: Ignore motion preferences
+
+## Performance
+
+- **Configure content paths** — Do: Use 'content' array in config · Don't: Use deprecated 'purge' option (v2)

package/assets/skills/ui-patterns/references/stacks/nextjs.md

@@ -0,0 +1,52 @@
+# Next.js — high-severity implementation guidelines
+
+Subordinate to the design stack (ui-design first). Implementation correctness only; never visual direction.
+
+## Routing
+
+- **Handle errors with error.tsx** — Do: error.tsx with reset function · Don't: try/catch in every component
+
+## Rendering
+
+- **Use Server Components by default** — Do: Keep components server by default · Don't: Add 'use client' unnecessarily
+- **Mark Client Components explicitly** — Do: Add 'use client' only when needed · Don't: Server Component with hooks/events
+- **Push Client Components down** — Do: Client wrapper for interactive parts only · Don't: Mark page as Client Component
+
+## DataFetching
+
+- **Fetch data in Server Components** — Do: async function Page() { const data = await fetch() } · Don't: useEffect for initial data
+- **Configure caching explicitly (Next.js 15+)** — Do: Explicitly set cache: 'force-cache' for static data · Don't: Assume default is cached (it's not in Next.js 15)
+
+## Images
+
+- **Use next/image for optimization** — Do: <Image> component for all images · Don't: <img> tags directly
+- **Provide width and height** — Do: width and height props or fill · Don't: Missing dimensions
+- **Configure remote image domains** — Do: remotePatterns in next.config.js · Don't: Allow all domains
+
+## API
+
+- **Validate request body** — Do: Zod or similar for validation · Don't: Trust client input
+
+## Middleware
+
+- **Keep middleware edge-compatible** — Do: Edge-compatible code only · Don't: Node.js APIs in middleware
+
+## Environment
+
+- **Use NEXT_PUBLIC prefix** — Do: NEXT_PUBLIC_ for client vars · Don't: Server vars exposed to client
+- **Validate env vars** — Do: Validate on startup · Don't: Undefined env at runtime
+- **Use .env.local for secrets** — Do: .env.local gitignored · Don't: Secrets in .env committed
+
+## Performance
+
+- **Avoid layout shifts** — Do: Skeleton loaders aspect ratios · Don't: Content popping in
+
+## Link
+
+- **Use next/link for navigation** — Do: <Link href=""> for internal links · Don't: <a> for internal navigation
+
+## Security
+
+- **Sanitize user input** — Do: Escape sanitize validate all input · Don't: Direct interpolation of user data
+- **Use CSP headers** — Do: Configure CSP in next.config.js · Don't: No security headers
+- **Validate Server Action input** — Do: Validate and authorize in Server Action · Don't: Trust Server Action input