get-shit-pretty 0.5.1 → 0.5.2

package/gsp/references/anti-patterns.md

@@ -0,0 +1,173 @@
+# AI Design Anti-Patterns
+
+Convergence patterns that make AI-generated UI look AI-generated. Each entry: what it looks like, why it fails, what to do instead.
+
+---
+
+## Typography
+
+**Inter/Roboto as default** — instantly signals "AI made this." Use Geist, Outfit, Cabinet Grotesk, Satoshi, or a brand-specific typeface.
+
+**Hierarchy only through size** — creates monotone pages. Combine weight, color, spacing, and opacity to build clear typographic layers.
+
+**Missing letter-spacing** — large type looks loose, small caps look cramped. Apply negative tracking on display sizes, positive on small text and all-caps.
+
+**Proportional numbers in data tables** — columns won't align. Use `font-variant-numeric: tabular-nums` or a monospace face for numeric data.
+
+**Orphaned words on last lines** — single words dangling below headings look unfinished. Use `text-wrap: balance` for headings, `text-wrap: pretty` for body.
+
+**All-caps overuse** — screaming text flattens hierarchy. Reserve caps for overlines, labels, and navigation items only.
+
+**Serif fonts in software UI** — serif faces fight functional interfaces. Sans-serif only for dashboards, tools, and product UI.
+
+**Same weight everywhere** — 400 regular on every element is invisible hierarchy. Introduce medium (500) and semibold (600) to create contrast.
+
+---
+
+## Color
+
+**Pure #000000** — harsh and unnatural on screens. Use off-black: `zinc-950`, `slate-900`, or a hue-tinted dark.
+
+**Oversaturated accents above 80% chroma** — vibrate against neutrals and fail accessibility. Desaturate until the accent blends with the surrounding palette.
+
+**AI purple/blue gradient aesthetic** — the single most recognizable AI fingerprint. Use neutral bases with one singular, considered accent color.
+
+**Multiple accent colors** — fragments attention and looks undesigned. One accent, period. Use shade variations of that accent for states.
+
+**Mixing warm and cool grays** — creates visual tension. Pick one temperature for your neutral scale and commit.
+
+**Inconsistent shadow direction** — suggests multiple light sources, breaks spatial logic. Establish a single top-left or top-center light source.
+
+**Random dark sections in a light page** — jarring breaks in visual continuity. Commit to one mode or use subtle shade shifts (e.g., `gray-50` to `gray-100`).
+
+---
+
+## Layout
+
+**Centered-everything bias** — the laziest composition. Use split screen, left-aligned sections, asymmetric white-space when variance serves the brand.
+
+**Generic 3-column equal card rows** — screams template. Use 2-column zig-zag, asymmetric grid, horizontal scroll, or masonry instead.
+
+**`h-screen` for full-height sections** — breaks on mobile when the address bar hides/shows. Use `min-h-[100dvh]` with dynamic viewport units.
+
+**No max-width container** — text lines stretch to 200+ characters on wide screens. Add `max-w-7xl mx-auto` or equivalent.
+
+**Cards for everything** — elevation without purpose is noise. Use `border-t`, `divide-y`, or negative space for grouping. Cards only when elevation communicates hierarchy.
+
+**Equal top/bottom padding** — bottom padding looks visually shorter due to optical illusion. Make bottom ~10-20% larger for balance.
+
+**Complex flexbox percentage math** — fragile and hard to maintain. Use CSS Grid for reliable multi-column layouts.
+
+**Buttons not bottom-aligned in card groups** — CTAs at different vertical positions look broken. Pin actions to the card bottom so they form a clean horizontal line.
+
+**Inconsistent vertical rhythm** — side-by-side elements with misaligned baselines, titles, or images. Align shared elements across columns.
+
+---
+
+## Surfaces & Depth
+
+**Generic `box-shadow` with untinted black** — looks pasted on. Tint shadows to match or complement the background hue.
+
+**Flat design with zero texture** — sterile and lifeless. Add subtle noise, grain, or micro-patterns for tactile quality.
+
+**Generic card borders everywhere** — monotonous elevation. Vary treatment: some borderless, some elevated, some with subtle background shifts.
+
+**Inconsistent elevation** — random shadow sizes break spatial logic. Establish a z-layer system: flat, subtle, elevated, floating, overlay.
+
+**Perfectly even gradients** — look synthetic. Break with radial gradients, noise overlays, or mesh gradients for organic depth.
+
+---
+
+## Content
+
+**Lorem Ipsum placeholder text** — signals incomplete thinking. Write real draft copy, always. Even rough copy is better than Latin.
+
+**Generic names: "John Doe", "Jane Smith"** — lazy and culturally flat. Invent creative, diverse, realistic names that feel like real people.
+
+**Fake round numbers: 99.99%, $100.00, 50%** — obviously fake data. Use organic numbers: 47.2%, $99.00, 73%.
+
+**AI copywriting cliches: "Elevate", "Seamless", "Unleash", "Next-Gen", "Delve"** — immediately identifiable as AI slop. Use concrete, specific verbs that describe what actually happens.
+
+**"Oops!" error messages** — infantilizing and unhelpful. Be direct: "Connection failed. Try again."
+
+**Exclamation marks in success messages** — "Saved!" feels insecure. Be confident and quiet: "Changes saved."
+
+**Startup name slop: "Acme", "Nexus", "SmartFlow"** — generic placeholder branding. Invent contextual brand names with personality.
+
+**Broken Unsplash URLs** — AI hallucinates image URLs that 404. Use `picsum.photos/seed/{name}/800/600` or SVG placeholders.
+
+**Same avatar for multiple users** — destroys the illusion of real data. Unique asset per person.
+
+**Title Case On Every Header** — looks like a newspaper from 2003. Use sentence case for modern UI.
+
+---
+
+## Motion
+
+**Linear easing on everything** — mechanical and robotic. Use `cubic-bezier(0.16, 1, 0.3, 1)` or spring physics: `type: "spring", stiffness: 100, damping: 20`.
+
+**Animating `top`/`left`/`width`/`height`** — triggers layout reflow, causes jank. Use `transform` and `opacity` only (GPU-accelerated).
+
+**Instant transitions with zero duration** — feels broken. 200-300ms minimum for interactive element state changes.
+
+**No `prefers-reduced-motion` respect** — accessibility violation. Always wrap animations in `@media (prefers-reduced-motion: no-preference)`.
+
+**`window.addEventListener('scroll')` for scroll effects** — fires on every frame, kills performance. Use `IntersectionObserver` or CSS scroll-driven animations.
+
+**Everything mounts simultaneously** — wall of content appearing at once has zero visual hierarchy. Stagger with `animation-delay` cascade or `staggerChildren`.
+
+**Custom mouse cursors** — outdated gimmick that hurts performance and accessibility. Use native cursors.
+
+---
+
+## Components
+
+**Default shadcn/ui without customization** — recognizable on sight. Customize radii, colors, shadows, and spacing to match the brand.
+
+**Pill-shaped badges for everything** — visual clutter. Try square badges, flags, or plain styled text labels.
+
+**3-card testimonial carousel with dots** — the most generic social proof pattern. Use masonry wall, embedded posts, or a single rotating quote.
+
+**Modal for every interaction** — breaks flow and adds clicks. Use inline editing, slide-over panels, or expandable sections.
+
+**Sun/moon dark mode toggle** — overdone and takes up prime real estate. Use dropdown, system preference detection, or integrate into settings.
+
+**Generic circular spinner for loading** — tells user nothing about what's coming. Use skeleton loaders matching the actual layout shape.
+
+**Accordion FAQ section** — feels like a support page from 2015. Use side-by-side list, searchable help, or inline progressive disclosure.
+
+**4-column footer link farm** — nobody reads these. Simplify to main paths and legal links.
+
+**Generic SVG user avatars** — the gray circle person. Use creative photo placeholders or styled initial letters.
+
+---
+
+## Code Quality
+
+**Div soup** — inaccessible and unreadable. Use semantic HTML: `nav`, `main`, `article`, `aside`, `section`.
+
+**Inline styles mixed with utility classes** — inconsistent styling strategy. Pick one approach per project.
+
+**Hardcoded pixel widths** — breaks on every screen size. Use relative units: `%`, `rem`, `max-width`.
+
+**Arbitrary `z-index: 9999`** — z-index arms race. Establish a clean z-index scale in the theme config.
+
+**Missing alt text on meaningful images** — accessibility failure. Describe content for screen readers; use `alt=""` only for decorative images.
+
+**Missing meta tags** — invisible to search and social. Include `title`, `description`, `og:image` at minimum.
+
+**Commented-out dead code** — debug artifacts that signal carelessness. Remove all dead code before delivery.
+
+**Import hallucinations** — AI invents packages that don't exist. Verify every import resolves to a real dependency in `package.json`.
+
+**Emoji in UI code and markup** — unprofessional in product interfaces. Use quality icon sets: Phosphor, Heroicons, Lucide, or Radix Icons.
+
+---
+
+## How to Use
+
+This reference is loaded by designer, builder, and critic agents. When generating or evaluating design:
+
+1. **Designer** — avoid these patterns when creating screen specs
+2. **Builder** — check implemented code against this list before marking a screen complete
+3. **Critic** — flag any anti-patterns found as issues in `prioritized-fixes.md`

package/gsp/references/block-patterns.md

@@ -89,3 +89,47 @@ Single row: logo + horizontal link list + copyright. Centered or space-between.
 | Testimonials | 3 cards | 2 cards | 1 card or scroll |
 | Pricing cards | Side by side | Side by side | Stacked |
 | Rich footer | 4 columns | 2×2 grid | Stacked |
+
+---
+
+## Advanced Compositions
+
+### Bento 2.0
+
+Asymmetric grid where every cell is alive — each tile runs a perpetual micro-animation (pulse, float, shimmer, or infinite mini-carousel). Cells are self-contained components with their own animation loops, creating ambient motion across the grid. Mixed sizes: 1×1 through 2×2, 3-4 column grid.
+**Responsive:** Collapse to 2-col then 1-col. Animations persist at all breakpoints — they're per-tile, not layout-dependent.
+
+### Split-screen scroll
+
+Viewport divided into two vertical halves that scroll in opposite directions. Left pane scrolls content upward while right pane scrolls downward (or vice versa), creating a parallax tension effect. Content in each half is independent — typically images vs. text, or two complementary narratives.
+**Responsive:** Stack vertically with normal unified scroll direction. No split on viewports < 768px.
+
+### Curtain reveal
+
+Hero section that splits down the center like a curtain as the user scrolls, revealing the next section behind it. Each half translates outward (left half → left, right half → right) tied to scroll position. Content behind is fixed-position until fully revealed.
+**Responsive:** Replace curtain split with a simple crossfade on mobile — the split effect requires sufficient viewport width to read.
+
+### Sticky scroll sequence
+
+Image or video frames tied to scroll position, advancing one frame per scroll increment (like Apple product pages). A tall scroll container (300-500vh) drives a fixed-position media element through a sequence of states. Text callouts appear at keyframe positions.
+**Responsive:** Replace scroll-tied frames with auto-playing video or animated sequence. Maintain text callouts as overlay cards.
+
+### Accordion image slider
+
+5-7 narrow vertical strips displayed side by side, each showing a slice of its full image. On hover, the targeted strip expands to full width while others compress. Creates an explorable gallery in a single viewport-height section.
+**Responsive:** Convert to standard horizontal carousel with snap points on mobile. Hover-expand doesn't translate to touch.
+
+### Mega menu reveal
+
+Full-viewport-width dropdown panel triggered by nav hover or click. Content organized in 3-5 columns with staggered fade-in (80ms per column). Includes category headers, link lists, optional featured image or CTA card. Overlay dims page content behind.
+**Responsive:** Replace with full-screen slide-in panel from the side. Stagger animation applies to rows instead of columns.
+
+### Dynamic island
+
+Pill-shaped floating UI component that morphs shape and content contextually — expanding to show notifications, progress bars, media controls, or status updates. Uses `border-radius` transitions and `layout` animation (Framer Motion `layoutId`) for smooth shape-shifting.
+**Responsive:** Same behavior at all breakpoints. Adjust max-width and font size. Pin to top or bottom of viewport on mobile.
+
+### Command palette
+
+`⌘K` / `Ctrl+K` triggered search overlay with fuzzy matching, keyboard navigation (arrow keys + enter), and grouped results (pages, actions, settings). Modal with input field, scrollable results list, and keyboard shortcut hints. Escape or click-outside to dismiss.
+**Responsive:** Full-screen takeover on mobile with larger touch targets. Input auto-focused. Results fill available height.

