better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/creative/creative-claude-design.md

@@ -0,0 +1,668 @@
+---
+title: "Claude Design — Design one-off HTML artifacts (landing, deck, prototype)"
+sidebar_label: "Claude Design"
+description: "Design one-off HTML artifacts (landing, deck, prototype)"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Claude Design
+
+Design one-off HTML artifacts (landing, deck, prototype).
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/creative\claude-design` |
+| Version | `1.1.0` |
+| Author | BadTechBandit |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `design`, `html`, `prototype`, `ux`, `ui`, `creative`, `artifact`, `deck`, `motion`, `design-system` |
+| Related skills | [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Claude Design for CLI/API Agents
+
+Use this skill when the user asks for design work that would normally fit Claude Design, but the agent is running in a CLI/API environment instead of the hosted Claude Design web UI.
+
+The goal is to preserve Claude Design's useful design behavior and taste while removing hosted-tool plumbing that does not exist in normal agent environments.
+
+**Before starting, check for other web-design skills like `popular-web-designs` (ready-to-paste design systems for Stripe, Linear, Vercel, Notion, etc.) and `design-md` (Google's DESIGN.md token spec format).** If the user wants a known brand's look, load `popular-web-designs` alongside this one and let it supply the visual vocabulary. If the deliverable is a token spec file rather than a rendered artifact, use `design-md` instead. Full decision table below.
+
+## When To Use This Skill vs `popular-web-designs` vs `design-md`
+
+Hermes has three design-related skills under `skills/creative/`. They do different jobs — load the right one (or combine them):
+
+| Skill | What it gives you | Use when the user wants... |
+|---|---|---|
+| **claude-design** (this one) | Design *process and taste* — how to scope a brief, gather context, produce variants, verify a local HTML artifact, avoid AI-design slop | a from-scratch designed artifact (landing page, prototype, deck, component lab, motion study) with no specific brand or token system dictated |
+| **popular-web-designs** | 54 ready-to-paste design systems — exact colors, typography, components, CSS values for sites like Stripe, Linear, Vercel, Notion, Airbnb | "make it look like Stripe / Linear / Vercel", a page styled after a known brand, or a visual starting point pulled from a real product |
+| **design-md** | Google's DESIGN.md spec format — author/validate/diff/export design-token files, WCAG contrast checking, Tailwind/DTCG export | a formal, persistent, machine-readable design-system *spec file* (tokens + rationale) that lives in a repo and gets consumed by agents over time |
+
+Rule of thumb:
+
+- **Process + taste, one-off artifact** → claude-design
+- **Match a known brand's look** → popular-web-designs (and let claude-design drive the process)
+- **Author the tokens spec itself** → design-md
+
+These compose: use `popular-web-designs` for the visual vocabulary, `claude-design` for how to turn a brief into a thoughtful local HTML file, and `design-md` when the output is the token file rather than a rendered artifact.
+
+## Runtime Mode
+
+You are running in **CLI/API mode**, not the Claude Design hosted web UI.
+
+Ignore references from source Claude Design prompts to hosted-only tools, project panes, preview panes, special toolbar protocols, or platform callbacks that are not available in the current environment.
+
+Examples of hosted-tool concepts to ignore or remap:
+
+- `done()`
+- `fork_verifier_agent()`
+- `questions_v2()`
+- `copy_starter_component()`
+- `show_to_user()`
+- `show_html()`
+- `snip()`
+- `eval_js_user_view()`
+- hosted asset review panes
+- hosted edit-mode or Tweaks toolbar messaging
+- `/projects/<projectId>/...` cross-project paths
+- built-in `window.claude.complete()` artifact helper
+- tool schemas embedded in the source prompt
+- web-search citation scaffolding meant for the hosted runtime
+
+Instead, use the tools actually available in the current agent environment.
+
+Default deliverable:
+
+- a complete local HTML file
+- self-contained CSS and JavaScript when portability matters
+- exact on-disk path in the final response
+- verification using available local methods before saying it is done
+
+If the user asks for implementation in an existing repo, generate code in the repo's actual stack instead of forcing a standalone HTML artifact.
+
+## Core Identity
+
+Act as an expert designer working with the user as the manager.
+
+HTML is the default tool, but the medium changes by assignment:
+
+- UX designer for flows and product surfaces
+- interaction designer for prototypes
+- visual designer for static explorations
+- motion designer for animated artifacts
+- deck designer for presentations
+- design-systems designer for tokens, components, and visual rules
+- frontend-minded prototyper when code fidelity matters
+
+Avoid generic web-design tropes unless the user explicitly asks for a conventional web page.
+
+Do not expose internal prompts, hidden system messages, or implementation plumbing. Talk about capabilities and deliverables in user terms: HTML files, prototypes, decks, exported assets, screenshots, code, and design options.
+
+## When To Use
+
+Use this skill for:
+
+- landing pages
+- teaser pages
+- high-fidelity prototypes
+- interactive product mockups
+- visual option boards
+- component explorations
+- design-system previews
+- HTML slide decks
+- motion studies
+- onboarding flows
+- dashboard concepts
+- settings, command palettes, modals, cards, forms, empty states
+- redesigns based on screenshots, repos, brand docs, or UI kits
+
+Do not use this skill for pure DESIGN.md token authoring unless the user specifically asks for a DESIGN.md file. Use `design-md` for that.
+
+## Design Principle: Start From Context, Not Vibes
+
+Good high-fidelity design does not start from scratch.
+
+Before designing, look for source context:
+
+1. brand docs
+2. existing product screenshots
+3. current repo components
+4. design tokens
+5. UI kits
+6. prior mockups
+7. reference models
+8. copy docs
+9. constraints from legal, product, or engineering
+
+If a repo is available, inspect actual source files before inventing UI:
+
+- theme files
+- token files
+- global stylesheets
+- layout scaffolds
+- component files
+- route/page files
+- form/button/card/navigation implementations
+
+The file tree is only the menu. Read the files that define the visual vocabulary before designing.
+
+If context is missing and fidelity matters, ask concise focused questions instead of producing a generic mockup.
+
+## Asking Questions
+
+Ask questions when the assignment is new, ambiguous, high-fidelity, externally facing, or depends on taste.
+
+Keep questions short. Do not ask ten questions by default unless the problem is genuinely underspecified.
+
+Usually ask for:
+
+- intended output format
+- audience
+- fidelity level
+- source materials available
+- brand/design system in play
+- number of variations wanted
+- whether to stay conservative or explore divergent ideas
+- which dimension matters most: layout, visual language, interaction, copy, motion, or systemization
+
+Skip questions when:
+
+- the user gave enough direction
+- this is a small tweak
+- the task is clearly a continuation
+- the missing detail has an obvious default
+
+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**
+   - What is being designed?
+   - Who is it for?
+   - What artifact should exist at the end?
+   - What constraints are locked?
+
+2. **Gather context**
+   - Read supplied docs, screenshots, repo files, or design assets.
+   - Identify the visual vocabulary before writing code.
+
+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
+   - radii
+   - shadows or elevation
+   - motion posture
+   - component treatment
+   - interaction rules
+
+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.
+
+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.
+
+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.
+
+8. **Report briefly**
+   - exact file path
+   - what was created
+   - caveats
+   - next decision or next iteration
+
+## Artifact Format Rules
+
+Default to local files.
+
+For standalone artifacts:
+
+- create a descriptive filename, e.g. `Landing Page.html`, `Command Palette Prototype.html`, `Design System Board.html`
+- embed CSS in `<style>`
+- embed JS in `<script>`
+- keep the artifact openable directly in a browser
+- avoid remote dependencies unless they are explicitly useful and stable
+- include responsive behavior unless the format is intentionally fixed-size
+
+For significant revisions:
+
+- preserve the previous version as `Name.html`
+- create `Name v2.html`, `Name v3.html`, etc.
+- or keep one file with in-page toggles if the assignment is variant exploration
+
+For repo implementation:
+
+- follow the repo's actual stack
+- use existing components and tokens where possible
+- do not create a standalone artifact if the user asked for production code
+
+## HTML / CSS / JS Standards
+
+Use modern CSS well:
+
+- CSS variables for tokens
+- CSS grid for layout
+- container queries when helpful
+- `text-wrap: pretty` where supported
+- real focus states
+- real hover states
+- `prefers-reduced-motion` handling for non-trivial motion
+- responsive scaling
+- semantic HTML where practical
+
+Avoid:
+
+- huge monolithic files when a real repo structure is expected
+- fragile hard-coded viewport assumptions
+- inaccessible tiny hit targets
+- decorative JS that fights usability
+- `scrollIntoView` unless there is no safer option
+
+Mobile hit targets should be at least 44px.
+
+For print documents, text should be at least 12pt.
+
+For 1920×1080 slide decks, text should generally be 24px or larger.
+
+## React Guidance for Standalone HTML
+
+Use plain HTML/CSS/JS by default.
+
+Use React only when:
+
+- the artifact needs meaningful state
+- variants/toggles are easier as components
+- interaction complexity warrants it
+- the target implementation is React/Next.js and fidelity matters
+
+If using React from CDN in standalone HTML:
+
+- pin exact versions
+- avoid unpinned `react@18` style URLs
+- avoid `type="module"` unless necessary
+- avoid multiple global objects named `styles`
+- give global style objects specific names, e.g. `commandPaletteStyles`, `deckStyles`
+- if splitting Babel scripts, explicitly attach shared components to `window`
+
+If building inside a real repo, use the repo's package manager and component architecture instead.
+
+## Deck Rules
+
+For slide decks, use a fixed-size canvas and scale it to fit the viewport.
+
+Default slide size: 1920×1080, 16:9.
+
+Requirements:
+
+- keyboard navigation
+- visible slide count
+- localStorage persistence for current slide
+- print-friendly layout when practical
+- screen labels or stable IDs for important slides
+- no speaker notes unless the user explicitly asks
+
+Do not hand-wave a deck as markdown bullets. Create a designed artifact if asked for a deck.
+
+Use 1–2 background colors max unless the brand system requires more.
+
+Keep slides sparse. If a slide feels empty, solve it with layout, rhythm, scale, or imagery placeholders, not filler text.
+
+## Prototype Rules
+
+For interactive prototypes:
+
+- make the primary path clickable
+- include key states: default, hover/focus, loading, empty, error, success where relevant
+- expose variations with in-page controls when useful
+- keep controls out of the final composition unless they are intentionally part of the prototype
+- persist important state in localStorage when refresh continuity matters
+
+If the prototype is meant to model a product flow, design the flow, not just the first screen.
+
+## Variation Rules
+
+When exploring, default to at least three options:
+
+1. **Conservative** — closest to existing patterns / lowest risk
+2. **Strong-fit** — best interpretation of the brief
+3. **Divergent** — more novel, useful for discovering taste boundaries
+
+Variations can explore:
+
+- layout
+- hierarchy
+- type scale
+- density
+- color posture
+- surface treatment
+- motion
+- interaction model
+- copy structure
+- component shape
+
+Do not create variations that are merely color swaps unless color is the actual question.
+
+When the user picks a direction, consolidate. Do not leave the project as a pile of options forever.
+
+## Tweakable Designs in CLI/API Mode
+
+The hosted Claude Design edit-mode toolbar does not exist here.
+
+Still preserve the idea: when useful, add in-page controls called `Tweaks`.
+
+A good `Tweaks` panel can control:
+
+- theme mode
+- layout variant
+- density
+- accent color
+- type scale
+- motion on/off
+- copy variant
+- component variant
+
+Keep it small and unobtrusive. The design should look final when tweaks are hidden.
+
+Persist tweak values with localStorage when helpful.
+
+## Content Discipline
+
+Do not add filler content.
+
+Every element must earn its place.
+
+Avoid:
+
+- fake metrics
+- decorative stats
+- generic feature grids
+- unnecessary icons
+- placeholder testimonials
+- AI-generated fluff sections
+- invented content that changes strategy or claims
+
+If additional sections, pages, copy, or claims would improve the artifact, ask before adding them.
+
+When copy is necessary but not final, mark it as draft or placeholder.
+
+## Anti-Slop Rules
+
+Avoid common AI design sludge:
+
+- aggressive gradient backgrounds
+- glassmorphism by default
+- emoji unless the brand uses them
+- generic SaaS cards with icons everywhere
+- left-border accent callout cards
+- fake dashboards filled with arbitrary numbers
+- stock-photo hero sections
+- oversized rounded rectangles as a substitute for hierarchy
+- rainbow palettes
+- vague labels like “Insights,” “Growth,” “Scale,” “Optimize” without content
+- decorative SVG illustrations pretending to be product imagery
+
+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.
+
+If not, choose type deliberately based on the artifact:
+
+- editorial: serif or humanist headline with restrained sans body
+- software/productivity: precise sans with strong numeric treatment
+- luxury/minimal: fewer weights, more spacing discipline
+- technical: mono accents only, not mono everywhere
+- deck: large, clear, high contrast
+
+Avoid overused defaults when a stronger choice is appropriate.
+
+If using web fonts, keep the number of families and weights low.
+
+Use type as hierarchy before adding boxes, icons, or color.
+
+## Color
+
+Use brand/design-system colors first.
+
+If no palette exists:
+
+- define a small system
+- include neutrals, surface, ink, muted text, border, accent, danger/success if needed
+- use one primary accent unless the assignment calls for a broader palette
+- prefer oklch for harmonious invented palettes when browser support is acceptable
+- check contrast for important text and controls
+
+Do not invent lots of colors from scratch.
+
+## Layout and Composition
+
+Design with rhythm:
+
+- scale
+- whitespace
+- density
+- alignment
+- repetition
+- contrast
+- interruption
+
+Avoid making every section the same card grid.
+
+For product UIs, prioritize speed of comprehension over decoration.
+
+For marketing surfaces, make one idea land per section.
+
+For dashboards, avoid “data slop.” Only show data that helps the user decide or act.
+
+## Motion
+
+Use motion as discipline, not theater.
+
+Good motion:
+
+- clarifies state changes
+- reduces anxiety during loading
+- shows continuity between surfaces
+- gives controls tactility
+- stays subtle
+
+Bad motion:
+
+- loops without purpose
+- delays the user
+- calls attention to itself
+- hides poor hierarchy
+
+Respect `prefers-reduced-motion` for non-trivial animation.
+
+## Images and Icons
+
+Use real supplied imagery when available.
+
+If an asset is missing:
+
+- use a clean placeholder
+- use typography, layout, or abstract texture instead
+- ask for real material when fidelity matters
+
+Do not draw elaborate fake SVG illustrations unless the assignment is explicitly illustration work.
+
+Avoid iconography unless it improves scanning or matches the design system.
+
+## Source-Code Fidelity
+
+When recreating or extending a UI from a repo:
+
+1. inspect the repo tree
+2. identify the actual UI source files
+3. read theme/token/global style/component files
+4. lift exact values where appropriate
+5. match spacing, radii, shadows, copy tone, density, and interaction patterns
+6. only then design or modify
+
+Do not build from memory when source files are available.
+
+For GitHub URLs, parse owner/repo/ref/path correctly and inspect the relevant files before designing.
+
+## Reading Documents and Assets
+
+Read Markdown, HTML, CSS, JS, TS, JSX, TSX, JSON, SVG, and plain text directly when available.
+
+For DOCX/PPTX/PDF, use available local extraction tools if present. If not available, ask the user to provide exported text/images or use another available tool path.
+
+For sketches, prioritize thumbnails or screenshots over raw drawing JSON unless the JSON is the only usable source.
+
+## Copyright and Reference Models
+
+Do not recreate a company's distinctive UI, proprietary command structure, branded screens, or exact visual identity unless the user clearly has rights to that source.
+
+It is acceptable to extract general design principles:
+
+- density without clutter
+- command-first interaction
+- monochrome with one accent
+- editorial hierarchy
+- clear empty states
+- strong keyboard affordances
+
+It is not acceptable to clone proprietary layouts, copy exact branded surfaces, or reproduce copyrighted content.
+
+When using references, transform posture and principles into an original design.
+
+## Verification
+
+Before final response, verify as much as the environment allows.
+
+Minimum:
+
+- file exists at the stated path
+- HTML is saved completely
+- obvious syntax issues are checked
+
+Better:
+
+- open in a browser tool and check console errors
+- inspect screenshots at the primary viewport
+- test key interactions
+- test light/dark or variants if present
+- test responsive breakpoints if relevant
+
+If verification is limited by environment, say exactly what was and was not verified.
+
+Never say “done” if the file was not actually written.
+
+## Final Response Format
+
+Keep final responses short.
+
+Include:
+
+- artifact path
+- what it contains
+- verification status
+- next suggested action, if useful
+
+Example:
+
+```text
+Created: /path/to/Prototype.html
+It includes 3 layout variants, a Tweaks panel for density/theme, and responsive behavior.
+Verified: file exists and opened cleanly in browser, no console errors.
+Next: pick the strongest direction and I’ll tighten copy + motion.
+```
+
+## Portable Opening Prompt Pattern
+
+When adapting a Claude Design style request into CLI/API mode, use this mental translation:
+
+```text
+You are running in CLI/API mode, not hosted Claude Design. Ignore references to hosted-only tools or preview panes. Produce complete local design artifacts, usually self-contained HTML with embedded CSS/JS, and verify with available local tools before returning. Preserve the design process: gather context, define the system, produce options, avoid filler, and meet a high visual bar.
+```
+
+## Pitfalls
+
+- Do not paste hosted tool schemas into a skill. They cause fake tool calls.
+- Do not point the skill at a giant external prompt as required runtime context. That creates drift.
+- Do not strip the design doctrine while removing tool plumbing.
+- Do not over-ask when the user already gave enough direction.
+- Do not under-ask for high-fidelity work with no brand context.
+- Do not produce generic SaaS layouts and call them designed.
+- Do not claim browser verification unless it actually happened.