From gaia-prototyping
Build HTML prototypes using the Gaia design system. Use this skill whenever the user wants to create a UI prototype, mockup, or proof-of-concept using Gaia components, or when they mention prototyping with Gaia, building a page layout with ga- classes, or recreating a UI screenshot with the Gaia design system.
How this skill is triggered — by the user, by Claude, or both
Slash command
/gaia-prototyping:build-prototypeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Build standalone HTML prototypes that use the Gaia design system via its CSS from a public CDN.
Build standalone HTML prototypes that use the Gaia design system via its CSS from a public CDN.
Every visible UI element in the prototype must be built from Gaia components discovered in Step 2. Do not create custom-styled elements that replicate what a Gaia component already provides — even if it seems simpler or faster. If you need a progress bar, check if ProgressBar.md exists before writing custom CSS. If you need a badge, use the Gaia badge. Always cross-reference the discovered component list against what you need.
The only custom CSS allowed is layout scaffolding: flexbox/grid containers, spacing between sections, page-level margins and paddings. Everything else — buttons, inputs, cards, tags, progress bars, alerts, etc. — must come from Gaia.
If the UI requires something that has no Gaia equivalent, stop and ask the user before proceeding. Present them with options:
Never silently substitute a custom element or skip something — the user may know of a better Gaia component to use, or may have a preference you can't predict. Wait for their answer before continuing.
Clarify the user's intent if not already obvious:
chrome-devtools-mcp only) — the user provides a URL to an existing page. Use chrome-devtools-mcp to navigate to the page, take a screenshot, and extract the HTML structure yourself. This is the easiest path for the user and gives you the best input (both visual and semantic).Ask the user which case applies before proceeding. If the user shares a URL and chrome-devtools-mcp is available, prefer option 2 — it saves them the work of capturing screenshots and copying HTML.
The prototype depends on two CDN-hosted packages. Both must be version-pinned so the prototype remains stable over time.
| Package | CDN URL pattern |
|---|---|
@vsn-ux/gaia-styles | https://cdn.jsdelivr.net/npm/@vsn-ux/gaia-styles@{VERSION}/dist/all.css |
lucide | https://cdn.jsdelivr.net/npm/lucide@{VERSION}/dist/umd/lucide.min.js |
Creating a new prototype:
For each package, fetch its latest version from the npm registry (https://registry.npmjs.org/{package}/latest) and extract the version field from the JSON response. Use these exact versions in the CDN URLs so the prototype is pinned and won't break if packages update later.
Editing an existing prototype:
Find the existing <link> and <script> tags that reference these packages in the HTML. Keep the versions that are already there — do not upgrade or change them.
Download and extract the package to discover components and read their docs:
npm pack @vsn-ux/gaia-styles@{VERSION} --pack-destination /tmp 2>/dev/null && tar -xzf /tmp/vsn-ux-gaia-styles-{VERSION}.tgz -C /tmp
Then list the available component docs:
ls /tmp/package/dist/docs/
Each {ComponentName}.md file represents an available component — these are the only components you may use. File names are PascalCase (e.g. FormField.md, not form-field.md).
If the user asks for something that doesn't have a doc file, stop and ask the user — present the closest Gaia alternatives and let them decide how to proceed (see "Core constraint" above).
Before using any component, read its documentation to understand the correct HTML structure from the extracted files at /tmp/package/dist/docs/{ComponentName}.md. Do not guess the structure, always consult the docs first.
Output a single standalone HTML file. Structure:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{Prototype title}</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@vsn-ux/gaia-styles@{VERSION}/dist/all.css">
<style>body { font-family: 'Inter', sans-serif; }</style>
</head>
<body>
<!-- Prototype content using only ga- classes -->
<!-- Use <i data-lucide="icon-name"></i> for icons -->
<script src="https://cdn.jsdelivr.net/npm/lucide@{VERSION}/dist/umd/lucide.min.js"></script>
<script>
lucide.createIcons();
</script>
</body>
</html>
Rules:
.html file. All JavaScript, styles, and content go in this one file. Do not create any additional files (no separate .js, .css, .json, images, etc.).<style> only for layout scaffolding (grid, flexbox positioning, page-level spacing) — never to style UI elements that Gaia already provides.<script> for any interactive behavior (tabs, modals, form validation, mock data, etc.).When the user provides a URL and chrome-devtools-mcp is available:
Ideal input is screenshot + HTML source. When you have both, use the HTML to understand the semantic structure (headings, lists, form elements, containers) and the screenshot to understand the visual layout and intent. Map semantic HTML elements to their Gaia equivalents — the original CSS classes don't matter, but the element types and nesting do. If you only received one, ask the user if they can provide the other before proceeding.
Then determine the source type — this changes how you approach the build:
The user may be using this as a base to build upon later, so accuracy is critical.
Component identification: Look carefully at each UI element and match it to the exact Gaia component. Do not substitute similar-looking components — e.g. a segmented control is not two side-by-side buttons, and vice versa. When in doubt, check the component docs to compare.
Iterative refinement (Claude Code with chrome-devtools-mcp only):
If the chrome-devtools-mcp MCP server is available, do 2-3 rounds of visual comparison:
Only present the prototype to the user once you're confident it closely matches the screenshot.
If chrome-devtools-mcp is not available (e.g. in Claude.ai chat or Cowork), skip the visual comparison rounds and present the prototype after best-effort construction.
The goal here is to translate the intent and layout into Gaia — not to replicate the original look pixel-for-pixel. The source is a reference for structure and functionality, not a visual target.
If it's not obvious which case applies (e.g. a clean screenshot that could be Gaia or something else), ask the user.
Use Lucide icons via <i data-lucide="icon-name"></i>. The Lucide UMD script and lucide.createIcons() call must be placed at the end of <body> — they replace all data-lucide elements with inline SVGs at load time. If JavaScript adds icons dynamically after page load, call lucide.createIcons() again after inserting the new elements.
General Gaia design guidelines will be linked here in the future. For now, follow standard UX best practices: consistent spacing, clear visual hierarchy, and accessible markup.
npx claudepluginhub visma-software-nordic/claude-code-marketplace --plugin gaia-prototyping**TRIGGER: about to populate `AskUserQuestion` options with `preview:` content for any visual UI / screen / layout / component / animation comparison.** STOP and ask the user one short question first: *"Would you like a quick inline chip comparison, or a full HTML prototype you can open in the browser?"* The chip is fast but flattens color, type, spacing, and motion into monospace text; the HTML prototype is heavier but real. Asking costs one question; skipping costs a full redo if they wanted HTML — always ask. **No carve-out for "simulate", "demo", "mock up", "quick decision" — those framings name the surface, not an exception.** When the user picks HTML, this skill creates HTML prototypes for visual design, component playgrounds, animation tuning, and design system exploration — even when the final surface is React, Swift, SwiftUI, Android, or another framework. Use whenever the user wants to mock, prototype, sketch, tune, or explore any UI element — components, animations, transitions, layouts, design systems — before committing to production code. HTML is the fastest design-thinking surface; reach for it even for non-web targets. For N alternatives use html-brainstorm-grid; for a single tunable component use this skill.
Generates interactive, semantic HTML prototypes for human+AI agent use with Tailwind+DaisyUI (Tier A) or React+shadcn/ui+Vite (Tier B). Includes Playwright previews for iteration.
Creates high-fidelity HTML design artifacts including prototypes, slide decks, landing pages, UI mockups, and animations. Uses Playwright for browser rendering and screenshot verification.