package/gsp/references/chunk-format.md

@@ -46,3 +46,34 @@ Lightweight — just a lookup table. No prose.
 - **Self-contained:** each chunk must be understandable without loading other chunks
 - **Cross-references:** `## Related` section uses relative paths to related chunks
 - **Idempotent:** re-running a phase regenerates all chunks in that phase directory
+
+## Output Budgets
+
+Context is finite. Every line in a chunk is consumed by downstream agents. Budget accordingly.
+
+### Per-chunk budgets
+
+| Chunk type | Target | Hard max | Notes |
+|-----------|--------|----------|-------|
+| Phase chunk (design, research, etc.) | 50-150 lines | 200 lines | Self-contained, one concept per chunk |
+| INDEX.md | 10-30 lines | 50 lines | Lookup table only, no prose |
+| BUILD-LOG.md | 50-100 lines | 150 lines | Summary + tables, not narrative |
+| Component spec | 30-80 lines | 120 lines | Props, states, behavior — not full implementation |
+| Screen spec | 80-150 lines | 200 lines | Layout, components, interactions, states |
+
+### Per-phase budgets (total across all chunks)
+
+| Phase | Target total | Hard max | Typical chunks |
+|-------|-------------|----------|----------------|
+| Brief | 100-200 lines | 300 lines | 2-4 |
+| Research | 200-400 lines | 600 lines | 5-8 |
+| Design | 300-600 lines | 800 lines | 6-12 |
+| Critique | 100-200 lines | 300 lines | 2-4 |
+| Build log | 50-100 lines | 150 lines | 1 |
+| Review | 100-200 lines | 300 lines | 2-4 |
+
+### Terminal output (inline skills)
+
+- **Diagnostic** (doctor, progress): uncapped — user needs to see it, does not persist in agent context
+- **Greeting/status** (start): 20-40 lines
+- **Phase transitions**: 10-20 lines

