From dux
Generates individual production-quality HTML screens from DESIGN.md plus a brief. Use when the user says 'generate a screen', 'build screens from PRD', or selects SC from Mayasura's menu.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dux:dux-screenThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Generates one or more standalone HTML/CSS/JS screens that materialize the project's `DESIGN.md` into a working surface a developer can lift wholesale. Output is self-contained — Tailwind CSS via Play CDN, semantic markup, AA-passing color pairs, and an inline accessibility self-check block.
Generates one or more standalone HTML/CSS/JS screens that materialize the project's DESIGN.md into a working surface a developer can lift wholesale. Output is self-contained — Tailwind CSS via Play CDN, semantic markup, AA-passing color pairs, and an inline accessibility self-check block.
Two modes:
bmad-create-ux-design output) produced sequentially without further interaction.Output lives at {design_output_folder}/screens/. That folder is the workspace: it carries manifest.json (the canonical record of every screen produced), .decision-log.md (load-bearing decisions across sessions), and one folder per screen.
The workflow runs under Mayasura, the Visual Architect — that persona is established by dux-agent-mayasura and carries through unchanged. Do not re-greet, do not break character.
Args: optional brief (single screen) or path to a manifest (batch). --headless triggers batch mode end-to-end.
references/screen-recipe.md) resolve from the skill root.{skill-root} resolves to this skill's installed directory.{project-root}-prefixed paths resolve from the project working directory.{skill-name} resolves to the skill directory's basename.Load module config from {project-root}/_bmad/config.yaml and {project-root}/_bmad/config.user.yaml — root level plus the dux section. Bind:
{design_md_path} from dux.design_md_path (default {project-root}/docs/DESIGN.md){design_output_folder} from dux.design_output_folder (default {project-root}/_bmad-output/design){screens_workspace} = {design_output_folder}/screensRead {design_md_path} into context — every screen reads from it. If the file is missing, exit early with a pointer to dux-design-md (DM); do not generate without a source of truth.
Read {screens_workspace}/manifest.json if present (list of previously produced screens). Read {screens_workspace}/.decision-log.md if present (prior decisions about screen archetypes, recurring patterns, naming). The decision log is canonical memory for this workspace.
Read {design_output_folder}/lint/ directory listing (most recent lint run, if any). If the latest lint report had errors, surface a warning before any generation: "DESIGN.md last linted with N errors at {timestamp}. Proceed anyway, or run DL first?" Do not block — the user may be iterating.
| Situation | Route |
|---|---|
| User provides a single brief (sentence or short paragraph) | Single |
| User provides a manifest path or a list of screens | Batch |
--headless with a --manifest <path> arg | Batch (headless) |
| Neither — user just invoked SC | Ask: single or batch? Offer to read a known PRD location for a screen list. |
In Update intent (regenerate an existing screen), read its prior manifest entry and decision-log notes before regenerating; preserve the slug.
Reserved for Single mode. Batch entries arrive with their own briefs and are sharpened only when the manifest entry is too thin to act on.
A usable screen brief names at minimum:
Bland briefs get one sharp clarifying question per missing dimension, never a guess. "Build the dashboard" → "What's the one number a user is looking at first when this page loads?"
When the brief is sharp, write a one-line summary to the workspace decision log and proceed.
Before writing any HTML, plan against DESIGN.md:
{colors.*} tokens. If the screen needs a value DESIGN.md doesn't have, raise it: offer to extend DESIGN.md via DM, or, if the user explicitly accepts, document the divergence in the workspace decision log and proceed. Never invent a token inline.display-* for the hero, heading-* for sections, body-* for prose, caption for metadata.components.* entries from DESIGN.md compose this screen? List them. If a needed component isn't in DESIGN.md, same gap-handling as palette.## Responsive Behavior apply, and what changes at each? Touch-target rules are inherited from DESIGN.md, not invented.Compute contrast for every meaningful foreground/background pair on the screen against AA. Don't ship a pair that fails. If a planned pair fails, swap the role before generation — don't generate first and fix later. (The math is the same formula dux-design-md-lint uses; the LLM can compute relative luminance from sRGB without a script. If unsure, recommend a quick run of DL first.)
references/screen-recipe.md carries the construction recipe — semantic HTML structure, the Tailwind Play CDN bootstrap, how to inline DESIGN.md tokens as Tailwind theme extensions, and the a11y notes block. Load it now.
For each screen:
signin, dashboard-overview, settings-billing). Slug collisions append -2, -3, etc.{screens_workspace}/{slug}/.index.html (happy-path screen). If variants were requested, write one HTML file per variant alongside (empty.html, loading.html, error.html, success.html).{screens_workspace}/manifest.json (see Manifest Format).Single mode walks one screen at a time, showing the planned palette/type/composition before writing, then offering a review. Batch mode produces all screens sequentially without prompting; questions become decision-log entries with rationale.
After each screen is written, run a self-check before moving on:
index.html).<main>. <nav>, <header>, <footer> when the screen has them. Buttons are <button>, links are <a>, form fields use real <label> association.Failed self-checks block the screen from being marked complete in the manifest. Fix and re-emit.
Single mode: show the screen path, ask whether to open it, and offer follow-up (another screen, batch from a list, or hand to DM if a DESIGN.md extension was queued).
Batch mode: summary table — slug, variants written, any deferred extensions to DESIGN.md, any contrast warnings the user opted into.
Headless mode: emit JSON to stdout (see Headless Mode below).
{screens_workspace}/manifest.json:
{
"design_md": "{design_md_path}",
"design_md_hash": "<sha256 of DESIGN.md at time of last write>",
"screens": [
{
"slug": "signin",
"title": "Sign in",
"brief": "One-line summary used to generate this screen",
"purpose": "...",
"primary_action": "...",
"variants": ["index", "error"],
"components_used": ["button-primary", "card", "input"],
"responsive_breakpoints": ["mobile", "desktop"],
"design_md_extensions_requested": [],
"created": "<iso8601>",
"updated": "<iso8601>"
}
]
}
When regenerating an existing screen, preserve the slug and created, update updated. Compute design_md_hash so future invocations can tell whether DESIGN.md drifted under the manifest.
Accepts a manifest in the same shape on input (typically with brief/purpose/primary_action filled in but no created/variants yet — those are written as each screen completes). Common sources:
bmad-create-ux-design output (when installed).Each entry runs through Stages 2–4. A failure on one screen (missing required brief fields, DESIGN.md gap the user did not authorize, AA contrast that cannot be resolved) is recorded as a blocked entry in the manifest and the batch continues to the next screen. The summary lists blocked entries with the reason.
--headless --manifest <path> runs batch mode end-to-end without conversation. Every non-obvious decision is recorded in the workspace decision log with an assumption tag.
Emit JSON on stdout:
{
"status": "complete" | "partial",
"screens_written": <count>,
"screens_blocked": <count>,
"workspace": "{screens_workspace}",
"manifest": "{screens_workspace}/manifest.json",
"design_md": "{design_md_path}"
}
Exit code:
0 if screens_blocked == 01 if any screen blocked (manifest carries the reasons)<button> not <div role="button">. <form> not a stack of divs with onClick. Labels associated with inputs by for/id.dux-agent-mayasura. Do not re-greet, do not break character.Provides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.
npx claudepluginhub yash-1511/bmad-dux-visual-architect --plugin dux