# Visual Companion > Explore interactive UI structure before requirements. Use when a concept exists and the team needs to discuss and decide the rough shape of the interface: sidepanel vs modal vs drawer vs split view vs wizard vs dedicated page, navigation model, screen flow, and interaction container. Starts with conversational discovery questions, then produces multiple clickable low-fidelity HTML approaches grounded in the existing app, then returns to conversation for selection and iteration. Not for polished visual design, final mockups, colors/typography, or detailed acceptance criteria. - Skill: `silviobeer/visual-companion` (Agent Skill) - Install (CLI): `npx skillmds@latest add silviobeer/visual-companion` - Raw SKILL.md: https://api.skillmd.com/api/skills/silviobeer/visual-companion/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: silviobeer (https://skillmd.com/u/silviobeer) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/silviobeer/visual-companion --- # Visual Companion — Interactive Layout Exploration Turn a UI concept into **multiple rough, clickable layout approaches** so the team can decide what the interface should broadly feel like before requirements are written. Do NOT write production code, define colors/typography, create final components, or write detailed acceptance criteria. This step produces disposable low-fidelity exploration artifacts only. ## Purpose Bridge concept and requirements by answering: **What is the right UI shape?** Examples: - Sidepanel vs modal vs full page - Drawer vs inline editor vs split view - Wizard vs single-page form - Sidebar navigation vs tabs vs contextual actions - Master-detail vs list/detail pages The output is not "the design". It is a decision aid for requirements. ## Decomposed PROJ Handling Visual Companion normally runs for one PROJ at a time. If the concept says the seed was decomposed into sibling PROJs: - Read the `Decomposition Context` in the concept and keep this exploration scoped to the current PROJ's user outcome. - Mention sibling PROJs only as context, dependencies, or future navigation/entry points. - Do not design screens or flows that belong to sibling PROJs unless the user explicitly asks for a combined UI review. - If several sibling PROJs are tightly linked in the same UI, the shared **design language** may be handled once by `frontend-design` for the PROJ family; this skill still records the current PROJ's layout decision. - Record any cross-PROJ UI dependency in `layout-decision.md` so `ui-mockup` and `requirements-engineer` do not accidentally absorb sibling scope. ## Required Outputs Write all outputs to `specs/PROJ--/1b_visual-companion/`: 1. `layout-exploration.html` — one interactive HTML file with 3-4 clickable layout approaches. 2. `layout-decision.md` — summary, project mode, trade-off matrix, recommendation, and open decisions. Commit with: ```bash docs(PROJ-): explore UI layout approaches for ``` ## Workflow ### 1. Read Concept And Existing UI Read the concept doc: ```text specs/PROJ--/1_brainstorm/PROJ--concept.md ``` Then inspect the existing app so the exploration fits what is already there: - Routes: `src/app`, `src/pages`, router files - Layout shells: app layouts, dashboard layouts, nav components - Existing interaction containers: modal, dialog, drawer, sidepanel, sheet, popover, tabs, command palette, wizard/stepper - Components: `src/components`, `src/features/*/components`, `docs/components.md` - Design/system hints: `docs/DESIGN-SYSTEM.md`, `docs/TECHNICAL.md`, `AGENTS.md`, existing CSS/Tailwind/component conventions Note the design system state explicitly — this is the earliest point where it is cheap to decide, and every later step (1c, 1d, P0 preflight, the wave gate) reads the outcome instead of re-asking: - `docs/DESIGN-SYSTEM.md` present, missing, or over its 80-line cap - `docs/components.md` generated (carries the `GENERATED by` marker), still hand-written from before the generator, or absent while components exist Summarize the reusable patterns found in `layout-decision.md` under `Existing UI Patterns`. On the **discovery track there is no codebase to inspect**. If `specs/PROJ--/0_context/existing-state.md` exists (brownfield discovery), use it and the references in `0_context/references/` as the source of existing surfaces, navigation shell, and design system instead of scanning the repo. If no app UI and no captured existing state exist yet, state that clearly (greenfield) and choose common patterns appropriate to the domain. Classify the project mode and document it in `layout-decision.md`: - `greenfield` — no reusable app shell, component set, design tokens, or real screens exist yet. - `brownfield` — existing screens/components/tokens/navigation meaningfully constrain the new feature. - `hybrid` — some reusable structure exists, but meaningful design or component gaps remain. Use concrete evidence, not vibes: - Existing components: `Button`, `Dialog`, `Drawer`, `Table`, `Tabs`, form primitives, etc. - Existing visual language: CSS variables, Tailwind theme, fonts, spacing/radius conventions. - Existing product structure: routes, navigation, app shell, page patterns. - Missing gaps: no overlay primitive, no data-table pattern, no mobile shell, no documented tokens. ### 2. Reflect The Idea And Discuss Before generating artifacts, come back to the conversation with a short reflection and discovery questions. If the scan found UI work without design rules — components in the code but no `docs/DESIGN-SYSTEM.md`, or a greenfield UI project — put it to the user as a decision here rather than assuming: > "This chain expects `docs/DESIGN-SYSTEM.md` (design rules, ≤80 lines) plus a > generated component registry — this repo has neither. Build the design system > in `1c_frontend-design`, or skip and let `ui-mockup` use greyscale wireframes?" Skipping is a valid answer for a repo that predates the design system or hands the visual design to someone else. Record the answer under `## Design System State` either way; later steps must not re-open a decision the user already made. Your message must include: - **Idea reflection:** "I understand the feature as..." - **Existing UI scan:** what app patterns/components/routes you found, or that no UI exists yet - **Project mode:** `greenfield`, `brownfield`, or `hybrid`, with one-sentence reason - **Likely UI tension:** the 1-3 layout decisions that matter most - **Initial candidate directions:** 2-4 rough options worth exploring Then ask targeted questions. Prefer one question at a time unless the user explicitly asks to move fast. Question topics to choose from: - Should the user keep surrounding context visible, or enter a focused task flow? - Is this primarily quick operational work or deep editing/review? - Is mobile use important for this flow? - Is the data shape list/detail, form-heavy, review/approval, timeline, dashboard, or wizard-like? - Should the feature feel like a small addition to an existing screen or a dedicated workspace? - Are destructive/irreversible actions involved? - Does the user expect shareable URLs/deep links? Do not ask generic questions whose answers are already obvious from the concept or app scan. Stop and wait for the user's answer when the layout direction is genuinely ambiguous. After the answer, summarize the decision axes and proceed. ### 3. Identify The UI Decision Extract the 1-3 layout decisions that matter most. Do not enumerate every possible screen yet. Examples: - "Where does object detail open: sidepanel, modal, or full page?" - "Is creation a wizard or an inline form?" - "Does the feature belong in the existing dashboard shell or a focused workspace?" Document assumptions from the conversation in `layout-decision.md`. ### 4. Generate 3-4 Approaches Create distinct approaches. Prefer variants that answer the user's real uncertainty. Common approach set: - **Approach A — Sidepanel / Drawer:** keeps list context visible, good for inspect/edit flows. - **Approach B — Modal / Popup:** focused short task, good for quick create/confirm flows. - **Approach C — Dedicated Page / Full View:** good for deep editing, complex data, shareable URLs. - **Approach D — Split View / Wizard / Inline Flow:** include only if it genuinely fits. Each approach must include: - Best-fit use case - Main flow steps - Pros - Cons - Fit with existing UI patterns - Mobile/responsive concern ### 5. Build One Interactive HTML Prototype Create: ```text specs/PROJ--/1b_visual-companion/layout-exploration.html ``` The file must be self-contained HTML/CSS/JS and runnable by opening it in a browser. No build step. Interaction requirements: - Tabs or segmented control to switch between approaches - Clickable primary actions such as `Create`, `Open details`, `Edit`, `Save`, `Cancel` - State changes that demonstrate the flow: panel opens, modal appears, wizard advances, selected row changes, etc. - A compact "decision notes" area per approach - At least one desktop-width frame and one mobile-width preview or responsive toggle when mobile behavior matters Visual rules: - Low fidelity only: neutral grays, borders, labels, placeholder content - Use rough boxes and real layout relationships, not polished styling - Reuse existing app vocabulary from the scan: route names, object names, component names - Do not invent final copy, colors, typography, or branded visuals ### 6. Write Decision Summary Create: ```text specs/PROJ--/1b_visual-companion/layout-decision.md ``` Use this structure: ```markdown # PROJ- Visual Companion — ## Existing UI Patterns - ... ## Project Mode - Mode: greenfield | brownfield | hybrid - Evidence: - Design/component gaps: ## Design System State - `docs/DESIGN-SYSTEM.md`: present | missing | over cap (/80 lines) - `docs/components.md`: generated | hand-written (migration pending) | absent - Decision: build it in `1c_frontend-design` | skip knowingly () | already exists - Decided with the user on: ## Layout Decision To Make - ... ## Approaches ### A. - Flow: - Pros: - Cons: - Existing-fit: - Mobile: ### B. ... ## Trade-off Matrix | Approach | Speed | Clarity | Complexity | Mobile fit | Existing fit | Risk | |---|---:|---:|---:|---:|---:|---| ## Recommendation ## Shape Brief - Primary job: - User context: - Information shape: - Interaction container: - Existing components to preserve: - New component candidates: - Design constraints: - Anti-goals: ## Conversation Notes - Questions asked: - User answers: - Assumptions: ## Open Decisions For User - ... ``` ### 7. Return To Conversation After generating the HTML and decision summary, return to the conversation. Do not silently continue to the next skill. Your response must: - Link the generated files - Summarize the 3-4 approaches in one line each - State your recommendation - Ask the user to choose, reject, or combine approaches - Offer to iterate the same files based on feedback Good prompt: > "I created an interactive layout exploration at `specs/PROJ--/1b_visual-companion/layout-exploration.html`. Please try the variants and tell me which direction should drive the requirements: A, B, C, or a combination." Iterate by editing the same files. Do not create many `v2` files unless the user explicitly wants history. ### 8. Transition After the user chooses a direction: - Update `layout-decision.md` with `## Selected Direction`. - Then invoke `frontend-design` if the recorded `## Design System State` decision says to build it — the default for `greenfield`, and for `hybrid` with meaningful design-language gaps. - If the user chose to skip knowingly, go to `ui-mockup` directly and tell it to use greyscale wireframes. - Otherwise invoke `ui-mockup` directly for `brownfield`. - The selected layout direction is the required input for `ui-mockup`. Do NOT invoke `requirements-engineer`, `architecture`, or implementation directly from this skill. Do not transition until the user has explicitly selected or approved a direction after seeing the generated exploration. ## Key Principles - **Explore alternatives, then recommend.** The skill must produce multiple approaches, not a single assumed layout. - **Discuss before generating.** Ask the few questions that clarify the layout decision; do not skip straight to artifacts. - **Return after generating.** The generated HTML is the start of the decision conversation, not the end of the skill. - **Interactive beats static.** Demonstrate panels, popups, drawers, tabs, and flow transitions with clickable HTML. - **Grounded in the app.** Existing routes, components, and navigation patterns are constraints, not afterthoughts. - **Coarse before detailed.** Decide containers, flow, and information hierarchy; leave detailed UI to `ui-mockup` and design language to `frontend-design`. - **Decision-oriented.** The artifact should help the user pick a direction quickly. ## What This Step Does NOT Do | Concern | Handled by | |---|---| | Colors, typography, visual identity | `frontend-design` | | Detailed HTML mockups with polished styling | `ui-mockup` | | User stories and acceptance criteria | `requirements-engineer` | | Technical architecture | `architecture` | | Production implementation | `executing` | ## 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.