package/gsp/references/style-preset-schema.md

@@ -0,0 +1,63 @@
+# Style Preset YAML Schema
+
+Template for brand-derived style preset files (`{brand-name}.yml`). All values must trace to foundation chunks.
+
+```yaml
+name: {brand-slug}
+description: {one-line brand aesthetic summary}
+tags: [5-8 fuzzy-match tags for style discovery]
+source: brand  # marks this as brand-derived, not a GSP preset
+
+tokens:
+  color:
+    primary: "{hex}"        # from foundations/color-system.md
+    secondary: "{hex}"
+    accent: "{hex}"
+    background: "{hex}"
+    surface: "{hex}"
+    on-primary: "{hex}"
+    on-background: "{hex}"
+    error: "{hex}"
+    success: "{hex}"
+    warning: "{hex}"
+    info: "{hex}"
+
+  typography:
+    font-family-primary: "{font stack}"  # from foundations/typography.md
+    font-family-mono: "{font stack}"
+    font-weight-heading: {number}
+    font-weight-body: {number}
+    font-size-base: "{px}"
+    line-height-base: {number}
+
+  shape:
+    border-radius-sm: "{px}"  # from foundations/border-radius.md
+    border-radius-md: "{px}"
+    border-radius-lg: "{px}"
+    border-width: "{px}"
+    border-color: "{hex}"
+
+  elevation:
+    shadow-sm: "{value}"  # from foundations/elevation.md
+    shadow-md: "{value}"
+    shadow-lg: "{value}"
+    shadow-xl: "{value}"
+
+  spacing:
+    base: {number}  # from foundations/spacing.md
+    scale: [{values}]
+
+  motion:
+    duration-fast: "{ms}"
+    duration-normal: "{ms}"
+    easing: "{value}"
+
+dark_mode:
+  color:
+    background: "{hex}"
+    surface: "{hex}"
+    on-background: "{hex}"
+
+compatibility: []  # leave empty for brand styles
+clashes: []
+```

package/gsp/references/visual-effects.md

@@ -208,6 +208,253 @@ background: linear-gradient(to top, rgba(0,0,0,0.7) 0%, transparent 60%);
 
 ---
 
