mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-06-30 11:52:04 +00:00
feat(claude-design): add surface-first conditioning + slop diagnostic (#55399)
Port the two genuinely-novel ideas from Command Code's /design skill into our existing claude-design skill (skill-only, zero model-tool footprint): - Surface-First: commit to one of 7 surface archetypes (Monitor/Operate/ Compare/Configure/Decide/Explore/Command) before any visual tokens. Most AI design slop is compositional, not cosmetic — conditioning generation on a surface choice collapses entropy the way a CoT step does. Workflow step 3. - Slop Diagnostic: the ~10 tells that account for ~90% of the 'this is AI' signal, as a score-out-of-10 self-audit. Diagnose-then-treat: the report is context not a to-do list; repair only what fired, matched to the tell (re-layout vs recolor vs de-decorate). Workflow step 7 (Verify). Did NOT clone /design's 16-mode CLI, proprietary reference corpus, or make it a core tool. Docs page regenerated via generate-skill-docs.py.
This commit is contained in:
Teknium
GitHub
parent
5a3d7fb99d
commit
d4c14011eb
2 changed files with 130 additions and 12 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue