@stacksjs/defaults 0.70.206 → 0.70.208

package/ai/skills/stacks-design-minimalist/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: stacks-design-minimalist
+description: Use when a Stacks UI should feel editorial and minimalist (Notion/Linear vibe) - designing a docs site, dashboard, landing page, or content surface that needs restrained warm monochrome, typographic contrast, flat bento grids, muted pastel accents, and no gradients or heavy shadows. Composes with stacks-design-taste as an aesthetic preset built on stx + Crosswind + composables.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Editorial / Minimalist UI (Stacks)
+
+**Related skills:** refines [`stacks-design-taste`](../stacks-design-taste/SKILL.md) (the flagship anti-slop skill) with a restrained editorial preset. Build with [`stacks-stx`](../stacks-stx/SKILL.md) (templating, signals), [`stacks-crosswind`](../stacks-crosswind/SKILL.md) (utilities, dark mode, custom rules), and [`stacks-ui`](../stacks-ui/SKILL.md) (Craft + headless components). Full composable reference: [`stacks-composables`](../stacks-composables/SKILL.md).
+
+## 1. Protocol Overview
+Premium utilitarian minimalism and editorial UI. A frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms, built with stx + Crosswind. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends.
+
+## 2. Absolute Negative Constraints (Banned Elements)
+Strictly avoid these generic web development defaults:
+- DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces. (These are font *choices*; load your chosen fonts via the `fonts` config plus `@font-face` / `<link>` with `font-display: swap`, never `next/font`.)
+- DO NOT use generic thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons". Use Iconify `i-*` classes instead, and NEVER hand-roll SVG icon paths or `npm install` an icon package.
+- DO NOT use Crosswind's default heavy drop shadows (for example `shadow-md`, `shadow-lg`, `shadow-xl`). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05).
+- DO NOT use primary colored backgrounds for large elements or sections (no bright blue, green, or red hero sections).
+- DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
+- DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons.
+- DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper Iconify icons or clean SVG primitives.
+- DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content.
+- DO NOT use AI copywriting cliches: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language.
+
+## 3. Typographic Architecture
+The interface must rely on extreme typographic contrast and premium font selection for an editorial feel. Register these in the `fonts` config; load with `@font-face` + `font-display: swap`.
+- Primary Sans-Serif (Body, UI, Buttons): clean, geometric, or system-native fonts with character. Target: `font-family: 'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`.
+- Editorial Serif (Hero Headings & Quotes): Target: `font-family: 'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif`. Apply tight tracking (`letter-spacing: -0.02em` to `-0.04em`) and tight line-height (`1.1`).
+- Monospace (Code, Keystrokes, Meta-data): Target: `font-family: 'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace`.
+- Text Colors: Body text must never be absolute black (`#000000`). Use off-black/charcoal (`#111111` or `#2F3437`) with a generous `line-height` of `1.6` for legibility. Secondary text should be muted gray (`#787774`).
+
+## 4. Color Palette (Warm Monochrome + Spot Pastels)
+Color is a scarce resource, used only for semantic meaning or subtle accents.
+- Canvas / Background: Pure White `#FFFFFF` or Warm Bone/Off-White `#F7F6F3` / `#FBFBFA`.
+- Primary Surface (Cards): `#FFFFFF` or `#F9F9F8`.
+- Structural Borders / Dividers: Ultra-light gray `#EAEAEA` or `rgba(0,0,0,0.06)`.
+- Accent Colors: Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds.
+  - Pale Red: `#FDEBEC` (Text: `#9F2F2D`)
+  - Pale Blue: `#E1F3FE` (Text: `#1F6C9F`)
+  - Pale Green: `#EDF3EC` (Text: `#346538`)
+  - Pale Yellow: `#FBF3DB` (Text: `#956400`)
+
+Expose these as Crosswind theme tokens or CSS custom properties in `config/ui.ts` so dark mode (`dark:` + `useColorMode()` / `useDark()`) stays consistent.
+
+## 5. Component Specifications
+- Bento Box Feature Grids:
+  - Use asymmetrical CSS Grid layouts (`grid grid-cols-1 md:grid-cols-6` with mixed `col-span`).
+  - Cards must have exactly `border: 1px solid #EAEAEA` (`border border-[#EAEAEA]`).
+  - Border-radius must be crisp: `8px` or `12px` maximum (`rounded-lg` / `rounded-xl`).
+  - Internal padding must be generous (`p-6` to `p-10`).
+- Primary Call-To-Action (Buttons):
+  - Solid background `#111111`, text `#FFFFFF`.
+  - Slight border-radius (`rounded` to `rounded-md`). No box-shadow.
+  - Hover state is a subtle color shift to `#333333` or a micro `active:scale-[0.98]`.
+- Tags & Status Badges:
+  - Pill-shaped (`rounded-full`), very small typography (`text-xs`), uppercase with wide tracking (`tracking-[0.05em]`).
+  - Background uses the defined muted pastels. (Pills are allowed on small badges, never on large containers.)
+- Accordions (FAQ):
+  - Strip all container boxes. Separate items only with `border-b border-[#EAEAEA]`.
+  - Use a clean, sharp `+` and `-` toggle. Reach for the headless `Disclosure` component in [`stacks-ui`](../stacks-ui/SKILL.md) and toggle state with a signal.
+- Keystroke Micro-UIs:
+  - Render shortcuts as physical keys using `<kbd>`: `border border-[#EAEAEA] rounded bg-[#F7F6F3]` in the monospace font.
+- Faux-OS Window Chrome:
+  - When mocking software, wrap it in a minimalist container with a white top bar containing three small, light gray circles (macOS window controls).
+
+```html
+<!-- resources/components/BentoCard.stx -->
+<article class="p-8 bg-white dark:bg-neutral-900 border border-[#EAEAEA] rounded-xl">
+  <span class="inline-block px-2 py-0.5 text-[#1F6C9F] text-xs tracking-[0.05em] uppercase bg-[#E1F3FE] rounded-full">Docs</span>
+  <h3 class="mt-4 text-[#111111] text-2xl dark:text-neutral-100">Structured writing</h3>
+  <p class="mt-2 leading-[1.6] text-[#787774]"><slot /></p>
+</article>
+```
+
+## 6. Iconography & Imagery Directives
+- System Icons: Use Iconify `i-*` classes with a technical, slightly thicker-stroke aesthetic (for example `i-ph-*` bold/fill weights, or `i-radix-icons-*`). Standardize stroke width across all icons; keep one collection per project. NEVER hand-roll SVG icon paths.
+- Illustrations: Monochromatic, rough continuous-line ink sketches on white, featuring a single offset geometric shape filled with a muted pastel color.
+- Photography: High-quality, desaturated, warm-toned images. Apply subtle overlays (`opacity: 0.04` warm grain) to blend photos into the monochrome palette. Never use oversaturated stock photos. Use `<img>` with explicit `width`/`height` (reserve space to avoid CLS) and the stx asset pipeline; heavy assets go through `@stacksjs/storage`. Placeholder: `https://picsum.photos/seed/{context}/1200/800`.
+- Hero & Section Backgrounds: Sections should not feel empty and flat. Use subtle full-width background imagery at very low opacity, soft radial light spots (`radial-gradient` with warm tones at `opacity: 0.03`), or minimal geometric line patterns to add depth without breaking the clean aesthetic.
+
+## 7. Subtle Motion & Micro-Animations
+Motion should feel invisible: present but never distracting. Quiet sophistication, not spectacle. Stacks ships no animation library; build motion with Crosswind transitions, CSS keyframes in the `.stx` `<style>` block, and the allowed composables. Do NOT import `motion`, `gsap`, or `framer-motion`.
+- Scroll Entry: Elements fade in gently as they enter the viewport. Use `translateY(12px)` + `opacity: 0` resolving over `600ms` with `cubic-bezier(0.16, 1, 0.3, 1)`. Toggle the class with `useIntersectionObserver(target, cb)` or `useElementVisibility(target)`; NEVER `window.addEventListener('scroll', ...)`.
+- Hover States: Cards lift with an ultra-subtle shadow shift (`box-shadow` from `0 0 0` to `0 2px 8px rgba(0,0,0,0.04)` over `200ms`). Buttons respond with `active:scale-[0.98]`.
+- Staggered Reveals: List and grid items enter with a cascade delay (`animation-delay: calc(var(--index) * 80ms)`). Never mount everything at once.
+- Background Ambient Motion: Optional. A single very slow radial gradient blob (`animation-duration: 20s+`, `opacity: 0.02-0.04`) drifting behind hero sections, applied to a `position: fixed; pointer-events: none` layer. Never on scrolling containers.
+- Performance: Animate exclusively via `transform` and `opacity`. No layout-triggering properties (`top`, `left`, `width`, `height`). Use `will-change: transform` sparingly and only on actively animating elements.
+- Reduced motion: gate with CSS `@media (prefers-reduced-motion: reduce)` and/or `useMediaQuery('(prefers-reduced-motion: reduce)')`.
+
+```html
+<script client>
+  const block = useRef('block')
+  const shown = state(false)
+  useIntersectionObserver(block, (e) => { if (e[0].isIntersecting) shown.set(true) }, { threshold: 0.2 })
+</script>
+
+<section ref="block"
+         :class="shown() ? 'translate-y-0 opacity-100' : 'translate-y-3 opacity-0'"
+         class="duration-[600ms] ease-[cubic-bezier(0.16,1,0.3,1)] transition-all">
+  <slot />
+</section>
+```
+
+## 8. Execution Protocol
+When writing stx / Crosswind or designing a layout:
+1. Establish macro-whitespace first. Use massive vertical padding between sections (`py-24` or `py-32`).
+2. Constrain main typography content width to `max-w-4xl` or `max-w-5xl`.
+3. Apply the custom typographic hierarchy and monochromatic color tokens immediately.
+4. Ensure every card, divider, and border adheres strictly to the `1px solid #EAEAEA` rule.
+5. Add scroll-entry animations to all major content blocks via `useIntersectionObserver`.
+6. Ensure sections have visual depth through imagery, ambient gradients, or subtle textures; no empty flat backgrounds.
+7. Deliver complete stx that reflects this high-end, uncluttered, editorial aesthetic natively without requiring manual adjustments. Ship the full file, never a skeleton or placeholder comment.

