diff --git a/skills/creative/claude-design/SKILL.md b/skills/creative/claude-design/SKILL.md index 673d1ff827a..d67fa6ce1ba 100644 --- a/skills/creative/claude-design/SKILL.md +++ b/skills/creative/claude-design/SKILL.md @@ -1,7 +1,7 @@ --- name: claude-design description: Design one-off HTML artifacts (landing, deck, prototype). -version: 1.0.0 +version: 1.1.0 author: BadTechBandit license: MIT platforms: [linux, macos, windows] @@ -165,6 +165,31 @@ Skip questions when: When proceeding with assumptions, label only the important ones. +## Surface-First: Commit to a Composition Before Touching Tokens + +The single highest-leverage anti-slop rule. Most AI design slop is **compositional, not cosmetic** — the model reaches for a centered hero + three equal-weight feature cards for *every* surface, then decorates. Recoloring or restyling that layout never fixes it, because the layout was wrong before a single color was chosen. + +Before you write any colors, type scale, or components, **commit out loud to exactly one surface archetype.** This conditions generation on a high-level plan first, which collapses the entropy of what gets produced — the same reason a chain-of-thought step improves reasoning. + +The seven surfaces: + +1. **Monitor** — the user is watching state change (dashboards, status pages, observability). Density, glanceable hierarchy, no marketing framing. +2. **Operate** — the user is taking action on things (consoles, admin panels, queues, inboxes). Action affordances and selection state dominate. +3. **Compare** — the user is weighing options against each other (pricing, plans, spec tables, search results). Aligned columns, parity of structure, one differentiator emphasized. +4. **Configure** — the user is setting things up (settings, forms, wizards, onboarding). Progressive disclosure, clear save/validation states, low decoration. +5. **Decide / Learn** — the user is being convinced or taught (landing pages, docs, marketing). One idea lands per section; this is the ONLY surface where a hero is usually correct. +6. **Explore** — the user is browsing an open space (galleries, maps, search-and-filter, catalogs). Filters, result grids, and zoom/peek are the composition. +7. **Command / Inspect** — the user is driving by keyboard or drilling into one object (command bars, inspectors, detail panes, property editors). Speed and focus over breadth. + +Rules: + +- State the surface in one line before designing (e.g. "This is a **Monitor** surface, so density and glanceability beat a hero"). +- A dashboard is a Monitor surface, not a Decide surface — do not give it a centered hero and three feature cards. +- If a screen genuinely spans two surfaces, name the **primary** one and treat the other as secondary; do not average them into mush. +- The hero-plus-three-cards composition is correct for **Decide/Learn only**. Reaching for it anywhere else is the #1 tell. + +This one constraint eliminates more generic-looking UI than any aesthetic rule below. + ## Workflow 1. **Understand the brief** @@ -177,7 +202,11 @@ When proceeding with assumptions, label only the important ones. - Read supplied docs, screenshots, repo files, or design assets. - Identify the visual vocabulary before writing code. -3. **Define the design system for this artifact** +3. **Commit to a surface** (see "Surface-First") + - Name the one surface archetype before any visual tokens. + - This conditions the composition; everything below inherits from it. + +4. **Define the design system for this artifact** - colors - type - spacing @@ -187,25 +216,26 @@ When proceeding with assumptions, label only the important ones. - component treatment - interaction rules -4. **Choose the right format** +5. **Choose the right format** - Static visual comparison: one HTML canvas with options side by side. - Interaction/flow: clickable prototype. - Presentation: fixed-size HTML deck with slide navigation. - Component exploration: component lab with variants. - Motion: timeline or state-based animation. -5. **Build the artifact** +6. **Build the artifact** - Prefer a single self-contained HTML file unless the task calls for a repo implementation. - Preserve prior versions for major revisions. - Avoid unnecessary dependencies. -6. **Verify** +7. **Verify** - Confirm files exist. - Run any available syntax/static checks. - If browser tools are available, open the file and check console errors. - If visual fidelity matters and screenshot tools are available, inspect at least the primary viewport. + - Run the slop self-audit (see "Slop Diagnostic") and repair only what it flags. -7. **Report briefly** +8. **Report briefly** - exact file path - what was created - caveats @@ -403,6 +433,35 @@ Avoid common AI design sludge: Minimal is not automatically good. Dense is not automatically cluttered. Choose intentionally. +## Slop Diagnostic: Score Before You Fix + +AI design slop has a tiny, predictable failure distribution — designers asked to label AI UIs collapse the "this is AI" signal down to about ten tells. Before polishing or repairing an artifact, run this as an explicit self-audit and write a short report. **Diagnose first, treat second** — auditing and fixing in one breath fails, because the model's prior outweighs the instruction and it repeats the mistake (recolors when it needed re-layout, polishes type on a composition problem). + +The ten tells (presence of each = one point of slop; lower is better): + +1. **Tech gradient** — blue/violet/indigo glossy gradient on everything. +2. **Generic tech hue** — the default accent is indigo/violet (not chosen for the brand, just the model's favorite). +3. **Feature-tile grid** — icon + heading + sentence × 3, all equal weight, nothing prioritized. +4. **Accent rail** — a colored left strip on cards: decoration pretending to be organization. +5. **Unearned blur** — glassmorphism with no real depth/elevation system behind it. +6. **Monument stat** — oversized numbers filling space that should carry product story. +7. **Icon topper** — a rounded-square icon centered above every heading (Tailwind-template filler). +8. **Center stack** — everything centered because no real composition was committed to. +9. **Default type** — Inter (or system-ui) used by default rather than chosen. +10. **Wrong surface** — the composition doesn't match the surface (e.g. a hero on a Monitor surface). This is the root cause behind most of the others. + +How to run it: + +- Score the artifact out of 10 (10 = maximum slop). State the score and list which tells fired, in one short report. +- Treat the report as **context, not a to-do list** — it tells you *where* to spend repair effort, it does not dictate edits. +- Then repair, matched to the diagnosis: + - tells 3, 8, 10 → **re-layout / re-compose** (revisit the surface choice — do not recolor). + - tells 1, 2, 9 → **recolor / re-typeset** (palette and type are genuinely the problem here). + - tells 4, 5, 6, 7 → **remove the decoration**; replace it with real hierarchy (scale, weight, spacing). +- Re-score after repairing. Do not declare done while compositional tells (3, 8, 10) are still firing — those are causes, the rest are usually symptoms. + +The point of separating diagnosis from treatment: let the audit complain first, then fix only what it complained about, in the register the complaint calls for. + ## Typography Use the existing type system if one exists. diff --git a/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md index bf6f4eafaa3..c20dd7dceb7 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md @@ -16,7 +16,7 @@ Design one-off HTML artifacts (landing, deck, prototype). |---|---| | Source | Bundled (installed by default) | | Path | `skills/creative/claude-design` | -| Version | `1.0.0` | +| Version | `1.1.0` | | Author | BadTechBandit | | License | MIT | | Platforms | linux, macos, windows | @@ -183,6 +183,31 @@ Skip questions when: When proceeding with assumptions, label only the important ones. +## Surface-First: Commit to a Composition Before Touching Tokens + +The single highest-leverage anti-slop rule. Most AI design slop is **compositional, not cosmetic** — the model reaches for a centered hero + three equal-weight feature cards for *every* surface, then decorates. Recoloring or restyling that layout never fixes it, because the layout was wrong before a single color was chosen. + +Before you write any colors, type scale, or components, **commit out loud to exactly one surface archetype.** This conditions generation on a high-level plan first, which collapses the entropy of what gets produced — the same reason a chain-of-thought step improves reasoning. + +The seven surfaces: + +1. **Monitor** — the user is watching state change (dashboards, status pages, observability). Density, glanceable hierarchy, no marketing framing. +2. **Operate** — the user is taking action on things (consoles, admin panels, queues, inboxes). Action affordances and selection state dominate. +3. **Compare** — the user is weighing options against each other (pricing, plans, spec tables, search results). Aligned columns, parity of structure, one differentiator emphasized. +4. **Configure** — the user is setting things up (settings, forms, wizards, onboarding). Progressive disclosure, clear save/validation states, low decoration. +5. **Decide / Learn** — the user is being convinced or taught (landing pages, docs, marketing). One idea lands per section; this is the ONLY surface where a hero is usually correct. +6. **Explore** — the user is browsing an open space (galleries, maps, search-and-filter, catalogs). Filters, result grids, and zoom/peek are the composition. +7. **Command / Inspect** — the user is driving by keyboard or drilling into one object (command bars, inspectors, detail panes, property editors). Speed and focus over breadth. + +Rules: + +- State the surface in one line before designing (e.g. "This is a **Monitor** surface, so density and glanceability beat a hero"). +- A dashboard is a Monitor surface, not a Decide surface — do not give it a centered hero and three feature cards. +- If a screen genuinely spans two surfaces, name the **primary** one and treat the other as secondary; do not average them into mush. +- The hero-plus-three-cards composition is correct for **Decide/Learn only**. Reaching for it anywhere else is the #1 tell. + +This one constraint eliminates more generic-looking UI than any aesthetic rule below. + ## Workflow 1. **Understand the brief** @@ -195,7 +220,11 @@ When proceeding with assumptions, label only the important ones. - Read supplied docs, screenshots, repo files, or design assets. - Identify the visual vocabulary before writing code. -3. **Define the design system for this artifact** +3. **Commit to a surface** (see "Surface-First") + - Name the one surface archetype before any visual tokens. + - This conditions the composition; everything below inherits from it. + +4. **Define the design system for this artifact** - colors - type - spacing @@ -205,25 +234,26 @@ When proceeding with assumptions, label only the important ones. - component treatment - interaction rules -4. **Choose the right format** +5. **Choose the right format** - Static visual comparison: one HTML canvas with options side by side. - Interaction/flow: clickable prototype. - Presentation: fixed-size HTML deck with slide navigation. - Component exploration: component lab with variants. - Motion: timeline or state-based animation. -5. **Build the artifact** +6. **Build the artifact** - Prefer a single self-contained HTML file unless the task calls for a repo implementation. - Preserve prior versions for major revisions. - Avoid unnecessary dependencies. -6. **Verify** +7. **Verify** - Confirm files exist. - Run any available syntax/static checks. - If browser tools are available, open the file and check console errors. - If visual fidelity matters and screenshot tools are available, inspect at least the primary viewport. + - Run the slop self-audit (see "Slop Diagnostic") and repair only what it flags. -7. **Report briefly** +8. **Report briefly** - exact file path - what was created - caveats @@ -421,6 +451,35 @@ Avoid common AI design sludge: Minimal is not automatically good. Dense is not automatically cluttered. Choose intentionally. +## Slop Diagnostic: Score Before You Fix + +AI design slop has a tiny, predictable failure distribution — designers asked to label AI UIs collapse the "this is AI" signal down to about ten tells. Before polishing or repairing an artifact, run this as an explicit self-audit and write a short report. **Diagnose first, treat second** — auditing and fixing in one breath fails, because the model's prior outweighs the instruction and it repeats the mistake (recolors when it needed re-layout, polishes type on a composition problem). + +The ten tells (presence of each = one point of slop; lower is better): + +1. **Tech gradient** — blue/violet/indigo glossy gradient on everything. +2. **Generic tech hue** — the default accent is indigo/violet (not chosen for the brand, just the model's favorite). +3. **Feature-tile grid** — icon + heading + sentence × 3, all equal weight, nothing prioritized. +4. **Accent rail** — a colored left strip on cards: decoration pretending to be organization. +5. **Unearned blur** — glassmorphism with no real depth/elevation system behind it. +6. **Monument stat** — oversized numbers filling space that should carry product story. +7. **Icon topper** — a rounded-square icon centered above every heading (Tailwind-template filler). +8. **Center stack** — everything centered because no real composition was committed to. +9. **Default type** — Inter (or system-ui) used by default rather than chosen. +10. **Wrong surface** — the composition doesn't match the surface (e.g. a hero on a Monitor surface). This is the root cause behind most of the others. + +How to run it: + +- Score the artifact out of 10 (10 = maximum slop). State the score and list which tells fired, in one short report. +- Treat the report as **context, not a to-do list** — it tells you *where* to spend repair effort, it does not dictate edits. +- Then repair, matched to the diagnosis: + - tells 3, 8, 10 → **re-layout / re-compose** (revisit the surface choice — do not recolor). + - tells 1, 2, 9 → **recolor / re-typeset** (palette and type are genuinely the problem here). + - tells 4, 5, 6, 7 → **remove the decoration**; replace it with real hierarchy (scale, weight, spacing). +- Re-score after repairing. Do not declare done while compositional tells (3, 8, 10) are still firing — those are causes, the rest are usually symptoms. + +The point of separating diagnosis from treatment: let the audit complain first, then fix only what it complained about, in the register the complaint calls for. + ## Typography Use the existing type system if one exists.