dux-screen

dux-screen

Overview

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:

• Single — one screen from a tight brief, walked interactively.
• Batch — a manifest of screens (often produced from a PRD or 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.

Conventions

• Bare paths (e.g. 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.

On Activation

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}/screens

Read {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.

Intent Routing

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.

Stage 1 — Sharpen the Brief

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:

• Purpose — what is this screen for? Not "the dashboard" — "the daily-activity dashboard a user lands on after login".
• Primary action — the one thing the user is expected to do. Used to size the hero CTA.
• Content blocks — what regions appear (header, hero, stats, table, footer, etc.). A list, not a paragraph.
• State — happy-path by default; if variants are wanted, name them now (empty, loading, error, success).
• Audience — power user vs. first-time, signed-in vs. anonymous — affects density and tone.

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.

Stage 2 — Plan the Screen

Before writing any HTML, plan against DESIGN.md:

• Palette — which roles power this screen? Always grounded in {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.
• Type scale — which typography roles for which regions? display-* for the hero, heading-* for sections, body-* for prose, caption for metadata.
• Component composition — which 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 plan — which breakpoints from ## 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.)

Stage 3 — Generate Screens

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:

1. Slugify the brief title into kebab-case (signin, dashboard-overview, settings-billing). Slug collisions append -2, -3, etc.
2. Create {screens_workspace}/{slug}/.
3. Write index.html (happy-path screen). If variants were requested, write one HTML file per variant alongside (empty.html, loading.html, error.html, success.html).
4. Update {screens_workspace}/manifest.json (see Manifest Format).
5. Append a workspace decision-log entry for any non-obvious choice — a palette gap that was deferred, a component substitution, a breakpoint deviation, a state variant that wasn't in the brief but was added on user request.

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.

Stage 4 — Verify

After each screen is written, run a self-check before moving on:

• Every Tailwind utility resolves against the project's tokenized theme (the Play CDN config injected at the top of index.html).
• Every meaningful color pair on the page passes WCAG AA at the appropriate tier (body 4.5:1, large 3:1). Compute and surface the ratios if uncertain.
• Semantic landmarks are present: at minimum <main>. <nav>, <header>, <footer> when the screen has them. Buttons are <button>, links are <a>, form fields use real <label> association.
• The inline a11y notes JSON block is present and accurate.

Failed self-checks block the screen from being marked complete in the manifest. Fix and re-emit.

Stage 5 — Handoff

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

Manifest Format

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

Batch Mode

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:

• A PRD's screen-list section.
• bmad-create-ux-design output (when installed).
• A hand-authored YAML/JSON the user wrote.

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 Mode

--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 == 0
• 1 if any screen blocked (manifest carries the reasons)

Non-Negotiables

• Tokens are the floor. Every color/type/spacing/radius on a screen resolves to a DESIGN.md token. Inventing values is a defect.
• AA is the floor. No screen ships with a body-text contrast under 4.5:1 or large-text under 3:1.
• Semantic HTML. <button> not <div role="button">. <form> not a stack of divs with onClick. Labels associated with inputs by for/id.
• Self-contained output. Tailwind via Play CDN is the only external resource. No bundlers, no other CDNs, no fonts pulled from the web unless DESIGN.md says so.
• Workspace decision log is canonical memory. Every non-obvious call lives there, not in conversation.
• Mayasura persona. Carries through from dux-agent-mayasura. Do not re-greet, do not break character.