Design Screens

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 CSS
• current-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)
├── -001.css           # Main theme derived from wireframe (CSS custom properties + components)
├── -tailwind-config.js# Main Tailwind color/font config
├── -001.css            # Optional alternative theme variant
├── -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('-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 `. 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

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

1. Set the lang attribute on `` 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.

1. Detect the project locale automatically. Check these sources in order:

• The project's CLAUDE.md for the marker `` (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"

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

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

Înregistrează-te
Adresă de email

Câmpul este obligatoriu
Încărcați documentele necesare
Verificare în curs de procesare

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 `` block — token definitions belong

in the theme CSS files only. The HTML `` 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

1. Read the use case specification from docs/use_cases/UC-XXX.md
2. Read the entity model from docs/entity_model.md (if applicable)
3. Read the example files from this skill's examples/ directory to understand the expected

output format, HTML structure, and theming patterns

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

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

1. 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-.png (e.g., UC-001-overview.png, UC-001-form-screen.png). Create the docs/snapshots/ directory if it does not exist.

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

1. 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-.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 `` suffix

1. Close the Playwright browser

Phase 3 — Produce the HTML design artifact

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

1. 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 `` — never Markdown.

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

1. Include a navigation flow section showing how screens connect
2. Include responsive behavior using Tailwind responsive prefixes and CSS media queries
3. 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 ( Mobile Layout (

Navigation: [How nav transforms — hamburger, drawer, etc.]

Layout changes:

[Change 1 — e.g., "2-column grid → single column stack"] [Change 2 — e.g., "Sidebar collapses into bottom sheet"] [Change 3 — e.g., "Data table → card list with key fields only"]

Touch targets: All interactive elements meet 44x44px minimum. Gestures: [Any swipe, pull-to-refresh, or other mobile gestures]

## HTML Structure

The design HTML must follow this structure:

```html

UC-XXX — [Use Case Name] — [Project] Design

  
  
    UC-XXX — [Use Case Name]
    [Brief description of what this screen/flow accomplishes]

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nexadevapp](https://github.com/nexadevapp)
- **Source:** [nexadevapp/nexa-claude-skills-marketplace](https://github.com/nexadevapp/nexa-claude-skills-marketplace)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.