Frontend Design
Instructions
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.
Theming Architecture
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 config
File structure in docs/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
└── ...
How the theme switcher works
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.
Examples
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:
- How HTML uses Tailwind utility classes with semantic names (e.g.,
bg-forest-800, text-coral-500 in the green example)
- How CSS custom properties (e.g.,
var(--forest-600), var(--bg-card)) are used in component styles
- The section-by-section design layout with
design-section-divider, design-annotation,
design-screen patterns
- How
design-header, design-meta, design-annotation, design-data-table classes annotate
the design without embedding styling in HTML
- How theme CSS files share identical structure (resets, animations, components) but differ only
in
:root token values and rgba references
Inputs
| 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 |
Output
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.
Internationalization (i18n)
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.
Rules
- Never approximate accented characters. Use the exact Unicode characters the language
requires. For example, Romanian requires ă, â, î, ș (with comma below, U+0219), and
ț (with comma below, U+021B) — never substitute with ş (cedilla, U+015F) or t̜.
Similarly, French requires é, è, ê, ë, ç, etc. Missing or wrong diacritics are treated
as bugs.
- Set the
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.
- Detect the project locale automatically. Check these sources in order:
- The project's
CLAUDE.md for the marker <!-- NEXA_I18N_CONFIGURED --> (includes locale list and default locale)
- i18n configuration files (e.g.,
next-intl config, i18n.ts, middleware.ts locale list)
- Translation files in
messages/ or locales/ directories
- The use case specification (which may contain localized text)
- If no locale information is found, default to
lang="en"
- All visible UI text — labels, buttons, placeholders, headings, error messages, empty
states, success messages — must be written in the project's primary locale with correct
accents. This includes placeholder content that demonstrates realistic data.
- Ensure fonts support the required character set. Google Fonts loaded in the HTML head
must include the character subsets needed for the locale (e.g.,
&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.
Example — Romanian
<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>
Common mistakes to avoid
| 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 |
DO NOT
- Produce Markdown — the output is HTML, never
.md. No Markdown syntax anywhere in the file.
- Skip reading the use case specification first
- Hardcode colors, fonts, or spacing in HTML — use Tailwind utility classes with the theme's
semantic color names and CSS custom properties from the theme
- Embed CSS custom property definitions in the HTML
<style> block — token definitions belong
in the theme CSS files only. The HTML <style> block is for screen-specific layout rules only.
- Use any framework-specific code (no React, no Next.js, no component libraries)
- Use lorem ipsum — use realistic placeholder content that matches entity model attributes
- Strip or approximate diacritics/accents — all UI text must use correct Unicode characters
for the project locale (see Internationalization section)
- Design screens for steps not in the use case specification
- Omit error states or empty states
- Ignore the wireframe layout — the wireframe takes precedence over assumptions
- Ignore project design rules — if
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.
Nexa Rules Gate
Read and follow ${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md.
Workflow
Phase 1 — Gather context
- Read the use case specification from
docs/use_cases/UC-XXX.md
- Read the entity model from
docs/entity_model.md (if applicable)
- Read the example files from this skill's
examples/ directory to understand the expected
output format, HTML structure, and theming patterns
- Read project design rules from
docs/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.
- Detect the project locale following the rules in the Internationalization section.
Determine the
lang attribute value and whether &subset=latin-ext (or other subsets)
are needed for the Google Fonts URL.
- Check if
docs/designs/current-theme.css exists:
- If it exists: Read it and the active theme CSS it imports — all design tokens and base
styles are already defined.
- If it does NOT exist: You will create the theme infrastructure during Phase 3.
Inspect the wireframe's visual language (colors, fonts, spacing) during Phase 2
and use those observations to populate the theme tokens.
Phase 2 — Inspect the wireframe with Playwright
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.
- Open the wireframe in Playwright:
a. Navigate to the
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.png
- Navigate to the screen(s) relevant to the use case:
a. Using the use case specification, identify which screen(s) in the wireframe correspond
to the use case
b. Click links, tabs, or navigation elements to reach the relevant screen
c. Take a screenshot (full page) and save it as
docs/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> suffix
- Close the Playwright browser
Phase 3 — Produce the HTML design artifact
- If the theme infrastructure does not exist, create it now using the Write tool.
The wireframe's visual language dictates the theme — extract colors, fonts, and spacing
from the wireframe screenshots taken in Phase 2 and use them as the basis for the theme tokens.
- Choose evocative palette names that reflect the wireframe's color identity (e.g.,
ocean
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.
- Create a theme CSS file (e.g.,
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.
- Create the matching Tailwind config (e.g.,
docs/designs/ocean-tailwind-config.js)
with color palettes matching the theme CSS tokens.
- Create
current-theme.css with a single @import pointing to the theme CSS.
- Create
current-tailwind-config.js with contents matching the active Tailwind config.
- Optionally create a second theme variant to demonstrate the theme switching capability.
- Using the Write tool, create
docs/designs/UC-XXX-design.html following the HTML structure
below. The file content MUST be valid HTML starting with <!DOCTYPE html> — never Markdown.
- For each screen identified in the wireframe:
- Reproduce the layout and visual structure from the wireframe
- Use Tailwind utility classes with the theme's semantic color names (e.g.,
bg-[primary]-800,
text-[accent]-500, border-[neutral]-200) for layout and styling — never hardcode hex values
- Use CSS custom properties (
var(--[primary]-600), var(--bg-card)) in the theme CSS for
component styles that can't be expressed as Tailwind utilities
- Map components to use case steps using
data-uc-step attributes
- Map data fields to entity model attributes using
data-entity attributes
- Include all states: default, loading, empty, error, success — each rendered as a
visible section
- Use
design-section-divider, design-section-title, design-annotation, design-screen,
and design-data-table CSS classes from the theme for design artifact structure
- Include a navigation flow section showing how screens connect
- Include responsive behavior using Tailwind responsive prefixes and CSS media queries
- Include a Mobile Layout section showing how the design adapts to mobile viewports
Mobile Layout Section
Every 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.
What to include
- Navigation changes — e.g., hamburger menu replacing horizontal nav
- Layout reflows — e.g., sidebar collapses, grid becomes single column
- Component adaptations — e.g., data tables become cards, horizontal tabs become dropdowns
- Touch targets — buttons/links sized for finger taps (minimum 44x44px)
- Hidden/revealed elements — what's hidden on mobile, what's shown differently
HTML structure for Mobile Layout section
<!-- ============================================================== -->
<!-- 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>
HTML Structure
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>
Data Attribute Reference
| 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" |
Design Principles
- Wireframe-faithful — The layout, component placement, and navigation structure must match
the wireframe. Do not invent layouts.
- Mobile-explicit — Every design includes a dedicated Mobile Layout section. Do not assume
responsiveness works automatically — mobile requires explicit decisions about navigation,
layout reflows, and component adaptations.
- CSS-separated theming — All visual identity (colors, fonts, spacing tokens) lives in
external CSS theme files and Tailwind configs. HTML never contains hardcoded brand values.
Changing the theme = swapping CSS files. This is the most important architectural principle.
- Semantic HTML + Tailwind — Use appropriate elements (
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.
- All states visible — Every state (default, loading, empty, error, success) is rendered as a
visible section. This makes the design a complete reference — no hidden requirements.
- Traceable — Every interactive element traces back to a use case step via
data-uc-step.
Every data field traces to the entity model via data-entity.
- Section-by-section layout — Each logical section of the screen gets its own
design-section-divider + design-section-title + design-annotation + design-screen
block, making the design easy to review and implement incrementally.
Theme CSS Structure
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).
Required sections
/* ── 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) */
Semantic color names
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 use forest/coral/cream/gold
as their palette names. These are specific to the green example theme, not universal defaults.
Your project's palette names should reflect its own wireframe.
1---2name: design-screens3description: 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.4---56# Frontend Design78## Instructions910Create or update an HTML screen design artifact for $ARGUMENTS in `docs/designs/`.11$ARGUMENTS is a use case ID (`UC-XXX`) that has an existing specification in `docs/use_cases/`.1213The design artifact bridges the use case specification (what the system does) and the14implementation (how it looks and behaves). It is a **standalone HTML file** that faithfully15translates the relevant wireframe section into a viewable, annotated design reference.1617## Theming Architecture1819**CSS is fully separated from HTML.** All visual identity lives in external CSS theme files and20Tailwind config files. The HTML uses Tailwind utility classes with semantic color names and CSS21custom properties from the theme — it never contains hardcoded colors, font stacks, or brand values.2223Switching the entire visual theme across all design artifacts requires changing only two files:24- `current-theme.css` — change the `@import` to point to a different theme CSS25- `current-tailwind-config.js` — replace contents with the matching Tailwind config2627### File structure in `docs/designs/`2829```30docs/designs/31├── current-theme.css # Theme switcher — @imports the active theme32├── current-tailwind-config.js # Active Tailwind config (colors, fonts)33├── <main-theme>-001.css # Main theme derived from wireframe (CSS custom properties + components)34├── <main-theme>-tailwind-config.js# Main Tailwind color/font config35├── <alt-theme>-001.css # Optional alternative theme variant36├── <alt-theme>-tailwind-config.js # Optional alternative Tailwind config37├── UC-000-design.html # Design artifact (references current-theme.css)38├── UC-001-design.html39└── ...40```4142### How the theme switcher works4344**`current-theme.css`** contains a single `@import` pointing to the active theme:45```css46@import url('<main-theme>-001.css');47```4849**`current-tailwind-config.js`** contains the active Tailwind configuration that maps semantic50color names to the theme's palette. Each theme defines four color palette roles with evocative51names derived from the wireframe's visual language:5253| Role | Purpose | Example names |54|------|---------|---------------|55| **Primary** | Main brand color | `forest`, `ocean`, `ember`, `indigo` |56| **Accent** | Secondary/accent color | `coral`, `azure`, `mint`, `amber` |57| **Neutral** | Background/surface neutrals | `cream`, `slate`, `sand`, `mist` |58| **Highlight** | Premium/highlight color | `gold`, `lemon`, `copper`, `silver` |5960```js61tailwind.config = {62 theme: {63 extend: {64 colors: {65 // Names derived from the wireframe's visual language — NOT prescribed66 [primary]: { 50:'...', 100:'...', /* ... */ 900:'...' },67 [accent]: { 50:'...', 100:'...', /* ... */ 900:'...' },68 [neutral]: { 50:'...', 100:'...', /* ... */ },69 [highlight]:{ 50:'...', 100:'...', /* ... */ 900:'...' },70 },71 fontFamily: {72 display: ['...', 'sans-serif'],73 body: ['...', 'serif'],74 mono: ['...', 'monospace'],75 }76 }77 }78}79```8081To switch themes: change the `@import` in `current-theme.css` and replace82`current-tailwind-config.js` contents with the matching config. All design HTML files instantly83reflect the new theme.8485## Examples8687Reference examples are available in this skill's `examples/` directory. These examples use a88**green/forest theme** — study the **structure and patterns**, not the specific color names.89Your project's theme must be derived from its own wireframe:9091| File | Purpose |92|------|---------|93| `examples/UC-000_landing_page.html` | Complete landing page design — shows section-by-section layout with annotations |94| `examples/UC-001_register.html` | Registration flow design — shows forms, validation states, multi-step flow |95| `examples/UC-002_verify_ong_company.html` | Verification flow — shows admin review screens, status states |96| `examples/current-theme.css` | Theme switcher file — single `@import` line |97| `examples/current-tailwind-config.js` | Active Tailwind config file |98| `examples/green-theme-001.css` | Green/Forest theme — full CSS custom properties + component styles |99| `examples/green-tailwind-config.js` | Green/Forest Tailwind color palette |100| `examples/blue-theme-001.css` | Blue/Indigo theme — same structure, different palette |101| `examples/blue-tailwind-config.js` | Blue/Indigo Tailwind color palette |102103**Study these examples before producing output.** They demonstrate:104- How HTML uses Tailwind utility classes with semantic names (e.g., `bg-forest-800`, `text-coral-500` in the green example)105- How CSS custom properties (e.g., `var(--forest-600)`, `var(--bg-card)`) are used in component styles106- The section-by-section design layout with `design-section-divider`, `design-annotation`,107 `design-screen` patterns108- How `design-header`, `design-meta`, `design-annotation`, `design-data-table` classes annotate109 the design without embedding styling in HTML110- How theme CSS files share identical structure (resets, animations, components) but differ only111 in `:root` token values and rgba references112113## Inputs114115| Input | Location | Required |116|-------|----------|----------|117| Use case specification | `docs/use_cases/UC-XXX.md` | Yes |118| Entity model | `docs/entity_model.md` | If applicable |119| Wireframe | `docs/wireframes/index.html` | Yes |120| Design rules | `docs/designs/DESIGN_RULES.md` | Optional — project-specific design constraints |121| Theme CSS | `docs/designs/current-theme.css` | Optional — created automatically if missing |122| Tailwind config | `docs/designs/current-tailwind-config.js` | Optional — created automatically if missing |123124## Output125126A single **HTML** file: `docs/designs/UC-XXX-design.html`127128If the theme files do not exist yet, also create the theme infrastructure (see Phase 3).129130**CRITICAL: The output MUST be an `.html` file written with the Write tool. Do NOT produce Markdown.131Do NOT create a `.md` file. The file extension MUST be `.html` and the content MUST start with132`<!DOCTYPE html>`. If you find yourself writing Markdown syntax (headings with `#`, lists with `-`,133tables with `|`), STOP — you are producing the wrong format.**134135## Internationalization (i18n)136137When the project uses internationalization, all placeholder text in design artifacts MUST use138**correct, native-quality text** for the target locale — including every diacritical mark and139accent required by the language.140141### Rules1421431. **Never approximate accented characters.** Use the exact Unicode characters the language144 requires. For example, Romanian requires ă, â, î, ș (with comma below, U+0219), and145 ț (with comma below, U+021B) — never substitute with ş (cedilla, U+015F) or t̜.146 Similarly, French requires é, è, ê, ë, ç, etc. Missing or wrong diacritics are treated147 as bugs.1482. **Set the `lang` attribute** on `<html>` to match the project's primary locale (e.g.,149 `lang="ro"` for Romanian, `lang="fr"` for French). If the project supports multiple150 locales, use the default locale.1513. **Detect the project locale automatically.** Check these sources in order:152 - The project's `CLAUDE.md` for the marker `<!-- NEXA_I18N_CONFIGURED -->` (includes locale list and default locale)153 - i18n configuration files (e.g., `next-intl` config, `i18n.ts`, `middleware.ts` locale list)154 - Translation files in `messages/` or `locales/` directories155 - The use case specification (which may contain localized text)156 - If no locale information is found, default to `lang="en"`1574. **All visible UI text** — labels, buttons, placeholders, headings, error messages, empty158 states, success messages — must be written in the project's primary locale with correct159 accents. This includes placeholder content that demonstrates realistic data.1605. **Ensure fonts support the required character set.** Google Fonts loaded in the HTML head161 must include the character subsets needed for the locale (e.g., `&subset=latin-ext` for162 Romanian, Polish, Czech, etc.). Add the subset parameter to the Google Fonts URL when the163 locale requires characters beyond basic Latin.164165### Example — Romanian166167```html168<html lang="ro">169<!-- Google Fonts with latin-ext subset -->170<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&subset=latin-ext&display=swap" rel="stylesheet">171172<!-- Correct Romanian text -->173<button>Înregistrează-te</button>174<label>Adresă de email</label>175<input placeholder="exemplu@email.com">176<p class="error">Câmpul este obligatoriu</p>177<p>Încărcați documentele necesare</p>178<span>Verificare în curs de procesare</span>179```180181### Common mistakes to avoid182183| Wrong | Correct | Language |184|-------|---------|----------|185| Inregistreaza-te | Înregistrează-te | Romanian |186| Adresa de email | Adresă de email | Romanian |187| Incarcati documentele | Încărcați documentele | Romanian |188| Campul este obligatoriu | Câmpul este obligatoriu | Romanian |189| Reusit | Reușit | Romanian |190| Resumé | Résumé | French |191| Uber | Über | German |192193## DO NOT194195- **Produce Markdown** — the output is HTML, never `.md`. No Markdown syntax anywhere in the file.196- Skip reading the use case specification first197- **Hardcode colors, fonts, or spacing in HTML** — use Tailwind utility classes with the theme's198 semantic color names and CSS custom properties from the theme199- **Embed CSS custom property definitions in the HTML `<style>` block** — token definitions belong200 in the theme CSS files only. The HTML `<style>` block is for screen-specific layout rules only.201- Use any framework-specific code (no React, no Next.js, no component libraries)202- Use lorem ipsum — use realistic placeholder content that matches entity model attributes203- **Strip or approximate diacritics/accents** — all UI text must use correct Unicode characters204 for the project locale (see Internationalization section)205- Design screens for steps not in the use case specification206- Omit error states or empty states207- Ignore the wireframe layout — the wireframe takes precedence over assumptions208- **Ignore project design rules** — if `docs/designs/DESIGN_RULES.md` exists, every rule in it209 must be followed. Missing a shared element (header, footer, sidebar) specified in design rules210 is a defect.211212## Nexa Rules Gate213214Read and follow `${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md`.215216## Workflow217218### Phase 1 — Gather context2192201. Read the use case specification from `docs/use_cases/UC-XXX.md`2212. Read the entity model from `docs/entity_model.md` (if applicable)2223. Read the example files from this skill's `examples/` directory to understand the expected223 output format, HTML structure, and theming patterns2244. **Read project design rules** from `docs/designs/DESIGN_RULES.md` (if it exists).225 These are project-specific constraints that every design artifact must follow — e.g.,226 shared layout elements (header, footer, sidebar), mandatory components, consistent227 navigation patterns, accessibility requirements, or brand guidelines. Every rule in this228 file applies to **all** design artifacts unless the rule itself specifies a narrower scope.2295. **Detect the project locale** following the rules in the Internationalization section.230 Determine the `lang` attribute value and whether `&subset=latin-ext` (or other subsets)231 are needed for the Google Fonts URL.2326. Check if `docs/designs/current-theme.css` exists:233 - **If it exists**: Read it and the active theme CSS it imports — all design tokens and base234 styles are already defined.235 - **If it does NOT exist**: You will create the theme infrastructure during Phase 3.236 Inspect the wireframe's visual language (colors, fonts, spacing) during Phase 2237 and use those observations to populate the theme tokens.238239### Phase 2 — Inspect the wireframe with Playwright240241All screenshots taken during this phase MUST be saved to `docs/snapshots/` using the naming242convention `UC-XXX-<description>.png` (e.g., `UC-001-overview.png`, `UC-001-form-screen.png`).243Create the `docs/snapshots/` directory if it does not exist.2442453. Open the wireframe in Playwright:246 a. Navigate to the `file://` absolute path of `docs/wireframes/index.html`247 b. Take an **accessibility snapshot** to understand the overall structure and navigation248 c. Take a **screenshot** (full page) and save it as `docs/snapshots/UC-XXX-wireframe-overview.png`2494. Navigate to the screen(s) relevant to the use case:250 a. Using the use case specification, identify which screen(s) in the wireframe correspond251 to the use case252 b. Click links, tabs, or navigation elements to reach the relevant screen253 c. Take a **screenshot** (full page) and save it as254 `docs/snapshots/UC-XXX-<screen-name>.png` to capture the visual layout255 d. Take an **accessibility snapshot** to capture the semantic structure, components,256 and hierarchy257 e. If the use case spans multiple screens, repeat for each screen with a distinct258 `<screen-name>` suffix2595. Close the Playwright browser260261### Phase 3 — Produce the HTML design artifact2622636. If the theme infrastructure does not exist, create it now using the **Write** tool.264 **The wireframe's visual language dictates the theme** — extract colors, fonts, and spacing265 from the wireframe screenshots taken in Phase 2 and use them as the basis for the theme tokens.266 - Choose evocative **palette names** that reflect the wireframe's color identity (e.g., `ocean`267 for a blue maritime palette, `ember` for warm reds, `forest` for greens). Do NOT default to268 the example names (`forest`, `coral`, `cream`, `gold`) — those belong to the green example theme.269 - Create a **theme CSS file** (e.g., `docs/designs/ocean-theme-001.css`) following the270 structure from the examples. Populate `:root` custom properties with values extracted from271 the wireframe. Include all base resets, animations, and component styles.272 - Create the matching **Tailwind config** (e.g., `docs/designs/ocean-tailwind-config.js`)273 with color palettes matching the theme CSS tokens.274 - Create **`current-theme.css`** with a single `@import` pointing to the theme CSS.275 - Create **`current-tailwind-config.js`** with contents matching the active Tailwind config.276 - Optionally create a second theme variant to demonstrate the theme switching capability.2777. Using the **Write** tool, create `docs/designs/UC-XXX-design.html` following the HTML structure278 below. The file content MUST be valid HTML starting with `<!DOCTYPE html>` — never Markdown.2798. For each screen identified in the wireframe:280 - Reproduce the **layout and visual structure** from the wireframe281 - Use **Tailwind utility classes** with the theme's semantic color names (e.g., `bg-[primary]-800`,282 `text-[accent]-500`, `border-[neutral]-200`) for layout and styling — never hardcode hex values283 - Use **CSS custom properties** (`var(--[primary]-600)`, `var(--bg-card)`) in the theme CSS for284 component styles that can't be expressed as Tailwind utilities285 - Map **components** to use case steps using `data-uc-step` attributes286 - Map **data fields** to entity model attributes using `data-entity` attributes287 - Include all **states**: default, loading, empty, error, success — each rendered as a288 visible section289 - Use `design-section-divider`, `design-section-title`, `design-annotation`, `design-screen`,290 and `design-data-table` CSS classes from the theme for design artifact structure2919. Include a **navigation flow** section showing how screens connect29210. Include **responsive behavior** using Tailwind responsive prefixes and CSS media queries29311. Include a **Mobile Layout** section showing how the design adapts to mobile viewports294295## Mobile Layout Section296297Every design artifact MUST include a dedicated **Mobile Layout** section that explicitly shows298how the UI adapts for mobile viewports (< 768px). Responsiveness cannot be assumed to work299"out of the box" — mobile requires explicit design decisions.300301### What to include3023031. **Navigation changes** — e.g., hamburger menu replacing horizontal nav3042. **Layout reflows** — e.g., sidebar collapses, grid becomes single column3053. **Component adaptations** — e.g., data tables become cards, horizontal tabs become dropdowns3064. **Touch targets** — buttons/links sized for finger taps (minimum 44x44px)3075. **Hidden/revealed elements** — what's hidden on mobile, what's shown differently308309### HTML structure for Mobile Layout section310311```html312<!-- ============================================================== -->313<!-- MOBILE LAYOUT -->314<!-- ============================================================== -->315<div class="design-section-divider"></div>316<div class="design-section-title">Mobile Layout (< 768px)</div>317318<div class="design-annotation">319 <strong>Navigation:</strong> [How nav transforms — hamburger, drawer, etc.]320</div>321322<div class="design-annotation">323 <strong>Layout changes:</strong>324 <ul class="list-disc ml-5 mt-2">325 <li>[Change 1 — e.g., "2-column grid → single column stack"]</li>326 <li>[Change 2 — e.g., "Sidebar collapses into bottom sheet"]</li>327 <li>[Change 3 — e.g., "Data table → card list with key fields only"]</li>328 </ul>329</div>330331<div class="design-screen">332 <!-- Mobile viewport rendering of the main screen -->333 <div class="max-w-[375px] mx-auto border border-[neutral]-300 rounded-xl overflow-hidden">334 <!-- Mobile layout here -->335 </div>336</div>337338<div class="design-annotation">339 <strong>Touch targets:</strong> All interactive elements meet 44x44px minimum.340 <strong>Gestures:</strong> [Any swipe, pull-to-refresh, or other mobile gestures]341</div>342```343344## HTML Structure345346The design HTML must follow this structure:347348```html349<!DOCTYPE html>350<html lang="[project locale, e.g. en, ro, fr — see Internationalization section]">351<head>352<meta charset="UTF-8">353<meta name="viewport" content="width=device-width, initial-scale=1.0">354<title>UC-XXX — [Use Case Name] — [Project] Design</title>355<script src="https://cdn.tailwindcss.com"></script>356<link rel="preconnect" href="https://fonts.googleapis.com">357<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">358<script src="current-tailwind-config.js"></script>359<link rel="stylesheet" href="current-theme.css">360</head>361<body class="bg-[neutral]-100 text-[primary]-800 antialiased">362363<div class="max-w-[1400px] mx-auto px-6 py-8">364365 <!-- Design Header -->366 <div class="design-header">367 <h1>UC-XXX — [Use Case Name]</h1>368 <p>[Brief description of what this screen/flow accomplishes]</p>369 <div class="design-meta">370 <span>Actor: <strong>[Primary Actor]</strong></span>371 <span>Route: <strong>[URL route]</strong></span>372 <span>Priority: <strong>[Priority]</strong></span>373 </div>374 </div>375376 <!-- ============================================================== -->377 <!-- SECTION 1: [Section Name] -->378 <!-- ============================================================== -->379 <div class="design-section-divider"></div>380 <div class="design-section-title">1. [Section Name]</div>381382 <div class="design-annotation">383 <strong>[Annotation type]:</strong> [Description of the section's purpose,384 layout, behavior, and key interactions]385 </div>386387 <div class="design-screen">388 <!-- Actual screen content using Tailwind utility classes -->389 <!-- Use the theme's semantic color names (e.g., bg-[primary]-800, text-[accent]-500) -->390 </div>391392 <div class="design-annotation">393 <strong>Data mapping:</strong> [Entity-to-field mappings, navigation targets,394 API endpoints]395 </div>396397 <!-- Repeat sections for each part of the screen -->398399 <!-- ============================================================== -->400 <!-- STATES -->401 <!-- ============================================================== -->402 <div class="design-section-divider"></div>403 <div class="design-section-title">States</div>404405 <!-- Loading state -->406 <div class="design-annotation">407 <strong>Loading:</strong> [What the user sees while data loads]408 </div>409 <div class="design-screen">410 <!-- Loading skeleton / spinner -->411 </div>412413 <!-- Empty state -->414 <div class="design-annotation">415 <strong>Empty:</strong> [What the user sees when there is no data]416 </div>417 <div class="design-screen">418 <!-- Empty state content -->419 </div>420421 <!-- Error state -->422 <div class="design-annotation">423 <strong>Error:</strong> [What the user sees on failure — map to Alternative Flows]424 </div>425 <div class="design-screen">426 <!-- Error state content -->427 </div>428429 <!-- Success state -->430 <div class="design-annotation">431 <strong>Success:</strong> [What the user sees after successful action]432 </div>433 <div class="design-screen">434 <!-- Success state content -->435 </div>436437</div>438</body>439</html>440```441442## Data Attribute Reference443444| Attribute | Purpose | Example |445|-----------|---------|---------|446| `data-uc-step="N"` | Maps element to use case Main Success Scenario step N | `data-uc-step="3"` |447| `data-uc-alt="N"` | Maps element to Alternative Flow N | `data-uc-alt="2"` |448| `data-entity="Entity.attr"` | Maps field to entity model attribute | `data-entity="User.email"` |449450## Design Principles451452- **Wireframe-faithful** — The layout, component placement, and navigation structure must match453 the wireframe. Do not invent layouts.454- **Mobile-explicit** — Every design includes a dedicated Mobile Layout section. Do not assume455 responsiveness works automatically — mobile requires explicit decisions about navigation,456 layout reflows, and component adaptations.457- **CSS-separated theming** — All visual identity (colors, fonts, spacing tokens) lives in458 external CSS theme files and Tailwind configs. HTML never contains hardcoded brand values.459 Changing the theme = swapping CSS files. This is the most important architectural principle.460- **Semantic HTML + Tailwind** — Use appropriate elements (`form`, `table`, `nav`, `button`,461 `input`) styled with Tailwind utility classes using the theme's semantic color names (four462 palettes: primary, accent, neutral, highlight — with evocative names derived from the wireframe).463 Custom component styles use CSS custom properties from the theme.464- **All states visible** — Every state (default, loading, empty, error, success) is rendered as a465 visible section. This makes the design a complete reference — no hidden requirements.466- **Traceable** — Every interactive element traces back to a use case step via `data-uc-step`.467 Every data field traces to the entity model via `data-entity`.468- **Section-by-section layout** — Each logical section of the screen gets its own469 `design-section-divider` + `design-section-title` + `design-annotation` + `design-screen`470 block, making the design easy to review and implement incrementally.471472## Theme CSS Structure473474Each theme CSS file contains the **complete** visual identity. All theme files for a project share475identical structure but differ in `:root` token values. The theme name reflects the wireframe's476visual language (e.g., `ocean-theme-001.css` for a blue palette, `ember-theme-001.css` for warm tones).477478### Required sections479480```css481/* ── Reset & Base ── */482/* box-sizing, body font, heading font families */483484/* ── CSS Custom Properties (Theme Tokens) ── */485:root {486 /* Color palettes: --[primary]-*, --[accent]-*, --[neutral]-*, --[highlight]-* (50-900 scale) */487 /* Semantic aliases: --bg-page, --bg-card, --text-primary, --accent, etc. */488 /* Sizing: --radius-*, --shadow-*, --nav-height */489}490491/* ── Grain Overlay ── */492/* ── Custom Scrollbar ── */493/* ── Animations ── (fadeUp, fadeIn, scaleIn, slideRight, float, pulse-ring, shimmer) */494/* ── Page Transitions ── */495/* ── Component styles ── (hero-blob, card-hover, tab-link, toggle-switch, etc.) */496/* ── Status Chips ── */497/* ── Language Switcher ── */498/* ── Design Artifact classes ── (design-header, design-section-divider, design-annotation,499 design-screen, design-data-table, design-state-label) */500```501502### Semantic color names503504Each project defines four palette names derived from the wireframe's visual identity. All themes505within the same project use the same four names so HTML never changes — only the `:root` values506differ between themes.507508| Role | Purpose | Example (green theme) | Example (ocean theme) |509|------|---------|----------------------|----------------------|510| **Primary** | Main brand color | `forest` (emerald scale) | `ocean` (deep blue scale) |511| **Accent** | Secondary/accent color | `coral` (orange/amber) | `azure` (sky blue) |512| **Neutral** | Background/surface neutrals | `cream` (green-tinted) | `mist` (blue-tinted) |513| **Highlight** | Premium/highlight color | `gold` (true gold) | `copper` (warm metallic) |514515The HTML always writes `bg-[primary]-600` or `var(--[primary]-600)` using the project's chosen516palette names — the actual rendered color depends entirely on which theme CSS is active.517518> **Note:** The examples in this skill's `examples/` directory use `forest`/`coral`/`cream`/`gold`519> as their palette names. These are specific to the green example theme, not universal defaults.520> Your project's palette names should reflect its own wireframe.
nexadevapp