From a89f7f504083d354a61d8d973c0c44a9289d9478 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Wed, 8 Apr 2026 10:26:01 -0700 Subject: [PATCH] Polish pass on editorial wrappers and skill detail layout Feedback round from first review of the skill pages. Six concrete fixes: 1. Contain the auto-rendered SKILL.md in a distinct card. The "skill itself" section was flowing straight into the editorial wrapper above, making the two blocks read as one long mixed document. Wrap the canonical body in .skill-source-card: white paper background, mist border, rounded, with a small "SKILL.md" badge header and an italic subtitle. Drop the old full-width divider treatment; the card does the visual separation work. 2. Rewrite the /impeccable "do not fight the opinion" pitfall. The old text said "fighting the opinion usually produces worse output", which discouraged informed pushback. Replace with language that explicitly encourages users with real reasons (brand guideline, accessibility, user research) to push back; the skill raises the floor, not overrules your judgment when you have evidence. 3. Move /onboard from create to refine. Onboarding is refinement of empty states and first-run experiences, not greenfield creation. Fixed in: - scripts/lib/sub-pages-data.js SKILL_CATEGORIES - public/js/data.js commandCategories Both locations now list onboard under 'refine'. 4. De-dupe overdrive and animate. - overdrive: "how it works" listed 7 techniques as bullets and then "try it" listed 5 concrete examples using the same 7 techniques. Collapse "how it works" into a tight paragraph and make "try it" a specific scenario instead of a laundry list. - animate: pitfalls repeated the "no layout properties" rule that was already stated in "how it works". Drop the duplicate. 5. Remove outdated tutorial guidance. getting-started.md said "Cursor needs Nightly channel plus Agent Skills in Settings. Gemini CLI needs the preview version." Neither is true anymore. Replace with a generic pointer to check the harness's own skill docs. 6. Embed the live visual overlay in critique-with-overlay tutorial. The tutorial now renders the same demo iframe the homepage uses (/antipattern-examples/visual-mode-demo.html) inside step 2, with a mac-window chrome frame that mirrors the homepage preview. New .tutorial-embed CSS in sub-pages.css defines the header with traffic-light dots + mono title, the iframe body (520px tall), and an optional caption. The user now sees the overlay in action before being asked to run it locally. --- content/site/skills/animate.md | 3 +- content/site/skills/impeccable.md | 2 +- content/site/skills/overdrive.md | 20 +-- .../site/tutorials/critique-with-overlay.md | 24 +++- content/site/tutorials/getting-started.md | 2 +- public/css/sub-pages.css | 118 +++++++++++++++--- public/js/data.js | 2 +- scripts/build-sub-pages.js | 12 +- scripts/lib/sub-pages-data.js | 2 +- 9 files changed, 135 insertions(+), 50 deletions(-) diff --git a/content/site/skills/animate.md b/content/site/skills/animate.md index a758bc6ce..6781a8675 100644 --- a/content/site/skills/animate.md +++ b/content/site/skills/animate.md @@ -39,5 +39,4 @@ Typical additions: ## Pitfalls - **Asking for "more animation".** Animate is not a dial. It adds where motion communicates, not everywhere. -- **Animating layout properties.** Never `width`, `height`, `top`, `left`, `padding`, `margin`. Transform and opacity only. -- **Skipping reduced-motion fallbacks.** Non-negotiable for accessibility. Animate will add them; do not remove them. +- **Removing the reduced-motion fallbacks.** The skill adds them automatically. Non-negotiable for accessibility. diff --git a/content/site/skills/impeccable.md b/content/site/skills/impeccable.md index 7ae0bcdc6..8a87487f1 100644 --- a/content/site/skills/impeccable.md +++ b/content/site/skills/impeccable.md @@ -35,5 +35,5 @@ You should get a page that commits to one clear aesthetic direction, uses non-de ## Pitfalls - **Skipping `/impeccable teach`.** Without a `.impeccable.md` file, the skill has to ask you context questions mid-flight. Faster to set it up once. -- **Treating it like a style guide.** It is an opinionated design partner, not a linter. If it says "do not use Inter," it means it. Fighting the opinion usually produces worse output. +- **Treating it like a style guide.** It is an opinionated design partner, not a linter. The defaults exist to raise the floor, not to overrule your judgment. If you have a real reason to push back (brand guideline, accessibility constraint, user research that says otherwise), push back and explain why. The skill will work with you. What produces worse output is ignoring the opinion without a reason. - **Expecting it to fix existing code.** For that, reach for `/polish`, `/distill`, or `/critique` instead. `/impeccable` is for creation. diff --git a/content/site/skills/overdrive.md b/content/site/skills/overdrive.md index ce76ce2e6..b01135358 100644 --- a/content/site/skills/overdrive.md +++ b/content/site/skills/overdrive.md @@ -10,17 +10,9 @@ Do not use it on operator tools, dashboards, or anything where reliability beats ## How it works -The skill starts by picking the one moment to make extraordinary, not spreading effort across the whole interface. Then it reaches for technically ambitious implementations that most AI-generated UIs never touch: +The skill picks one moment to make extraordinary and commits to it, rather than spreading effort across the whole interface. It then reaches for techniques most AI-generated UIs never touch: WebGL shaders, spring physics, Scroll Timeline, View Transitions, canvas animation, GPU-accelerated filters. Everything is budgeted, profiled, and tested at 60fps, with reduced-motion fallbacks baked in. -- **Shaders and WebGL** for hero visuals and background effects -- **Spring physics** (react-spring, framer-motion springs) instead of CSS transitions for elements the user drags, flicks, or directly manipulates -- **Scroll-driven animations** using Scroll Timeline API, not scroll listeners -- **View transitions** for cinematic page changes -- **Canvas and SVG animation** for custom visualizations that actually interact -- **GPU-accelerated filters** (backdrop-filter, SVG filters) used with purpose -- **60fps everywhere**: every animation budgeted, profiled, and tested - -The skill output is announced with `──── ⚡ OVERDRIVE ────` so you know you are entering a more ambitious mode. Expect larger diffs, new dependencies, and implementation depth beyond what other skills produce. +Overdrive output is announced with `──── ⚡ OVERDRIVE ────` so you know you are entering a more ambitious mode. Expect larger diffs, new dependencies, and implementation depth beyond what other skills produce. ## Try it @@ -28,13 +20,7 @@ The skill output is announced with `──── ⚡ OVERDRIVE ────` so /overdrive the landing hero ``` -Expected additions might include: - -- A WebGL shader background driven by mouse position and scroll -- Display headline with a mask reveal on scroll using Scroll Timeline -- Featured product image with a 3D tilt effect on pointer move -- A View Transition on the CTA that morphs into the next page -- Full reduced-motion fallback that swaps all of it for a static composition +One concrete run might replace a static hero with a WebGL shader background driven by mouse position, a display headline that reveals with a mask on scroll using the Scroll Timeline API, and a View Transition on the CTA that morphs into the next page. Plus a reduced-motion fallback that swaps all of it for a clean static composition. ## Pitfalls diff --git a/content/site/tutorials/critique-with-overlay.md b/content/site/tutorials/critique-with-overlay.md index 8a6c00c2f..4ce1e75fd 100644 --- a/content/site/tutorials/critique-with-overlay.md +++ b/content/site/tutorials/critique-with-overlay.md @@ -41,11 +41,25 @@ You get back a JSON list of every finding with its element selector, the rule th ## Step 2. Open the visual overlay -Impeccable ships with a visual mode that highlights every detected anti-pattern directly on the page. You have three ways to run it: +Impeccable ships with a visual mode that highlights every detected anti-pattern directly on the page. Here is what it looks like running on a deliberately-bad synthwave landing page: -1. **Chrome extension (coming soon)**: one-click activation on any page, yours or anyone's. -2. **Inside `/critique`**: the skill automatically opens the overlay during the browser portion of the assessment. -3. **Standalone CLI**: `npx impeccable live` starts a local overlay server, then you paste the URL you want to inspect. +
+
+ + + + Live detection overlay +
+ +
+ +Every outlined element has a floating label naming the rule that fired. Hover an outline to see the full finding. This is exactly what you will see on your own page. + +You have three ways to open it: + +1. **Chrome extension (coming soon)**: one-click activation on any page. +2. **Inside `/critique`**: the skill opens the overlay automatically during the browser portion of the assessment. +3. **Standalone CLI**: `npx impeccable live` starts a local overlay server, then you paste any URL. For this tutorial we will use the standalone CLI so you can see it without depending on the extension. @@ -55,7 +69,7 @@ In a new terminal: npx impeccable live ``` -This starts a server on `localhost:5199`. Open it. Paste the URL of your pricing page. The page loads inside an iframe with the detector script injected. Every flagged anti-pattern gets an outline and a floating label naming the rule. +This starts a server on `localhost:5199`. Open it. Paste the URL of your pricing page. The page loads inside an iframe with the detector script injected, and you get back the same overlay you saw above but on your own work. ## Step 3. Merge the two assessments diff --git a/content/site/tutorials/getting-started.md b/content/site/tutorials/getting-started.md index ea9a33f91..91a196f43 100644 --- a/content/site/tutorials/getting-started.md +++ b/content/site/tutorials/getting-started.md @@ -85,5 +85,5 @@ Review the diff. If something does not feel right, ask the model to explain the ## Common issues - **The skill says "no design context found"**. You skipped step 2. Run `/impeccable teach` first. -- **Commands do not appear in the harness**. Make sure your harness supports skills and has skills enabled. Cursor needs Nightly channel plus Agent Skills in Settings. Gemini CLI needs the preview version. +- **Commands do not appear in the harness**. Reload the harness after installing. If they still do not appear, check that the installer wrote files into the expected location (`.claude/skills/`, `.cursor/skills/`, etc.) and that your harness is picking up that directory. - **The polish pass rewrote something you liked**. Say so. Revert the change, tell the model which specific edit to undo, and continue from there. diff --git a/public/css/sub-pages.css b/public/css/sub-pages.css index 8c499563b..7c0406064 100644 --- a/public/css/sub-pages.css +++ b/public/css/sub-pages.css @@ -860,6 +860,62 @@ main#main { transform: translateX(4px); } +/* ============================================ + TUTORIAL EMBEDS (live overlays, screenshots) + ============================================ */ + +.tutorial-embed { + margin: var(--spacing-lg) 0 var(--spacing-xl); + border-radius: 10px; + overflow: hidden; + border: 1px solid var(--color-mist); + box-shadow: 0 8px 30px -6px rgba(0, 0, 0, 0.12); + max-width: none; +} + +.tutorial-embed-header { + display: flex; + align-items: center; + gap: 6px; + padding: 10px 14px; + background: var(--color-cream); + border-bottom: 1px solid var(--color-mist); +} + +.tutorial-embed-dot { + width: 10px; + height: 10px; + border-radius: 50%; + flex-shrink: 0; +} + +.tutorial-embed-dot.red { background: #ff5f56; } +.tutorial-embed-dot.yellow { background: #ffbd2e; } +.tutorial-embed-dot.green { background: #27c93f; } + +.tutorial-embed-title { + margin-left: auto; + font-family: var(--font-mono); + font-size: 0.75rem; + color: var(--color-ash); +} + +.tutorial-embed-iframe { + display: block; + width: 100%; + height: 520px; + border: none; + background: white; +} + +.tutorial-embed-caption { + font-size: 0.8125rem; + color: var(--color-ash); + margin-top: var(--spacing-sm); + font-style: italic; + max-width: 60ch; +} + /* ============================================ TUTORIAL DETAIL ============================================ */ @@ -1043,34 +1099,62 @@ main#main { } .skill-detail-editorial { - margin-bottom: clamp(3rem, 6vw, 4.5rem); + margin-bottom: clamp(2rem, 4vw, 3rem); } -.skill-detail-divider { +/* "The skill itself" card: visually contains the auto-rendered SKILL.md + body so it reads as a distinct reference block, not a continuation of + the editorial section above. */ +.skill-source-card { + background: var(--color-paper); + border: 1px solid var(--color-mist); + border-radius: 12px; + padding: clamp(var(--spacing-md), 3vw, var(--spacing-xl)); + margin-top: clamp(2rem, 4vw, 3rem); + box-shadow: 0 1px 0 oklch(90% 0 0); +} + +.skill-source-card-header { display: flex; - align-items: center; - gap: var(--spacing-md); - margin: clamp(3rem, 6vw, 4.5rem) 0 clamp(2rem, 4vw, 3rem); + align-items: baseline; + flex-wrap: wrap; + gap: var(--spacing-sm); + padding-bottom: var(--spacing-md); + margin-bottom: var(--spacing-md); + border-bottom: 1px solid var(--color-mist); } -.skill-detail-divider::before, -.skill-detail-divider::after { - content: ""; - flex: 1; - height: 1px; - background: var(--color-mist); -} - -.skill-detail-divider span { +.skill-source-card-label { font-family: var(--font-mono); - font-size: 0.6875rem; + font-size: 0.75rem; font-weight: 600; text-transform: uppercase; - letter-spacing: 0.14em; - color: var(--color-ash); + letter-spacing: 0.1em; + color: var(--color-accent); + padding: 3px 8px; + background: var(--color-accent-dim); + border-radius: 4px; flex-shrink: 0; } +.skill-source-card-subtitle { + font-size: 0.8125rem; + color: var(--color-ash); + font-style: italic; +} + +.skill-source-card-body { + max-width: none; +} + +.skill-source-card-body > :first-child { + margin-top: 0; +} + +.skill-source-card-body > :last-child { + margin-bottom: 0; +} + .skill-references { margin-top: clamp(3rem, 6vw, 4.5rem); padding-top: clamp(2rem, 4vw, 3rem); diff --git a/public/js/data.js b/public/js/data.js index 50d475207..8761a68fd 100644 --- a/public/js/data.js +++ b/public/js/data.js @@ -83,7 +83,6 @@ export const commandCategories = { 'shape': 'create', 'impeccable craft': 'create', 'impeccable': 'create', - 'onboard': 'create', 'overdrive': 'create', // EVALUATE - review and assess 'critique': 'evaluate', @@ -96,6 +95,7 @@ export const commandCategories = { 'delight': 'refine', 'bolder': 'refine', 'quieter': 'refine', + 'onboard': 'refine', // SIMPLIFY - reduce and clarify 'distill': 'simplify', 'clarify': 'simplify', diff --git a/scripts/build-sub-pages.js b/scripts/build-sub-pages.js index 39f77e9c8..697a0fe37 100644 --- a/scripts/build-sub-pages.js +++ b/scripts/build-sub-pages.js @@ -94,12 +94,14 @@ ${refBody} ${editorialHtml ? `
\n${editorialHtml}\n
` : ''} -
- The skill itself -
- -
+
+
+ SKILL.md + The canonical skill definition your AI harness loads. +
+
${bodyHtml} +
${referencesHtml} diff --git a/scripts/lib/sub-pages-data.js b/scripts/lib/sub-pages-data.js index d283ed6cd..26cc9eae3 100644 --- a/scripts/lib/sub-pages-data.js +++ b/scripts/lib/sub-pages-data.js @@ -32,7 +32,6 @@ const SKILL_CATEGORIES = { // CREATE - build something new impeccable: 'create', shape: 'create', - onboard: 'create', overdrive: 'create', // EVALUATE - review and assess critique: 'evaluate', @@ -45,6 +44,7 @@ const SKILL_CATEGORIES = { delight: 'refine', bolder: 'refine', quieter: 'refine', + onboard: 'refine', // SIMPLIFY - reduce and clarify distill: 'simplify', clarify: 'simplify',