claude-design

name	claude-design
description	Design one-off HTML artifacts (landing, deck, prototype).
version	1.0.0
author	BadTechBandit
license	MIT
metadata	{"hermes":{"tags":["design","html","prototype","ux","ui","creative","artifact","deck","motion","design-system"],"related_skills":["design-md","popular-web-designs","excalidraw","architecture-diagram"]}}

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 — and only when the answer would meaningfully change the artifact.

Target: 0–2 focused questions. If you can make a reasonable default, make it and label it. Do not ask about things you can decide.

Usually ask for:

• intended output format (if multiple interpretations exist)
• audience (if it changes the artifact substantially)
• source materials available (if they'd save significant rework)
• brand/design system in play (if unspecified and matters)
• number of variations (if the request is ambiguous about scope)

Proceed without asking for:

• responsive behavior — add it unless fixed-size is explicitly requested
• viewport meta tag — always include it
• localStorage persistence in decks — always add it
• prefers-reduced-motion handling — always include for non-trivial animation
• semantic HTML structure — always use it
• real focus and hover states — always include
• file naming — use a descriptive name derived from the brief
• minor structural elements (skip links, <meta charset>, <title>) — always include
• placeholder text marking — always use <!-- TODO: placeholder --> for draft content
• versioning scheme — auto-create Name v2.html etc. on revisions without asking

When proceeding with assumptions, label only the ones that could meaningfully surprise the user.

Skip questions entirely when:

• the user gave enough direction to make a complete artifact
• this is a small tweak or continuation
• the missing detail has an obvious default that costs nothing to undo

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. Define the design system for this artifact

   • colors
   • type
   • spacing
   • radii
   • shadows or elevation
   • motion posture
   • component treatment
   • interaction rules

4. 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

   • If no explicit path is given, write to the current working directory using a descriptive name.
   • Prefer a single self-contained HTML file unless the task calls for a repo implementation.
   • Auto-create Name v2.html, Name v3.html on significant revisions — do not ask permission.
   • Avoid unnecessary dependencies.

6. Verify — run the verification sequence in the Verification section before responding. Do not skip and do not ask the user to run it.

7. Report briefly — exact file path, what it contains, verification status, next suggested action.

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:

• auto-create Name v2.html, Name v3.html, etc. — do not ask permission for this, just do it and report the path
• 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

Verification

Run the full sequence below before responding. Do not skip steps. Do not ask the user to run them.

Step 1 — Prerequisite check

# Detect python3 availability
command -v python3 >/dev/null 2>&1 && echo "python3: OK" || echo "python3: unavailable"

# Detect browser-open command
if command -v open >/dev/null 2>&1; then
  echo "browser-open: open (macOS)"
elif command -v xdg-open >/dev/null 2>&1; then
  echo "browser-open: xdg-open (Linux)"
else
  echo "browser-open: unavailable (headless)"
fi

Run this once per session or when the environment is unknown. Record the results — they determine which checks below are available.

Step 2 — File existence and content

FILE="/absolute/path/to/File.html"
test -s "$FILE" && echo "OK: $FILE exists and is non-zero" || echo "FAIL: $FILE is missing or zero bytes"

If FAIL: retry the write operation once using the Write tool. If the second write also fails, output the full HTML content inline in the response so the user can save it manually, and state clearly that the file was not written to disk.

Step 3 — HTML parse

If python3 is available:

python3 - <<'EOF' "/absolute/path/to/File.html"
import html.parser, sys
class P(html.parser.HTMLParser):
    pass
try:
    P().feed(open(sys.argv[1]).read())
    print("parse OK")
except Exception as e:
    print(f"parse FAIL: {e}")
EOF

If parse FAIL: report the error verbatim in the response (includes line/column when present). Do not claim the artifact is valid.

If python3 is unavailable: skip Step 3 and note "HTML parse skipped — python3 not found" in the verification status.

Step 4 — Open in browser

macOS:

open "/absolute/path/to/File.html"

Linux:

xdg-open "/absolute/path/to/File.html"

Headless/unavailable: skip and report "Browser open unavailable in this environment — open manually to inspect."

If a screenshot tool is available, capture the primary viewport immediately after opening and inspect for layout breaks or console errors.

Verification status to report

Always include one of these in the final response:

• Verified: file exists (non-zero), HTML parses clean, opened in browser.
• Verified: file exists (non-zero), HTML parses clean. Browser open unavailable — open manually.
• Verified: file exists (non-zero). HTML parse skipped (python3 not found). Browser open unavailable.
• FAIL: file not written — content provided inline above.

Never say "done" if the file was not actually written.

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 to an exact version. Use the unpkg path pattern:

<script crossorigin src="https://unpkg.com/react@18.3.1/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/@babel/standalone@7.24.7/babel.min.js"></script>

Additional rules:

• never use react@18 (unpinned) — breaks when React publishes a major
• avoid type="module" in Babel-transpiled scripts
• avoid multiple global objects named styles — use specific names (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 (include all automatically — no need to ask):

• 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

For obvious structural additions (footer placeholder, <meta> tags, skip link, <title>, empty state): add them automatically and note them in the report. Do not ask.

For content additions that change scope, strategy, or claims: ask before adding them.

When copy is necessary but not final, mark it as draft with <!-- TODO: 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.

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. Always include the media query — do not ask.

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.

Final Response Format

Keep final responses short.

Include:

• artifact path
• what it contains
• verification status (use the exact status strings from the Verification section)
• next suggested action, if useful

Example:

Created: /Users/kosta/Design/Prototype.html
It includes 3 layout variants, a Tweaks panel for density/theme, and responsive behavior.
Verified: file exists (non-zero), HTML parses clean, opened in browser.
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:

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.
• Do not ask for permission to version files, add <meta> tags, or include prefers-reduced-motion — these are always right.
• Do not use open on Linux or in headless environments — use xdg-open or skip and report.
• Do not use unpinned CDN URLs like react@18 — always use an exact semver like react@18.3.1.
• Do not skip the file-existence check and assume a tool write succeeded — verify with test -s.