From a8b032d362f49b8d5afcb180b31a6776455436cb Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Tue, 5 May 2026 10:40:28 -0700 Subject: [PATCH] skill: drop quality tiers, keep the real brand-craft guardrails Codex's craft/brand pass introduced fast/ship/showpiece "quality bars" plus brand-specific build gates, asset ledgers, sub-agent review, and self-graded fallback labels. In practice those tiers became escape hatches rather than craft pressure: the final output should always be 10/10, and the real decision points are splashiness and maximalism, not quality. Removed: - All quality-bar / showpiece / fast / ship framing in shape.md and craft.md - Standalone Brand Direction (#4) and Asset Requirements (#10) sections in shape's brief; renumbered back to 1-10 - The Brand hard rules section in brand.md (folded its real prohibitions into the existing Imagery and Brand bans sections) - Brand-specific build-gate item, mock-fidelity bullet, production-bar bullet, present-step bullet in craft.md - Asset ledger ceremony in craft Step 4 - Review-only sub-agents and "self-reviewed fallback, not independently validated" machinery in craft.md and polish.md - The For brand surfaces, assess hard failures subsection in polish.md and the brand checklist row - tests/brand-showpiece-reference.test.mjs (and its package.json wiring) Kept (the real nuggets): - Asset-substitution prohibition: image-led briefs ship real/generated assets or canvas/SVG/WebGL, not generic CSS panels, cards, bullets, or copy - Repeated tiny uppercase tracked kicker labels as a brand ban - Detector/QA output is defect evidence only, never proof of quality - "What visual assets are real content here?" discovery question - Inspect each major section individually for brand and long-form work - repeated-section-kickers detection rule + fixture - CLI improvements (JSON to stdout, -json/-fast aliases, severity field) - critique.md: npx impeccable detect --json fix Harness output dirs refreshed via bun run build. Full test suite (186) passes. Co-Authored-By: Claude Opus 4.7 (1M context) --- .agents/skills/impeccable/reference/brand.md | 3 +- .agents/skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- .agents/skills/impeccable/reference/polish.md | 14 +- .agents/skills/impeccable/reference/shape.md | 3 +- .claude/skills/impeccable/reference/brand.md | 3 +- .claude/skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- .claude/skills/impeccable/reference/polish.md | 14 +- .claude/skills/impeccable/reference/shape.md | 3 +- .cursor/skills/impeccable/reference/brand.md | 3 +- .cursor/skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- .cursor/skills/impeccable/reference/polish.md | 14 +- .cursor/skills/impeccable/reference/shape.md | 3 +- .gemini/skills/impeccable/reference/brand.md | 3 +- .gemini/skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- .gemini/skills/impeccable/reference/polish.md | 14 +- .gemini/skills/impeccable/reference/shape.md | 3 +- .github/skills/impeccable/reference/brand.md | 3 +- .github/skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- .github/skills/impeccable/reference/polish.md | 14 +- .github/skills/impeccable/reference/shape.md | 3 +- .kiro/skills/impeccable/reference/brand.md | 3 +- .kiro/skills/impeccable/reference/craft.md | 8 + .kiro/skills/impeccable/reference/critique.md | 2 +- .kiro/skills/impeccable/reference/polish.md | 14 +- .kiro/skills/impeccable/reference/shape.md | 3 +- .../skills/impeccable/reference/brand.md | 3 +- .../skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- .../skills/impeccable/reference/polish.md | 14 +- .../skills/impeccable/reference/shape.md | 3 +- .pi/skills/impeccable/reference/brand.md | 3 +- .pi/skills/impeccable/reference/craft.md | 8 + .pi/skills/impeccable/reference/critique.md | 2 +- .pi/skills/impeccable/reference/polish.md | 14 +- .pi/skills/impeccable/reference/shape.md | 3 +- .qoder/skills/impeccable/reference/brand.md | 3 +- .qoder/skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- .qoder/skills/impeccable/reference/polish.md | 14 +- .qoder/skills/impeccable/reference/shape.md | 3 +- .rovodev/skills/impeccable/reference/brand.md | 3 +- .rovodev/skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- .../skills/impeccable/reference/polish.md | 14 +- .rovodev/skills/impeccable/reference/shape.md | 3 +- .trae-cn/skills/impeccable/reference/brand.md | 3 +- .trae-cn/skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- .../skills/impeccable/reference/polish.md | 14 +- .trae-cn/skills/impeccable/reference/shape.md | 3 +- .trae/skills/impeccable/reference/brand.md | 3 +- .trae/skills/impeccable/reference/craft.md | 8 + .trae/skills/impeccable/reference/critique.md | 2 +- .trae/skills/impeccable/reference/polish.md | 14 +- .trae/skills/impeccable/reference/shape.md | 3 +- cli/engine/detect-antipatterns-browser.js | 138 ++++++++++++++++ cli/engine/detect-antipatterns.mjs | 152 +++++++++++++++++- plugin/skills/impeccable/reference/brand.md | 3 +- plugin/skills/impeccable/reference/craft.md | 8 + .../skills/impeccable/reference/critique.md | 2 +- plugin/skills/impeccable/reference/polish.md | 14 +- plugin/skills/impeccable/reference/shape.md | 3 +- site/pages/index.astro | 8 +- skill/reference/brand.md | 3 +- skill/reference/craft.md | 8 + skill/reference/critique.md | 2 +- skill/reference/polish.md | 14 +- skill/reference/shape.md | 3 +- tests/detect-antipatterns-fixtures.test.mjs | 35 ++++ tests/detect-antipatterns.test.js | 25 ++- .../repeated-section-kickers.html | 146 +++++++++++++++++ 76 files changed, 783 insertions(+), 141 deletions(-) create mode 100644 tests/fixtures/antipatterns/repeated-section-kickers.html diff --git a/.agents/skills/impeccable/reference/brand.md b/.agents/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.agents/skills/impeccable/reference/brand.md +++ b/.agents/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.agents/skills/impeccable/reference/craft.md b/.agents/skills/impeccable/reference/craft.md index 337b5c9b7..ed40a688c 100644 --- a/.agents/skills/impeccable/reference/craft.md +++ b/.agents/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.agents/skills/impeccable/reference/critique.md b/.agents/skills/impeccable/reference/critique.md index 4e9b73db0..8079dd3ff 100644 --- a/.agents/skills/impeccable/reference/critique.md +++ b/.agents/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.agents/skills/impeccable/reference/polish.md b/.agents/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.agents/skills/impeccable/reference/polish.md +++ b/.agents/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.agents/skills/impeccable/reference/shape.md b/.agents/skills/impeccable/reference/shape.md index 4eaa99a30..834b7d15b 100644 --- a/.agents/skills/impeccable/reference/shape.md +++ b/.agents/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.claude/skills/impeccable/reference/brand.md b/.claude/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.claude/skills/impeccable/reference/brand.md +++ b/.claude/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.claude/skills/impeccable/reference/craft.md b/.claude/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.claude/skills/impeccable/reference/craft.md +++ b/.claude/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.claude/skills/impeccable/reference/critique.md b/.claude/skills/impeccable/reference/critique.md index 18f855e62..fddf20f11 100644 --- a/.claude/skills/impeccable/reference/critique.md +++ b/.claude/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.claude/skills/impeccable/reference/polish.md b/.claude/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.claude/skills/impeccable/reference/polish.md +++ b/.claude/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.claude/skills/impeccable/reference/shape.md b/.claude/skills/impeccable/reference/shape.md index 756631825..b31b75646 100644 --- a/.claude/skills/impeccable/reference/shape.md +++ b/.claude/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.cursor/skills/impeccable/reference/brand.md b/.cursor/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.cursor/skills/impeccable/reference/brand.md +++ b/.cursor/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.cursor/skills/impeccable/reference/craft.md b/.cursor/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.cursor/skills/impeccable/reference/craft.md +++ b/.cursor/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.cursor/skills/impeccable/reference/critique.md b/.cursor/skills/impeccable/reference/critique.md index 712e8f757..1f8ab2868 100644 --- a/.cursor/skills/impeccable/reference/critique.md +++ b/.cursor/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.cursor/skills/impeccable/reference/polish.md b/.cursor/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.cursor/skills/impeccable/reference/polish.md +++ b/.cursor/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.cursor/skills/impeccable/reference/shape.md b/.cursor/skills/impeccable/reference/shape.md index 0785187ef..cba058e60 100644 --- a/.cursor/skills/impeccable/reference/shape.md +++ b/.cursor/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.gemini/skills/impeccable/reference/brand.md b/.gemini/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.gemini/skills/impeccable/reference/brand.md +++ b/.gemini/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.gemini/skills/impeccable/reference/craft.md b/.gemini/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.gemini/skills/impeccable/reference/craft.md +++ b/.gemini/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.gemini/skills/impeccable/reference/critique.md b/.gemini/skills/impeccable/reference/critique.md index 225badb88..0c63f1b7d 100644 --- a/.gemini/skills/impeccable/reference/critique.md +++ b/.gemini/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.gemini/skills/impeccable/reference/polish.md b/.gemini/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.gemini/skills/impeccable/reference/polish.md +++ b/.gemini/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.gemini/skills/impeccable/reference/shape.md b/.gemini/skills/impeccable/reference/shape.md index 0785187ef..cba058e60 100644 --- a/.gemini/skills/impeccable/reference/shape.md +++ b/.gemini/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.github/skills/impeccable/reference/brand.md b/.github/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.github/skills/impeccable/reference/brand.md +++ b/.github/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.github/skills/impeccable/reference/craft.md b/.github/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.github/skills/impeccable/reference/craft.md +++ b/.github/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.github/skills/impeccable/reference/critique.md b/.github/skills/impeccable/reference/critique.md index 39028f39a..abb442146 100644 --- a/.github/skills/impeccable/reference/critique.md +++ b/.github/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.github/skills/impeccable/reference/polish.md b/.github/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.github/skills/impeccable/reference/polish.md +++ b/.github/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.github/skills/impeccable/reference/shape.md b/.github/skills/impeccable/reference/shape.md index 0785187ef..cba058e60 100644 --- a/.github/skills/impeccable/reference/shape.md +++ b/.github/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.kiro/skills/impeccable/reference/brand.md b/.kiro/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.kiro/skills/impeccable/reference/brand.md +++ b/.kiro/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.kiro/skills/impeccable/reference/craft.md b/.kiro/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.kiro/skills/impeccable/reference/craft.md +++ b/.kiro/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.kiro/skills/impeccable/reference/critique.md b/.kiro/skills/impeccable/reference/critique.md index cf5ac3725..5ed7159be 100644 --- a/.kiro/skills/impeccable/reference/critique.md +++ b/.kiro/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.kiro/skills/impeccable/reference/polish.md b/.kiro/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.kiro/skills/impeccable/reference/polish.md +++ b/.kiro/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.kiro/skills/impeccable/reference/shape.md b/.kiro/skills/impeccable/reference/shape.md index 0785187ef..cba058e60 100644 --- a/.kiro/skills/impeccable/reference/shape.md +++ b/.kiro/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.opencode/skills/impeccable/reference/brand.md b/.opencode/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.opencode/skills/impeccable/reference/brand.md +++ b/.opencode/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.opencode/skills/impeccable/reference/craft.md b/.opencode/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.opencode/skills/impeccable/reference/craft.md +++ b/.opencode/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.opencode/skills/impeccable/reference/critique.md b/.opencode/skills/impeccable/reference/critique.md index c3f404442..3a8d39c41 100644 --- a/.opencode/skills/impeccable/reference/critique.md +++ b/.opencode/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.opencode/skills/impeccable/reference/polish.md b/.opencode/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.opencode/skills/impeccable/reference/polish.md +++ b/.opencode/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.opencode/skills/impeccable/reference/shape.md b/.opencode/skills/impeccable/reference/shape.md index 9fee0a100..b9eac54c0 100644 --- a/.opencode/skills/impeccable/reference/shape.md +++ b/.opencode/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.pi/skills/impeccable/reference/brand.md b/.pi/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.pi/skills/impeccable/reference/brand.md +++ b/.pi/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.pi/skills/impeccable/reference/craft.md b/.pi/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.pi/skills/impeccable/reference/craft.md +++ b/.pi/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.pi/skills/impeccable/reference/critique.md b/.pi/skills/impeccable/reference/critique.md index 1c8485b81..d5563b0d3 100644 --- a/.pi/skills/impeccable/reference/critique.md +++ b/.pi/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.pi/skills/impeccable/reference/polish.md b/.pi/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.pi/skills/impeccable/reference/polish.md +++ b/.pi/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.pi/skills/impeccable/reference/shape.md b/.pi/skills/impeccable/reference/shape.md index 0785187ef..cba058e60 100644 --- a/.pi/skills/impeccable/reference/shape.md +++ b/.pi/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.qoder/skills/impeccable/reference/brand.md b/.qoder/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.qoder/skills/impeccable/reference/brand.md +++ b/.qoder/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.qoder/skills/impeccable/reference/craft.md b/.qoder/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.qoder/skills/impeccable/reference/craft.md +++ b/.qoder/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.qoder/skills/impeccable/reference/critique.md b/.qoder/skills/impeccable/reference/critique.md index 1c8485b81..d5563b0d3 100644 --- a/.qoder/skills/impeccable/reference/critique.md +++ b/.qoder/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.qoder/skills/impeccable/reference/polish.md b/.qoder/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.qoder/skills/impeccable/reference/polish.md +++ b/.qoder/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.qoder/skills/impeccable/reference/shape.md b/.qoder/skills/impeccable/reference/shape.md index 0785187ef..cba058e60 100644 --- a/.qoder/skills/impeccable/reference/shape.md +++ b/.qoder/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.rovodev/skills/impeccable/reference/brand.md b/.rovodev/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.rovodev/skills/impeccable/reference/brand.md +++ b/.rovodev/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.rovodev/skills/impeccable/reference/craft.md b/.rovodev/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.rovodev/skills/impeccable/reference/craft.md +++ b/.rovodev/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.rovodev/skills/impeccable/reference/critique.md b/.rovodev/skills/impeccable/reference/critique.md index 1c8485b81..d5563b0d3 100644 --- a/.rovodev/skills/impeccable/reference/critique.md +++ b/.rovodev/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.rovodev/skills/impeccable/reference/polish.md b/.rovodev/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.rovodev/skills/impeccable/reference/polish.md +++ b/.rovodev/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.rovodev/skills/impeccable/reference/shape.md b/.rovodev/skills/impeccable/reference/shape.md index 0785187ef..cba058e60 100644 --- a/.rovodev/skills/impeccable/reference/shape.md +++ b/.rovodev/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.trae-cn/skills/impeccable/reference/brand.md b/.trae-cn/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.trae-cn/skills/impeccable/reference/brand.md +++ b/.trae-cn/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.trae-cn/skills/impeccable/reference/craft.md b/.trae-cn/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.trae-cn/skills/impeccable/reference/craft.md +++ b/.trae-cn/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.trae-cn/skills/impeccable/reference/critique.md b/.trae-cn/skills/impeccable/reference/critique.md index 1033d9464..6db43b3ec 100644 --- a/.trae-cn/skills/impeccable/reference/critique.md +++ b/.trae-cn/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.trae-cn/skills/impeccable/reference/polish.md b/.trae-cn/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.trae-cn/skills/impeccable/reference/polish.md +++ b/.trae-cn/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.trae-cn/skills/impeccable/reference/shape.md b/.trae-cn/skills/impeccable/reference/shape.md index 0785187ef..cba058e60 100644 --- a/.trae-cn/skills/impeccable/reference/shape.md +++ b/.trae-cn/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/.trae/skills/impeccable/reference/brand.md b/.trae/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/.trae/skills/impeccable/reference/brand.md +++ b/.trae/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.trae/skills/impeccable/reference/craft.md b/.trae/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/.trae/skills/impeccable/reference/craft.md +++ b/.trae/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/.trae/skills/impeccable/reference/critique.md b/.trae/skills/impeccable/reference/critique.md index 1033d9464..6db43b3ec 100644 --- a/.trae/skills/impeccable/reference/critique.md +++ b/.trae/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.trae/skills/impeccable/reference/polish.md b/.trae/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.trae/skills/impeccable/reference/polish.md +++ b/.trae/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.trae/skills/impeccable/reference/shape.md b/.trae/skills/impeccable/reference/shape.md index 0785187ef..cba058e60 100644 --- a/.trae/skills/impeccable/reference/shape.md +++ b/.trae/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/cli/engine/detect-antipatterns-browser.js b/cli/engine/detect-antipatterns-browser.js index 00c608176..28935ada7 100644 --- a/cli/engine/detect-antipatterns-browser.js +++ b/cli/engine/detect-antipatterns-browser.js @@ -257,6 +257,16 @@ const ANTIPATTERNS = [ skillSection: 'Typography', skillGuideline: 'tiny uppercase tracked label above the hero headline', }, + { + id: 'repeated-section-kickers', + category: 'slop', + severity: 'advisory', + name: 'Repeated section kicker labels', + description: + 'Repeating tiny uppercase tracked labels above section headings turns a brand page into AI editorial scaffolding. Replace them with stronger structure, artifacts, imagery, or a deliberate brand system.', + skillSection: 'Typography', + skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding', + }, // ── Quality: general design and accessibility issues ── { @@ -733,6 +743,15 @@ function checkHeroEyebrow(opts) { }]; } +function checkRepeatedSectionKickers(opts) { + const { candidates, minCount = 3 } = opts; + if (!Array.isArray(candidates) || candidates.length < minCount) return []; + return candidates.map(candidate => ({ + id: 'repeated-section-kickers', + snippet: `repeated section kicker "${candidate.kickerText}" before ${candidate.headingTag} "${candidate.headingText}" (${candidates.length} on page)`, + })); +} + const LAYOUT_TRANSITION_PROPS = new Set([ 'width', 'height', 'padding', 'margin', 'max-height', 'max-width', 'min-height', 'min-width', @@ -1231,6 +1250,107 @@ function checkElementHeroEyebrowDOM(el) { }); } +const REPEATED_KICKER_SKIP_SELECTOR = [ + 'nav', + 'form', + 'table', + 'thead', + 'tbody', + 'tfoot', + 'figure', + 'figcaption', + 'ol', + 'ul', + 'li', + '[role="navigation"]', + '[aria-label*="breadcrumb" i]', + '[class*="breadcrumb" i]', + '[data-impeccable-allow-kickers]', +].join(','); + +function cleanInlineText(el) { + return [...el.childNodes] + .filter(n => n.nodeType === 3) + .map(n => n.textContent) + .join(' ') + .replace(/\s+/g, ' ') + .trim(); +} + +function isRepeatedKickerCandidate(opts) { + const { + headingTag, + headingText, + headingFontSize, + kickerTag, + kickerText, + kickerTextTransform, + kickerFontSize, + kickerLetterSpacing, + } = opts; + if (!['h2', 'h3', 'h4'].includes(headingTag)) return false; + if (!headingText || headingText.length < 3) return false; + if (!(headingFontSize >= 20)) return false; + if (!kickerTag || HEADING_TAGS.has(kickerTag)) return false; + if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false; + if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false; + if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false; + + const isUppercased = kickerTextTransform === 'uppercase' + || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText)); + if (!isUppercased) return false; + if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false; + const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08); + if (!(kickerLetterSpacing >= minTrackedSpacing)) return false; + return true; +} + +function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpacing) { + const candidates = []; + for (const heading of doc.querySelectorAll('h2, h3, h4')) { + if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue; + const kicker = heading.previousElementSibling; + if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue; + + const headingStyle = getStyle(heading); + const kickerStyle = getStyle(kicker); + const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim(); + const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim(); + const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0; + const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0; + const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize); + + if (!isRepeatedKickerCandidate({ + headingTag: heading.tagName.toLowerCase(), + headingText, + headingFontSize, + kickerTag: kicker.tagName.toLowerCase(), + kickerText, + kickerTextTransform: kickerStyle.textTransform || '', + kickerFontSize, + kickerLetterSpacing, + })) { + continue; + } + + candidates.push({ + headingTag: heading.tagName.toLowerCase(), + headingText: headingText.replace(/^"|"$/g, '').slice(0, 60), + kickerText: kickerText.slice(0, 40), + }); + } + return candidates; +} + +function checkRepeatedSectionKickersDOM() { + const candidates = collectRepeatedSectionKickerCandidates( + document, + (el) => getComputedStyle(el), + (value, fontSize) => resolveLengthPx(value, fontSize) || 0, + ); + return checkRepeatedSectionKickers({ candidates }); +} + function checkElementMotionDOM(el) { const tag = el.tagName.toLowerCase(); if (SAFE_TAGS.has(tag)) return []; @@ -1658,6 +1778,15 @@ function checkElementHeroEyebrow(el, style, tag, window) { }); } +function checkRepeatedSectionKickersFromDoc(doc, win) { + const candidates = collectRepeatedSectionKickerCandidates( + doc, + (el) => win.getComputedStyle(el), + (value, fontSize) => resolveLengthPx(value, fontSize) || 0, + ); + return checkRepeatedSectionKickers({ candidates }); +} + function checkElementMotion(tag, style) { return checkMotion({ tag, @@ -2511,6 +2640,7 @@ if (IS_BROWSER) { return { type: f.type || f.id, category: ap ? ap.category : 'quality', + severity: ap?.severity || 'warning', detail: f.detail || f.snippet, name: ap ? ap.name : (f.type || f.id), description: ap ? ap.description : '', @@ -2585,6 +2715,14 @@ if (IS_BROWSER) { allFindings.push({ el: document.body, findings: typoFindings }); } + const sectionKickerFindings = checkRepeatedSectionKickersDOM() + .map(f => ({ type: f.id, detail: f.snippet })) + .filter(f => _ruleOk(f.type)); + if (sectionKickerFindings.length > 0) { + pageLevelFindings.push(...sectionKickerFindings); + allFindings.push({ el: document.body, findings: sectionKickerFindings }); + } + const layoutFindings = checkLayout().filter(f => _ruleOk(f.type)); for (const f of layoutFindings) { const el = f.el || document.body; diff --git a/cli/engine/detect-antipatterns.mjs b/cli/engine/detect-antipatterns.mjs index 7dd20c21f..5bc987efb 100644 --- a/cli/engine/detect-antipatterns.mjs +++ b/cli/engine/detect-antipatterns.mjs @@ -253,6 +253,16 @@ const ANTIPATTERNS = [ skillSection: 'Typography', skillGuideline: 'tiny uppercase tracked label above the hero headline', }, + { + id: 'repeated-section-kickers', + category: 'slop', + severity: 'advisory', + name: 'Repeated section kicker labels', + description: + 'Repeating tiny uppercase tracked labels above section headings turns a brand page into AI editorial scaffolding. Replace them with stronger structure, artifacts, imagery, or a deliberate brand system.', + skillSection: 'Typography', + skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding', + }, // ── Quality: general design and accessibility issues ── { @@ -729,6 +739,15 @@ function checkHeroEyebrow(opts) { }]; } +function checkRepeatedSectionKickers(opts) { + const { candidates, minCount = 3 } = opts; + if (!Array.isArray(candidates) || candidates.length < minCount) return []; + return candidates.map(candidate => ({ + id: 'repeated-section-kickers', + snippet: `repeated section kicker "${candidate.kickerText}" before ${candidate.headingTag} "${candidate.headingText}" (${candidates.length} on page)`, + })); +} + const LAYOUT_TRANSITION_PROPS = new Set([ 'width', 'height', 'padding', 'margin', 'max-height', 'max-width', 'min-height', 'min-width', @@ -1227,6 +1246,107 @@ function checkElementHeroEyebrowDOM(el) { }); } +const REPEATED_KICKER_SKIP_SELECTOR = [ + 'nav', + 'form', + 'table', + 'thead', + 'tbody', + 'tfoot', + 'figure', + 'figcaption', + 'ol', + 'ul', + 'li', + '[role="navigation"]', + '[aria-label*="breadcrumb" i]', + '[class*="breadcrumb" i]', + '[data-impeccable-allow-kickers]', +].join(','); + +function cleanInlineText(el) { + return [...el.childNodes] + .filter(n => n.nodeType === 3) + .map(n => n.textContent) + .join(' ') + .replace(/\s+/g, ' ') + .trim(); +} + +function isRepeatedKickerCandidate(opts) { + const { + headingTag, + headingText, + headingFontSize, + kickerTag, + kickerText, + kickerTextTransform, + kickerFontSize, + kickerLetterSpacing, + } = opts; + if (!['h2', 'h3', 'h4'].includes(headingTag)) return false; + if (!headingText || headingText.length < 3) return false; + if (!(headingFontSize >= 20)) return false; + if (!kickerTag || HEADING_TAGS.has(kickerTag)) return false; + if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false; + if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false; + if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false; + + const isUppercased = kickerTextTransform === 'uppercase' + || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText)); + if (!isUppercased) return false; + if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false; + const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08); + if (!(kickerLetterSpacing >= minTrackedSpacing)) return false; + return true; +} + +function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpacing) { + const candidates = []; + for (const heading of doc.querySelectorAll('h2, h3, h4')) { + if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue; + const kicker = heading.previousElementSibling; + if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue; + + const headingStyle = getStyle(heading); + const kickerStyle = getStyle(kicker); + const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim(); + const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim(); + const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0; + const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0; + const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize); + + if (!isRepeatedKickerCandidate({ + headingTag: heading.tagName.toLowerCase(), + headingText, + headingFontSize, + kickerTag: kicker.tagName.toLowerCase(), + kickerText, + kickerTextTransform: kickerStyle.textTransform || '', + kickerFontSize, + kickerLetterSpacing, + })) { + continue; + } + + candidates.push({ + headingTag: heading.tagName.toLowerCase(), + headingText: headingText.replace(/^"|"$/g, '').slice(0, 60), + kickerText: kickerText.slice(0, 40), + }); + } + return candidates; +} + +function checkRepeatedSectionKickersDOM() { + const candidates = collectRepeatedSectionKickerCandidates( + document, + (el) => getComputedStyle(el), + (value, fontSize) => resolveLengthPx(value, fontSize) || 0, + ); + return checkRepeatedSectionKickers({ candidates }); +} + function checkElementMotionDOM(el) { const tag = el.tagName.toLowerCase(); if (SAFE_TAGS.has(tag)) return []; @@ -1654,6 +1774,15 @@ function checkElementHeroEyebrow(el, style, tag, window) { }); } +function checkRepeatedSectionKickersFromDoc(doc, win) { + const candidates = collectRepeatedSectionKickerCandidates( + doc, + (el) => win.getComputedStyle(el), + (value, fontSize) => resolveLengthPx(value, fontSize) || 0, + ); + return checkRepeatedSectionKickers({ candidates }); +} + function checkElementMotion(tag, style) { return checkMotion({ tag, @@ -2507,6 +2636,7 @@ if (IS_BROWSER) { return { type: f.type || f.id, category: ap ? ap.category : 'quality', + severity: ap?.severity || 'warning', detail: f.detail || f.snippet, name: ap ? ap.name : (f.type || f.id), description: ap ? ap.description : '', @@ -2581,6 +2711,14 @@ if (IS_BROWSER) { allFindings.push({ el: document.body, findings: typoFindings }); } + const sectionKickerFindings = checkRepeatedSectionKickersDOM() + .map(f => ({ type: f.id, detail: f.snippet })) + .filter(f => _ruleOk(f.type)); + if (sectionKickerFindings.length > 0) { + pageLevelFindings.push(...sectionKickerFindings); + allFindings.push({ el: document.body, findings: sectionKickerFindings }); + } + const layoutFindings = checkLayout().filter(f => _ruleOk(f.type)); for (const f of layoutFindings) { const el = f.el || document.body; @@ -2719,7 +2857,7 @@ function getAP(id) { function finding(id, filePath, snippet, line = 0) { const ap = getAP(id); - return { antipattern: id, name: ap.name, description: ap.description, file: filePath, line, snippet }; + return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', file: filePath, line, snippet }; } /** Check if content looks like a full page (not a component/partial) */ @@ -2985,6 +3123,9 @@ async function detectHtml(filePath) { for (const f of checkPageTypography(document, window)) { findings.push(finding(f.id, filePath, f.snippet)); } + for (const f of checkRepeatedSectionKickersFromDoc(document, window)) { + findings.push(finding(f.id, filePath, f.snippet)); + } for (const f of checkPageLayout(document, window)) { findings.push(finding(f.id, filePath, f.snippet)); } @@ -3653,7 +3794,11 @@ Examples: } async function main() { - const args = process.argv.slice(2); + const args = process.argv.slice(2).map(arg => { + if (arg === '-json') return '--json'; + if (arg === '-fast') return '--fast'; + return arg; + }); const jsonMode = args.includes('--json'); const helpMode = args.includes('--help'); const fastMode = args.includes('--fast'); @@ -3762,7 +3907,8 @@ async function main() { } if (allFindings.length > 0) { - process.stderr.write(formatFindings(allFindings, jsonMode) + '\n'); + if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n'); + else process.stderr.write(formatFindings(allFindings, false) + '\n'); process.exit(2); } if (jsonMode) process.stdout.write('[]\n'); diff --git a/plugin/skills/impeccable/reference/brand.md b/plugin/skills/impeccable/reference/brand.md index b069f2553..bea638948 100644 --- a/plugin/skills/impeccable/reference/brand.md +++ b/plugin/skills/impeccable/reference/brand.md @@ -79,7 +79,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". @@ -102,6 +102,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/plugin/skills/impeccable/reference/craft.md b/plugin/skills/impeccable/reference/craft.md index bdeee0294..ce958b98f 100644 --- a/plugin/skills/impeccable/reference/craft.md +++ b/plugin/skills/impeccable/reference/craft.md @@ -105,12 +105,16 @@ Before building, inventory the approved mock's major visible ingredients: For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, cards, bullets, or copy, stop and fix it. That is not a harmless interpretation; it is a broken implementation. + Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. + Good candidates: - stickers @@ -155,6 +159,8 @@ Implement the feature following the design brief. Build in passes so structure, Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. + ### Required viewport pass Check the experience at the viewports that matter for the brief. Default minimum: @@ -165,6 +171,8 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. + ### Critique and fix loop After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: diff --git a/plugin/skills/impeccable/reference/critique.md b/plugin/skills/impeccable/reference/critique.md index 18f855e62..fddf20f11 100644 --- a/plugin/skills/impeccable/reference/critique.md +++ b/plugin/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/plugin/skills/impeccable/reference/polish.md b/plugin/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/plugin/skills/impeccable/reference/polish.md +++ b/plugin/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/plugin/skills/impeccable/reference/shape.md b/plugin/skills/impeccable/reference/shape.md index 756631825..b31b75646 100644 --- a/plugin/skills/impeccable/reference/shape.md +++ b/plugin/skills/impeccable/reference/shape.md @@ -36,6 +36,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -136,7 +137,7 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). diff --git a/site/pages/index.astro b/site/pages/index.astro index a24d68faf..5ee3451d1 100644 --- a/site/pages/index.astro +++ b/site/pages/index.astro @@ -491,7 +491,7 @@ import '../styles/sub-pages.css';