+## Advanced Interactions
+
+### Spotlight border cards
+
+Mouse-tracking radial gradient on a pseudo-element, creating a glowing border that follows the cursor.
+
+```css
+.card { position: relative; border-radius: var(--radius-md); }
+.card::before {
+  content: ''; position: absolute; inset: -1px; border-radius: inherit;
+  background: radial-gradient(600px circle at var(--x) var(--y),
+    rgba(var(--color-primary-rgb), 0.3), transparent 40%);
+  z-index: -1;
+}
+```
+```js
+card.addEventListener('mousemove', (e) => {
+  const r = card.getBoundingClientRect();
+  card.style.setProperty('--x', `${e.clientX - r.left}px`);
+  card.style.setProperty('--y', `${e.clientY - r.top}px`);
+});
+```
+
+**When to use:** Feature grids, pricing cards, portfolio tiles — anywhere cards need subtle life on hover.
+
+### Parallax tilt cards
+
+3D tilt effect tracking cursor position within the card bounds.
+
+```css
+.tilt-card {
+  perspective: 800px;
+  transform-style: preserve-3d;
+  transition: transform 0.1s ease-out;
+}
+```
+```js
+card.addEventListener('mousemove', (e) => {
+  const r = card.getBoundingClientRect();
+  const x = (e.clientX - r.left) / r.width - 0.5;
+  const y = (e.clientY - r.top) / r.height - 0.5;
+  card.style.transform = `rotateY(${x * 10}deg) rotateX(${y * -10}deg)`;
+});
+card.addEventListener('mouseleave', () => card.style.transform = 'none');
+```
+
+**When to use:** Product showcases, testimonial cards, image galleries where depth reinforces premium feel.
+
+### Magnetic buttons
+
+Element pulls toward cursor proximity using Framer Motion spring physics.
+
+```tsx
+const x = useMotionValue(0);
+const y = useMotionValue(0);
+function handleMouse(e: React.MouseEvent) {
+  const r = e.currentTarget.getBoundingClientRect();
+  x.set((e.clientX - r.left - r.width / 2) * 0.3);
+  y.set((e.clientY - r.top - r.height / 2) * 0.3);
+}
+<motion.button style={{ x, y }} onMouseMove={handleMouse}
+  onMouseLeave={() => { x.set(0); y.set(0); }}
+  transition={{ type: "spring", stiffness: 150, damping: 15 }} />
+```
+
+**Performance:** CRITICAL — use `useMotionValue`, never `useState` for continuous animation. useState triggers re-renders every frame.
+**When to use:** Primary CTAs, nav icons, floating action buttons — sparingly, max 2-3 per viewport.
+
+### Staggered orchestration
+
+Cascade reveal for groups of elements entering the viewport.
+
+```tsx
+// Framer Motion — container orchestration
+<motion.div variants={{ show: { transition: { staggerChildren: 0.08 } } }}
+  initial="hidden" whileInView="show" viewport={{ once: true }}>
+  {items.map(item => (
+    <motion.div key={item.id}
+      variants={{ hidden: { opacity: 0, y: 20 }, show: { opacity: 1, y: 0 } }} />
+  ))}
+</motion.div>
+```
+```css
+/* CSS-only alternative */
+.stagger-item { animation: fade-up 0.5s ease-out both;
+  animation-delay: calc(var(--index) * 80ms); }
+```
+
+**When to use:** Feature lists, card grids, any repeated group entering on scroll. Limit to 6-8 items per stagger group.
+
+### Spring physics defaults
+
+Standard spring configurations for interactive elements. Never use linear easing for UI motion.
+
+```tsx
+// Interactive elements (buttons, toggles, cards)
+transition={{ type: "spring", stiffness: 100, damping: 20 }}
+
+// Snappy micro-interactions (checkboxes, switches)
+transition={{ type: "spring", stiffness: 300, damping: 25 }}
+
+// Gentle layout shifts (expanding panels, modals)
+transition={{ type: "spring", stiffness: 60, damping: 18 }}
+```
+
+**Performance:** Spring physics self-resolve — no need to specify duration. Overdamped (damping > 2√stiffness) prevents oscillation.
+**When to use:** Every animated element. Springs feel organic; linear/ease-in-out feel mechanical.
+
+### Scroll-driven reveals
+
+Native CSS scroll-driven animations or IntersectionObserver class toggling for entrance effects.
+
+```css
+/* CSS scroll-driven (modern browsers) */
+@keyframes reveal { from { opacity: 0; translate: 0 30px; } }
+.scroll-reveal {
+  animation: reveal linear both;
+  animation-timeline: view();
+  animation-range: entry 0% entry 40%;
+}
+```
+```css
+/* IO fallback — toggle class */
+.reveal { opacity: 0; transform: translateY(20px); transition: all 0.6s ease-out; }
+.reveal.visible { opacity: 1; transform: translateY(0); }
+```
+
+**Performance:** CSS `animation-timeline: view()` is compositor-driven — zero JS cost. Use IO fallback for Safari < 18.
+**When to use:** Default entrance pattern for all below-fold content. Prefer CSS scroll-driven where supported.
+
+### Sticky scroll stacking
+
+Sections with `position: sticky` that stack as user scrolls, creating a layered card deck effect.
+
+```css
+.stack-section {
+  position: sticky;
+  top: calc(var(--index) * 40px);
+  height: 80vh;
+  border-radius: var(--radius-lg);
+  transition: scale 0.3s ease;
+}
+.stack-section:not(:last-child) { scale: calc(1 - var(--index) * 0.02); }
+```
+
+**Performance:** Use `will-change: transform` on sticky elements. Limit to 4-6 stacking sections.
+**When to use:** Case studies, feature deep-dives, storytelling sequences where layered reveal adds narrative weight.
+
+### Horizontal scroll hijack
+
+Vertical scroll input translates to horizontal gallery panning.
+
+```css
+.h-scroll-wrapper { overflow-x: scroll; scroll-snap-type: x mandatory; }
+.h-scroll-wrapper > * {
+  scroll-snap-align: start; flex-shrink: 0; width: 80vw;
+}
+```
+```js
+// Alternative: translateX driven by scrollY
+const x = useTransform(scrollY, [sectionTop, sectionBottom],
+  ['0%', `-${(items.length - 1) * 100}%`]);
+```
+
+**Performance:** CSS `scroll-snap` is GPU-composited. JS transform approach needs `useMotionValue` for frame budgets.
+**When to use:** Image galleries, timelines, portfolio showcases — when horizontal layout serves content better than vertical.
+
+### Text mask reveal
+
+Large typography with media showing through the text shape.
+
+```css
+.text-mask {
+  font-size: clamp(4rem, 12vw, 10rem);
+  font-weight: 900;
+  background: url('video-or-gradient.mp4') center/cover;
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+}
+```
+
+**Performance:** `background-clip: text` with video is paint-heavy — limit to one instance per page.
+**When to use:** Hero headlines, section dividers, brand moments where type IS the visual.
+
+### Kinetic marquee
+
+Infinite horizontal text scroll, with hover pause or direction reversal.
+
+```css
+.marquee { overflow: hidden; white-space: nowrap; }
+.marquee-inner {
+  display: inline-flex; gap: 2rem;
+  animation: scroll-x 20s linear infinite;
+}
+.marquee:hover .marquee-inner { animation-direction: reverse; }
+@keyframes scroll-x { to { transform: translateX(-50%); } }
+```
+
+**Performance:** Duplicate content so the strip is 2× viewport width. `translateX` is compositor-only.
+**When to use:** Logo walls, social proof tickers, decorative text bands between sections.
+
+### Directional hover
+
+Detect which side the cursor enters and animate a fill from that direction.
+
+```js
+function getDirection(e, el) {
+  const { top, left, width, height } = el.getBoundingClientRect();
+  const x = (e.clientX - left - width / 2) / width;
+  const y = (e.clientY - top - height / 2) / height;
+  return Math.round((Math.atan2(y, x) * (180 / Math.PI) + 180) / 90) % 4;
+}
+// Set CSS custom property: --enter-from: top|right|bottom|left
+```
+```css
+.dir-hover::before {
+  transition: transform 0.3s ease;
+  transform: translateY(calc(var(--dir-y, 0) * 100%)) translateX(calc(var(--dir-x, 0) * 100%));
+}
+.dir-hover:hover::before { transform: translate(0, 0); }
+```
+
+**When to use:** Nav links, card overlays, image hover reveals — adds spatial awareness to interactions.
+
+### Liquid glass refraction
+
+Beyond basic glassmorphism — simulating realistic glass edge refraction and depth.
+
+```css
+.liquid-glass {
+  backdrop-filter: blur(20px) saturate(200%);
+  background: rgba(255, 255, 255, 0.05);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.1),   /* top edge highlight */
+    inset 0 -1px 0 rgba(0, 0, 0, 0.05),        /* bottom edge shadow */
+    0 8px 32px rgba(0, 0, 0, 0.12);
+  border-radius: var(--radius-lg);
+}
+```
+
+**Performance:** `backdrop-filter` triggers compositing — avoid stacking multiple blurred layers.
+**When to use:** Floating toolbars, modal overlays, nav bars over dynamic backgrounds — upgrade from flat glassmorphism.
+
+---
+
 ## Accessibility
 
 All visual effects must degrade gracefully: