Claude Design Skill for Hermes Agent: One-Off HTML Artifacts in CLI/API Mode

This skill is for when an agent running in a CLI or API environment is asked to do design work that would normally be handled by Claude Design in the hosted web UI. It keeps Claude Design's design sense and behavior but strips out the hosted-tool plumbing that doesn't exist in a standard agent setup.

Before you start, check whether the user wants a specific brand's look. If they do, load the popular-web-designs skill alongside this one to get ready-to-paste design systems for Stripe, Linear, Vercel, Notion, and others. If the deliverable is a token spec file instead of a rendered artifact, use the design-md skill instead. The full decision table is below.

When To Use This Skill vs popular-web-designs vs design-md

Hermes ships three design skills under skills/creative/. Each targets a different outcome. Picking the wrong one wastes time; combining them is often the right move.

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 operating in CLI/API mode, not the Claude Design hosted web UI.

Ignore any references in source Claude Design prompts to hosted-only tools, project panes, preview panes, special toolbar protocols, or platform callbacks that are not available in your 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//... 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

This mode treats the model as an expert designer and you as the manager. You describe what you need, and it produces design artifacts.

HTML is the default output format, but the medium shifts depending on the 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

Unless you explicitly ask for a conventional web page, the model avoids generic web-design tropes. It will not show you internal prompts, hidden system messages, or implementation plumbing. Instead, it talks about capabilities and deliverables in terms you would use with a human designer: HTML files, prototypes, decks, exported assets, screenshots, code, and design options.

Reach for this mode when you need a design artifact fast and want to iterate with the model as a collaborator rather than a code generator. It pairs well with tasks that benefit from visual thinking, like laying out a dashboard, mocking up a user flow, or building a component library. The caveat is that the model's design sense is based on common patterns, so if you have strong brand guidelines or unconventional requirements, you will need to be explicit about them.

When To Use

Reach for this skill when you need a browser-rendered, interactive version of a UI concept. It is a good fit 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, and dashboard concepts. It also handles common UI patterns like settings panels, command palettes, modals, cards, forms, and empty states. If you are working from existing material, you can feed it screenshots, a repository, brand documentation, or a UI kit to produce a redesign.

Do not use this skill when your goal is to produce a DESIGN.md token file. That is a separate workflow handled by the design-md skill. If you need a written design specification rather than a live preview, use design-md instead.

Design Principle: Start From Context, Not Vibes

Effective high-fidelity design builds on existing foundations rather than starting from a blank canvas.

Before you begin designing, gather source context from:

1. brand documentation
2. screenshots of the current product
3. components already in the repository
4. design tokens (colors, spacing, typography)
5. UI kits the team uses
6. earlier mockups or wireframes
7. reference models or pattern libraries
8. copy docs (actual text that will appear)
9. constraints from legal, product, or engineering teams

When a repository is available, examine the actual source files before inventing new UI. Look at:

• theme files
• token files
• global stylesheets
• layout scaffolds
• component files
• route or page files
• implementations of forms, buttons, cards, and navigation

The file tree shows you what exists, but you must read the files themselves to understand the visual vocabulary. That is where the real constraints live.

If context is missing and you need high fidelity, ask concise, focused questions rather than producing a generic mockup. A few targeted questions will get you closer to the right design than guessing.

When to reach for this: Any time you are designing for an existing product or codebase. Skip it only for greenfield projects with no prior work.

What it pairs with: Component audits, design system documentation, and developer handoff. The context you gather here feeds directly into those later steps.

Caveats in practice: Gathering context takes time. Resist the urge to skip it when deadlines are tight. A design that ignores existing tokens or components will create rework for engineers and inconsistency for users. Also, context can be stale. Verify that the screenshots or repo branch you are using reflect the current state.

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

This is the single most effective rule for avoiding generic AI-generated UI. The problem is almost never cosmetic. When a model produces slop, it is because it defaults to a centered hero section followed by three equal-weight feature cards, regardless of what the screen is for. Changing colors or fonts on that layout does not fix it. The layout was wrong before a single pixel was chosen.

Before you write any CSS variables, type scale, or component code, state out loud which surface archetype this screen belongs to. Naming the archetype forces a high-level plan first, which dramatically reduces the entropy of what gets generated. It works for the same reason chain-of-thought prompting improves reasoning: you commit to a structure before filling in details.

There are seven surfaces:

1. Monitor, the user watches state change. Think dashboards, status pages, observability views. Density and glanceable hierarchy matter. Marketing framing does not belong here.
2. Operate, the user takes action on things. Consoles, admin panels, queues, inboxes. Action affordances and selection state dominate the layout.
3. Compare, the user weighs options against each other. Pricing tables, plan comparisons, spec sheets, search results. Use aligned columns, keep structure parallel, and emphasize one differentiator.
4. Configure, the user sets things up. Settings pages, forms, wizards, onboarding flows. Use progressive disclosure, show clear save and validation states, and keep decoration low.
5. Decide / Learn, the user is being convinced or taught. Landing pages, documentation, marketing sites. This is the only surface where a hero section is usually correct. One idea per section.
6. Explore, the user browses an open space. Galleries, maps, search-and-filter views, catalogs. Filters, result grids, and zoom or peek interactions define the composition.
7. Command / Inspect, the user drives by keyboard or drills into one object. Command bars, inspectors, detail panes, property editors. Speed and focus matter more than breadth.

Apply these rules:

• State the surface in one line before you start designing. For example: "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 serves two surfaces, name the primary one and treat the other as secondary. Do not average them into something that serves neither well.
• The hero-plus-three-cards composition is correct for Decide/Learn only. Reaching for it anywhere else is the number one sign of generic AI output.

This single constraint eliminates more generic-looking UI than any aesthetic rule that follows.

Workflow

1. Understand the brief
   Clarify the design problem before touching a tool. Ask: what is being designed, who is it for, what artifact should exist at the end, and what constraints are locked. This prevents wasted work on the wrong thing.

2. Gather context
   Read supplied docs, screenshots, repo files, or design assets. Identify the visual vocabulary before writing code. Skipping this step often leads to mismatched aesthetics that require rework.

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. If you skip this, your layout will lack a coherent foundation.

4. Define the design system for this artifact
   Establish colors, type, spacing, radii, shadows or elevation, motion posture, component treatment, and interaction rules. This is your local design system, not a global one. It keeps the artifact internally consistent without over-engineering.

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.
     Pick the format that matches the deliverable. A static comparison is fast; a prototype is better for testing flows.

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. This keeps the artifact portable and easy to review.

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. Do not fix things the audit does not mention.

8. Report briefly
   State the exact file path, what was created, caveats, and the next decision or next iteration. This keeps the handoff clean and the next step obvious.

Artifact Format Rules

Start with local files. When you build a standalone artifact, give it a clear filename that describes its purpose, like Landing Page.html, Command Palette Prototype.html, or Design System Board.html. Put CSS inside <style> tags and JavaScript inside <script> tags so the file works when opened directly in a browser. Avoid pulling in remote libraries unless they are genuinely useful and have a stable CDN. Include responsive styling unless the design intentionally targets a fixed viewport.

When you make a major update to an artifact, keep the old version around. You can save it as Name.html and create Name v2.html, Name v3.html, and so on. If the task is exploring multiple variations, you might keep everything in one file with in-page toggles instead.

If the user asks for production code that goes into a repository, do not produce a standalone artifact. Follow the repo's actual stack, reuse existing components and design tokens, and write code that fits into the project's structure.

HTML / CSS / JS Standards

Reach for modern CSS features to keep stylesheets expressive and maintainable. CSS custom properties (variables) let you define a design token system once and reuse it everywhere. CSS Grid handles two-dimensional layout cleanly, and container queries let components adapt to their own available space rather than the viewport alone. Where browser support allows, text-wrap: pretty prevents orphaned words in headings and paragraphs.

Interactive elements need real focus and hover states. These are not decorative; they are the primary way users know what is clickable and where they are on the page. For any non-trivial animation or transition, respect prefers-reduced-motion so users with vestibular disorders are not disoriented. Responsive scaling means your layout works across phone, tablet, and desktop without hard-coded breakpoints that guess at device widths. Semantic HTML (landmarks, headings, lists, buttons) is the foundation of accessibility and should be the default, not an afterthought.

Avoid patterns that make a codebase or experience brittle. A single monolithic CSS file works for a prototype but not for a project that expects a real repo structure. Hard-coded viewport assumptions (e.g., "this element is always 400 px wide") break on the next device size. Hit targets smaller than 44 px on mobile are inaccessible to many users. JavaScript that fights the browser's built-in behaviour (e.g., reimplementing scrolling, overriding native form controls) usually introduces more bugs than it solves. scrollIntoView can disorient users and should only be used when there is no safer alternative.

Concrete size guidelines: mobile touch targets must be at least 44 px. For print documents, body text should be at least 12 pt. For slide decks targeting 1920×1080, text should generally be 24 px or larger.

React Guidance for Standalone HTML

Start with plain HTML, CSS, and JavaScript. Only reach for React when the artifact demands it: meaningful state management, variants or toggles that are cleaner as components, interaction complexity that justifies the overhead, or when the target implementation is React or Next.js and you need high fidelity.

If you do use React from a CDN in a standalone HTML file, follow these rules:

• Pin exact versions in the CDN URL. Avoid unpinned references like react@18 that can silently break your artifact when a new patch ships.
• Do not use type="module" unless you have a specific reason. It changes how scripts are loaded and can cause ordering issues.
• Avoid creating multiple global objects named styles. Name each one uniquely, for example commandPaletteStyles or deckStyles, to prevent collisions.
• If you split your logic across multiple Babel scripts, explicitly attach any shared components to the window object so they are accessible across scripts.

When you are working inside a real repository, skip the CDN approach entirely. Use the repo's package manager and component architecture instead.

Deck Rules

When building a slide deck, work on a fixed-size canvas and let the browser scale it to fit the viewport. The default slide dimensions are 1920×1080 (16:9).

A deck must include:

• Keyboard navigation (arrow keys or similar)
• A visible slide counter so the audience knows where they are
• localStorage persistence for the current slide (so refreshing returns to the same spot)
• A print-friendly layout when practical
• Screen labels or stable IDs for important slides (useful for linking or analytics)
• No speaker notes unless the user explicitly asks for them

If someone asks for a deck, do not hand-wave it as a list of markdown bullets. Create a designed artifact.

Stick to one or two background colors 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

When building an interactive prototype, focus on making the primary user path clickable so the flow can be tested end-to-end. Include key states for each component: default, hover/focus, loading, empty, error, and success where applicable. This helps stakeholders and developers understand how the interface behaves under real conditions.

Use in-page controls to expose variations (e.g., toggling between light and dark mode, switching data sets) without cluttering the final design. Keep these controls out of the final composition unless they are intentionally part of the prototype's functionality.

For prototypes that need to survive page refreshes during testing, persist important state in localStorage. This is especially useful when demonstrating multi-step flows or data entry scenarios.

If the prototype models a product flow, design the entire flow, not just the first screen. A single polished screen can mislead reviewers into thinking the rest of the experience is equally polished, when it may not exist yet.

Variation Rules

When you start exploring design directions, default to at least three options:

1. Conservative, stays closest to existing patterns and carries the lowest risk.
2. Strong-fit, the version that best interprets the brief.
3. Divergent, a more novel take that helps you discover where the client's taste boundaries actually lie.

Variations can explore any of these dimensions:

• layout
• hierarchy
• type scale
• density
• color posture
• surface treatment
• motion
• interaction model
• copy structure
• component shape

A practical caveat: don't create variations that are merely color swaps unless color is the specific question you're answering. That kind of variation wastes time and clutters the review.

Once the user picks a direction, consolidate. Don't leave the project as a pile of options forever. Pick one and move forward.

Tweakable Designs in CLI/API Mode

