refactor(design): move cross-tool wireframe conventions into Designer Denise

design/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "design",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Designer Denise, the design persona. Creates and updates Pencil (.pen) mockups via the Pencil MCP, the Pencil-native counterpart to gstack's HTML-oriented design skills. Every mockup canvas carries a style guide frame. Skills: design:pencil-mockup, design:style-guide.",
   "author": { "name": "Mujtaba Badat", "email": "mj@belalbadat.com" }
 }

design/README.md

@@ -20,7 +20,7 @@ Denise is a basket; more skills (review, variant exploration, and so on) will la
 ## Conventions
 
 - `shared/core.md` carries the Denise persona plus the Pencil ground rules (MCP-only, schema-first via `get_editor_state(include_schema: true)`, the in-memory save model).
-- Canvas layout follows the plugin's bundled `skills/pencil-mockup/references/wireframes.md` (self-contained, so the plugin is portable). It defers, in order, to a project-level `spec/WIREFRAMES.md` and then a workspace-level `~/dev/WIREFRAMES.md` when either exists. Horizontal is a new view, vertical is a state variant, overlap is a hard error, annotations are sticky notes, planned views carry the `🚧 NEW NEW` marker.
+- Canvas layout follows the plugin's bundled `skills/pencil-mockup/references/wireframes.md` (self-contained, so the plugin is portable). It defers to a project-level `spec/WIREFRAMES.md` when one exists. Horizontal is a new view, vertical is a state variant, overlap is a hard error, annotations are sticky notes, planned views carry the `🚧 NEW NEW` marker. The tool-agnostic principles alone (for any future non-Pencil tool) live at `references/wireframes-cross-tool.md`; the Pencil reference is the superset.
 
 ## Requirements
 

design/references/wireframes-cross-tool.md

