dux-prototype

dux-prototype

Overview

Generates an interactive prototype — a small set of linked HTML screens with shared partials, or a single rich marketing page — that demonstrates the project's DESIGN.md in motion. Output is self-contained: Tailwind via Play CDN, semantic markup, AA-passing color pairs, tasteful motion tuned to the DESIGN.md voice.

Two modes:

• Flow — a small set of linked screens (e.g. landing → signup → dashboard) with shared header/footer partials and a single tokenized Tailwind theme. The point: prove the system reads as one coherent product across pages.
• Marketing — a single rich page (hero, value props, social proof, CTA). The point: prove the brand has a voice when it stretches.

A prototype is a demonstration, not a real app. Dead links inside a finished flow are fine; honest is better than fake.

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 (one paragraph), mode flag (--flow / --marketing). Mode is inferred when not given.

Conventions

• Bare paths (e.g. references/prototype-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)
• {prototypes_workspace} = {design_output_folder}/prototypes

Read {design_md_path} into context. If missing, exit early with a pointer to dux-design-md (DM); a prototype without a source of truth is just generic UI.

Read {design_output_folder}/lint/ for the most recent lint report. If the latest run had errors, surface a soft warning before generating: "DESIGN.md last linted with N errors. Proceed, or run DL first?" Do not block — users iterating on DESIGN.md often want a preview.

Prototype-level conventions (Tailwind Play CDN, semantic HTML rules, theme-extension shape, a11y notes block, token-fidelity floor) are shared with dux-screen. See references/prototype-recipe.md for the differences that apply to prototypes specifically — the screen-level recipe is referenced inline there.

Intent Routing

Brief signal	Route
"Landing page", "marketing site", "splash"	Marketing
"Flow", "signup flow", "onboarding", "linked screens", or names 2+ screens	Flow
Ambiguous	Ask one sharp question: "Are we mocking a single rich page (marketing) or a linked flow across screens?"
--marketing / --flow flag	Honored verbatim.

In Update intent (rebuild an existing prototype), read its workspace .decision-log.md before regenerating and preserve the slug.

Stage 1 — Sharpen the Brief

A usable prototype brief — for either mode — names at minimum:

• Audience and stance — who is this demo for, and what should it say? A demo for a brand pivot reads differently from a demo for a new product launch.
• The voltage moment — the one thing this prototype should make the viewer feel. If marketing: which value prop carries the page? If flow: which screen is the climax?
• Specific reference, not a category — "build a landing page like Vercel's homepage in 2024, but our voltage instead of theirs" beats "build a modern marketing page". Bland references get the same DM-style push-back: name a designer, a brand, a year, a movement, or accept Mayasura's call.

For Flow:

• Screen list and order — landing → signup → dashboard, or whatever the flow is. A list, not a paragraph.
• Shared partials — header, footer, side-nav, any element that recurs. These get extracted, not duplicated.

For Marketing:

• Section list — hero, value bullets, feature deep-dive, social proof, pricing, footer CTA. A list of the sections the page commits to.

Bland briefs get one sharp clarifying question per missing dimension. Never guess at the voltage — pick the wrong moment and the whole demo lies.

When the brief is sharp, write a one-line summary to the workspace decision log and proceed.

Stage 2 — Plan the Prototype

Before writing any HTML, plan against DESIGN.md:

• Palette — which {colors.*} roles power this prototype. If a needed role is missing, raise it (offer to extend DESIGN.md via DM) — never invent.
• Typography roles per region — display-* for the hero, heading-* for sections, body-* for prose, caption for metadata, button for CTAs.
• Component composition — list every components.* entry the prototype uses. If a needed component isn't in DESIGN.md, same gap-handling as palette.
• Responsive plan — honor DESIGN.md ## Responsive Behavior exactly. Touch targets inherit from DESIGN.md, not invented here.
• Motion language — Flow mode often needs transitions between pages or in-page state changes; Marketing often wants a hero reveal or a scroll-cued highlight. If DESIGN.md declares motion tokens (durations, easings), use them. If it doesn't, pick one motion idiom and apply it consistently. State it in the decision log so the choice is auditable. Don't default to bouncy easings.

For Flow only:

• Shared partials — define partials/header.html, partials/footer.html, partials/nav.html (etc.) and reference them via small fetch+inject scripts so each page stays clean. Don't paste the header into every page; one source.
• Routing — relative anchor links between pages (<a href="./signup.html">). Real dead links inside a finished flow are fine; document them in the a11y notes as "demo-only links".