The interactive edit-mode toolbar that appears in the hosted Claude Design interface is not available when you work through the CLI or API. You need another way to adjust a design without editing source files directly.

The recommended pattern is to add a small, in-page control panel called Tweaks. This gives you a lightweight way to experiment with variations during development or when generating multiple outputs from a single prompt.

A well-designed Tweaks panel typically exposes options like:

• Theme mode (light / dark)
• Layout variant (e.g., sidebar vs. top nav)
• Density (compact / comfortable)
• Accent color
• Type scale
• Motion on/off
• Copy variant (different text versions)
• Component variant (e.g., primary vs. secondary button style)

Keep the panel small and unobtrusive. When the tweaks are hidden, the design should look like a finished product, not a workbench. This means the default state of every toggle should match the final intended look.

If it makes sense for your workflow, persist the current tweak values in localStorage so they survive a page refresh. This is especially useful when you are iterating on a design across multiple API calls or CLI runs.

When you would reach for this: You are generating a UI component or page via the API and want to quickly compare a few visual options without rebuilding the prompt each time. Or you are building a design system starter that ships with a demo page where visitors can toggle settings.

What typically goes wrong: The panel grows too large and distracts from the actual design. Keep the list short. If you find yourself adding more than eight controls, consider splitting the design into separate prompts instead.

Content Discipline

Do not pad the artifact with filler. Every element should justify its existence.

Avoid these common traps:

• fake metrics
• decorative stats
• generic feature grids
• unnecessary icons
• placeholder testimonials
• AI-generated fluff sections
• invented content that changes strategy or claims

If you believe the artifact would benefit from additional sections, pages, copy, or claims, ask before adding them. Do not assume.

When copy is needed but not yet final, mark it clearly as draft or placeholder. This keeps expectations honest and avoids shipping unfinished claims.

Anti-Slop Rules

Avoid the patterns that make AI-generated interfaces feel hollow:

• Aggressive gradient backgrounds that fight the content.
• Glassmorphism as a default effect rather than a deliberate choice.
• Emoji in UI copy unless the brand already uses them in its voice.
• Generic SaaS cards with icons scattered everywhere for no reason.
• Left-border accent callout cards (the tired "tip box" look).
• Fake dashboards populated with arbitrary numbers that mean nothing.
• Stock-photo hero sections that communicate nothing about the product.
• Oversized rounded rectangles used as a crutch instead of real hierarchy.
• Rainbow palettes that signal indecision rather than intent.
• Vague labels like "Insights," "Growth," "Scale," or "Optimize" that sit empty.
• Decorative SVG illustrations that pretend to be product imagery but aren't.

None of this means minimal is automatically good or dense is automatically cluttered. The point is to choose intentionally, not to follow a trend.

Reach for this list when you are reviewing a design that feels off but you cannot name why, or when you are prompting an AI tool and want to steer it away from the defaults it learned from the internet. Pair it with a brand style guide or a content-first layout to keep the result grounded.

Slop Diagnostic: Score Before You Fix

AI-generated design tends to fail in a narrow, predictable set of ways. When experienced designers are asked to spot AI-made UIs, their judgments converge on roughly ten recurring tells. Before you polish or repair a generated artifact, run this as an explicit self-audit and write a short report. Diagnose first, treat second. If you try to audit and fix in a single pass, the model's prior overrides your instruction and it repeats the same mistake: it recolors when it should re-layout, or polishes type on a composition problem.

The ten tells (each present adds 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

Start by checking whether the project already has a type system. If it does, use it. If not, choose typefaces deliberately based on what you are building.

• Editorial (articles, long-form content): a serif or humanist headline paired with a restrained sans-serif body. The contrast signals reading mode.
• Software / productivity (dashboards, tools, apps): a precise sans-serif with strong numeral handling. Numbers appear often in this context, so they need to read clearly at small sizes.
• Luxury / minimal (brand sites, high-end product pages): use fewer weights and more spacing discipline. The whitespace does the work that extra type variants would normally do.
• Technical (docs, API references, code samples): use monospace only for accents (inline code, code blocks, file paths), not for body text. Reading paragraphs in a monospace face fatigues the eye.
• Deck (presentations, slides): large, clear letterforms with high contrast against the background. Readability at a distance is the priority.

Avoid the default system font stack when a stronger choice fits the artifact. The default is safe, but it rarely communicates intent.

If you load web fonts, keep the number of families and weight variants low. Each additional font file adds latency and layout shift risk. Two families with two or three weights each covers most needs.

Use type to establish hierarchy before reaching for boxes, icons, or color. If the typographic scale already guides the reader's eye, you may not need the extra visual furniture.

Color

Start with colors from your brand or design system. They are already tested and consistent.

If you do not have a palette, build a minimal one rather than picking colors ad hoc. A workable system includes:

• Neutrals for backgrounds and structure
• Surface and ink for the main canvas and text
• Muted text for secondary information
• Border for separating elements
• An accent color for primary actions or highlights (use one unless the project explicitly needs more)
• Danger and success colors if your interface communicates errors or confirmations

When inventing a palette, prefer the oklch color space. It produces perceptually uniform hues, which makes manual color selection more predictable. Only use it if your target browsers support it.

Check contrast ratios for any text or interactive control that must be legible. This matters most for small text, form labels, and buttons.

Do not generate many colors from scratch. A small, deliberate palette is easier to maintain and less likely to introduce accessibility problems.

Layout and Composition

Build rhythm into your layouts using these seven levers: scale, whitespace, density, alignment, repetition, contrast, and interruption. Each one controls how the eye moves across the page and how quickly a viewer finds what matters.

A common trap is defaulting to the same card grid for every section. Vary the structure. A wall of identical cards hides information instead of revealing it.

For product UIs, optimize for speed. A user who lands on a settings page or a checkout flow should grasp the available actions in under a second. Decoration that slows that down is noise.

For marketing surfaces, commit to one idea per section. A hero, a feature highlight, a testimonial: each block should make a single point and then exit. Trying to sell three things in one section usually sells none.

For dashboards, resist the urge to dump every metric you have. Show only the data that supports a decision or triggers an action. Everything else is "data slop" that dilutes the signal.

Motion

Treat motion as a functional tool, not decoration.

Motion earns its place when it:

• Makes state transitions obvious
• Eases the wait during loading
• Connects one screen to the next
• Adds a responsive feel to buttons and controls
• Stays out of the way

Motion wastes its place when it:

• Runs in an endless, pointless loop
• Slows the user down
• Draws the eye to itself instead of the content
• Tries to compensate for a confusing layout

Always honor the prefers-reduced-motion media query. Non-essential animation should not play for users who have requested reduced motion.

Images and Icons

Always prefer actual supplied images over generated or stock alternatives. When a real asset is not available, reach for a clean placeholder rather than a busy or distracting graphic. You can also lean on typography, layout, or abstract texture to fill the space without pretending the asset exists. If the final output requires high fidelity, request real material from the client or team.

Do not generate elaborate fake SVG illustrations unless the assignment explicitly calls for illustration work. That kind of effort misleads stakeholders about what is real and wastes time on something that will be replaced.

Use iconography sparingly. Only add icons when they genuinely improve scanning (for example, in a list or navigation element) or when the design system you are working within requires them. Otherwise, leave them out.

Source-Code Fidelity

When you are recreating or extending an existing UI from a repository, work from the actual source files, not from memory or screenshots. The process is straightforward:

1. Inspect the repository tree to understand its structure.
2. Identify which files contain the UI source code (components, pages, layouts).
3. Read the theme, token, global style, and component files to understand the design system.
4. Lift exact values (colors, spacing, font sizes) from those files where appropriate.
5. Match the original spacing, border radii, shadows, copy tone, density, and interaction patterns.
6. Only then design new elements or modify existing ones.

This approach is especially important when you are working with a codebase you did not write yourself. It prevents guesswork and ensures the new UI fits the existing system without introducing inconsistencies.

For GitHub URLs, parse the owner, repo, ref (branch or tag), and path correctly so you can inspect the relevant files before starting any design work. A common mistake is to rely on a screenshot or a vague memory of what a component looked like; always go back to the source.

Reading Documents and Assets

When the file format is Markdown, HTML, CSS, JavaScript, TypeScript, JSX, TSX, JSON, SVG, or plain text, read the file directly. These formats are natively supported and require no conversion.

For DOCX, PPTX, or PDF files, check whether local extraction tools are already available on the system. If they are, use them to pull out the text or images. If no extraction tool is present, do not attempt to parse the binary format yourself. Instead, ask the person you are working with to export the content as text or images, or to point you to another tool that can handle the conversion.

When working with sketches, prefer thumbnails or screenshots over the raw drawing JSON. The JSON is harder to interpret visually and should only be used when no image-based representation exists.

Copyright and Reference Models

When building a design inspired by another product, you must not reproduce its distinctive UI, proprietary command structure, branded screens, or exact visual identity unless you have clear rights to that source material.

You can extract general design principles from any reference. For example, you might take ideas like:

• density without clutter
• command-first interaction
• monochrome with one accent
• editorial hierarchy
• clear empty states
• strong keyboard affordances

These are patterns, not protected expressions. What you cannot do is clone proprietary layouts, copy exact branded surfaces, or reproduce copyrighted content verbatim.

The practical test: if someone familiar with the original would recognize your interface as a copy of its layout, branding, or surface details, you have crossed the line. The safe path is to distill the underlying posture and principles from your references, then build an original design that expresses them in your own way. This section pairs with the earlier guidance on using reference images and the overall design system rules: treat references as inspiration for structure and behavior, not as templates to trace.

Verification

Before you mark a task as complete, verify the output as thoroughly as your current environment allows. The goal is to catch mistakes that an automated process would miss.

Minimum checks (always run these):

• Confirm the file exists at the exact path you specified.
• Confirm the HTML was saved in full (not truncated mid-tag).
• Scan for obvious syntax errors: unclosed tags, mismatched quotes, broken attribute values.

Better checks (run when you have access to a browser or rendering tool):

• Open the file in a browser and check the developer console for JavaScript errors or resource loading failures.
• Visually inspect any screenshots at the primary viewport size you designed for.
• Click through key interactive elements (buttons, links, forms) to confirm they behave as expected.
• Toggle between light and dark mode (or any other theme variants) if the design includes them.
• Resize the browser to each responsive breakpoint you defined and verify the layout adapts correctly.

If your environment prevents you from running some of these checks, be explicit about what you verified and what you could not. For example: "Verified file exists and HTML is well-formed; could not test browser console because no browser is available."

Never say "done" unless the file was actually written to disk. A successful generation step is not the same as a delivered file.

Final Response Format

Keep final responses short.

Include:

• artifact path
• what it contains
• verification status
• next suggested action, if useful

Example:

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 you need to take a style request written for Claude Design and run it through the CLI or API instead, keep this mental translation handy. It rewires the model's expectations so it doesn't ask for hosted-only features or preview panes that don't exist in your environment.

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.

Reach for this pattern whenever you are pasting a design brief that was originally written for the hosted chat interface. It pairs well with the system prompt you set at the start of a session. The main caveat: the model still needs a local tool to verify output, so make sure you have something like a browser or a local server available before you ask it to check its work.

Pitfalls

• Never paste hosted tool schemas into a skill. They produce fake tool calls that break the workflow.
• Avoid pointing the skill at a giant external prompt for runtime context. That setup drifts over time and becomes unreliable.
• When you strip out tool plumbing, keep the design doctrine intact. Removing both leaves the skill without direction.
• Don't keep asking for input after the user has already given enough direction. It wastes time and frustrates the user.
• For high-fidelity work, don't under-ask. Without brand context, the output will be generic and unusable.
• Generic SaaS layouts are not design. If the output looks like a template, it fails the purpose of the skill.
• Only claim browser verification if the verification actually ran. False claims erode trust and break downstream processes.