From 731c0ceaf7f2eaed54a12320b5a40547ffbf5b40 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Sun, 15 Mar 2026 19:58:02 -0700 Subject: [PATCH] feat: add /overdrive skill for technically extraordinary effects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New skill that pushes interfaces past conventional limits with bleeding-edge browser APIs: WebGPU shaders, scroll-driven animations, View Transitions, generative art, spring physics, and more. Key design decisions: - Strong "when to use / when not to" guardrails - Progressive enhancement is non-negotiable - "Pick ONE hero moment" philosophy — restraint in choosing where - The extraordinary/gimmicky line defined explicitly - prefers-reduced-motion respect required Also updates all counts to 20 commands across website, docs, and plugin metadata. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 4 +- .claude-plugin/plugin.json | 2 +- .claude/skills/overdrive/SKILL.md | 161 ++++++++++++++++++++++++++ AGENTS.md | 2 +- NOTICE.md | 2 +- README.md | 7 +- public/cheatsheet.html | 10 +- public/index.html | 10 +- public/js/components/framework-viz.js | 6 +- public/js/data.js | 9 +- public/js/demos/commands/index.js | 2 + public/js/demos/commands/overdrive.js | 31 +++++ source/skills/overdrive/SKILL.md | 161 ++++++++++++++++++++++++++ 13 files changed, 385 insertions(+), 22 deletions(-) create mode 100644 .claude/skills/overdrive/SKILL.md create mode 100644 public/js/demos/commands/overdrive.js create mode 100644 source/skills/overdrive/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a40e07883..3787cbe17 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -2,7 +2,7 @@ "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", "name": "impeccable", "metadata": { - "description": "Design fluency for AI harnesses. 1 skill, 19 commands, and curated anti-patterns for impeccable frontend design." + "description": "Design fluency for AI harnesses. 1 skill, 20 commands, and curated anti-patterns for impeccable frontend design." }, "owner": { "name": "Paul Bakaus", @@ -11,7 +11,7 @@ "plugins": [ { "name": "impeccable", - "description": "Design vocabulary and skills for frontend development. Includes 19 commands (/polish, /distill, /audit, /typeset, /arrange, etc.) and an enhanced frontend-design skill with curated anti-patterns.", + "description": "Design vocabulary and skills for frontend development. Includes 20 commands (/polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced frontend-design skill with curated anti-patterns.", "version": "1.3.0", "author": { "name": "Paul Bakaus", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ae647c5c8..1798439b6 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "impeccable", - "description": "Design vocabulary and skills for frontend development. Includes 20 skills (19 user-invokable: /polish, /distill, /audit, /typeset, /arrange, etc.) and an enhanced frontend-design skill with curated anti-patterns.", + "description": "Design vocabulary and skills for frontend development. Includes 21 skills (20 user-invokable: /polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced frontend-design skill with curated anti-patterns.", "version": "1.3.0", "author": { "name": "Paul Bakaus", diff --git a/.claude/skills/overdrive/SKILL.md b/.claude/skills/overdrive/SKILL.md new file mode 100644 index 000000000..ee0f799b9 --- /dev/null +++ b/.claude/skills/overdrive/SKILL.md @@ -0,0 +1,161 @@ +--- +name: overdrive +description: Add technically extraordinary effects that push the boundaries of what's possible in the browser. WebGPU shaders, scroll-driven animations, generative art, and bleeding-edge APIs — ambitious without gimmicky. +user-invokable: true +args: + - name: target + description: The feature or area to push into overdrive (optional) + required: false +--- + +Push an interface past conventional limits with technically ambitious, visually extraordinary effects that make people stop and ask "how did they do that?" + +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. + +**EXTRA IMPORTANT FOR THIS SKILL**: Context is everything. A particle system on a creative portfolio is extraordinary. The same particle system on a SaaS settings page is embarrassing. You MUST understand the project's personality, audience, and goals before deciding what's appropriate. + +--- + +## When to Use This (and When Not To) + +This skill is not for every project. Use it when: +- The project's brand rewards boldness and spectacle (creative agencies, games, music, art, portfolios) +- There's a specific moment that should feel extraordinary (launch page, hero section, key transition) +- The audience expects to be impressed (developers, designers, creative professionals) +- The client or team has explicitly asked for something that stands out + +Do NOT use this when: +- The product needs to feel reliable and predictable (banking, healthcare, enterprise tools) +- Performance budgets are tight and every KB counts +- The audience values speed and efficiency over experience (dashboards, admin panels) +- You're adding complexity to compensate for weak fundamentals — fix those with other skills first + +**The test**: Would a senior creative director at a top agency look at this and nod approvingly, or roll their eyes? If the latter, dial it back. + +## Assess the Opportunity + +Before adding anything, understand what moment deserves the investment: + +1. **Find the hero moment**: Not everything can be extraordinary — pick ONE moment that gets the full treatment. A page load. A state transition. A scroll reveal. A hover interaction. Restraint in choosing where to go big is what separates impressive from gimmicky. + +2. **Match the ambition to the brand**: A glitch shader fits a music visualizer. A fluid simulation fits an environmental nonprofit. A generative mesh fits a creative tool. The effect should feel like it *belongs* to this product, not like it was bolted on. + +3. **Check the technical floor**: What browsers does this need to support? What devices? Progressive enhancement is non-negotiable — the experience must work without the effect, and the effect must enhance rather than replace. + +## The Toolkit + +These are the technologies that enable extraordinary interfaces. Choose based on what the moment needs, not what's newest. + +### CSS Bleeding Edge +- **Scroll-driven animations** (`animation-timeline: scroll()`) — tie any animation to scroll position without JavaScript +- **View Transitions API** — cinematic page transitions with shared element morphing +- **`@property`** — register custom properties for animatable gradients, colors, and complex values +- **Anchor positioning** — CSS-native popovers and tooltips that follow elements +- **CSS Houdini** (`paint()` worklets) — custom rendering directly in CSS +- **Container style queries** — style children based on parent's custom property values + +### WebGL / WebGPU +- **Shader effects** — noise distortion, chromatic aberration, liquid effects, ray marching +- **Post-processing** — bloom, depth of field, film grain on 3D or 2D content +- **Particle systems** — reactive particles, cursor trails, ambient atmosphere +- **Libraries**: Three.js, OGL (lightweight), regl, gpu-curtains (DOM + WebGL blend) + +### SVG & Canvas +- **Generative art** — algorithmic patterns, organic shapes, procedural textures +- **SVG filter chains** — displacement maps, turbulence, morphology for organic effects +- **Canvas 2D** — pixel manipulation, custom rendering, performance-critical 2D +- **Lottie / Rive** — vector animations with interactive state machines + +### Advanced Motion +- **FLIP animations** — layout animations at 60fps (First, Last, Invert, Play) +- **Spring physics** — natural motion with mass, tension, damping instead of cubic-bezier +- **Orchestrated sequences** — coordinated multi-element choreography with precise timing +- **Scroll snapping + scroll-driven** — hybrid scroll experiences with momentum + +### Audio & Haptics +- **Web Audio API** — reactive visualizations, spatial audio, sonic feedback +- **Haptic feedback** — `navigator.vibrate()` for tactile responses on mobile +- **Audio-reactive visuals** — effects that respond to music or ambient sound + +## Implement with Discipline + +### Progressive Enhancement is Non-Negotiable + +Every effect MUST degrade gracefully: + +```css +/* Feature detection first */ +@supports (animation-timeline: scroll()) { + .hero { animation-timeline: scroll(); } +} + +/* GPU capability check */ +@media (prefers-reduced-motion: no-preference) { + .shader-bg { /* only show if motion is OK */ } +} +``` + +```javascript +// Always check before using bleeding-edge APIs +if ('gpu' in navigator) { + // WebGPU path +} else if (canvas.getContext('webgl2')) { + // WebGL fallback +} else { + // CSS-only fallback — still must look good +} +``` + +### Performance is the Constraint + +Extraordinary effects that cause jank are worse than no effects at all. + +- **GPU-only**: Effects should run on the GPU. If it touches the main thread per frame, rethink. +- **Budget your frames**: Target 60fps. If you're dropping below 50, simplify. +- **Respect `prefers-reduced-motion`**: Always. No exceptions. Provide a beautiful static alternative. +- **Lazy initialization**: Don't load WebGL/WebGPU until the element is near viewport. +- **Kill off-screen**: Pause rendering when elements scroll out of view. + +### Quality Over Quantity + +- **One extraordinary moment** beats five mediocre effects +- **Polish relentlessly** — the difference between "cool" and "extraordinary" is in the final 20% of refinement: easing curves, timing, color grading, subtle secondary motion +- **Test on real devices** — effects that look amazing on a MacBook Pro might crawl on a mid-range Android + +## The Line Between Extraordinary and Gimmicky + +**Extraordinary:** +- Serves the narrative or emotional arc of the experience +- Feels integrated, like the interface couldn't exist without it +- Makes the user feel something (awe, delight, curiosity) +- Works WITH the content, not on top of it + +**Gimmicky:** +- Exists to demonstrate a technology, not to serve the user +- Feels bolted on — could be removed and nothing would change +- Distracts from the content it's supposed to enhance +- Prioritizes initial "wow" over sustained experience + +When in doubt, ask: **"If I removed this effect, would the experience feel incomplete, or would nobody notice?"** If nobody would notice, it's decoration. If it would feel incomplete, it's design. + +**NEVER**: +- Add effects that can't be turned off or reduced +- Ignore `prefers-reduced-motion` — this is an accessibility requirement, not a suggestion +- Ship effects that drop below 50fps on mid-range devices +- Use WebGPU/WebGL without a meaningful CSS fallback +- Add multiple competing effects — choose ONE hero moment +- Use effects to mask weak design fundamentals — fix those first with other skills +- Add sound without explicit user opt-in + +## Verify the Result + +- **The jaw-drop test**: Show it to someone who hasn't seen it. Do they react? +- **The removal test**: Remove the effect. Does the experience feel diminished? +- **The device test**: Run it on a phone, a tablet, a slow laptop. Still smooth? +- **The accessibility test**: Enable reduced motion. Is the fallback still beautiful? +- **The context test**: Does this effect make sense for THIS brand and audience? +- **The longevity test**: Will this still feel fresh in 6 months, or is it a trend? + +Remember: The goal isn't to use every API in the browser. It's to find the ONE technically ambitious idea that makes this specific interface unforgettable, then execute it with absolute precision. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 3119602a7..60e29e45c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Impeccable -The vocabulary you didn't know you needed. 1 skill, 19 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI. +The vocabulary you didn't know you needed. 1 skill, 20 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI. ## Repository Purpose diff --git a/NOTICE.md b/NOTICE.md index c74d45c23..ddf948fa0 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -13,5 +13,5 @@ The `frontend-design` skill in this project builds on Anthropic's original front This project extends the original with: - 7 domain-specific reference files (typography, color-and-contrast, spatial-design, motion-design, interaction-design, responsive-design, ux-writing) -- 19 steering commands +- 20 steering commands - Expanded patterns and anti-patterns diff --git a/README.md b/README.md index fa200af4d..37c942024 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Impeccable -The vocabulary you didn't know you needed. 1 skill, 19 commands, and curated anti-patterns for impeccable frontend design. +The vocabulary you didn't know you needed. 1 skill, 20 commands, and curated anti-patterns for impeccable frontend design. > **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles. @@ -12,7 +12,7 @@ Every LLM learned from the same generic templates. Without guidance, you get the Impeccable fights that bias with: - **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/frontend-design/)) -- **19 steering commands** to audit, review, polish, distill, animate, and more +- **20 steering commands** to audit, review, polish, distill, animate, and more - **Curated anti-patterns** that explicitly tell the AI what NOT to do ## What's Included @@ -31,7 +31,7 @@ A comprehensive design skill with 7 domain-specific references ([view skill](sou | [responsive-design](source/skills/frontend-design/reference/responsive-design.md) | Mobile-first, fluid design, container queries | | [ux-writing](source/skills/frontend-design/reference/ux-writing.md) | Button labels, error messages, empty states | -### 19 Commands +### 20 Commands | Command | What it does | |---------|--------------| @@ -54,6 +54,7 @@ A comprehensive design skill with 7 domain-specific references ([view skill](sou | `/onboard` | Design onboarding flows | | `/typeset` | Fix font choices, hierarchy, sizing | | `/arrange` | Fix layout, spacing, visual rhythm | +| `/overdrive` | Add technically extraordinary effects | ### Anti-Patterns diff --git a/public/cheatsheet.html b/public/cheatsheet.html index 094b782f4..0f0d4d7b6 100644 --- a/public/cheatsheet.html +++ b/public/cheatsheet.html @@ -4,7 +4,7 @@ Impeccable Command Cheatsheet - + @@ -160,7 +160,7 @@

Impeccable Commands

-

Quick reference for all 19 design commands

+

Quick reference for all 20 design commands

← Back to impeccable.style
@@ -203,7 +203,8 @@ 'adapt': 'adaptation', 'onboard': 'enhancement', 'typeset': 'enhancement', - 'arrange': 'enhancement' + 'arrange': 'enhancement', + 'overdrive': 'enhancement' }; const commandRelationships = { @@ -225,7 +226,8 @@ 'adapt': { combinesWith: ['normalize', 'clarify'], flow: 'Different devices/contexts' }, 'onboard': { combinesWith: ['clarify', 'delight'], flow: 'Onboarding & empty states' }, 'typeset': { combinesWith: ['bolder', 'normalize'], flow: 'Fix typography' }, - 'arrange': { combinesWith: ['distill', 'adapt'], flow: 'Fix layout & spacing' } + 'arrange': { combinesWith: ['distill', 'adapt'], flow: 'Fix layout & spacing' }, + 'overdrive': { combinesWith: ['animate', 'delight'], flow: 'Technically extraordinary effects' } }; async function loadCommands() { diff --git a/public/index.html b/public/index.html index bcbf78be0..c5d00baa4 100644 --- a/public/index.html +++ b/public/index.html @@ -4,7 +4,7 @@ Impeccable: The missing upgrade to Anthropic's frontend-design skill - + @@ -12,7 +12,7 @@ - + @@ -20,7 +20,7 @@ - + @@ -57,7 +57,7 @@
Enhanced frontend-design skill + anti-patterns · - 19 design skills: /polish, /audit, /typeset, /arrange... + 20 design skills: /polish, /audit, /typeset, /overdrive...
@@ -162,7 +162,7 @@

The Framework

-

One comprehensive skill with deep expertise, plus 19 commands that form the language of design.

+

One comprehensive skill with deep expertise, plus 20 commands that form the language of design.

diff --git a/public/js/components/framework-viz.js b/public/js/components/framework-viz.js index a20455872..f2850250d 100644 --- a/public/js/components/framework-viz.js +++ b/public/js/components/framework-viz.js @@ -44,7 +44,8 @@ const commandSymbols = { quieter: 'Qu', onboard: 'On', typeset: 'Ty', - arrange: 'Ar' + arrange: 'Ar', + overdrive: 'Od' }; // Atomic numbers (just for visual interest) @@ -67,7 +68,8 @@ const commandNumbers = { quieter: 15, onboard: 16, typeset: 17, - arrange: 18 + arrange: 18, + overdrive: 19 }; export class PeriodicTable { diff --git a/public/js/data.js b/public/js/data.js index 2e0c49cde..dc1d2de62 100644 --- a/public/js/data.js +++ b/public/js/data.js @@ -55,7 +55,8 @@ export const commandProcessSteps = { 'adapt': ['Analyze', 'Adjust', 'Optimize'], 'onboard': ['Map', 'Design', 'Guide'], 'typeset': ['Assess', 'Select', 'Scale', 'Refine'], - 'arrange': ['Assess', 'Grid', 'Rhythm', 'Balance'] + 'arrange': ['Assess', 'Grid', 'Rhythm', 'Balance'], + 'overdrive': ['Assess', 'Choose', 'Build', 'Polish'] }; export const commandCategories = { @@ -77,7 +78,8 @@ export const commandCategories = { 'adapt': 'adaptation', 'onboard': 'enhancement', 'typeset': 'enhancement', - 'arrange': 'enhancement' + 'arrange': 'enhancement', + 'overdrive': 'enhancement' }; // Skill relationships - now consolidated into frontend-design skill @@ -108,6 +110,7 @@ export const commandRelationships = { 'adapt': { combinesWith: ['normalize', 'clarify'], flow: 'Adaptation: Different devices/contexts' }, 'onboard': { combinesWith: ['clarify', 'delight'], flow: 'Enhancement: Onboarding & empty states' }, 'typeset': { combinesWith: ['bolder', 'normalize'], flow: 'Enhancement: Fix typography' }, - 'arrange': { combinesWith: ['distill', 'adapt'], flow: 'Enhancement: Fix layout & spacing' } + 'arrange': { combinesWith: ['distill', 'adapt'], flow: 'Enhancement: Fix layout & spacing' }, + 'overdrive': { combinesWith: ['animate', 'delight'], flow: 'Enhancement: Technically extraordinary effects' } }; diff --git a/public/js/demos/commands/index.js b/public/js/demos/commands/index.js index f57744725..6be37758e 100644 --- a/public/js/demos/commands/index.js +++ b/public/js/demos/commands/index.js @@ -18,6 +18,7 @@ import adapt from "./adapt.js"; import onboard from "./onboard.js"; import typeset from "./typeset.js"; import arrange from "./arrange.js"; +import overdrive from "./overdrive.js"; export const commandDemos = { normalize, @@ -38,6 +39,7 @@ export const commandDemos = { onboard, typeset, arrange, + overdrive, }; export function getCommandDemo(commandId) { diff --git a/public/js/demos/commands/overdrive.js b/public/js/demos/commands/overdrive.js new file mode 100644 index 000000000..5eb7a0fd3 --- /dev/null +++ b/public/js/demos/commands/overdrive.js @@ -0,0 +1,31 @@ +// Overdrive command demo - shows conventional UI becoming technically extraordinary +export default { + id: 'overdrive', + caption: 'Conventional static hero → Technically extraordinary experience', + + before: ` +
+
INTRODUCING
+
Nova Engine
+

The next generation of creative tools.

+ +
+ `, + + after: ` +
+
+
+
+
INTRODUCING
+
Nova Engine
+

The next generation of creative tools.

+ +
+ +
+ ` +}; diff --git a/source/skills/overdrive/SKILL.md b/source/skills/overdrive/SKILL.md new file mode 100644 index 000000000..950764942 --- /dev/null +++ b/source/skills/overdrive/SKILL.md @@ -0,0 +1,161 @@ +--- +name: overdrive +description: Add technically extraordinary effects that push the boundaries of what's possible in the browser. WebGPU shaders, scroll-driven animations, generative art, and bleeding-edge APIs — ambitious without gimmicky. +args: + - name: target + description: The feature or area to push into overdrive (optional) + required: false +user-invokable: true +--- + +Push an interface past conventional limits with technically ambitious, visually extraordinary effects that make people stop and ask "how did they do that?" + +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. + +**EXTRA IMPORTANT FOR THIS SKILL**: Context is everything. A particle system on a creative portfolio is extraordinary. The same particle system on a SaaS settings page is embarrassing. You MUST understand the project's personality, audience, and goals before deciding what's appropriate. + +--- + +## When to Use This (and When Not To) + +This skill is not for every project. Use it when: +- The project's brand rewards boldness and spectacle (creative agencies, games, music, art, portfolios) +- There's a specific moment that should feel extraordinary (launch page, hero section, key transition) +- The audience expects to be impressed (developers, designers, creative professionals) +- The client or team has explicitly asked for something that stands out + +Do NOT use this when: +- The product needs to feel reliable and predictable (banking, healthcare, enterprise tools) +- Performance budgets are tight and every KB counts +- The audience values speed and efficiency over experience (dashboards, admin panels) +- You're adding complexity to compensate for weak fundamentals — fix those with other skills first + +**The test**: Would a senior creative director at a top agency look at this and nod approvingly, or roll their eyes? If the latter, dial it back. + +## Assess the Opportunity + +Before adding anything, understand what moment deserves the investment: + +1. **Find the hero moment**: Not everything can be extraordinary — pick ONE moment that gets the full treatment. A page load. A state transition. A scroll reveal. A hover interaction. Restraint in choosing where to go big is what separates impressive from gimmicky. + +2. **Match the ambition to the brand**: A glitch shader fits a music visualizer. A fluid simulation fits an environmental nonprofit. A generative mesh fits a creative tool. The effect should feel like it *belongs* to this product, not like it was bolted on. + +3. **Check the technical floor**: What browsers does this need to support? What devices? Progressive enhancement is non-negotiable — the experience must work without the effect, and the effect must enhance rather than replace. + +## The Toolkit + +These are the technologies that enable extraordinary interfaces. Choose based on what the moment needs, not what's newest. + +### CSS Bleeding Edge +- **Scroll-driven animations** (`animation-timeline: scroll()`) — tie any animation to scroll position without JavaScript +- **View Transitions API** — cinematic page transitions with shared element morphing +- **`@property`** — register custom properties for animatable gradients, colors, and complex values +- **Anchor positioning** — CSS-native popovers and tooltips that follow elements +- **CSS Houdini** (`paint()` worklets) — custom rendering directly in CSS +- **Container style queries** — style children based on parent's custom property values + +### WebGL / WebGPU +- **Shader effects** — noise distortion, chromatic aberration, liquid effects, ray marching +- **Post-processing** — bloom, depth of field, film grain on 3D or 2D content +- **Particle systems** — reactive particles, cursor trails, ambient atmosphere +- **Libraries**: Three.js, OGL (lightweight), regl, gpu-curtains (DOM + WebGL blend) + +### SVG & Canvas +- **Generative art** — algorithmic patterns, organic shapes, procedural textures +- **SVG filter chains** — displacement maps, turbulence, morphology for organic effects +- **Canvas 2D** — pixel manipulation, custom rendering, performance-critical 2D +- **Lottie / Rive** — vector animations with interactive state machines + +### Advanced Motion +- **FLIP animations** — layout animations at 60fps (First, Last, Invert, Play) +- **Spring physics** — natural motion with mass, tension, damping instead of cubic-bezier +- **Orchestrated sequences** — coordinated multi-element choreography with precise timing +- **Scroll snapping + scroll-driven** — hybrid scroll experiences with momentum + +### Audio & Haptics +- **Web Audio API** — reactive visualizations, spatial audio, sonic feedback +- **Haptic feedback** — `navigator.vibrate()` for tactile responses on mobile +- **Audio-reactive visuals** — effects that respond to music or ambient sound + +## Implement with Discipline + +### Progressive Enhancement is Non-Negotiable + +Every effect MUST degrade gracefully: + +```css +/* Feature detection first */ +@supports (animation-timeline: scroll()) { + .hero { animation-timeline: scroll(); } +} + +/* GPU capability check */ +@media (prefers-reduced-motion: no-preference) { + .shader-bg { /* only show if motion is OK */ } +} +``` + +```javascript +// Always check before using bleeding-edge APIs +if ('gpu' in navigator) { + // WebGPU path +} else if (canvas.getContext('webgl2')) { + // WebGL fallback +} else { + // CSS-only fallback — still must look good +} +``` + +### Performance is the Constraint + +Extraordinary effects that cause jank are worse than no effects at all. + +- **GPU-only**: Effects should run on the GPU. If it touches the main thread per frame, rethink. +- **Budget your frames**: Target 60fps. If you're dropping below 50, simplify. +- **Respect `prefers-reduced-motion`**: Always. No exceptions. Provide a beautiful static alternative. +- **Lazy initialization**: Don't load WebGL/WebGPU until the element is near viewport. +- **Kill off-screen**: Pause rendering when elements scroll out of view. + +### Quality Over Quantity + +- **One extraordinary moment** beats five mediocre effects +- **Polish relentlessly** — the difference between "cool" and "extraordinary" is in the final 20% of refinement: easing curves, timing, color grading, subtle secondary motion +- **Test on real devices** — effects that look amazing on a MacBook Pro might crawl on a mid-range Android + +## The Line Between Extraordinary and Gimmicky + +**Extraordinary:** +- Serves the narrative or emotional arc of the experience +- Feels integrated, like the interface couldn't exist without it +- Makes the user feel something (awe, delight, curiosity) +- Works WITH the content, not on top of it + +**Gimmicky:** +- Exists to demonstrate a technology, not to serve the user +- Feels bolted on — could be removed and nothing would change +- Distracts from the content it's supposed to enhance +- Prioritizes initial "wow" over sustained experience + +When in doubt, ask: **"If I removed this effect, would the experience feel incomplete, or would nobody notice?"** If nobody would notice, it's decoration. If it would feel incomplete, it's design. + +**NEVER**: +- Add effects that can't be turned off or reduced +- Ignore `prefers-reduced-motion` — this is an accessibility requirement, not a suggestion +- Ship effects that drop below 50fps on mid-range devices +- Use WebGPU/WebGL without a meaningful CSS fallback +- Add multiple competing effects — choose ONE hero moment +- Use effects to mask weak design fundamentals — fix those first with other skills +- Add sound without explicit user opt-in + +## Verify the Result + +- **The jaw-drop test**: Show it to someone who hasn't seen it. Do they react? +- **The removal test**: Remove the effect. Does the experience feel diminished? +- **The device test**: Run it on a phone, a tablet, a slow laptop. Still smooth? +- **The accessibility test**: Enable reduced motion. Is the fallback still beautiful? +- **The context test**: Does this effect make sense for THIS brand and audience? +- **The longevity test**: Will this still feel fresh in 6 months, or is it a trend? + +Remember: The goal isn't to use every API in the browser. It's to find the ONE technically ambitious idea that makes this specific interface unforgettable, then execute it with absolute precision.