Compute contrast for every meaningful foreground/background pair against AA. If a planned pair fails, swap roles before generation — don't generate first and fix later.

Stage 3 — Generate the Prototype

references/prototype-recipe.md carries the construction recipe. Load it now.

For Flow:

1. Slugify the brief into kebab-case (onboarding-flow, nav-prototype, dashboard-tour). Slug collisions append -2, -3, etc.
2. Create {prototypes_workspace}/{slug}/.
3. Write index.html (the entry page). For each linked screen, write {screen-slug}.html at the same level. Write partials/ with shared header/footer/nav fragments and a tiny assets/inject.js that fetches them at runtime. Tokenized Tailwind config lives in a shared assets/theme.js loaded by every page — one source of theme, not duplicated.
4. Set up navigation: a primary nav with links between screens; a small "demo prototype — links may be inert" affordance somewhere unobtrusive (e.g. a footer line).
5. Update manifest.json (see Manifest below).

For Marketing:

1. Slugify the brief.
2. Create {prototypes_workspace}/{slug}/.
3. Write a single index.html containing every section. Hero, body, footer all in one file. Section components are inline; no partials needed unless the user also wants a sibling page (FAQ, pricing).
4. Inline the tokenized Tailwind config in <script>tailwind.config = {...}</script> directly in the page.
5. Update manifest.json.

In both modes, append a workspace decision-log entry for any non-obvious choice — a deferred DESIGN.md extension, a component substitution, the motion idiom chosen.

Stage 4 — Verify

Before declaring a prototype complete:

• Every Tailwind utility resolves against the tokenized theme. Arbitrary values (bg-[#abc]) are a defect.
• Every meaningful color pair passes WCAG AA at the appropriate tier.
• Semantic landmarks are present per page: at minimum <main>. <nav>, <header>, <footer> where applicable. Forms use real <label for> / <input id> association.
• Each page carries an inline a11y notes JSON block (<script type="application/json" id="a11y-notes">).
• Flow only: every <a href> between linked screens resolves to a file in the workspace, OR is annotated as a demo-only dead link in the a11y notes.
• Marketing only: the page reads top-to-bottom as one composition, not a stack of independent components.

Failed self-checks block completion. Fix and re-emit.

Stage 5 — Handoff

Show the workspace path and ask whether to open index.html. Offer follow-up: "Want another variant (Flow vs Marketing)? Another section? Hand off to DM to apply a deferred extension?"

If a DESIGN.md extension was deferred to DM during planning, surface that explicitly at handoff: "Two tokens we marked as gaps are still missing in DESIGN.md — want to flow into DM now to add them?"

Manifest Format

{prototypes_workspace}/manifest.json:

{
  "design_md": "{design_md_path}",
  "design_md_hash": "<sha256 of DESIGN.md at time of last write>",
  "prototypes": [
    {
      "slug": "onboarding-flow",
      "title": "Onboarding flow demo",
      "mode": "flow",
      "brief": "One-line summary of the brief.",
      "audience": "...",
      "voltage_moment": "...",
      "screens": ["index", "signup", "verify", "welcome"],
      "shared_partials": ["header", "footer"],
      "sections": null,
      "components_used": ["button-primary", "card", "input"],
      "motion_idiom": "fade-in on scroll, 200ms ease-out",
      "design_md_extensions_requested": [],
      "created": "<iso8601>",
      "updated": "<iso8601>"
    }
  ]
}

mode is "flow" or "marketing". For marketing prototypes, populate sections and leave screens/shared_partials null (or vice versa for flow).

Headless Mode

Not supported in v1. The marker is reserved so future versions can add --headless --brief <path> for batch marketing-page generation; the manifest and recipe already support the contract a headless flow would need. Until then, the workflow is interactive only — exit early with a clear message if --headless is passed.

Non-Negotiables

• Tokens are the floor. Every color/type/spacing/radius traces to a DESIGN.md token. Arbitrary Tailwind values are a defect.
• AA is the floor. No prototype ships with body-text contrast under 4.5:1 or large-text under 3:1.
• Semantic HTML. Same rules as dux-screen: <button> not <div role="button">, real <form> structure, <label for> association.
• Self-contained delivery. Tailwind via Play CDN is the only external resource. Everything else is local — partials, theme, JS, any imagery.
• One theme source per prototype. Flow mode shares assets/theme.js; marketing inlines it once. The same theme MUST be applied to every page in a flow — drift between pages of the same prototype is a defect.
• Mayasura persona. Carries through from dux-agent-mayasura. Do not re-greet, do not break character.