| name | ui-mockups |
| description | Create several selectable UI mockup options before implementation for substantial EDHB browser UI additions, Pixi canvas UI refactors, major responsive/layout changes, new design directions, or feature plans that need user choice among visual approaches. Use this skill while planning meaningful frontend presentation work, especially when the user supplies a reference image or Google Stitch export bundle. Do not use for small UI fixes, copy tweaks, already-approved designs, or post-implementation screenshot review. |
UI Mockups
Use this skill before implementation when an EDHB UI change needs visual
direction. The goal is to give the user several concrete options, let them
choose or combine directions, and record that choice in the active ExecPlan
before UI code changes begin.
Boundaries
Use .agents/skills/review-ui-screenshots/SKILL.md after implementation for
the final screenshot UX review. This skill is earlier in the workflow: it
creates candidate mockups and gathers the user's design decision.
Use this skill for substantial Pixi canvas UI additions, larger layout
refactors, major responsive changes, or new visual directions. Do not use it
for small visual fixes, copy edits, already-approved layouts, or backend-only
changes that do not need visual direction.
Use a supplied reference sample for style by default. Copy palette, typography,
spacing rhythm, density, radius, shadows, component feel, and design language.
Do not clone the sample's layout or content unless the user explicitly asks for
that. If the requested EDHB feature needs a different information architecture,
let the feature win.
Workflow
-
Confirm there is an active ExecPlan or create one using PLANS.md.
Mockups must be saved under plans/<plan-stem>/mockups/, where
<plan-stem> is the ExecPlan filename without .md.
-
Read DESIGN.md, the active ExecPlan, and the EDHB UI files or screenshots
that describe the current surface. For Pixi work, relevant files often live
in src/frontend/ and screenshot artifacts often live under the active
plan's screenshots/ folder.
-
If the user supplied a sample, confirm it is safe to copy into the
repository and contains no secrets or restricted third-party material.
-
Write a short prompt file that describes the feature outcome, target
surface, primary workflow, platform, important states, and constraints.
Keep the prompt about what the user needs, not implementation details.
-
Run the Stitch tooling from the repository root:
npm run stitch:mockups -- --plan <plan-stem> --prompt-file <prompt.md> --reference <sample-path> --variants 4 --device DESKTOP
Omit --reference only when no visual sample exists. Use --device MOBILE,
TABLET, or AGNOSTIC when the main design question is device-specific.
-
Inspect plans/<plan-stem>/mockups/index.html,
plans/<plan-stem>/mockups/index.md, the generated PNG files, and the
generated HTML files when available. The Stitch CLI prints a clickable
preview link when generation completes; include that exact link in the
user-facing update so the user can open the mockups directly in a browser.
On WSL, the link must use the Windows-browser-accessible
file://wsl.localhost/<distro>/... form, not file:///home/.... Present the
user with a concise option matrix that covers visual direction, EDHB
workflow fit, risks, and the option you recommend.
-
Stop for the user's choice. Do not implement the UI until the user selects
an option, asks for a hybrid, or requests another mockup round.
-
Record the selected direction in plans/<plan-stem>/mockups/decision.md and
in the ExecPlan Decision Log, Plan of Work, and visual-evidence notes.
Use the selected mockup files as implementation references.
Reference Inputs
The v1 tooling supports local files and local folders only:
- Image file:
.png, .jpg, .jpeg, or .webp.
- Google Stitch export bundle: a folder containing a preview image plus
optional HTML and CSS.
- HTML or CSS file: useful when the visual reference is a code export without
a screenshot.
When a Stitch export bundle includes both image and HTML/CSS, prefer it over an
image-only sample. The image gives visual intent; the HTML/CSS gives exact
colors, spacing, fonts, radius, and shadow values that reduce guesswork.
Tooling Notes
The command requires STITCH_API_KEY, or STITCH_ACCESS_TOKEN with
GOOGLE_CLOUD_PROJECT, in the local environment. Before declaring credentials
missing, check for an untracked repo-root .env file and load it for the
current shell without printing secret values:
set -a
. ./.env
set +a
Then run npm run stitch:mockups from that same shell. If credentials are still
missing after loading .env, explain that live Stitch generation could not run
and do not fake generated mockups.
The command copies only supported reference artifacts into
plans/<plan-stem>/mockups/reference/ and extracts design-language clues into
reference-style.json and reference-style.md. Generated options are saved as
option-01.png, option-01.html, option-01-notes.md, and matching numbered
files. It also writes index.html for browser preview and index.md for
plain-text review. When running under WSL, the CLI should format the preview
URL through wsl.localhost so Windows 11 browsers can open the generated page.
Pre-implementation mockups do not replace EDHB's screenshot requirements. Any
implemented frontend-visible change still needs baseline screenshots, matching
after screenshots, and a review-ui-screenshots pass when PLANS.md requires
visual evidence.
