From bb6f5c5ab8601171169a053cc154a3c452374c14 Mon Sep 17 00:00:00 2001 From: Mujtaba Badat <1470881+mujtaba3B@users.noreply.github.com> Date: Wed, 1 Jul 2026 15:56:20 -0500 Subject: [PATCH 1/2] refactor(design): move cross-tool wireframe conventions into Designer Denise Retire the workspace-level ~/dev/WIREFRAMES.md as the cross-tool source of truth and give Designer Denise ownership. The tool-agnostic canvas principles (axes, no-overlap, tight canvas, sticky notes, the NEW NEW marker + demotion sweep, LEGEND) now live in the design pack at design/references/wireframes-cross-tool.md. - New: design/references/wireframes-cross-tool.md (tool-agnostic principles). - pencil-mockup/references/wireframes.md stays the Pencil-specific superset; its precedence drops the workspace-override tier (now project spec/WIREFRAMES.md -> this file) and points at the cross-tool sibling for non-Pencil tools. - Repointed design README, shared/core.md, pencil-mockup SKILL, style-guide SKILL off the ~/dev/WIREFRAMES.md path. - Repointed the qa plugin's 5 citations (README, shared/core.md, browser SKILL, happy-path-extraction, qa-plan SKILL) and refreshed a stale gate-script comment. - design plugin 1.2.0 -> 1.3.0 with a pencil-mockup CHANGELOG entry. The matching removal of ~/dev/WIREFRAMES.md and the ~/dev/CLAUDE.md pointer repoint land in a separate ~/dev PR (the CLAUDE.md edit is behind the approval gate). Co-Authored-By: Claude Opus 4.8 (1M context) --- design/.claude-plugin/plugin.json | 2 +- design/README.md | 2 +- design/references/wireframes-cross-tool.md | 86 +++++++++++++++++++ design/shared/core.md | 2 +- design/skills/pencil-mockup/CHANGELOG.md | 4 + design/skills/pencil-mockup/SKILL.md | 2 +- .../pencil-mockup/references/wireframes.md | 5 +- design/skills/style-guide/SKILL.md | 2 +- qa/README.md | 2 +- qa/hooks/scripts/qa-status-gate.sh | 2 +- qa/shared/core.md | 2 +- qa/skills/browser/SKILL.md | 2 +- .../references/happy-path-extraction.md | 2 +- qa/skills/qa-plan/SKILL.md | 2 +- 14 files changed, 103 insertions(+), 14 deletions(-) create mode 100644 design/references/wireframes-cross-tool.md diff --git a/design/.claude-plugin/plugin.json b/design/.claude-plugin/plugin.json index b38088f..bdf064a 100644 --- a/design/.claude-plugin/plugin.json +++ b/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" } } diff --git a/design/README.md b/design/README.md index 98845c1..91ead5f 100644 --- a/design/README.md +++ b/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 diff --git a/design/references/wireframes-cross-tool.md b/design/references/wireframes-cross-tool.md new file mode 100644 index 0000000..55d2a8c --- /dev/null +++ b/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. Edges touching is fine; one pixel of overlap is not. Touching counts as overlap when the frames have visible strokes, since the strokes will visually merge. + +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 `[][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. diff --git a/design/shared/core.md b/design/shared/core.md index a9d16a2..02cd693 100644 --- a/design/shared/core.md +++ b/design/shared/core.md @@ -15,7 +15,7 @@ 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 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 to a project-level `spec/WIREFRAMES.md` when one exists (see the precedence note at the top of the reference). The load-bearing points it carries: - **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. diff --git a/design/skills/pencil-mockup/CHANGELOG.md b/design/skills/pencil-mockup/CHANGELOG.md index 5eabde0..641096c 100644 --- a/design/skills/pencil-mockup/CHANGELOG.md +++ b/design/skills/pencil-mockup/CHANGELOG.md @@ -1,5 +1,9 @@ # pencil-mockup changelog +## v1.3.0 + +Designer Denise now owns the cross-tool wireframe conventions outright. The workspace-level `~/dev/WIREFRAMES.md` (the old tool-agnostic source of truth other tools read) was retired and its tool-agnostic principles moved into the design pack at `design/references/wireframes-cross-tool.md`. The bundled Pencil reference (`references/wireframes.md`) stays the Pencil-specific superset; its precedence dropped the workspace-override tier and is now just project `spec/WIREFRAMES.md` -> this file. `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 ยท ` 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. diff --git a/design/skills/pencil-mockup/SKILL.md b/design/skills/pencil-mockup/SKILL.md index 7cc48f7..1102854 100644 --- a/design/skills/pencil-mockup/SKILL.md +++ b/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 diff --git a/design/skills/pencil-mockup/references/wireframes.md b/design/skills/pencil-mockup/references/wireframes.md index bffef9e..b05cf15 100644 --- a/design/skills/pencil-mockup/references/wireframes.md +++ b/design/skills/pencil-mockup/references/wireframes.md @@ -5,10 +5,9 @@ The canvas layout contract Designer Denise follows for every `.pen` create or up **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: 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 (the always-present baseline). -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. +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 Pencil contract. The tool-agnostic principles alone (shared with any future non-Pencil tool) also live at the design pack's `../../../references/wireframes-cross-tool.md`; this file is the Pencil-specific superset of that one, so for Pencil work read this file and ignore the sibling. --- diff --git a/design/skills/style-guide/SKILL.md b/design/skills/style-guide/SKILL.md index cc23f04..07309f8 100644 --- a/design/skills/style-guide/SKILL.md +++ b/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) diff --git a/qa/README.md b/qa/README.md index 2de26fa..9845bb4 100644 --- a/qa/README.md +++ b/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). diff --git a/qa/hooks/scripts/qa-status-gate.sh b/qa/hooks/scripts/qa-status-gate.sh index 61fd931..30de808 100755 --- a/qa/hooks/scripts/qa-status-gate.sh +++ b/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). diff --git a/qa/shared/core.md b/qa/shared/core.md index 570658d..7d957b5 100644 --- a/qa/shared/core.md +++ b/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. diff --git a/qa/skills/browser/SKILL.md b/qa/skills/browser/SKILL.md index ee75228..6026e5c 100644 --- a/qa/skills/browser/SKILL.md +++ b/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 diff --git a/qa/skills/browser/references/happy-path-extraction.md b/qa/skills/browser/references/happy-path-extraction.md index 60418de..8a31c62 100644 --- a/qa/skills/browser/references/happy-path-extraction.md +++ b/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. diff --git a/qa/skills/qa-plan/SKILL.md b/qa/skills/qa-plan/SKILL.md index 13032dd..ba74cbd 100644 --- a/qa/skills/qa-plan/SKILL.md +++ b/qa/skills/qa-plan/SKILL.md @@ -67,7 +67,7 @@ Read `../../shared/core.md` (the plugin root's shared file; resolves wherever th 2. Pull the **success criteria**, in this order of preference. Never invent them silently: - A `/spec` artifact for this work, if one exists. - The linked GitHub issue (PM Penny's `## QA instructions` / acceptance criteria). - - A Pencil `.pen` mockup whose flow defines the expected behavior (see `~/dev/WIREFRAMES.md`). + - A Pencil `.pen` mockup whose flow defines the expected behavior (see the `design` plugin's `references/wireframes-cross-tool.md`). - As a last resort, ask the user to state the acceptance criteria. Capture, do not paraphrase. 3. Express each criterion in a checkable form: **Given/When/Then** for behavior, **EARS** (`WHEN THE SYSTEM SHALL `) for system requirements. 4. Separate **per-change Acceptance Criteria** (what proves THIS change is correct) from the universal **Definition of Done** (the engineering bar every change meets). From e1d9f815d307aa7c9982ccabe6f5163efd856455 Mon Sep 17 00:00:00 2001 From: Mujtaba Badat <1470881+mujtaba3B@users.noreply.github.com> Date: Wed, 5 Aug 2026 20:43:09 +0200 Subject: [PATCH 2/2] docs(design): address CodeRabbit review on the cross-tool wireframes move Four findings from the PR #48 review, all valid: - Resolve the self-contradicting overlap rule. It said edges touching is fine, then said touching counts as overlap with visible strokes, giving the same geometry two outcomes. Now: never overlap, touch only when neither frame renders a stroke. - Stop the CHANGELOG claiming ~/dev/WIREFRAMES.md "was retired". The companion ~/dev PR that deletes it is still open, so the file is on disk; this release only drops it from Denise's precedence chain. The false-completion claim had already misled a later session into nearly deleting the only remaining copy. - Label core.md's bullets a non-authoritative checklist instead of telling readers not to paraphrase and then paraphrasing. - Make the cross-tool reference authoritative for shared principles rather than telling Pencil work to ignore it. The original self-contained rationale came from PR #28, when the shared file lived outside the plugin; both files now ship in the design plugin, so a reference between them always resolves and the duplication no longer buys portability. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011GsGa24cyrLQ85FswVAiBX --- design/references/wireframes-cross-tool.md | 2 +- design/shared/core.md | 4 +++- design/skills/pencil-mockup/CHANGELOG.md | 6 +++++- design/skills/pencil-mockup/references/wireframes.md | 9 +++++---- 4 files changed, 14 insertions(+), 7 deletions(-) diff --git a/design/references/wireframes-cross-tool.md b/design/references/wireframes-cross-tool.md index 55d2a8c..7504e6a 100644 --- a/design/references/wireframes-cross-tool.md +++ b/design/references/wireframes-cross-tool.md @@ -24,7 +24,7 @@ Naming should match the stacking. If `S1b. Build - bio empty` is a state variant ## 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. Edges touching is fine; one pixel of overlap is not. Touching counts as overlap when the frames have visible strokes, since the strokes will visually merge. +**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. diff --git a/design/shared/core.md b/design/shared/core.md index 02cd693..1968608 100644 --- a/design/shared/core.md +++ b/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 to a project-level `spec/WIREFRAMES.md` when one 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. diff --git a/design/skills/pencil-mockup/CHANGELOG.md b/design/skills/pencil-mockup/CHANGELOG.md index 641096c..541b260 100644 --- a/design/skills/pencil-mockup/CHANGELOG.md +++ b/design/skills/pencil-mockup/CHANGELOG.md @@ -2,7 +2,11 @@ ## v1.3.0 -Designer Denise now owns the cross-tool wireframe conventions outright. The workspace-level `~/dev/WIREFRAMES.md` (the old tool-agnostic source of truth other tools read) was retired and its tool-agnostic principles moved into the design pack at `design/references/wireframes-cross-tool.md`. The bundled Pencil reference (`references/wireframes.md`) stays the Pencil-specific superset; its precedence dropped the workspace-override tier and is now just project `spec/WIREFRAMES.md` -> this file. `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. +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 diff --git a/design/skills/pencil-mockup/references/wireframes.md b/design/skills/pencil-mockup/references/wireframes.md index b05cf15..cf5c520 100644 --- a/design/skills/pencil-mockup/references/wireframes.md +++ b/design/skills/pencil-mockup/references/wireframes.md @@ -1,13 +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. 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 Pencil contract. The tool-agnostic principles alone (shared with any future non-Pencil tool) also live at the design pack's `../../../references/wireframes-cross-tool.md`; this file is the Pencil-specific superset of that one, so for Pencil work read this file and ignore the sibling. +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. ---