package/ai/skills/stacks-design-output/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: stacks-design-output
+description: Use when generating stx components or design deliverables in a Stacks app and completeness matters - banning placeholder comments and truncation so you ship whole, runnable stx files instead of skeletons. Composes with stacks-design-taste and the aesthetic-preset skills as a full-output enforcement layer.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Full-Output Enforcement (Stacks)
+
+**Related skills:** the completeness enforcement layer for [`stacks-design-taste`](../stacks-design-taste/SKILL.md) (the flagship anti-slop skill) and the aesthetic presets [`stacks-design-soft`](../stacks-design-soft/SKILL.md), [`stacks-design-minimalist`](../stacks-design-minimalist/SKILL.md), [`stacks-design-brutalist`](../stacks-design-brutalist/SKILL.md), and [`stacks-redesign`](../stacks-redesign/SKILL.md). Deliverables are stx built with [`stacks-crosswind`](../stacks-crosswind/SKILL.md) and [`stacks-composables`](../stacks-composables/SKILL.md); see [`stacks-stx`](../stacks-stx/SKILL.md) for templating rules.
+
+## Baseline
+
+Treat every task as production-critical. A partial output is a broken output. Do not optimize for brevity; optimize for completeness. If the user asks for a full `.stx` file, deliver the full file. If the user asks for 5 components, deliver 5 components. No exceptions.
+
+## Banned Output Patterns
+
+The following patterns are hard failures. Never produce them:
+
+**In code blocks:** `// ...`, `// rest of code`, `// implement here`, `// TODO`, `/* ... */`, `// similar to above`, `// continue pattern`, `// add more as needed`, `{{-- ... --}}` or `<!-- rest of template -->` standing in for omitted markup, bare `...` standing in for omitted code, `@foreach` bodies replaced with a comment, or `<slot />` used to paper over content you were asked to write.
+
+**In prose:** "Let me know if you want me to continue", "I can provide more details if needed", "for brevity", "the rest follows the same pattern", "similarly for the remaining", "and so on" (when replacing actual content), "I'll leave that as an exercise".
+
+**Structural shortcuts:** Outputting a skeleton `.stx` when the request was for a full implementation. Showing the `<script>` and `<style>` blocks while skipping the `<template>` markup (or vice versa). Replacing repeated components with one example and a description. Describing what an stx component should do instead of writing it. Emitting one card and saying "repeat for the others".
+
+## Execution Process
+
+1. **Scope** - Read the full request. Count how many distinct deliverables are expected (`.stx` files, components, sections, views, layouts). Lock that number.
+2. **Build** - Generate every deliverable completely: every `<script>` / `<template>` / `<style>` block, every directive body (`@if`, `@foreach`, `@section`), every branch and every list item. No partial drafts, no "you can extend this later".
+3. **Cross-check** - Before output, re-read the original request. Compare your deliverable count against the scope count. If anything is missing, add it before responding.
+
+## Handling Long Outputs
+
+When a response approaches the token limit:
+- Do not compress remaining sections to squeeze them in.
+- Do not skip ahead to a conclusion.
+- Write at full quality up to a clean breakpoint (end of a component, end of an `.stx` file, end of a section).
+- End with:
+
+```
+[PAUSED - X of Y complete. Send "continue" to resume from: next section name]
+```
+
+On "continue", pick up exactly where you stopped. No recap, no repetition.
+
+## Quick Check
+
+Before finalizing any response, verify:
+- No banned patterns from the list above appear anywhere in the output
+- Every item the user requested is present and finished
+- Every `.stx` block that was asked for is complete: `<script>`, `<template>`/markup, and `<style>` as applicable
+- Code blocks contain actual runnable stx + Crosswind, not descriptions of what the component would do
+- No stx hard-ban leaked in while rushing: no `var`, no `document.*`, no `window.*` in `<script>` blocks; icons are Iconify `i-*` classes, never hand-rolled SVG
+- Nothing was shortened to save space

package/ai/skills/stacks-design-soft/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: stacks-design-soft
+description: Use when a Stacks UI should feel high-end, "expensive", soft, and premium - designing a landing page, hero, marketing section, pricing, or portfolio that needs generous whitespace, premium fonts, soft diffused shadows, and spring-like motion. Composes with stacks-design-taste as an aesthetic preset built on stx + Crosswind + composables.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Soft / High-End Visual Design (Stacks)
+
+**Related skills:** refines [`stacks-design-taste`](../stacks-design-taste/SKILL.md) (the flagship anti-slop skill) with a premium/soft aesthetic preset. Build with [`stacks-stx`](../stacks-stx/SKILL.md) (templating, signals), [`stacks-crosswind`](../stacks-crosswind/SKILL.md) (utilities, dark mode), and [`stacks-ui`](../stacks-ui/SKILL.md) (Craft + headless components). Full composable reference: [`stacks-composables`](../stacks-composables/SKILL.md).
+
+## 1. Core Directive
+- **Persona:** Principal UI/UX architect and motion choreographer, Awwwards-tier.
+- **Objective:** You engineer $150k+ agency-level digital experiences in a Stacks app, not just websites. Output must exude haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and flawless fluid motion, all built with stx + Crosswind + composables.
+- **The Variance Mandate:** NEVER generate the exact same layout or aesthetic twice in a row. Dynamically combine different premium layout archetypes and texture profiles while strictly adhering to the elite "Apple-esque / Linear-tier" design language.
+
+## 2. THE "ABSOLUTE ZERO" DIRECTIVE (STRICT ANTI-PATTERNS)
+If your generated stx includes ANY of the following, the design instantly fails:
+- **Banned Fonts:** Inter, Roboto, Arial, Open Sans, Helvetica. Use premium fonts (`Geist`, `Clash Display`, `PP Editorial New`, `Plus Jakarta Sans`). These are font *choices*; load them via the `fonts` config plus `@font-face` / `<link>` with `font-display: swap` in the layout `.stx` head (never `next/font`).
+- **Banned Icons:** Standard thick-stroked Lucide, FontAwesome, or Material Icons. Use only ultra-light precise lines via Iconify `i-*` classes (for example `i-ph-arrow-up-right` from Phosphor Light, or the hugeicons default). NEVER hand-roll SVG icon paths and NEVER `npm install` an icon library.
+- **Banned Borders & Shadows:** Generic 1px solid gray borders. Harsh dark drop shadows (`shadow-md`, `rgba(0,0,0,0.3)`).
+- **Banned Layouts:** Edge-to-edge sticky navbars glued to the top. Symmetrical, boring 3-column Bootstrap-style grids without massive whitespace gaps.
+- **Banned Motion:** Standard `linear` or `ease-in-out` transitions. Instant state changes without interpolation.
+
+## 3. THE CREATIVE VARIANCE ENGINE
+Before writing stx, silently "roll the dice" and select ONE combination from the archetypes below based on the prompt's context so output is uniquely tailored but always premium.
+
+### A. Vibe & Texture Archetypes (Pick 1)
+1. **Ethereal Glass (SaaS / AI / Tech):** Deepest OLED black (`#050505`), radial mesh gradients (subtle glowing purple/emerald orbs) in the background. Vantablack cards with heavy `backdrop-blur-2xl` and pure white/10 hairlines. Wide geometric Grotesk typography.
+2. **Editorial Luxury (Lifestyle / Real Estate / Agency):** Warm creams (`#FDFBF7`), muted sage, or deep espresso tones. High-contrast variable serif fonts for massive headings. Subtle CSS noise/film-grain overlay (`opacity-[0.03]`) for a physical paper feel.
+3. **Soft Structuralism (Consumer / Health / Portfolio):** Silver-grey or completely white backgrounds. Massive bold Grotesk typography. Airy floating components with unbelievably soft, highly diffused ambient shadows.
+
+### B. Layout Archetypes (Pick 1)
+1. **The Asymmetrical Bento:** A masonry-like CSS Grid of varying card sizes (for example `col-span-8 row-span-2` next to stacked `col-span-4` cards) to break visual monotony.
+   - **Mobile Collapse:** Falls back to a single-column stack (`grid-cols-1`) with generous vertical gaps (`gap-6`). All `col-span` overrides reset to `col-span-1`.
+2. **The Z-Axis Cascade:** Elements stacked like physical cards, slightly overlapping with varying depths of field, some with a subtle `-2deg` or `3deg` rotation to break the digital grid.
+   - **Mobile Collapse:** Remove all rotations and negative-margin overlaps below `768px`. Stack vertically with standard spacing. Overlapping elements cause touch-target conflicts on mobile.
+3. **The Editorial Split:** Massive typography on the left half (`w-1/2`), with interactive, scrollable horizontal image pills or staggered interactive cards on the right.
+   - **Mobile Collapse:** Converts to a full-width vertical stack (`w-full`). Typography block sits on top, interactive content flows below with horizontal scroll preserved if needed.
+
+**Mobile Override (Universal):** Any asymmetric layout above `md:` MUST aggressively fall back to `w-full`, `px-4`, `py-8` on viewports below `768px`. Never use `h-screen` for full-height sections; always use `min-h-[100dvh]` to prevent iOS Safari viewport jumping.
+
+## 4. HAPTIC MICRO-AESTHETICS (COMPONENT MASTERY)
+
+### A. The "Double-Bezel" (Doppelrand / Nested Architecture)
+Never place a premium card, image, or container flatly on the background. It must look like machined hardware (a glass plate sitting in an aluminum tray) using nested enclosures.
+- **Outer Shell:** A wrapper `div` with a subtle background (`bg-black/5` or `bg-white/5`), a hairline outer border (`ring-1 ring-black/5` or `border border-white/10`), specific padding (`p-1.5` or `p-2`), and a large outer radius (`rounded-[2rem]`).
+- **Inner Core:** The actual content container inside the shell. It has its own distinct background color, its own inner highlight (`shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]`), and a mathematically calculated smaller radius (`rounded-[calc(2rem-0.375rem)]`) for concentric curves.
+
+```html
+<!-- resources/components/BezelCard.stx -->
+<div class="p-2 bg-white/5 ring-1 ring-black/5 rounded-[2rem] dark:border dark:border-white/10">
+  <div class="p-8 bg-white dark:bg-neutral-900 rounded-[calc(2rem-0.5rem)] shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]">
+    <slot />
+  </div>
+</div>
+```
+
+### B. Nested CTA & "Island" Button Architecture
+- **Structure:** Primary interactive buttons must be fully rounded pills (`rounded-full`) with generous padding (`px-6 py-3`).
+- **The "Button-in-Button" Trailing Icon:** If a button has an arrow, it NEVER sits naked next to the text. It nests inside its own distinct circular wrapper (`w-8 h-8 rounded-full bg-black/5 dark:bg-white/10 flex items-center justify-center`) placed flush with the main button's right inner padding.
+
+```html
+<button class="inline-flex gap-3 items-center px-6 py-3 text-white bg-neutral-900 rounded-full duration-700 ease-[cubic-bezier(0.32,0.72,0,1)] transition-all active:scale-[0.98] group">
+  <span>Get started</span>
+  <span class="flex items-center justify-center h-8 w-8 bg-white/10 rounded-full duration-700 ease-[cubic-bezier(0.32,0.72,0,1)] transition-transform group-hover:scale-105 group-hover:translate-x-1 group-hover:-translate-y-px">
+    <i class="h-4 w-4 i-ph-arrow-up-right"></i>
+  </span>
+</button>
+```
+
+### C. Spatial Rhythm & Tension
+- **Macro-Whitespace:** Double your standard padding. Use `py-24` to `py-40` for sections. Let the design breathe heavily.
+- **Eyebrow Tags:** Precede major H1/H2s with a microscopic pill badge (`rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.2em] font-medium`). Use at most one eyebrow per section.
+
+## 5. MOTION CHOREOGRAPHY (FLUID DYNAMICS)
+Stacks ships no animation library. Do NOT import `motion/react`, `gsap`, or `framer-motion`. All motion is built with Crosswind transitions, CSS keyframes, and the allowed composables. Never use default transitions. All motion must simulate real-world mass and spring physics via custom cubic-beziers (`transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)]`).
+
+### A. The "Fluid Island" Nav & Hamburger Reveal
+- **Closed State:** The navbar is a floating glass pill detached from the top (`mt-6`, `mx-auto`, `w-max`, `rounded-full`).
+- **The Hamburger Morph:** On click, the hamburger lines fluidly rotate and translate to form a perfect 'X' (`rotate-45` and `-rotate-45` with absolute positioning), not just disappear. Drive the open state with a signal via `useToggle()`.
+- **The Modal Expansion:** The menu opens as a massive, screen-filling overlay with a heavy glass effect (`backdrop-blur-3xl bg-black/80` or `bg-white/80`). Reach for the `Transition` component in [`stacks-ui`](../stacks-ui/SKILL.md) for enter/leave.
+- **Staggered Mask Reveal:** Nav links do not just appear. They fade in and slide up from an invisible box (`translate-y-12 opacity-0` to `translate-y-0 opacity-100`) with a staggered delay (`delay-100`, `delay-150`, `delay-200` per item).
+
+```html
+<!-- resources/components/FluidNav.stx -->
+<script client>
+  const [open, toggle] = useToggle(false)
+</script>
+
+<nav class="mt-6 mx-auto px-4 py-2 w-max bg-white/70 dark:bg-black/60 ring-1 ring-black/5 rounded-full backdrop-blur-2xl">
+  <button @click="toggle()" class="relative h-6 w-6" aria-label="Menu">
+    <span :class="open() ? 'rotate-45 translate-y-0' : '-translate-y-1'"
+          class="absolute inset-x-0 h-px bg-current duration-500 ease-[cubic-bezier(0.32,0.72,0,1)] transition-transform"></span>
+    <span :class="open() ? '-rotate-45 translate-y-0' : 'translate-y-1'"
+          class="absolute inset-x-0 h-px bg-current duration-500 ease-[cubic-bezier(0.32,0.72,0,1)] transition-transform"></span>
+  </button>
+</nav>
+```
+
+### B. Magnetic Button Hover Physics
+- Use the `group` utility. On hover, do not just change the background color.
+- Scale the entire button down slightly (`active:scale-[0.98]`) to simulate a physical press.
+- The nested inner icon circle translates diagonally (`group-hover:translate-x-1 group-hover:-translate-y-px`) and scales up slightly (`scale-105`), creating internal kinetic tension.
+- For true pointer-magnetic tracking, use `useMouse()` inside a `<script client>` and drive a CSS custom property from an `effect` (`el.style.setProperty('--mx', ...)`); never React state, never a `requestAnimationFrame` loop that writes signal state every frame.
+
+### C. Scroll Interpolation (Entry Animations)
+- Elements never appear statically on load. As they enter the viewport, they execute a gentle heavy fade-up (`translate-y-16 blur-md opacity-0` resolving to `translate-y-0 blur-0 opacity-100` over 800ms+).
+- Use `useIntersectionObserver(target, cb)` or `useElementVisibility(target)` to toggle a Crosswind class when visible. This replaces Motion's `whileInView`. NEVER use `window.addEventListener('scroll', ...)`; it causes continuous reflows and kills mobile performance.
+
+```html
+<script client>
+  const card = useRef('reveal')
+  const shown = state(false)
+  useIntersectionObserver(card, (entries) => {
+    if (entries[0].isIntersecting) shown.set(true)
+  }, { threshold: 0.2 })
+</script>
+
+<div ref="reveal"
+     :class="shown() ? 'translate-y-0 blur-0 opacity-100' : 'translate-y-16 blur-md opacity-0'"
+     class="duration-[800ms] ease-[cubic-bezier(0.32,0.72,0,1)] transition-all">
+  <slot />
+</div>
+```
+
+## 6. PERFORMANCE GUARDRAILS
+- **GPU-Safe Animation:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`. Use `will-change: transform` sparingly and only on actively animating elements.
+- **Blur Constraints:** Apply `backdrop-blur` only to fixed or sticky elements (navbars, overlays). Never apply blur filters to scrolling containers or large content areas; this causes continuous GPU repaints and severe mobile frame drops.
+- **Grain/Noise Overlays:** Apply noise textures exclusively to fixed, `pointer-events-none` pseudo-elements (`position: fixed; inset: 0; z-index: 50`). Never attach them to scrolling containers.
+- **Z-Index Discipline:** Do not use arbitrary `z-50` or `z-[9999]`. Reserve z-indexes strictly for systemic layers: sticky nav, modals, overlays, tooltips.
+- **Reduced motion:** Above high motion intensity, gate everything with CSS `@media (prefers-reduced-motion: reduce)` and/or `useMediaQuery('(prefers-reduced-motion: reduce)')`.
+
+## 7. EXECUTION PROTOCOL
+When generating stx UI, follow this exact sequence:
+1. **[SILENT THOUGHT]** Roll the Variance Engine (Section 3). Choose Vibe and Layout Archetypes based on context to ensure a unique output.
+2. **[SCAFFOLD]** Establish background texture, macro-whitespace scale, and massive typography sizes.
+3. **[ARCHITECT]** Build the DOM strictly using the "Double-Bezel" technique for all major cards, inputs, and feature grids. Use exaggerated squircle radii (`rounded-[2rem]`).
+4. **[CHOREOGRAPH]** Inject custom `cubic-bezier` transitions, staggered nav reveals, and button-in-button hover physics, all in Crosswind + CSS + composables.
+5. **[OUTPUT]** Deliver flawless, complete stx + Crosswind. Ship the full file, never a skeleton or placeholder comment.
+
+## 8. PRE-OUTPUT CHECKLIST
+Evaluate your stx against this matrix before delivering. This is the last filter.
+- [ ] No banned fonts, icons, borders, shadows, layouts, or motion patterns from Section 2 are present
+- [ ] A Vibe Archetype and Layout Archetype from Section 3 were consciously selected and applied
+- [ ] All major cards and containers use the Double-Bezel nested architecture (outer shell + inner core)
+- [ ] CTA buttons use the Button-in-Button trailing icon pattern where applicable
+- [ ] Section padding is at minimum `py-24`; the layout breathes heavily
+- [ ] All transitions use custom cubic-bezier curves; no `linear` or `ease-in-out`
+- [ ] Scroll entry animations are present via `useIntersectionObserver` / `useElementVisibility`; no element appears statically
+- [ ] Layout collapses gracefully below `768px` to single-column with `w-full` and `px-4`
+- [ ] All animations use only `transform` and `opacity`; no layout-triggering properties
+- [ ] `backdrop-blur` is only applied to fixed/sticky elements, never to scrolling content
+- [ ] No `motion`/`gsap`/`framer-motion` import, no `var`/`document.*`/`window.*` in stx scripts, no hand-rolled SVG icons
+- [ ] The overall impression reads as "$150k agency build", not "template with nice fonts"