--- title: Wireframe reference description: Shape and content rules for .claude/wireframes/.md files --- # Wireframe reference Applies to per-surface entries under `.claude/wireframes/`. Skip for `index.md`, which is regenerated by `aitk indexes regen`. A wireframe file captures the spatial layout and interaction intent of one UI surface. It is not an implementation log. The check for any single line: would it still be true if the surface were rebuilt in a different framework? If not, it belongs in `.claude/context/`. ## Scope Governs per-surface wireframe entries under `.claude/wireframes/`: layout, variants, on-screen copy, and interaction intent. Does not govern: - Tokens, typography, spacing, and the rest of the visual system: `design.md` - The mechanism behind a surface: `context.md` - Voice, rhythm, and sentence construction in wireframe prose: the `write-human` skill - Punctuation, formatting, and word choice in wireframe prose: `markdown.md` ## What a working wireframe looks like A wireframe works when someone can rebuild the surface from it without opening the components: - What is on screen, and where does it sit relative to everything else? - Which states can a visitor reach, and what does each one look like? - What does it say, word for word? A wireframe that fails these is non-conforming regardless of whether it satisfies every section rule below. The fences are the means. These three questions are the test. ## Frontmatter - `title` (required): sentence case, names the surface (`Header`, `Section nav`, `Footer`). - `description` (required): one line on when and where the surface appears. Both fields feed `.claude/wireframes/index.md` when regenerated. ## Layout - Draw each surface as an ASCII block inside a `plaintext` fence. One fence per distinct layout. - Label regions with `←` annotations. Never use `#` for annotations. - Show a region's role, not its styling. `← status pill` reads better than a class name or hex value. - Keep the grid honest. The ASCII proportions should match the intended widths, since conveying proportion is the wireframe's job. ## Variants - Add a second fence only when the layout itself changes across a breakpoint or state. A wider gutter alone is not a new layout. - Name each variant by what triggers it (`## Desktop (≥768px)`, `## Empty state`), not by an arbitrary label. - One H2 per variant. Do not stack unrelated surfaces in one file. Keep one surface per file, indexed by `index.md`. ## Copy - Carry UI copy verbatim in the ASCII block or a short list below it. The wireframe is the source of truth for on-screen text. - Mark copy that is dynamic or templated so a reader does not treat a placeholder as final text. ## Behavior - Describe interaction intent: what the visitor does, what changes on screen, what each state looks like. - State the rule, not the mechanism. `The rail tracks the active section as the visitor scrolls` is intent. The scroll handler, throttle, and observer margins are not. - Keep it to a short list. A Behavior section longer than the layout is a sign implementation detail has leaked in. ## What moves to .claude/context/ Implementation detail that answers how the surface is built belongs in a `.claude/context/` entry, not the wireframe: - Algorithms, event-handler code, and lifecycle ordering - Framework component names, props, and CSS class or token names - Pixel-exact spacing, timing constants, and observer thresholds - Workarounds and rejected approaches Reference the context entry from the wireframe by path when a reader needs the mechanism. The wireframe stays answerable on its own for layout and intent. ## Maintenance - When a surface's layout or interaction changes, update its wireframe file in the same PR. A wireframe showing a defunct layout is worse than none. - The Behavior and Copy prose around an ASCII block is prose and follows `markdown.md` and the `write-human` skill. The fenced block itself is not, so a check scoped to prose is the wrong thing to rely on for what sits inside it. ## Template One H2 per layout variant, each holding its own fence. A surface with a single layout carries one. ````markdown --- title: description: --- # ## ```plaintext +------------------------------------------+ | ← | +------------------------------------------+ | | | ← | | | +------------------------------------------+ ``` ## Copy - - : ## Behavior - - ````