From nexa-claude-core
Creates screen design specifications as standalone HTML artifacts from the project wireframe. Uses Playwright to open the wireframe, identify the section relevant to the current use case, and produces a self-contained HTML design file faithful to the wireframe's layout and enriched with states, data mappings, and interactions from the use case specification. Uses a separated CSS theming approach — HTML references a theme switcher CSS file and a Tailwind config, so changing the theme across all designs requires only swapping CSS files. Use when the user asks to "design a screen", "create a wireframe", "define the UI", "design the frontend", or mentions screen design, wireframes, UI layout, or frontend design.
How this skill is triggered — by the user, by Claude, or both
Slash command
/nexa-claude-core:design-screensThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Create or update an HTML screen design artifact for $ARGUMENTS in `docs/designs/`.
Create or update an HTML screen design artifact for $ARGUMENTS in docs/designs/.
$ARGUMENTS is a use case ID (UC-XXX) that has an existing specification in docs/use_cases/.
The design artifact bridges the use case specification (what the system does) and the implementation (how it looks and behaves). It is a standalone HTML file that faithfully translates the relevant wireframe section into a viewable, annotated design reference.
CSS is fully separated from HTML. All visual identity lives in external CSS theme files and Tailwind config files. The HTML uses Tailwind utility classes with semantic color names and CSS custom properties from the theme — it never contains hardcoded colors, font stacks, or brand values.
Switching the entire visual theme across all design artifacts requires changing only two files:
current-theme.css — change the @import to point to a different theme CSScurrent-tailwind-config.js — replace contents with the matching Tailwind configdocs/designs/docs/designs/
├── current-theme.css # Theme switcher — @imports the active theme
├── current-tailwind-config.js # Active Tailwind config (colors, fonts)
├── <main-theme>-001.css # Main theme derived from wireframe (CSS custom properties + components)
├── <main-theme>-tailwind-config.js# Main Tailwind color/font config
├── <alt-theme>-001.css # Optional alternative theme variant
├── <alt-theme>-tailwind-config.js # Optional alternative Tailwind config
├── UC-000-design.html # Design artifact (references current-theme.css)
├── UC-001-design.html
└── ...
current-theme.css contains a single @import pointing to the active theme:
@import url('<main-theme>-001.css');
current-tailwind-config.js contains the active Tailwind configuration that maps semantic
color names to the theme's palette. Each theme defines four color palette roles with evocative
names derived from the wireframe's visual language:
| Role | Purpose | Example names |
|---|---|---|
| Primary | Main brand color | forest, ocean, ember, indigo |
| Accent | Secondary/accent color | coral, azure, mint, amber |
| Neutral | Background/surface neutrals | cream, slate, sand, mist |
| Highlight | Premium/highlight color | gold, lemon, copper, silver |
tailwind.config = {
theme: {
extend: {
colors: {
// Names derived from the wireframe's visual language — NOT prescribed
[primary]: { 50:'...', 100:'...', /* ... */ 900:'...' },
[accent]: { 50:'...', 100:'...', /* ... */ 900:'...' },
[neutral]: { 50:'...', 100:'...', /* ... */ },
[highlight]:{ 50:'...', 100:'...', /* ... */ 900:'...' },
},
fontFamily: {
display: ['...', 'sans-serif'],
body: ['...', 'serif'],
mono: ['...', 'monospace'],
}
}
}
}
To switch themes: change the @import in current-theme.css and replace
current-tailwind-config.js contents with the matching config. All design HTML files instantly
reflect the new theme.
Reference examples are available in this skill's examples/ directory. These examples use a
green/forest theme — study the structure and patterns, not the specific color names.
Your project's theme must be derived from its own wireframe:
| File | Purpose |
|---|---|
examples/UC-000_landing_page.html | Complete landing page design — shows section-by-section layout with annotations |
examples/UC-001_register.html | Registration flow design — shows forms, validation states, multi-step flow |
examples/UC-002_verify_ong_company.html | Verification flow — shows admin review screens, status states |
examples/current-theme.css | Theme switcher file — single @import line |
examples/current-tailwind-config.js | Active Tailwind config file |
examples/green-theme-001.css | Green/Forest theme — full CSS custom properties + component styles |
examples/green-tailwind-config.js | Green/Forest Tailwind color palette |
examples/blue-theme-001.css | Blue/Indigo theme — same structure, different palette |
examples/blue-tailwind-config.js | Blue/Indigo Tailwind color palette |
Study these examples before producing output. They demonstrate:
bg-forest-800, text-coral-500 in the green example)var(--forest-600), var(--bg-card)) are used in component stylesdesign-section-divider, design-annotation,
design-screen patternsdesign-header, design-meta, design-annotation, design-data-table classes annotate
the design without embedding styling in HTML:root token values and rgba references| Input | Location | Required |
|---|---|---|
| Use case specification | docs/use_cases/UC-XXX.md | Yes |
| Entity model | docs/entity_model.md | If applicable |
| Wireframe | docs/wireframes/index.html | Yes |
| Design rules | docs/designs/DESIGN_RULES.md | Optional — project-specific design constraints |
| Theme CSS | docs/designs/current-theme.css | Optional — created automatically if missing |
| Tailwind config | docs/designs/current-tailwind-config.js | Optional — created automatically if missing |
A single HTML file: docs/designs/UC-XXX-design.html
If the theme files do not exist yet, also create the theme infrastructure (see Phase 3).
CRITICAL: The output MUST be an .html file written with the Write tool. Do NOT produce Markdown.
Do NOT create a .md file. The file extension MUST be .html and the content MUST start with
<!DOCTYPE html>. If you find yourself writing Markdown syntax (headings with #, lists with -,
tables with |), STOP — you are producing the wrong format.
When the project uses internationalization, all placeholder text in design artifacts MUST use correct, native-quality text for the target locale — including every diacritical mark and accent required by the language.
lang attribute on <html> to match the project's primary locale (e.g.,
lang="ro" for Romanian, lang="fr" for French). If the project supports multiple
locales, use the default locale.CLAUDE.md for the marker <!-- NEXA_I18N_CONFIGURED --> (includes locale list and default locale)next-intl config, i18n.ts, middleware.ts locale list)messages/ or locales/ directorieslang="en"&subset=latin-ext for
Romanian, Polish, Czech, etc.). Add the subset parameter to the Google Fonts URL when the
locale requires characters beyond basic Latin.<html lang="ro">
<!-- Google Fonts with latin-ext subset -->
<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&subset=latin-ext&display=swap" rel="stylesheet">
<!-- Correct Romanian text -->
<button>Înregistrează-te</button>
<label>Adresă de email</label>
<input placeholder="exemplu@email.com">
<p class="error">Câmpul este obligatoriu</p>
<p>Încărcați documentele necesare</p>
<span>Verificare în curs de procesare</span>
| Wrong | Correct | Language |
|---|---|---|
| Inregistreaza-te | Înregistrează-te | Romanian |
| Adresa de email | Adresă de email | Romanian |
| Incarcati documentele | Încărcați documentele | Romanian |
| Campul este obligatoriu | Câmpul este obligatoriu | Romanian |
| Reusit | Reușit | Romanian |
| Resumé | Résumé | French |
| Uber | Über | German |
.md. No Markdown syntax anywhere in the file.<style> block — token definitions belong
in the theme CSS files only. The HTML <style> block is for screen-specific layout rules only.docs/designs/DESIGN_RULES.md exists, every rule in it
must be followed. Missing a shared element (header, footer, sidebar) specified in design rules
is a defect.Read and follow ${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md.
docs/use_cases/UC-XXX.mddocs/entity_model.md (if applicable)examples/ directory to understand the expected
output format, HTML structure, and theming patternsdocs/designs/DESIGN_RULES.md (if it exists).
These are project-specific constraints that every design artifact must follow — e.g.,
shared layout elements (header, footer, sidebar), mandatory components, consistent
navigation patterns, accessibility requirements, or brand guidelines. Every rule in this
file applies to all design artifacts unless the rule itself specifies a narrower scope.lang attribute value and whether &subset=latin-ext (or other subsets)
are needed for the Google Fonts URL.docs/designs/current-theme.css exists:
All screenshots taken during this phase MUST be saved to docs/snapshots/ using the naming
convention UC-XXX-<description>.png (e.g., UC-001-overview.png, UC-001-form-screen.png).
Create the docs/snapshots/ directory if it does not exist.
file:// absolute path of docs/wireframes/index.html
b. Take an accessibility snapshot to understand the overall structure and navigation
c. Take a screenshot (full page) and save it as docs/snapshots/UC-XXX-wireframe-overview.pngdocs/snapshots/UC-XXX-<screen-name>.png to capture the visual layout
d. Take an accessibility snapshot to capture the semantic structure, components,
and hierarchy
e. If the use case spans multiple screens, repeat for each screen with a distinct
<screen-name> suffixocean
for a blue maritime palette, ember for warm reds, forest for greens). Do NOT default to
the example names (forest, coral, cream, gold) — those belong to the green example theme.docs/designs/ocean-theme-001.css) following the
structure from the examples. Populate :root custom properties with values extracted from
the wireframe. Include all base resets, animations, and component styles.docs/designs/ocean-tailwind-config.js)
with color palettes matching the theme CSS tokens.current-theme.css with a single @import pointing to the theme CSS.current-tailwind-config.js with contents matching the active Tailwind config.docs/designs/UC-XXX-design.html following the HTML structure
below. The file content MUST be valid HTML starting with <!DOCTYPE html> — never Markdown.bg-[primary]-800,
text-[accent]-500, border-[neutral]-200) for layout and styling — never hardcode hex valuesvar(--[primary]-600), var(--bg-card)) in the theme CSS for
component styles that can't be expressed as Tailwind utilitiesdata-uc-step attributesdata-entity attributesdesign-section-divider, design-section-title, design-annotation, design-screen,
and design-data-table CSS classes from the theme for design artifact structureEvery design artifact MUST include a dedicated Mobile Layout section that explicitly shows how the UI adapts for mobile viewports (< 768px). Responsiveness cannot be assumed to work "out of the box" — mobile requires explicit design decisions.
<!-- ============================================================== -->
<!-- MOBILE LAYOUT -->
<!-- ============================================================== -->
<div class="design-section-divider"></div>
<div class="design-section-title">Mobile Layout (< 768px)</div>
<div class="design-annotation">
<strong>Navigation:</strong> [How nav transforms — hamburger, drawer, etc.]
</div>
<div class="design-annotation">
<strong>Layout changes:</strong>
<ul class="list-disc ml-5 mt-2">
<li>[Change 1 — e.g., "2-column grid → single column stack"]</li>
<li>[Change 2 — e.g., "Sidebar collapses into bottom sheet"]</li>
<li>[Change 3 — e.g., "Data table → card list with key fields only"]</li>
</ul>
</div>
<div class="design-screen">
<!-- Mobile viewport rendering of the main screen -->
<div class="max-w-[375px] mx-auto border border-[neutral]-300 rounded-xl overflow-hidden">
<!-- Mobile layout here -->
</div>
</div>
<div class="design-annotation">
<strong>Touch targets:</strong> All interactive elements meet 44x44px minimum.
<strong>Gestures:</strong> [Any swipe, pull-to-refresh, or other mobile gestures]
</div>
The design HTML must follow this structure:
<!DOCTYPE html>
<html lang="[project locale, e.g. en, ro, fr — see Internationalization section]">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>UC-XXX — [Use Case Name] — [Project] Design</title>
<script src="https://cdn.tailwindcss.com"></script>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700;800;900&family=Lora:ital,wght@0,400;0,500;0,600;1,400&family=JetBrains+Mono:wght@400;500[&subset=latin-ext if needed]&display=swap" rel="stylesheet">
<script src="current-tailwind-config.js"></script>
<link rel="stylesheet" href="current-theme.css">
</head>
<body class="bg-[neutral]-100 text-[primary]-800 antialiased">
<div class="max-w-[1400px] mx-auto px-6 py-8">
<!-- Design Header -->
<div class="design-header">
<h1>UC-XXX — [Use Case Name]</h1>
<p>[Brief description of what this screen/flow accomplishes]</p>
<div class="design-meta">
<span>Actor: <strong>[Primary Actor]</strong></span>
<span>Route: <strong>[URL route]</strong></span>
<span>Priority: <strong>[Priority]</strong></span>
</div>
</div>
<!-- ============================================================== -->
<!-- SECTION 1: [Section Name] -->
<!-- ============================================================== -->
<div class="design-section-divider"></div>
<div class="design-section-title">1. [Section Name]</div>
<div class="design-annotation">
<strong>[Annotation type]:</strong> [Description of the section's purpose,
layout, behavior, and key interactions]
</div>
<div class="design-screen">
<!-- Actual screen content using Tailwind utility classes -->
<!-- Use the theme's semantic color names (e.g., bg-[primary]-800, text-[accent]-500) -->
</div>
<div class="design-annotation">
<strong>Data mapping:</strong> [Entity-to-field mappings, navigation targets,
API endpoints]
</div>
<!-- Repeat sections for each part of the screen -->
<!-- ============================================================== -->
<!-- STATES -->
<!-- ============================================================== -->
<div class="design-section-divider"></div>
<div class="design-section-title">States</div>
<!-- Loading state -->
<div class="design-annotation">
<strong>Loading:</strong> [What the user sees while data loads]
</div>
<div class="design-screen">
<!-- Loading skeleton / spinner -->
</div>
<!-- Empty state -->
<div class="design-annotation">
<strong>Empty:</strong> [What the user sees when there is no data]
</div>
<div class="design-screen">
<!-- Empty state content -->
</div>
<!-- Error state -->
<div class="design-annotation">
<strong>Error:</strong> [What the user sees on failure — map to Alternative Flows]
</div>
<div class="design-screen">
<!-- Error state content -->
</div>
<!-- Success state -->
<div class="design-annotation">
<strong>Success:</strong> [What the user sees after successful action]
</div>
<div class="design-screen">
<!-- Success state content -->
</div>
</div>
</body>
</html>
| Attribute | Purpose | Example |
|---|---|---|
data-uc-step="N" | Maps element to use case Main Success Scenario step N | data-uc-step="3" |
data-uc-alt="N" | Maps element to Alternative Flow N | data-uc-alt="2" |
data-entity="Entity.attr" | Maps field to entity model attribute | data-entity="User.email" |
form, table, nav, button,
input) styled with Tailwind utility classes using the theme's semantic color names (four
palettes: primary, accent, neutral, highlight — with evocative names derived from the wireframe).
Custom component styles use CSS custom properties from the theme.data-uc-step.
Every data field traces to the entity model via data-entity.design-section-divider + design-section-title + design-annotation + design-screen
block, making the design easy to review and implement incrementally.Each theme CSS file contains the complete visual identity. All theme files for a project share
identical structure but differ in :root token values. The theme name reflects the wireframe's
visual language (e.g., ocean-theme-001.css for a blue palette, ember-theme-001.css for warm tones).
/* ── Reset & Base ── */
/* box-sizing, body font, heading font families */
/* ── CSS Custom Properties (Theme Tokens) ── */
:root {
/* Color palettes: --[primary]-*, --[accent]-*, --[neutral]-*, --[highlight]-* (50-900 scale) */
/* Semantic aliases: --bg-page, --bg-card, --text-primary, --accent, etc. */
/* Sizing: --radius-*, --shadow-*, --nav-height */
}
/* ── Grain Overlay ── */
/* ── Custom Scrollbar ── */
/* ── Animations ── (fadeUp, fadeIn, scaleIn, slideRight, float, pulse-ring, shimmer) */
/* ── Page Transitions ── */
/* ── Component styles ── (hero-blob, card-hover, tab-link, toggle-switch, etc.) */
/* ── Status Chips ── */
/* ── Language Switcher ── */
/* ── Design Artifact classes ── (design-header, design-section-divider, design-annotation,
design-screen, design-data-table, design-state-label) */
Each project defines four palette names derived from the wireframe's visual identity. All themes
within the same project use the same four names so HTML never changes — only the :root values
differ between themes.
| Role | Purpose | Example (green theme) | Example (ocean theme) |
|---|---|---|---|
| Primary | Main brand color | forest (emerald scale) | ocean (deep blue scale) |
| Accent | Secondary/accent color | coral (orange/amber) | azure (sky blue) |
| Neutral | Background/surface neutrals | cream (green-tinted) | mist (blue-tinted) |
| Highlight | Premium/highlight color | gold (true gold) | copper (warm metallic) |
The HTML always writes bg-[primary]-600 or var(--[primary]-600) using the project's chosen
palette names — the actual rendered color depends entirely on which theme CSS is active.
Note: The examples in this skill's
examples/directory useforest/coral/cream/goldas their palette names. These are specific to the green example theme, not universal defaults. Your project's palette names should reflect its own wireframe.
npx claudepluginhub nexadevapp/nexa-claude-skills-marketplace --plugin nexa-claude-coreCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.