1---
2name: wireframe-mode
3description: Add a toggleable "wireframe" / "blueprint" / "x-ray" mode to any UI component — a schematic view that reveals the component's hidden mechanics (motion paths, trigger zones, spacing gaps, alignment rails) as an annotated overlay, with a smooth crossfade between the real component and its wireframe. Use this skill whenever the user asks for a wireframe mode, blueprint mode, debug/dev overlay, schematic view, "show the zones", "visualize the mechanics", an exploded/annotated view of a component, or wants to demo/screen-record how a UI component works under the hood. Also use it when building design-tool-style toggles that switch a component between "real" and "skeleton/outline" rendering.
4---
5
6# Wireframe Mode
7
8A recipe for adding a polished, animated wireframe/blueprint mode to a UI
9component. The wireframe view renders the SAME live, interactive component in
10a schematic style — outlines instead of fills, dashed borders, plus annotation
11layers that expose invisible mechanics (interaction zones, motion rails,
12spacing bands). A single toggle crossfades between the two states.
13
14This is not a static mockup generator. The component stays fully functional in
15wireframe mode; only its rendering changes.
16
17## Core principles
18
191. **Never fork the component.** Wireframe is a boolean prop (`wireframe`) on
20 the real component. All geometry/math is shared; only colors, fills, and
21 annotation layers differ. Changing the prop must never remount the
22 component or reset its state (no `key` hacks — see Pitfall 1).
232. **Crossfade, don't swap.** Properties like `border-style: dashed`,
24 `fill: none`, and conditionally-rendered elements cannot be animated.
25 Render BOTH states' elements at all times and animate `opacity` (and
26 colors) instead. 200ms is a good default duration. See
27 `references/recipe.md` → "Crossfade architecture".
283. **Blueprint palette.** Grayish-blue monochrome for structure, with at most
29 2–3 accent colors reserved for annotations:
30 - Structure/outlines/text: `#9aa3b0` family (lighter for text: `#aab2be`)
31 - Interaction zones: blue `#4c8dff` at low alpha
32 - Spacing/gap bands: orange `#f7a942` at low alpha
33 - Guides: `#c3cad4`, dashed
34 Text in wireframe mode should be LIGHTER than the real component's text —
35 it's context, not content.
364. **Annotate the invisible.** The wireframe's value is showing what the real
37 component hides. Typical layers (each fades with the toggle):
38 - **Dashed guide paths** tracing motion rails / travel paths of moving parts
39 - **Hatched or dash-bounded regions** marking trigger/interaction zones
40 (45° `repeating-linear-gradient` hatch, or plain low-alpha fill —
41 ask the user which; both are valid)
42 - **Tinted bands** showing designed spacing/gaps (draw as an SVG
43 rounded-rect ring stroke so it follows corners exactly)
445. **Consistent outline weight.** All outlines must read as the same 1px line
45 centered on the true shape edge, or shapes appear to change size between
46 rendering techniques. This has a subtle trap for SVG stroked shapes — see
47 Pitfall 2.
486. **Hotkey + smooth toggle.** Bind a single key (default `w`) to toggle the
49 mode globally, ignoring keystrokes inside text inputs and when modifier
50 keys are held. Great for live demos and screen recordings.
51## Workflow
52
531. Identify the component's mechanics worth exposing: what moves, what
54 triggers where, what spacing is intentional. Each becomes an annotation
55 layer.
562. Thread a `wireframe` prop through the component. Derive a small set of
57 state-dependent colors (rest/hover/active for both modes) in one place.
583. Convert conditional rendering to always-rendered + opacity crossfade
59 (Principle 2). Group wireframe-only layers in containers with
60 `opacity: wireframe ? 1 : 0; transition: opacity 200ms`.
614. Build the annotation layers in the component's own coordinate space so
62 they adapt automatically when props (radius, sizes, content) change.
635. Add the global hotkey at the app/demo level.
646. Verify: toggle mid-interaction — state must persist, sizes must not
65 visually jump, and every layer must fade rather than pop.
66For concrete code patterns (React/SVG), the coordinate-space gotcha, and the
67full pitfall list, read `references/recipe.md` before writing code.
68
69## Pitfalls (summary — details in references/recipe.md)
70
711. **State reset on toggle/param change**: a changing `key` prop remounts the
72 component and wipes its state. Never key on the toggled props.
732. **SVG stroked-shape outlines look inset**: outlining a stroked path by
74 overlaying a background-colored core produces an outline INSIDE the shape,
75 while `stroke` on a filled path is CENTERED on the edge — the shape looks
76 smaller in one technique. Fix: widen the outer stroke to `T + 1` and use a
77 core of `T - 1` so the visible ring is centered on the true edge.
783. **Border-box vs padding-box coordinates**: absolutely-positioned overlays
79 render relative to the padding box (inside the border); math done in
80 border-box coordinates shifts everything by the border width, asymmetrically.
814. **Untweenable properties**: `border-style`, `stroke-dasharray` presence,
82 `fill: none` — replace with a faded-in duplicate element instead of
83 toggling the property.