@@ -0,0 +1,86 @@
+# Cross-tool wireframe conventions
+
+Designer Denise's tool-agnostic canvas principles. They apply to every wireframe file regardless of tool (Pencil `.pen`, Figma, tldraw, Balsamiq, Excalidraw). This is the canonical home for the cross-tool conventions: the tool-specific operating contract (exact MCP calls, stroke values, overlap-check tooling) lives with each tool's skill, not here.
+
+**Precedence (most specific wins).** Defer to a more specific convention file for anything it covers, and fall back to this doc for everything it does not:
+
+1. A project-level `spec/WIREFRAMES.md` in the repo you are working in (most specific).
+2. This file (Denise's cross-tool baseline).
+
+**Pencil operating contract.** For Pencil `.pen` work, the sibling reference `../skills/pencil-mockup/references/wireframes.md` is a self-contained superset: it carries every principle below plus the Pencil operating detail (the `mcp__pencil__*` calls, the orange-stroke JSON, the sticky-note overlap protocol, the style guide frame anatomy). Read that one for Pencil; read this one for any other tool.
+
+---
+
+## Canvas layout axes
+
+- **Horizontal axis (left to right) = new view in the flow.** Each step the user navigates to is its own column to the right of the previous step. Example: `1. Who` -> `1b. Who confirm` -> `1c. Who - new` -> `3a. Preview`.
+- **Vertical axis (top to bottom) = state variant of the same view.** Different states, populated vs empty, hover vs default, sibling branches of the same step, all stack below the original frame in the same column. Example: `1. Who` at the top of column 1, `1d. Who - after adding 2 observers` below it.
+
+When adding a new frame, decide first: is this a new view the user navigates to, or a state variant of an existing view? Then place it accordingly. Never place a new view below another (reads as state variant), never place a state variant to the right (reads as next step in flow).
+
+Naming should match the stacking. If `S1b. Build - bio empty` is a state variant of `S1. Build`, drop the `b` and name it `S1. Build - bio empty` so the column-level prefix matches what's actually stacked.
+
+---
+
+## Overlap is a hard error (no frame may sit on top of another)
+
+**This is the most common mistake when adding or resizing frames, and it must stop.** Two frames may never share canvas space. One pixel of overlap is never allowed. Bounding-box edges may touch only when neither frame renders a visible stroke; if either one does, leave a gap, because the strokes would visually merge into each other.
+
+The principle: **check before you write, and re-check after.** Snapshot the current layout before inserting, copying, moving, or resizing a frame; pick the new position with a real empty-space check rather than eyeballing the previous frame's height; and run the tool's overlap detector after, confirming it passes before you call the edit done. When you grow a frame, everything stacked below it in the same column probably now overlaps, so re-check.
+
+**Why this rule is strict:** overlap looks like progress in the screenshot of the new frame on its own, but corrupts the canvas as a whole. The frame below disappears under the new one, exports come out wrong, and reviewers think the underlying frame was deleted. This has shipped to the user repeatedly.
+
+The tool-specific protocol (which calls to run, and the caveat that some detectors are blind to sticky-note-on-sticky-note overlap) lives with the tool's skill: for Pencil, see the sibling reference linked at the top.
+
+**If a project-level `spec/WIREFRAMES.md` relaxes this rule, defer to it. Otherwise no exceptions.**
+
+---
+
+## Tight canvas: no big gaps
+
+Frames in the same column or row should sit close to each other (allow ~40px padding for readability, no more). Empty stretches break visual continuity and make the flow look incomplete.
+
+When a frame's height grows (e.g. a preview gets taller after adding fields), re-flow every frame stacked below it in the same column. Don't leave them at their old coordinates.
+
+---
+
+## Annotations live in sticky notes, not naked text
+
+Floating annotation text (copy-scaling rules, behavior notes, implementation pointers) on the canvas should be a sticky note, not free-floating text. Notes have a distinct visual treatment and read as "metadata about the design," whereas naked text reads as "content inside a frame that lost its frame."
+
+Frame labels (the frame `name`) handle "what is this frame called" already, so naked text is rarely the right answer.
+
+---
+
+## Planned-but-not-shipped views: `🚧 NEW NEW` marker
+
+A wireframe file is a mix of what's already in production and what's planned. Keep them visually distinct at a glance:
+
+- **Production views** (shipped): normal frame, no marker.
+- **Planned views** (designed but not yet built): prefix the frame's `name` with `🚧 NEW NEW`, followed by a space (literal "NEW NEW", capitalized, with the construction emoji), plus a tool-specific "unshipped" treatment (for Pencil, an orange dashed stroke; see the sibling reference). When the view ships to production, remove both the prefix and the treatment.
+
+This makes screenshots, exports, and the canvas itself obvious about which parts of the spec are aspirational. Variants of an unshipped feature (state variations of the same planned view) all get marked.
+
+If a project-level convention overrides the color or prefix, defer to it.
+
+### Post-deploy demotion sweep
+
+Any time work ships to production (`/land-and-deploy`, manual `git push` + deploy, Heroku release, Vercel promote, etc.):
+
+1. Identify which `🚧 NEW NEW`-prefixed frames correspond to what just shipped (check the diff, the LOG entry, the commit messages).
+2. For each one that's now in production: remove the `🚧 NEW NEW` prefix (and its trailing space) and the tool's unshipped treatment. The frame reverts to a normal production wireframe.
+3. If a frame is partially shipped (only some states/variants live), leave the marker on the unshipped variants and demote only the ones that are real.
+4. After demotion, note it in `LOG.md` under the relevant `[<feature>][spec]` tag so the wireframe state stays auditable.
+
+This runs as part of the deploy workflow, not standalone. With `/land-and-deploy` the sweep fires after canary passes; with a manual deploy, surface the sweep prompt after the deploy is confirmed live. `/close-out` also carries this sweep. Denise applies the markers; the deploy flow removes them.
+
+---
+
+## LEGEND frame on the canvas
+
+Every wireframe file should have a `LEGEND` frame (or sticky note) somewhere on the canvas explaining:
+- The axis convention (horizontal = view, vertical = variant).
+- The `🚧 NEW NEW` marker meaning.
+- Project-specific markers (if any).
+
+This lets any human or agent opening the file understand the conventions without leaving the canvas. Place it top-left or in an unused corner so it doesn't fight for attention with the actual flow.

design/shared/core.md

@@ -15,7 +15,9 @@ You are Designer Denise, the Pencil-native designer. While gstack's `design-*` s
 
 ## Canvas conventions live in the plugin's wireframes reference
 
-The canonical canvas rules ship with this plugin at `skills/pencil-mockup/references/wireframes.md`. **Read that file before laying anything out.** Do not duplicate or paraphrase it here; load it at runtime. It is self-contained, so the skill carries the conventions wherever the plugin is installed. It also defers, in order, to a project-level `spec/WIREFRAMES.md` and then a workspace-level `~/dev/WIREFRAMES.md` when either exists (see the precedence note at the top of the reference). The load-bearing points it carries:
+The canonical canvas rules ship with this plugin in two layers: `references/wireframes-cross-tool.md` holds the tool-agnostic principles and is **authoritative for anything shared across tools**, and `skills/pencil-mockup/references/wireframes.md` holds the Pencil operating contract (the `mcp__pencil__*` calls, the stroke JSON, the Pencil-only protocol). **Read them before laying anything out**, and load them at runtime. Both ship inside this plugin, so the conventions travel wherever it is installed, with no dependency on any workspace-level file. Both defer to a project-level `spec/WIREFRAMES.md` when one exists.
+
+The bullets below are a **non-authoritative quick checklist**, not a third copy of the rules. If they ever disagree with the referenced files, the referenced files win and the checklist is the thing to fix.
 
 - **Axes:** horizontal (left to right) = a new view in the flow; vertical (top to bottom) = a state variant of the same view. Decide which before placing a frame.
 - **Overlap is a hard error.** No frame may sit on top of another. Follow the mandatory protocol: `snapshot_layout(maxDepth: 0)` before, `find_empty_space_on_canvas` (padding 40) to pick a real position, `snapshot_layout(problemsOnly: true)` after, and it MUST return "No layout problems" before you finish. When a frame grows, re-flow and re-check everything stacked below it.

design/skills/pencil-mockup/CHANGELOG.md

@@ -1,5 +1,13 @@
 # pencil-mockup changelog
 
+## v1.3.0
+
+Designer Denise now owns the cross-tool wireframe conventions. This release copies the tool-agnostic principles into the design pack at `design/references/wireframes-cross-tool.md`, makes that file authoritative for anything shared across tools, and removes the workspace-level `~/dev/WIREFRAMES.md` from Denise's precedence chain.
+
+**Scope note:** this release does not delete the workspace file. Removing `~/dev/WIREFRAMES.md` itself is a companion `~/dev` PR and is still pending; until that lands, the file remains on disk and is simply no longer consulted by this plugin. Do not read this entry as a claim that it is gone.
+
+The bundled Pencil reference (`references/wireframes.md`) keeps the Pencil operating detail and now defers to the cross-tool file for the shared principles rather than superseding it, so the two cannot silently disagree. Precedence is project `spec/WIREFRAMES.md` -> this Pencil reference (for Pencil operating detail) -> the cross-tool reference (for shared principles). `shared/core.md`, `SKILL.md`, `style-guide/SKILL.md`, and the plugin README were repointed off the workspace path. The `qa` plugin's citations were repointed to the new cross-tool reference too.
+
 ## v1.2.0
 
 Style guides become a first-class artifact of every mockup: the create path builds a `Style guide · <Project>` root frame beside the mockup (five-card anatomy in `references/wireframes.md`), and the update path syncs that frame whenever an edit changes styles. The from-scratch flow (questionnaire, research, font options) lives in the new sibling skill `/design:style-guide`. The frame's panel title carries a 1-2 word named direction so the aesthetic is quotable later. `style-guide` borrows from Anthropic's official skills via a soft pointer, never a hard plugin dependency: distilled taste guardrails with an optional read of `frontend-design` when installed (the anti-slop rule scoped to display fonts, so neutral body fonts like Inter stay legitimate), and a named-aesthetic-direction menu fallback when the interview finds no brand or palette anchors.

design/skills/pencil-mockup/SKILL.md

@@ -42,7 +42,7 @@ Read `shared/core.md` from the plugin root before proceeding. The file lives at
 
 1. `get_editor_state(include_schema: true)` to load the schema and see what file/editor is active. (Skip the reload only if the schema is already in this session's context.)
 2. `get_guidelines` for Pencil's design guidance.
-3. Read this skill's `references/wireframes.md` for the canvas conventions (it is bundled with the plugin, so it is always present). It defers, in order, to a project-level `spec/WIREFRAMES.md` and then a workspace-level `~/dev/WIREFRAMES.md` when either exists, so read those too if present. Do not proceed to layout without these.
+3. Read this skill's `references/wireframes.md` for the canvas conventions (it is bundled with the plugin, so it is always present). It defers to a project-level `spec/WIREFRAMES.md` when one exists, so read that too if present. Do not proceed to layout without these.
 
 ## Step 3: Resolve the target
 

design/skills/pencil-mockup/references/wireframes.md

@@ -1,14 +1,14 @@
 # Pencil canvas conventions
 
-The canvas layout contract Designer Denise follows for every `.pen` create or update. This is the plugin's own copy, so the skill is self-contained: it carries these conventions wherever the `design` plugin is installed, with no dependency on any workspace-level file.
+The **Pencil operating contract** Designer Denise follows for every `.pen` create or update: the `mcp__pencil__*` calls, the stroke JSON, and the Pencil-only protocol. The tool-agnostic principles it rests on live beside it in the same plugin at `../../../references/wireframes-cross-tool.md`. Both files ship inside the `design` plugin, so reading one from the other always resolves and neither depends on any workspace-level file.
 
-**Precedence (most specific wins).** If a more specific convention file exists, defer to it for anything it covers, and fall back to this doc for everything it does not:
+**Precedence (most specific wins).** If a more specific convention file exists, defer to it for anything it covers, and fall back down the chain for everything it does not:
 
 1. A project-level `spec/WIREFRAMES.md` in the repo you are working in (most specific).
-2. A workspace-level `~/dev/WIREFRAMES.md`, if one exists (the user's cross-tool conventions).
-3. This file (the always-present baseline).
+2. This file, for **Pencil operating detail**: how to execute a rule with the Pencil MCP.
+3. `../../../references/wireframes-cross-tool.md`, **authoritative for the shared principles** themselves.
 
-The principles below are tool-agnostic; the operating detail (the `mcp__pencil__*` calls, the stroke JSON) is Pencil-specific and is what makes this the design plugin's home for the contract.
+Read both this file and the cross-tool sibling before laying anything out. The shared principles are restated below so the Pencil protocol reads as one continuous contract, but the sibling is the source of truth for them: **where the two ever disagree on a shared principle, the cross-tool file wins**, and the drift is a bug to fix here rather than a difference to work around.
 
 ---
 

design/skills/style-guide/SKILL.md

@@ -45,7 +45,7 @@ Read `shared/core.md` from the plugin root before proceeding. The file lives at
 
 1. `get_editor_state(include_schema: true)` to load the schema and see what file is active. (Skip the reload only if the schema is already in this session's context.)
 2. `get_guidelines` for Pencil's design guidance.
-3. Read the sibling skill's canvas reference at `../pencil-mockup/references/wireframes.md`, especially its **"Style guide frame"** section: it defines the five-card anatomy, placement, and sync rule this skill produces. It defers to a project-level `spec/WIREFRAMES.md` and a workspace `~/dev/WIREFRAMES.md` when those exist, so read those too if present.
+3. Read the sibling skill's canvas reference at `../pencil-mockup/references/wireframes.md`, especially its **"Style guide frame"** section: it defines the five-card anatomy, placement, and sync rule this skill produces. It defers to a project-level `spec/WIREFRAMES.md` when one exists, so read that too if present.
 
 ## Step 3: Interview (one question at a time, never a batch)
 

qa/README.md

@@ -44,4 +44,4 @@ See `shared/core.md` for the full identity. Quick facts:
 ## See also
 
 - `~/dev/gstack-extensions/pm/` (PM Penny: writes the issues QA Quincey verifies against, and receives `/pm:bug` handoffs).
-- `~/dev/WIREFRAMES.md` (Pencil canvas conventions; left-to-right is the flow order QA Quincey reads).
+- The `design` plugin's `design/references/wireframes-cross-tool.md` (Designer Denise's cross-tool canvas conventions; left-to-right is the flow order QA Quincey reads).

qa/hooks/scripts/qa-status-gate.sh

@@ -46,7 +46,7 @@ fi
 
 # Shippable work in the SESSION cwd (from the payload, not the hook process cwd)?
 # Commits ahead of the base branch ONLY. A dirty tree deliberately does NOT
-# count: long-lived local edits (a modified WIREFRAMES.md, a sibling pane's
+# count: long-lived local edits (a modified LOG.md, a sibling pane's
 # work) armed the gate on every chatty turn, and the noise outweighed the
 # catch. Uncommitted work gets caught at commit/ship time, when the commits
 # exist. All best-effort; any failure leaves shippable=0 (allow).

qa/shared/core.md

@@ -41,7 +41,7 @@ You do not @-mention or assign. You write reports; the team finds and acts on th
 Never start clicking until you have written down what you are testing. The happy path is the ordered list of steps the user takes plus the expected outcome at each step. Sources, in order of preference:
 
 1. A GitHub issue authored by PM Penny. Look for `## QA instructions`; that section was written for you.
-2. A Pencil `.pen` mockup. The screen-to-screen flow on the canvas IS the happy path. Read it left-to-right (the horizontal axis is the view sequence; see `~/dev/WIREFRAMES.md`).
+2. A Pencil `.pen` mockup. The screen-to-screen flow on the canvas IS the happy path. Read it left-to-right (the horizontal axis is the view sequence; see the `design` plugin's `references/wireframes-cross-tool.md`).
 3. The spec, design doc, or feature description provided by the user.
 4. As a last resort: ask the user to describe the happy path. Capture their answer, do not paraphrase.
 

qa/skills/browser/SKILL.md

@@ -689,7 +689,7 @@ Also pull any Pencil link from the issue body. Pattern: a `pencil.dev` URL, an a
 
 ### 3b. From a Pencil `.pen` file
 
-Use the Pencil MCP. The canvas convention (see `~/dev/WIREFRAMES.md`) is horizontal = view sequence, vertical = variants of the same view. So the happy path is the top row of screens, read left to right.
+Use the Pencil MCP. The canvas convention (see the `design` plugin's `references/wireframes-cross-tool.md`) is horizontal = view sequence, vertical = variants of the same view. So the happy path is the top row of screens, read left to right.
 
 ```
 # Open the document

qa/skills/browser/references/happy-path-extraction.md

@@ -50,7 +50,7 @@ If found, attach the path to every step that has a matching frame.
 
 ## Input shape 2: Pencil `.pen` file
 
-The canvas convention from `~/dev/WIREFRAMES.md`:
+The canvas convention (from the `design` plugin's `references/wireframes-cross-tool.md`):
 
 - **Horizontal axis = view sequence**: the flow reads left to right.
 - **Vertical axis = variants**: stacked variants of the same view (e.g. empty state, loading, error). The top row is the happy path.