# UI Mockup > Create lightweight HTML mockups, a visual sitemap, and a UI implementation handoff before requirements. Use after visual-companion and optional frontend-design when: (1) UI flows need to be visualized before requirements and architecture, (2) a page/screen sitemap is needed, (3) stakeholders need visual feedback before user stories are finalized. Not for: requirements, component libraries, technical architecture, or production UI code. - Skill: `silviobeer/ui-mockup` (Agent Skill) - Install (CLI): `npx skillmds@latest add silviobeer/ui-mockup` - Raw SKILL.md: https://api.skillmd.com/api/skills/silviobeer/ui-mockup/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: silviobeer (https://skillmd.com/u/silviobeer) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/silviobeer/ui-mockup --- # UI Mockup And Sitemap Generator Create lightweight HTML mockups and a visual sitemap from the concept and the approved Visual Companion decision. This skill is visual and structural only: no technical architecture and no acceptance criteria. For UI features, this skill is required before `requirements-engineer`. Pure backend/API features skip it. Also create a compact `implementation-handoff.md` so requirements, architecture, planning, and execution can consume the visual decision without interpreting the HTML mockups directly. ## Decomposed PROJ Handling Work one PROJ at a time. If the concept contains `Decomposition Context`: - Build mockups and sitemap only for the current PROJ. - Mark sibling PROJs only as context, navigation, dependencies, or future scope. - Do not design screens or states for sibling PROJs unless the user explicitly asks for a combined UI review. - If `frontend-design` created a shared design language for the PROJ family, use that canonical file even when it lives in a sibling PROJ. - If the current PROJ needs a local variation, read or create `1c_design/design-delta.md` and document it in the implementation handoff. ## Principles - **Lightweight:** Single HTML files, inline CSS, small vanilla JavaScript, no external dependencies. - **DRY mockups:** Reuse CSS classes, HTML patterns, and small JS helpers instead of writing one-off code per screen. - **Interactive when useful:** Clickable flows, tabs, side panels, modals, drawers, wizard steps, and state changes are encouraged when they clarify the UI. - **Simple:** No frameworks, no build step, no complex animation. - **Design-aware:** If an existing UI exists, scan and reuse colors, fonts, spacing, CSS variables, Tailwind config, and design tokens. - **Component-aware:** Prefer existing components and patterns; mark new UI pieces as candidates. - **Component-near, not pixel-perfect:** Approximate existing React components structurally and visually. Label intended reuse clearly. - **Show states:** Include normal, empty, loading, error, and success states where relevant. ## Fidelity Modes Pick the fidelity from the project mode and design references. State the chosen mode to the user before building. - **Wireframe (greyscale):** Default for greenfield projects with no design system, especially when a UI/UX expert takes over the visual design later. Use a neutral greyscale palette, very small border radii (about 2–4px), no brand colors, no decorative imagery. Communicate structure, hierarchy, flows, and states — not visual identity. This keeps mockups cheap to change during iteration and avoids implying final styling. - **Design-system:** Use when an existing design system is present (brownfield) or when `frontend-design` produced a `design-language.md`. Adopt the existing or defined tokens, colors, typography, spacing, and radii so the mockups read as the real product. - **Hybrid:** Apply the existing design system to known areas and fall back to greyscale wireframe for the documented gaps. If `1c_frontend-design` was skipped for a greenfield project, default to **Wireframe (greyscale)** rather than inventing a visual identity. ## Input Read these inputs: 1. Concept: `specs/PROJ--/1_brainstorm/PROJ--concept.md` 2. Visual Companion decision: `specs/PROJ--/1b_visual-companion/layout-decision.md` 3. Visual Companion prototype: `specs/PROJ--/1b_visual-companion/layout-exploration.html` 4. Optional design language: `specs/PROJ--/1c_design/design-language.md` or a canonical sibling design language that lists the current PROJ under `Applies To` 5. Optional design delta: `specs/PROJ--/1c_design/design-delta.md` 6. Optional brownfield as-is reference (discovery track): `specs/PROJ--/0_context/existing-state.md` and `0_context/references/` The selected direction in `layout-decision.md` is binding. Refine it into concrete screens and states. Do not invent alternate layout containers unless the user explicitly asks. Read these sections especially: - `Project Mode` (`greenfield`, `brownfield`, `hybrid`) - `Selected Direction` - `Shape Brief` - `Existing UI Patterns` - `Design/component gaps` ## Workflow ### 1. Detect Design System, Components, And App Shell Load design references: - If `1c_design/design-language.md` exists, use it as the primary design reference. - If the concept or layout decision references a canonical sibling design language, load it too and apply only local `design-delta.md` differences. - Check `docs/DESIGN-SYSTEM.md` (the curated design system baseline). If present, reuse its tokens, scales, patterns, and do/don't rules, and read `docs/components.md` for the component inventory. - For composed layouts — form, empty/loading/error state, page shell — open the showcase (`/dev/components#pattern-`, or `1c_design/component-showcase.html` before the scaffold) and copy the rendered pattern. Do not invent a layout that a pattern already fixes; that is how two screens end up with two different forms. If no design reference exists, scan: - `tailwind.config.*` - CSS custom properties such as `--color-*` and `--font-*` - `globals.css` or `theme.css` - Existing HTML/CSS files On the **discovery track there is no codebase to scan**. Use `0_context/existing-state.md` and the screenshots/links in `0_context/references/` as the design source instead: derive colors, typography, spacing, radii, and component patterns from the captured design system. This is the design-system fidelity input when there are no config files. If style evidence exists (config, design language, or captured existing state), reuse it in **design-system mode**. Otherwise, for greenfield discovery, use **Wireframe (greyscale)** rather than inventing a visual identity. Detect existing components before building mockups: - `docs/components.md` - `src/components/**` - `src/features/*/components/**` - UI library hints in `package.json` such as shadcn, Radix, MUI, Chakra, or Headless UI - Existing dialog, modal, drawer, table, form, button, card, badge, tabs, and command components Keep a short internal component map: ```markdown Reuse candidates: - Button: `src/components/ui/button.tsx` - Dialog: `src/components/ui/dialog.tsx` - DataTable: `src/components/data-table.tsx` New component candidates: - BulkActionBar — no matching batch-action component found ``` Label important mockup elements: - `[Reuse: Button] Save` - `[Reuse: Dialog] Confirm delete` - `[Reuse: DataTable] Orders` - `[New candidate: BulkActionBar]` Do not silently invent UI pieces. If no existing component fits, mark `New candidate:` and briefly explain why. **Design system excursion.** In design-system mode (`docs/DESIGN-SYSTEM.md` exists, or a real component library is in use), a `New candidate:` is not a mockup problem — it is a gap in the design system. Do not solve it with one-off CSS in the mockup. Instead: 1. Re-check `docs/components.md`: can an existing component cover it as a new **variant** (size, tone, state)? Variant beats new component. 2. Ask the user to confirm the gap and the choice (variant vs. new component). 3. Run the extension procedure from `1c_frontend-design` → *Extending The Design System* for that one piece: define it, implement it in the chosen stack, register it in `docs/components.md`, and add its showcase section under `id=""`. 4. Then use it in the mockup by its registered name. Keep the excursion narrow: one component, no revisiting of tokens or unrelated catalog entries. In **wireframe (greyscale)** mode there is no catalog yet — keep marking candidates and let `1c_frontend-design` or `5_executing` build them later. Detect the app shell: - Header/topbar: position, height, background color, breadcrumb structure - Sidebar: width, color, navigation items, active state - Main content area: padding, scrolling, max width If an app shell exists, embed every mockup inside it. If no shell exists, for example a landing or login page, mock up the screen without a shell. ### 2. Create The Sitemap Create `specs/PROJ--/1d_mockups/sitemap.html`. The sitemap must show: - All pages/screens as boxes - Parent-child hierarchy - Navigation flows with arrows - User flows with visual grouping - Role mapping for pages where relevant Use plain HTML/CSS boxes and links. Each sitemap box links to its mockup file. ### 3. Create Screen Mockups Create one HTML file per screen in `specs/PROJ--/1d_mockups/`. Each mockup includes: - App shell when detected: static header, sidebar, and content area - Mockup header: page name, PROJ reference, and link back to the sitemap - Navigation links to connected mockup pages - Main content with placeholder copy, images, forms, and data - Component labels for important UI elements - Relevant vanilla-JS interactions - State sections for `[Normal State]`, `[Empty State]`, `[Loading State]`, and `[Error State]` - Source reference labels for concept sections, Visual Companion decisions, or mockup assumptions Do not add acceptance-criteria labels; requirements are written after this skill. Interaction rules: - Use only vanilla JS inside the HTML file. - Demonstrate behavior, not final implementation. - No persistence, API calls, or build step. - Link multi-screen flows. Simulate overlays or panels in-place when they are part of the selected Visual Companion direction. Code minimalism: - Use a few reusable primitives such as `.shell`, `.panel`, `.toolbar`, `.button`, `.table`, `.state`, and `.overlay`. - Use `data-*` attributes for interactions, for example `data-open="trend-panel"`. - Use one central JS handler for common actions: open/close overlay, switch tab, next/previous step, select row. - Avoid duplicated markup. If screens share a structure, reuse it with different labels and placeholders. - Keep sample data small: two or three rows/cards are enough. - Avoid long resets or utility-class lists. Before writing, ask yourself: can this mockup be expressed with fewer reusable primitives? ### 4. Review And Iterate With Stakeholders Open the mockups in a browser and ask the user to review: - Is the page structure correct? - Are screens or flows missing? - Do the states fit? Stakeholders typically iterate here by prompting changes directly into the mockups until everyone agrees. Treat this as the primary working loop, not a single pass. Apply requested changes, present the updated mockups, and repeat until the user signals agreement. **Track every change** so the agreed result can later flow back into the concept. Maintain `specs/PROJ--/1d_mockups/iteration-log.md` and append an entry per iteration round: ```markdown # Mockup Iteration Log — PROJ- ## Iteration — - Change: - Driver: - Affects concept: yes (scope) | yes (behavior) | no (presentation-only) - Screen(s): ``` Classify each change's `Affects concept` field honestly: only scope or behavior changes need to flow back into the concept later; presentation-only tweaks stay in the mockups. This log is the input to `concept-sync` (1e). Do not edit the concept doc from this skill. Capture changes in the log; reconciliation happens in `concept-sync`. ### 5. Create The Implementation Handoff Create: ```text specs/PROJ--/1d_mockups/implementation-handoff.md ``` Required structure: ```markdown # PROJ- UI Implementation Handoff — ## Project Mode greenfield | brownfield | hybrid ## Source References - Concept: - Visual Companion decision: - Mockups: - Design language: ## Selected UI Direction [One paragraph describing the selected container/model.] ## Reuse - Component: `path/to/component.tsx` — intended use ## New Component Candidates - ComponentName — why no existing component fits ## Design Tokens And Styling - Use: - Avoid: - Existing app design takes precedence over exact HTML mockup CSS: yes ## Interaction Contract - Interaction: - Required states: - Responsive/mobile behavior: ## Implementation Tolerance - Mockups are structural, not pixel-perfect. - Existing React components and design tokens take precedence over mockup CSS. - Preserve the selected layout direction and interaction contract unless the user approves a change. ## Demo-Only In Mockup - [Things shown only to explain the flow and not required for implementation.] ## Open UI Risks - [Ambiguities or component gaps Architecture/Writing Plans should account for.] ``` The handoff must make clear: - Which existing components must be reused - Which new components may be built - Which tokens, fonts, and colors are binding - Which interactions must be implemented - Where HTML mockup differences are allowed ### 6. Final Review Present `sitemap.html`, the screen mockups, and `implementation-handoff.md` together. Ask the user: - Is the component reuse list correct? - Are the new component candidates accepted? - Are demo-only parts correctly separated? If changes are requested, update mockups and handoff together. ### 7. Handoff After approval: - If the mockups were iterated and the concept may have drifted (any `iteration-log.md` entry with `Affects concept: yes`), recommend `concept-sync` (1e) next so the agreed changes flow back into the concept before requirements. - If nothing affected the concept, recommend `requirements-engineer` (2) directly. Either way, the mockups are required input for user stories, acceptance criteria, and edge cases. ## Completion Checklist - [ ] Design reference loaded when available - [ ] Component registry and existing components scanned - [ ] Important UI elements labeled with `Reuse:` or `New candidate:` - [ ] App shell detected and embedded where applicable - [ ] Sitemap created with all pages and flows - [ ] Mockup created for each screen - [ ] Mockups linked to each other - [ ] Relevant interactions simulated with vanilla JS - [ ] Reusable HTML/CSS/JS primitives used - [ ] Empty, loading, and error states included - [ ] Source references included in mockups - [ ] Fidelity mode chosen and stated (wireframe greyscale / design-system / hybrid) - [ ] `iteration-log.md` maintained across iteration rounds with concept-impact classified - [ ] `implementation-handoff.md` created - [ ] User reviewed and approved mockups and handoff - [ ] Next step recommended: `concept-sync` (1e) if concept drifted, else `requirements-engineer` (2) ## Git Commit Format ```text docs(PROJ-): Add UI mockups and sitemap for ``` Git is optional on the discovery track. If the workspace is not a git repository, skip the commit; the mockup files and `iteration-log.md` are the durable artifacts. ## Legacy Folder Layout PROJ folders created before the layout rename use different subfolder names. Mapping, old → current: `2_visual-companion/` → `1b_visual-companion/` · `4_design/` → `1c_design/` · `5_mockups/` → `1d_mockups/` · `3_PRDs/` → `2_PRDs/` · `8_handoff/` → `2b_handoff/` · `6_plan/` → `3-4_plan/` · `7_progress/` → `5_progress/` If an expected folder is missing but its legacy twin exists, **read from the legacy one and keep writing where the existing files already are**. Never create a second folder next to it — a split PROJ is worse than an old name. Say it once, then continue either way: > "This PROJ uses the old folder layout (``). Rename the folders to the > current names, or continue with the existing layout?" Renaming is a `git mv` per folder plus a search for the old paths in the PROJ's own documents. It is never a precondition for this skill.