From 09c919617124dc61ea91f0c795cf109a4774c6f3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 13:38:09 +0000
Subject: [PATCH 01/10] Add design handoff v2 architecture proposal

Research-backed proposal to redesign the design-handoff command:
- Designer-driven modes (brainstorm/draft/ship) instead of Q&A brief
- Design system published as a native Figma Skill, not pasted into prompts
- Canonical .claude/constitution.md governing design + build
- Own design.md (Kiro-style split) instead of appending to spec.md
- Review as an evaluator-optimizer loop; async brief with [NEEDS CLARIFICATION]
- Agent topology: Scout, parallel frame agents (fixed schema), evaluator, consistency

Decisions settled: one Figma file per feature, .claude/constitution.md location.

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 .../design/design-handoff-v2-proposal.md      | 219 ++++++++++++++++++
 1 file changed, 219 insertions(+)
 create mode 100644 .claude/commands/design/design-handoff-v2-proposal.md

diff --git a/.claude/commands/design/design-handoff-v2-proposal.md b/.claude/commands/design/design-handoff-v2-proposal.md
new file mode 100644
index 0000000..df16901
--- /dev/null
+++ b/.claude/commands/design/design-handoff-v2-proposal.md
@@ -0,0 +1,219 @@
+# Design Handoff v2 — Architecture Proposal
+
+**Status:** Proposal under refinement — architecture decisions partly settled (see Decisions); not yet implemented
+**Author:** Design tooling research, June 2026
+**Supersedes design of:** `.claude/commands/design/design-handoff.md`
+**Next gate:** Confirm the two open recommendations, then rewrite the command to v2
+
+---
+
+## Why revisit this
+
+The current `design-handoff.md` is a solid 7-phase pipeline, but it was written before the
+mechanisms it needs actually existed, and three rounds of research surfaced both correctness
+bugs and structural gaps.
+
+### Correctness bugs (the command would not run today)
+- **Wrong Figma file key.** Hardcodes `v8BYFkebTGQNuiRrCXWssa` (an old shared "Canvas" file
+  with 4 unrelated sections). The real Metrics design work lives in `lSXpuOg6n0qXXwvMjOfU7G`.
+- **Non-existent MCP tool names.** Phase 3 references `mcp__figma__get_metadata`; the real
+  tools are `mcp__<server-id>__get_metadata` / `use_figma` / `get_screenshot`.
+- **Ghost dependency.** Every per-feature `FIGMA.md` says "read `~/Dalgo/FIGMA.md` first" —
+  that file does not exist in the repo.
+
+### Structural gaps (confirmed against industry practice)
+- **Designers are treated as approvers, not authors.** Claude reads the spec and asks
+  questions; the designer answers. Real design is visual and iterative — sketch, see, react,
+  revise. There is no loop and no brainstorm mode.
+- **Patterns are pasted into prompts.** `{paste relevant excerpts from patterns.md}` is manual,
+  inconsistent, and the source of cross-frame drift.
+- **Design decisions land in the wrong file.** Output is a `## Design` section appended to
+  `spec.md`; in the Metrics feature, decisions then leaked into `tasks.md` as "v2 overrides."
+  There is no single design source of truth.
+- **Review runs once, at the end.** Phase 4 produces a list of problems for a human to fix
+  manually, rather than looping until the design passes.
+- **Phase 2 hard-blocks the session.** The designer must be present in chat; thinking time and
+  generation time are coupled.
+
+---
+
+## What the research changed
+
+Full notes are in the session; the load-bearing findings:
+
+1. **Figma shipped native Skills (Mar 24, 2026)** — markdown files that make a design system
+   machine-readable, loaded by the canvas agent automatically. This is exactly what
+   `patterns.md` / `FIGMA.md` are doing by hand. *We should publish, not paste.*
+2. **Spec-driven dev converged on a 3-file split** (Kiro: `requirements.md` / `design.md` /
+   `tasks.md`; spec-kit: `spec.md` / `plan.md` / `tasks.md`). `design.md` is a first-class,
+   human-reviewed, **gated** phase — not an appendix to the spec.
+3. **The "constitution" pattern** (spec-kit) — one always-loaded, immutable-principles file
+   that governs every phase. Dalgo's NGO constraints are a constitution scattered across files.
+4. **Anthropic's evaluator-optimizer loop** — generate → evaluate against criteria → feed back
+   → repeat. We have the criteria (`checklist.md`) but run it once instead of in a loop.
+5. **Nobody has solved spec→design.** Even Kiro/spec-kit explicitly punt on UX methodology.
+   This command is novel work, not catch-up — worth getting right.
+
+---
+
+## Decisions (resolved June 2026)
+
+| # | Decision | Choice | Consequence |
+|---|----------|--------|-------------|
+| 1 | Feature → Figma file mapping | **One file per feature** | Reuse comes from the published Skill, not from scouting other features. Scout's job narrows to "design-system baseline + this feature's internal state." Phase 0 creates the file on first run and records its key in `design.md`. |
+| 2 | Constitution location | **New `.claude/constitution.md`** | Canonical and top-level. `patterns.md`, `checklist.md`, and `CLAUDE.md` point to it instead of restating rules. Loaded by design **and** engineering workflows. |
+| 3 | Frame naming standard *(recommended)* | **`S{n} · {Screen Name}` + `S{n}-{State}` for states** | One convention so Scout and the prototype wiring can resolve frames by name. Ends the Metrics-file mix of `–` / `·` / `-`. |
+| 4 | Brainstorm storage *(recommended)* | **Same feature file, separate "Explorations" page** | Rejected variants stay out of the handoff surface but remain recoverable. No throwaway files to track. |
+
+Decisions 3 and 4 are recommendations — flag if you'd rather decide differently; nothing else
+depends on them being settled today.
+
+The **one-file-per-feature** choice also retires the ghost `~/Dalgo/FIGMA.md` dependency: the
+cross-feature shared reference is now the **constitution + the design-system Skill**, not a
+parent file. Each feature keeps a small `FIGMA.md` that extends the Skill with feature-specific
+notes (screen list, file key, canvas positions).
+
+---
+
+## Proposed architecture
+
+### Principle 1 — Designer drives; the command serves
+
+Replace the question-and-answer brief with three intent-led modes:
+
+| Mode | Invocation | Output | When |
+|------|-----------|--------|------|
+| **Brainstorm** | `--brainstorm` | 2–3 rough variants per open screen, side-by-side in an "Explorations" section. No prototype, no spec change. | Direction is open; designer wants options |
+| **Draft** | `--draft` | Lo-fi wireframes, one feedback round per frame, in-place revision. | Direction is chosen; iterating on layout |
+| **Ship** (default) | _(none)_ | Full-fidelity frames, prototype wired, `design.md` written, ready for engineering. | Design is settled; producing the handoff |
+
+Variants-by-default in brainstorm matches where every serious tool landed (Google Stitch ships
+2–3; Figma First Draft previews multiple themes). A single output asked "does this work?" is
+behind the curve.
+
+### Principle 2 — Design system as a Figma Skill, not pasted text
+
+- Publish `patterns.md` + the visual half of `checklist.md` as a **Figma Skill** the canvas
+  agent loads automatically (native mechanism as of Mar 2026).
+- Frame agents stop receiving pasted excerpts. The prompt points at the skill; the agent reads
+  what it needs as it works.
+- This is also what shrinks the cross-frame consistency problem at the source — agents sharing
+  one skill drift far less, so a consistency check becomes a spot-check rather than a full pass.
+
+### Principle 3 — A constitution governs every phase
+
+Create `.claude/constitution.md` holding Dalgo's non-negotiables, today scattered across
+`CLAUDE.md` and `patterns.md`:
+
+- Never expose SQL, schema/table names, or code to non-admin users
+- Users are non-technical NGO staff on slow internet and old devices
+- Sentence case on buttons; no internal acronyms (RAG, blast radius) in UI copy
+- Admin-only fields are visually locked
+
+It is **canonical**: `patterns.md`, `checklist.md`, and `CLAUDE.md` reference it rather than
+restate the rules, so there is no drift. Both the design agents **and** the review checklist
+load it. To keep it useful for engineering too, the design-handoff and the engineering
+`plan-feature` / `execute-plan` flows should all point at the same file — one source of truth
+for "what Dalgo will never ship."
+
+### Principle 4 — Own `design.md`, don't append to `spec.md`
+
+Adopt the Kiro split. The handoff produces a gated `features/{name}/v1/design.md` — the design
+source of truth — containing screens, node IDs, flows, decisions, and known issues. `spec.md`
+keeps a one-line pointer to it. Engineering reads `design.md`; nothing leaks into `tasks.md`.
+
+### Principle 5 — Review is an evaluator loop, not a final report
+
+Restructure Phase 4 as evaluator-optimizer: the review agent checks each frame against
+`checklist.md` + constitution, and **feeds failures back to the frame agent** until it passes
+(bounded retries). Frames arrive already-passing instead of arriving with a to-do list.
+
+### Principle 6 — Async brief; mark ambiguity, don't block
+
+Replace the blocking Phase 2 with the spec-kit pattern:
+- Write the brief to `features/{name}/v1/design-brief.md`. The designer edits it on their own
+  time, in their own editor.
+- Re-running detects a filled-in brief and continues.
+- Where direction is genuinely missing, the command **generates anyway and tags the frame /
+  decision with `[NEEDS CLARIFICATION]`** rather than halting the whole run.
+
+---
+
+## Agent topology (Anthropic orchestrator-workers + evaluator)
+
+```
+design-handoff (orchestrator)
+  │
+  ├─ Scout (runs once)            establishes the design-system baseline from the Skill, then
+  │                               reads THIS feature's file via get_metadata. Empty file (first
+  │                               run) → start at x=0. Re-run → screenshots existing frames for
+  │                               internal consistency, returns rightmost free x-position.
+  │
+  ├─ Frame agents (parallel)      one per surface; load the Figma Skill; consume Scout's
+  │   └─ return a FIXED schema:   context; create the frame
+  │      {node_id, frame_name, screenshot, decisions[], needs_clarification[]}
+  │
+  ├─ Evaluator (loop)             checklist + constitution per frame → feeds failures back to
+  │                               the owning frame agent until pass or retry budget hit
+  │
+  └─ Consistency spot-check       screenshots all final frames; flags nav/header/footer drift
+                                  (small now that all agents shared one Skill)
+```
+
+Two guardrails from Anthropic's guidance:
+- **Fixed return schema** across parallel frame agents, so the orchestrator's fan-in never has
+  to reconcile formats.
+- **"Add agents only when simpler solutions fall short."** Scout and Evaluator earn their place
+  (they fix named failure modes). The Consistency spot-check stays deliberately thin.
+
+---
+
+## Proposed phase flow
+
+| Phase | Current | Proposed |
+|-------|---------|----------|
+| 0 | — | Resolve mode (`brainstorm`/`draft`/`ship`); load constitution; look up this feature's Figma file key in `design.md` — **create the file if missing** (`create_new_file`) and record the key |
+| 1 | Read spec, extract surfaces | _unchanged_ |
+| 1.5 | Extract user flows | _unchanged (skipped in brainstorm)_ |
+| 2 | **Blocking** designer brief | **Async** brief file; mark `[NEEDS CLARIFICATION]`, continue |
+| 2.9 | — | **Scout**: read canvas, return shared context |
+| 3 | Frame agents (pasted patterns) | Frame agents load **Figma Skill**; fixed return schema; variants in brainstorm |
+| 3.5 | Wire prototype | _unchanged (skipped in brainstorm/draft)_ |
+| 4 | Review once → report | **Evaluator loop** → frames return passing |
+| 3.9 | — | **Consistency** spot-check |
+| 5 | Designer sign-off | _unchanged_ |
+| 6 | Append `## Design` to spec.md | Write/own **`design.md`**; spec.md gets a pointer |
+| 7 | Signal readiness | _unchanged_ |
+
+---
+
+## Migration / sequencing
+
+P0 fixes are independent of the bigger redesign and can ship immediately:
+
+1. **P0 — make it runnable:** remove the hardcoded Figma file key (look up / create per-feature
+   instead), fix MCP tool names, and retire the ghost `~/Dalgo/FIGMA.md` dependency (replace
+   with constitution + Skill references).
+2. **P1 — constitution + Figma Skill:** extract the constitution; publish patterns as a Skill;
+   drop pattern-pasting from the agent prompt.
+3. **P1 — `design.md` ownership:** switch Phase 6 to write `design.md`; leave a spec.md pointer.
+4. **P2 — modes + async brief:** add `--brainstorm` / `--draft`; move the brief to a file with
+   `[NEEDS CLARIFICATION]` tagging.
+5. **P2 — agent topology:** add Scout, the evaluator loop, and the consistency spot-check with
+   a fixed frame-agent return schema.
+
+---
+
+## Still open
+
+The four questions from the first draft are now resolved in **Decisions** above (file strategy
+and constitution location chosen; naming and brainstorm-storage recommended). What remains
+before the command rewrite:
+
+1. **Confirm the two recommendations** (naming standard, brainstorm storage) — or override them.
+2. **Skill authoring:** publishing `patterns.md` as a Figma Skill is the one step that depends
+   on Figma's native Skills mechanism. We should confirm the workspace has it enabled and decide
+   whether the Skill is authored in Figma or generated from `patterns.md` in-repo.
+3. **Engineering buy-in on the constitution:** `plan-feature` / `execute-plan` pointing at the
+   same `.claude/constitution.md` is a cross-team change — worth a nod from engineering before
+   we wire it in.

From 1991637c86318529a0873d5c887f8c0ed47b48ff Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 16:59:52 +0000
Subject: [PATCH 02/10] Add design system integration section to v2 proposal

Documents the actual tokens.css / components.css structure from
DalgoT4D/dalgo-design-system as the source of truth, replacing the
manual pattern-pasting approach.

- Calls out three specific contradictions in patterns.md (token names,
  page padding, icon sizes) and the button-casing conflict
- Documents the 24 components grouped into Tier 1 (always load) and
  Tier 2 (per-frame, five component families)
- Flags missing RAG status color tokens as a gap to fill upstream
- Expands migration sequencing with P0 patterns.md fix and RAG token PR
- Adds button casing and RAG tokens to the Still Open list

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 .../design/design-handoff-v2-proposal.md      | 144 ++++++++++++++++--
 1 file changed, 135 insertions(+), 9 deletions(-)

diff --git a/.claude/commands/design/design-handoff-v2-proposal.md b/.claude/commands/design/design-handoff-v2-proposal.md
index df16901..bf64c94 100644
--- a/.claude/commands/design/design-handoff-v2-proposal.md
+++ b/.claude/commands/design/design-handoff-v2-proposal.md
@@ -139,6 +139,116 @@ Replace the blocking Phase 2 with the spec-kit pattern:
 
 ---
 
+## Design System Integration
+
+The canonical design system lives in `DalgoT4D/dalgo-design-system` (a separate repo), as two
+CSS files that are the **single source of truth** for all visual decisions:
+
+- **`tokens.css`** — CSS custom properties for color, typography, spacing, radii, shadow, z-index,
+  and transitions. All prefixed `--color-*`, `--font-*`, `--space-*`, `--spacing-*`, `--radius-*`,
+  `--shadow-*`, `--z-*`, `--transition-*`.
+- **`components.css`** — 24 components, all values referencing `var(--*)` — zero hardcoded values.
+
+### What `patterns.md` gets wrong today
+
+`patterns.md` is the current source of design truth inside the command. It has three specific
+contradictions with `tokens.css` and one policy conflict with `components.css`:
+
+| # | patterns.md says | Design system says | Fix |
+|---|------------------|--------------------|-----|
+| 1 | Uses Shadcn token names (`--primary`, `text-muted-foreground`) | Tokens are `--color-brand-primary`, `--color-text-secondary`, etc. | Replace all token references |
+| 2 | "24px page padding" | `--spacing-page-x` (horizontal, 32px); `--spacing-page-y` (vertical, 28px) | Update padding rule to match named tokens |
+| 3 | "Lucide icons at 16px (h-4 w-4) everywhere" | Icon sizes are context-specific per component | Replace blanket rule with per-context guidance |
+| 4 | "Sentence case on buttons" (constitution rule) | `.btn { text-transform: uppercase }` in `components.css` | **Needs a decision** — is casing set in code (uppercase) or copy (sentence case)? |
+
+Item 4 is a conflict between the UI constitution rule and the CSS implementation. The most likely
+intent: `.btn` sets uppercase as a CSS default that the design system overrides per variant;
+`patterns.md` / the constitution should govern copy, not override CSS `text-transform`. Resolution
+needed before rewriting the Figma Skill prompt.
+
+### Missing tokens (gaps in tokens.css)
+
+RAG status colors — used extensively throughout the app — are **not in `tokens.css`**:
+
+- on-track (green)
+- at-risk (amber)
+- off-track (red)
+- stale (grey)
+
+These are referenced in multiple features and need to be added to the design system repo before
+the Figma Skill can be authoritative. Until then, they should be documented in `patterns.md` as
+a pending addition.
+
+### Component families (basis for tiered loading)
+
+`components.css` contains 24 components, grouped into two tiers for context management:
+
+**Tier 1 — always load (layout skeleton, ~5 components)**
+
+Every screen shares these; they go into the Figma Skill's always-available section:
+
+| Component | Role |
+|-----------|------|
+| Reset | CSS baseline |
+| Page Shell | Fixed header + scrollable content pattern |
+| Header | Top bar, org switcher |
+| Sidebar | Left nav rail |
+| Nav Items | Active/hover states |
+
+**Tier 2 — load per frame (component families, ~19 components)**
+
+Frame agents request only what their surface needs. Group by screen archetype:
+
+| Family | Components | Typical surfaces |
+|--------|-----------|-----------------|
+| Data display | Table, Pagination, Action Buttons | List screens, data grids |
+| Input | Forms (label, input, select, tags, frequency, toggle, tabs) | Create/edit flows |
+| Overlay | Modal, Empty State | Dialogs, zero-state screens |
+| Status/card | Badge Pill, Badge/Avatar, Step Indicator, Card | Dashboards, pipeline status |
+| Specialist | Chart Type Icons, Header Org | Analytics screens, multi-org flows |
+
+The frame agent prompt declares which family it needs; the orchestrator loads only those component
+definitions into the agent's context. This keeps each agent's prompt under ~4k tokens for the
+design system portion.
+
+### How patterns.md should change
+
+`patterns.md` should become a **Tailwind/Shadcn mapping document**: it translates design-system
+token names into the framework-specific class names used in `webapp_v2`. It should not restate
+spacing values or hex codes — those live in `tokens.css`. Structure:
+
+```
+# patterns.md (after fix)
+
+Source of truth: DalgoT4D/dalgo-design-system (tokens.css + components.css)
+This file maps design-system tokens → Tailwind / Shadcn class names for webapp_v2.
+
+## Token mapping
+--color-brand-primary    → bg-teal-600 / text-teal-600
+--spacing-page-x         → px-12 (48px) [verify against tokens.css]
+--spacing-page-y         → py-7 (28px) [verify against tokens.css]
+...
+
+## Constitution reference
+Non-negotiables are in .claude/constitution.md — not restated here.
+```
+
+### Figma Skill authoring plan
+
+The Figma Skill is a markdown file that Figma's canvas agent loads automatically. Its content
+should be generated **from** `tokens.css` + `components.css`, not from `patterns.md`:
+
+1. **Tier 1 section** — universal layout tokens (colors, spacing, radii, shadows)
+2. **Tier 2 sections** — one section per component family; each references component CSS rules
+   translated into Figma property names (fills, auto-layout padding, corner radius, etc.)
+3. **Constitution section** — Dalgo's non-negotiable UX rules, imported from `.claude/constitution.md`
+
+Authoring question (still open): is the Skill file authored manually in Figma, or generated by a
+script that reads `tokens.css` → outputs Figma Skill markdown? The script approach is more
+maintainable but requires confirming Figma's native Skills format.
+
+---
+
 ## Agent topology (Anthropic orchestrator-workers + evaluator)
 
 ```
@@ -194,12 +304,21 @@ P0 fixes are independent of the bigger redesign and can ship immediately:
 1. **P0 — make it runnable:** remove the hardcoded Figma file key (look up / create per-feature
    instead), fix MCP tool names, and retire the ghost `~/Dalgo/FIGMA.md` dependency (replace
    with constitution + Skill references).
-2. **P1 — constitution + Figma Skill:** extract the constitution; publish patterns as a Skill;
-   drop pattern-pasting from the agent prompt.
-3. **P1 — `design.md` ownership:** switch Phase 6 to write `design.md`; leave a spec.md pointer.
-4. **P2 — modes + async brief:** add `--brainstorm` / `--draft`; move the brief to a file with
+2. **P0 — fix patterns.md:** correct the three token contradictions (token names, page padding,
+   icon sizes) so that agents reading it today get accurate information. Reframe it as a
+   Tailwind/Shadcn mapping doc — no pixel values, no hex codes, a reference to `tokens.css`
+   as source of truth.
+3. **P1 — add missing RAG tokens to dalgo-design-system:** open a PR to `tokens.css` adding
+   `--color-status-on-track`, `--color-status-at-risk`, `--color-status-off-track`,
+   `--color-status-stale`. Until merged, document interim values in `patterns.md`.
+4. **P1 — constitution:** extract the constitution from `CLAUDE.md` / `patterns.md`; resolve
+   the button-casing conflict before writing it. Point `patterns.md` and `checklist.md` at it.
+5. **P1 — Figma Skill:** author the Skill from `tokens.css` (Tier 1 universal tokens) and
+   `components.css` (Tier 2 component families). Drop pattern-pasting from agent prompts.
+6. **P1 — `design.md` ownership:** switch Phase 6 to write `design.md`; leave a spec.md pointer.
+7. **P2 — modes + async brief:** add `--brainstorm` / `--draft`; move the brief to a file with
    `[NEEDS CLARIFICATION]` tagging.
-5. **P2 — agent topology:** add Scout, the evaluator loop, and the consistency spot-check with
+8. **P2 — agent topology:** add Scout, the evaluator loop, and the consistency spot-check with
    a fixed frame-agent return schema.
 
 ---
@@ -211,9 +330,16 @@ and constitution location chosen; naming and brainstorm-storage recommended). Wh
 before the command rewrite:
 
 1. **Confirm the two recommendations** (naming standard, brainstorm storage) — or override them.
-2. **Skill authoring:** publishing `patterns.md` as a Figma Skill is the one step that depends
-   on Figma's native Skills mechanism. We should confirm the workspace has it enabled and decide
-   whether the Skill is authored in Figma or generated from `patterns.md` in-repo.
-3. **Engineering buy-in on the constitution:** `plan-feature` / `execute-plan` pointing at the
+2. **Button casing conflict:** `components.css` sets `text-transform: uppercase` on `.btn`;
+   the constitution rule says "sentence case on buttons." Needs a decision: does the CSS
+   govern (uppercase always), does copy govern (sentence case, CSS overridden per variant),
+   or is this a design-system bug to fix upstream?
+3. **RAG status tokens:** `on-track` / `at-risk` / `off-track` / `stale` color tokens are
+   missing from `tokens.css`. Need to be added to `DalgoT4D/dalgo-design-system` before the
+   Figma Skill can be authoritative for status screens.
+4. **Skill authoring approach:** should the Figma Skill file be authored manually in Figma, or
+   generated by a script that reads `tokens.css` → outputs Skill markdown? Script is more
+   maintainable. Also need to confirm the Figma workspace has native Skills enabled.
+5. **Engineering buy-in on the constitution:** `plan-feature` / `execute-plan` pointing at the
    same `.claude/constitution.md` is a cross-team change — worth a nod from engineering before
    we wire it in.

From c4ef86eaaf7022f76290cbb1ccdc8d553ce90341 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 17:13:44 +0000
Subject: [PATCH 03/10] Rewrite patterns.md to match dalgo-design-system
 tokens.css / components.css
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous version used Shadcn token names and incorrect values that
contradicted the canonical design system. This rewrite:

- Adds header pointing to DalgoT4D/dalgo-design-system as source of truth
- Replaces Shadcn token names with real --color-* / --font-* / --space-*
  token names from tokens.css, with Tailwind/Shadcn equivalents alongside
- Corrects page padding: 32px horizontal (--spacing-page-x), 28px vertical
  (--spacing-page-y) — was incorrectly stated as 24px / p-6
- Replaces blanket "16px icons" with context-specific size table
- Adds full typography scale (13–32px), font weights, letter spacing
- Adds spacing semantic aliases table with resolved pixel values
- Adds border radius, shadow, transition, and layout dimension tokens
- Notes missing RAG status color tokens and the placeholder names to use
- Notes the .btn text-transform:uppercase conflict with button copy rules
- Adds icon size guidance per context (buttons, nav, table, empty state)

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 .claude/skills/design-review/patterns.md | 206 ++++++++++++++++++-----
 1 file changed, 163 insertions(+), 43 deletions(-)

diff --git a/.claude/skills/design-review/patterns.md b/.claude/skills/design-review/patterns.md
index b7107a7..a384e51 100644
--- a/.claude/skills/design-review/patterns.md
+++ b/.claude/skills/design-review/patterns.md
@@ -1,51 +1,142 @@
 # Dalgo UI Patterns Reference
 
-Established patterns used across the Dalgo platform. Use these as the baseline when reviewing new UI work.
+**Source of truth:** [`DalgoT4D/dalgo-design-system`](https://github.com/DalgoT4D/dalgo-design-system)  
+— `tokens.css` (design tokens) + `components.css` (component specs, all values reference `var(--*)`).
+
+This file maps design-system tokens → Tailwind / Shadcn class names for `webapp_v2`.  
+Do not hardcode hex values or pixel sizes — reference CSS variables or the mappings below.
+
+---
 
 ## Component Library
 
 - **Primary library:** Shadcn UI (Radix UI headless primitives with custom styling)
 - **Components location:** `webapp_v2/components/ui/`
-- **Icon library:** Lucide icons, 16px (h-4 w-4)
-
-## Color Palette
+- **Icon library:** Lucide (size is context-specific — see Icon Sizes section)
+
+---
+
+## Design Tokens → Tailwind / Shadcn Mapping
+
+### Colors
+
+| Design system token | Value | Tailwind / Shadcn equivalent | Role |
+|---------------------|-------|------------------------------|------|
+| `--color-brand-primary` | `#00897b` | `style={{ backgroundColor: 'var(--color-brand-primary)' }}` | CTAs, active states, brand |
+| `--color-brand-primary-hover` | `#00796b` | hover on brand elements | Button hover |
+| `--color-brand-primary-light` | `#e8f4f3` | — | Light teal backgrounds |
+| `--color-text-primary` | `#1a1a2e` | `text-foreground` | Main body text |
+| `--color-text-secondary` | `#5c5c6d` | `text-muted-foreground` | Subtext, descriptions, subtitles |
+| `--color-text-tertiary` | `#7a7a8c` | — | De-emphasised labels |
+| `--color-text-placeholder` | `#b0b0be` | `placeholder:text-muted-foreground` | Input placeholders |
+| `--color-bg` | `#f8fafb` | `bg-background` | Page background |
+| `--color-surface` | `#ffffff` | `bg-white` / `bg-card` | Cards, panels, header |
+| `--color-surface-hover` | `#f5f7f8` | `hover:bg-muted` | Table row hover |
+| `--color-border` | `#e8ecef` | `border` | Default borders |
+| `--color-row-divider` | `#f1f5f9` | — | Between table rows |
+| `--color-alert` | `#ef5350` | `text-destructive` | Errors, delete actions |
+
+**Rule:** Never hardcode hex values. Reference `var(--color-*)` directly, or the Tailwind class equivalents above.
+
+**Missing (not yet in `tokens.css`):** RAG status colors — on-track, at-risk, off-track, stale.  
+These need to be added to the design system repo. Use the design-system token names when they land:  
+`--color-status-on-track`, `--color-status-at-risk`, `--color-status-off-track`, `--color-status-stale`.
+
+### Typography
+
+| Design system token | Value | Tailwind equivalent | Usage |
+|---------------------|-------|---------------------|-------|
+| `--font-size-3xl` | 32px | `text-3xl` | Page headings |
+| `--font-size-2xl` | 28px | `text-[28px]` | Large modal titles |
+| `--font-size-xl` | 26px | `text-[26px]` | Section headings |
+| `--font-size-lg` | 22px | `text-[22px]` | Card titles |
+| `--font-size-md` | 16px | `text-base` | Form labels, body text |
+| `--font-size-base` | 15px | `text-[15px]` | Standard body |
+| `--font-size-sm` | 14px | `text-sm` | Table cells, hints, secondary text |
+| `--font-size-xs` | 13px | `text-xs` | Badges, timestamps, metadata |
+
+| Design system token | Value | Usage |
+|---------------------|-------|-------|
+| `--font-weight-regular` | 400 | Body text |
+| `--font-weight-medium` | 500 | Labels, nav items |
+| `--font-weight-semibold` | 600 | Section headings |
+| `--font-weight-bold` | 700 | Page headings |
+| `--line-height-normal` | 1.5 | Default body |
+| `--letter-spacing-button` | 0.3px | Button labels |
+
+**Font:** `--font-sans: 'Anek Latin'` — set globally, never per-component.  
+Requires: `<link href="https://fonts.googleapis.com/css2?family=Anek+Latin:wght@400;500;600;700&display=swap" rel="stylesheet">`
+
+### Spacing
+
+The spacing scale is **not Tailwind's standard 4px multiples** — use the named semantic aliases:
+
+| Semantic alias | Resolves to | Value | Use |
+|----------------|-------------|-------|-----|
+| `--spacing-page-x` | `--space-12` | 32px | Horizontal page padding |
+| `--spacing-page-y` | `--space-11` | 28px | Vertical page padding |
+| `--spacing-section` | `--space-11` | 28px | Between major sections |
+| `--spacing-form-group` | `--space-10` | 24px | Between form field groups |
+| `--spacing-label` | `--space-3` | 8px | Label → input gap |
+| `--spacing-header-gap` | `--space-7` | 16px | Elements inside the header |
+| `--spacing-tag-gap` | `--space-2` | 6px | Between tags |
+| `--spacing-frequency-gap` | `--space-3` | 8px | Between frequency buttons |
+
+Raw scale (partial): `--space-3`=8px · `--space-5`=12px · `--space-7`=16px · `--space-9`=20px · `--space-10`=24px · `--space-11`=28px · `--space-12`=32px · `--space-13`=40px · `--space-14`=48px
+
+### Border Radius
 
 | Token | Value | Usage |
 |-------|-------|-------|
-| `--primary` | `#00897B` (teal) | CTAs, active states, brand elements |
-| `text-muted-foreground` | (from Shadcn) | Subtext, descriptions, subtitles |
-| `text-destructive` | (from Shadcn) | Delete buttons, error states |
-| `bg-background` | (from Shadcn) | Page/section backgrounds |
-| `text-foreground` | (from Shadcn) | Main text color |
+| `--radius-sm` | 6px | Inputs, tags, small chips |
+| `--radius-md` | 8px | Cards, modals, buttons |
+| `--radius-lg` | 12px | Large panels |
+| `--radius-full` | 50% | Avatars, circular badges |
 
-**Rule:** Never hardcode hex values. Always use CSS variables or Tailwind theme classes.
+### Layout Dimensions
 
-## Typography
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--sidebar-width` | 224px | Left navigation rail |
+| `--header-height` | 60px | Top bar |
+
+### Shadows
 
-| Class | Usage |
+| Token | Usage |
 |-------|-------|
-| `text-3xl font-bold` | Page headings (Charts, Pipelines, etc.) |
-| `text-xl font-semibold` | Section headings, card titles, modal titles |
-| `text-base` | Form labels, body text |
-| `text-sm` | Table cells, form hints, secondary text |
-| `text-xs` | Badges, timestamps, metadata |
+| `--shadow-modal` | Dialog / modal overlay |
+| `--shadow-dropdown` | Dropdown menus, popovers |
+| `--shadow-focus` | Focus ring on interactive elements (3px, brand-primary-ring) |
 
-**Font:** Anek Latin via `var(--font-anek-latin)`, set globally. Never set per-component.
+### Transitions
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--transition-fast` | 0.10s ease | Hover on small elements |
+| `--transition-normal` | 0.15s ease | Most interactive states |
+| `--transition-slow` | 0.25s ease | Page-level transitions |
+
+---
 
 ## Page Layout Pattern
 
-All list/index pages follow this structure:
+All list / index pages follow this structure:
 
 ```
-Fixed header (border-bottom, bg-background)
-  ├── Title (text-3xl font-bold) + Subheading (text-muted-foreground)
+Fixed header (border-bottom, bg: --color-surface, height: --header-height 60px)
+  ├── Title (--font-size-3xl / --font-weight-bold / --color-text-primary)
+  ├── Subheading (--font-size-sm / --color-text-secondary)
   └── Optional CTA button (top-right)
+
 Scrollable content area
+  padding: --spacing-page-y (28px) --spacing-page-x (32px)
   └── Tables, cards, lists, etc.
 ```
 
 **Reference:** `app/charts/page.tsx`, `components/pipeline/pipeline-list.tsx`
 
+---
+
 ## Button Patterns
 
 ### Primary CTA
@@ -53,10 +144,10 @@ Scrollable content area
 <Button
   variant="ghost"
   className="text-white hover:opacity-90 shadow-xs"
-  style={{ backgroundColor: 'var(--primary)' }}
+  style={{ backgroundColor: 'var(--color-brand-primary)' }}
 >
   <Plus className="h-4 w-4 mr-2" />
-  ACTION LABEL
+  Create Report
 </Button>
 ```
 
@@ -80,66 +171,95 @@ Scrollable content area
 </Button>
 ```
 
+**Note:** `components.css` applies `text-transform: uppercase` on `.btn`. In `webapp_v2` (Tailwind/Shadcn)
+this is not inherited; follow the label casing of existing Shadcn buttons in the codebase.  
+This is an open conflict — see the constitution once it is written.
+
+---
+
+## Icon Sizes
+
+Sizes are context-specific — do not apply a blanket 16px rule:
+
+| Context | Size | Tailwind class |
+|---------|------|----------------|
+| Button icons | 16px | `h-4 w-4` |
+| Nav rail icons | 18px | `h-[18px] w-[18px]` |
+| Table action icons | 14px | `h-3.5 w-3.5` |
+| Empty state illustration | 40–48px | `h-10 w-10` or `h-12 w-12` |
+
+---
+
 ## Dialog / Modal Pattern
 
 - Component: Shadcn `Dialog`
+- Shadow: `--shadow-modal`
 - Max width: `sm:max-w-md` for forms
-- Mobile: Should use bottom sheets for complex forms
+- Mobile: bottom sheets for complex forms
 - Reference: `components/reports/share-via-email-dialog.tsx`
 
+---
+
 ## Form Patterns
 
 - **Complex forms:** React Hook Form (uncontrolled)
 - **Simple inputs:** useState (controlled)
+- **Label gap:** `--spacing-label` (8px) between label and input
 - **Labels:** `<Label>` + required indicator `<span className="text-destructive">*</span>`
-- **Helper text:** 12px, `text-muted-foreground`, below input
-- **Errors:** Inline below field, red text
+- **Helper text:** `--font-size-xs` (13px), `--color-text-secondary`, below input
+- **Errors:** Inline below field, `--color-alert` (`#ef5350`) text
 - **Validation:** Inline as user types, not just on submit
 
+---
+
 ## Card Pattern
 
 - Shadcn `Card` + `CardContent`
-- Border: 1px solid
-- Padding: 16px
-- Border radius: 8px
-- Hover: Border color changes to primary for interactive cards
+- Border: 1px solid `--color-border`
+- Padding: `--space-7` (16px)
+- Border radius: `--radius-md` (8px)
+- Hover: border → `--color-brand-primary` for interactive cards
+
+---
 
 ## Dropdown Menu Pattern
 
 - Shadcn `DropdownMenu` + `DropdownMenuItem`
-- Icons: Lucide, h-4 w-4, left-aligned
+- Shadow: `--shadow-dropdown`
+- Icons: Lucide, `h-4 w-4`, left-aligned
 - Reference: `components/reports/report-share-menu.tsx`
 
+---
+
 ## Email Input Pattern
 
 - Textarea with comma/semicolon separation (NOT chip-based UI)
-- Validation: EMAIL_REGEX from `components/reports/utils.ts`
-- Max recipients: 20 (MAX_RECIPIENTS constant)
+- Validation: `EMAIL_REGEX` from `components/reports/utils.ts`
+- Max recipients: 20 (`MAX_RECIPIENTS` constant)
 - Helper text: "Recipients are separated by ',' or ';'"
 
+---
+
 ## Toast Notifications
 
 - Library: Sonner
 - Always use helpers from `lib/toast.ts`: `toastSuccess`, `toastError`, `toastInfo`, `toastPromise`
 - Never call `toast()` directly
-- Success: Specific + actionable ("Report sent to 3 recipients")
-- Error: Explain + suggest recovery ("Invalid email: maya@ngo (missing domain)")
-
-## Spacing System
+- Success: specific + actionable ("Report sent to 3 recipients")
+- Error: explain + suggest recovery ("Invalid email: maya@ngo (missing domain)")
 
-- Base grid: 4px (Tailwind defaults)
-- Component padding: 16px
-- Section gaps: 24px vertical
-- Page padding: `p-6`
+---
 
 ## Information Architecture
 
-- Dashboard (parent) -> Reports (children) hierarchy
+- Dashboard (parent) → Reports (children) hierarchy
 - Don't manage parent entities from child pages
-- Use awareness + jump links: "This dashboard has 2 schedules. [Manage ->]"
+- Use awareness + jump links: "This dashboard has 2 schedules. [Manage →]"
 - Breadcrumbs for deep hierarchies
 - Back buttons for linear flows
 
+---
+
 ## Data Display
 
 - Tables for structured data with sorting

From 4e988bc10c897c60e4c048281dbdf326ef1a7da5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 17:44:56 +0000
Subject: [PATCH 04/10] Rewrite design-handoff command to v2 + add
 constitution.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements all six principles from design-handoff-v2-proposal.md:

1. Three modes: --brainstorm (variants, no handoff), --draft (lo-fi,
   no prototype), ship default (full-fidelity, prototype, design.md)
2. Frame agents read patterns.md in full — no more manual excerpt pasting
3. New .claude/constitution.md as single source of non-negotiables;
   loaded by orchestrator and passed to every agent and evaluator
4. Phase 6 writes design.md (not appends ## Design to spec.md);
   spec.md gets a one-line pointer only
5. Phase 4 is now an evaluator loop: failures fed back to the frame
   agent, up to 3 retries, before marking as manual-fix-needed
6. Phase 2 is async: brief written to design-brief.md, session not
   blocked; [NEEDS CLARIFICATION] tags used where direction is missing

Also fixes all P0 correctness bugs:
- Hardcoded wrong Figma file key removed; key looked up from design.md
  or created fresh via create_new_file
- Wrong MCP tool names fixed (mcp__figma__get_metadata → get_metadata,
  use_figma, get_screenshot, create_new_file)
- Ghost ~/Dalgo/FIGMA.md dependency retired; replaced by constitution
  + patterns.md loaded directly
- /figma-use in agent prompts fixed: agents now load
  skill://figma/figma-use/SKILL.md themselves

New phases added:
- Phase 0: mode resolution, constitution load, file key setup
- Phase 2.9: Scout agent — reads canvas state, returns next_x
- Frame agents use fixed return schema {node_id, frame_name,
  screenshot_url, decisions[], needs_clarification[]}
- Phase 3.9: consistency spot-check across all final frames
- Frame naming convention: S{n} · {Screen Name} for ship/draft,
  S{n}a/b/c for brainstorm variants

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 .claude/commands/design/design-handoff.md | 549 ++++++++++++++--------
 .claude/constitution.md                   |  50 ++
 2 files changed, 390 insertions(+), 209 deletions(-)
 create mode 100644 .claude/constitution.md

diff --git a/.claude/commands/design/design-handoff.md b/.claude/commands/design/design-handoff.md
index 869f167..17023f2 100644
--- a/.claude/commands/design/design-handoff.md
+++ b/.claude/commands/design/design-handoff.md
@@ -2,364 +2,495 @@
 
 ## Input: $ARGUMENTS
 
-Bridge a feature spec into Figma designs with designer input, then update the spec so engineering can start.
+Bridge a feature spec into Figma designs, then produce `design.md` so engineering can start.
 
-Accepts:
-- A spec file path: `features/rbac/v1/spec.md`
-- A feature folder: `features/rbac/v1/`
-- A feature name: `rbac` (looks for `features/rbac/v1/spec.md`)
+**Accepts:**
+- A spec file path: `features/access-control/v1/spec.md`
+- A feature folder: `features/access-control/v1/`
+- A feature name: `access-control` (looks for `features/access-control/v1/spec.md`)
 
-Flags:
-- `--auto` — skip designer input, generate all surfaces autonomously (for prototyping only)
+**Flags:**
+- `--brainstorm` — 2–3 rough layout variants per screen on an "Explorations" page. No prototype, no `design.md`. Use when direction is still open.
+- `--draft` — One lo-fi wireframe per screen, one feedback round. No prototype wiring. Use when iterating on layout.
+- _(default, no flag)_ — Full-fidelity frames, prototype wired, `design.md` written. Use when design is settled and you're producing the engineering handoff.
+
+---
+
+## Phase 0: Setup
+
+### 1. Parse mode
+- Argument contains `--brainstorm` → **Brainstorm mode**
+- Argument contains `--draft` → **Draft mode**
+- No flag → **Ship mode**
+
+Strip the flag from `$ARGUMENTS` before locating the spec.
+
+### 2. Read the constitution
+Read `.claude/constitution.md` — these rules govern every phase and every agent spawned.
+Do not proceed until this file is loaded.
+
+### 3. Locate the spec
+From the cleaned `$ARGUMENTS`, find the spec:
+- If it ends in `.md`, use it directly
+- If it's a folder, look for `spec.md` inside it
+- If it's a feature name, check `features/{name}/v1/spec.md` then `features/{name}/spec.md`
+
+Derive `{feature_name}` and `{version}` (e.g. `v1`) from the path.
+
+### 4. Resolve the Figma file key
+Look for `features/{feature_name}/{version}/design.md`. If it exists, find the line:
+```
+file_key: {key}
+```
+Use that key.
+
+If `design.md` doesn't exist or has no `file_key`, create a new Figma file:
+- Use `create_new_file` with the name `"{Feature Name} — {Version}"` (e.g. `"Access Control — v1"`)
+- Create `features/{feature_name}/{version}/design.md` with just the file key recorded:
+
+```markdown
+# {Feature Name} — Design ({Version})
+
+**Status:** In progress
+
+## Figma
+
+file_key: {key}
+```
 
 ---
 
 ## Phase 1: Read & Extract
 
 ### 1. Read the spec
-Load the spec file from `$ARGUMENTS`. If a folder is given, look for `spec.md` inside it. If only a feature name is given, check `features/{name}/v1/spec.md` then `features/{name}/spec.md`.
+Load the spec file. Read it in full.
 
 ### 2. Extract UI surfaces
-Parse the spec for every user-facing screen, flow, modal, or component that needs designing. Look for:
+Parse the spec for every user-facing screen, flow, modal, or component that needs designing:
 - Explicit screen names ("User management page", "Invite modal")
-- User stories that imply a UI ("As an admin, I want to assign roles...")
-- State changes that need visual design (empty states, error states, success states)
-- Shared components mentioned (badges, selectors, inline controls)
-
-For each surface, extract:
-- **Purpose:** what the user accomplishes on this screen
-- **Persona:** which Dalgo user type interacts with it (admin, PM, field staff)
-- **Key decisions:** things that need a designer's judgment before the screen can be built
+- User stories implying a UI ("As an admin, I want to assign roles...")
+- State changes requiring visual design (empty, error, success states)
+- Shared components (badges, selectors, inline controls)
+
+For each surface extract:
+- **Purpose:** what the user accomplishes
+- **Persona:** which Dalgo user type (admin, PM, analyst, viewer)
+- **Key decisions:** things needing a designer's judgment before building
 - **Dependencies:** does this screen reference another surface?
 
-### 3. Load patterns
-Read `.claude/skills/design-review/patterns.md` and `.claude/skills/design-review/checklist.md` — these are the design standards all generated frames must pass.
+### 3. Load design standards
+Read `.claude/skills/design-review/patterns.md` and `.claude/skills/design-review/checklist.md`
+into the orchestrator context. These are passed to agents in full — do not paste excerpts.
 
 ---
 
-## Phase 1.5: User Flow Extraction
+## Phase 1.5: User Flow Extraction (skip in brainstorm mode)
 
-For each surface extracted above, map the full user journey through that screen. This becomes the basis for prototype connections wired in Figma after frames are created.
+For each surface, map the full user journey. This becomes the basis for prototype connections.
 
 For each surface, produce a flow block:
 
 ```
-**Screen: {Screen Name}**
+Screen: {Screen Name}
+
 Entry points:
 - {How the user arrives — e.g. "clicks 'Invite user' button on User management page"}
 - {Alternative entry — e.g. "redirected here after accepting email invite"}
 
 Happy path:
-1. {Step 1 — e.g. "User sees modal with Name, Email, Role fields"}
-2. {Step 2 — e.g. "User fills in details and clicks 'Send invite'"}
-3. {Step 3 — e.g. "Success toast shown, modal closes, user appears in table"}
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
 
 Branch points:
-- {Condition → Screen} e.g. "Email already exists → inline field error (stays on modal)"
-- {Condition → Screen} e.g. "Last admin demotion attempt → blocked with error banner"
-- {Condition → Screen} e.g. "Cancel / Esc → dismiss modal, no change"
+- {Condition} → {Screen or state}
+- {Condition} → {Screen or state}
 
 Exit points:
 - Success → {target screen or state}
 - Cancel → {target screen or state}
-- Error → {stays on screen / redirects to X}
+- Error → {stays / redirects to X}
 ```
 
-Group screens into **scenarios** — named end-to-end journeys a user might take:
+Group screens into **scenarios** — named end-to-end journeys:
 - e.g. "Invite a new team member" → Invite modal → Success state → User management table
-- e.g. "Change a user's role" → User table → Role selector → Confirm modal → Updated table
-- e.g. "Remove a user" → User table → Delete confirm → Empty state (if last user)
-
-Each scenario becomes a **named prototype flow** in Figma.
 
-Store the extracted flows and scenarios for use in Phase 3 (Figma agent prompts) and Phase 3.5 (prototype wiring).
+Each scenario becomes a named prototype flow in Figma.
 
 ---
 
-## Phase 2: Design Brief (skip if `--auto`)
+## Phase 2: Async Brief
 
-Present the extracted surfaces to the designer in this format:
+### 1. Check for an existing brief
+Look for `features/{feature_name}/{version}/design-brief.md`.
 
-```
-I found {N} screens to design for {Feature Name}.
+**If it exists and has content below any `Your direction:` line:** Read it, extract designer
+direction per surface, and continue directly to Phase 2.9.
 
-Before I generate anything in Figma, I need your direction on a few things:
+**If it's missing or blank:** Write the brief file (step 2) and stop.
 
----
+### 2. Write the brief file
+Create `features/{feature_name}/{version}/design-brief.md`:
 
-**Screen 1: {Screen Name}**
-Who uses it: {persona}
-What it does: {purpose}
-Decisions needed:
-- {Decision 1 — e.g. "Inline role edit or separate modal?"}
-- {Decision 2 — e.g. "What happens when you demote the last admin?"}
-- {Decision 3 — e.g. "Any reference design or existing Dalgo screen to match?"}
+```markdown
+# Design Brief — {Feature Name} {Version}
+
+**Status:** Awaiting designer input
+**Generated:** {date}
+
+Fill in your direction below each surface, then re-run:
+`/design:design-handoff {spec path}`
+
+Leave a section blank to let me use best judgment for an NGO audience
+(I'll tag those decisions `[NEEDS CLARIFICATION]` in the output).
 
 ---
 
-**Screen 2: {Screen Name}**
-...
+{for each surface:}
+
+## Surface: {Screen Name}
+
+**Who uses it:** {persona}
+**What it does:** {purpose}
+
+**Decisions needed:**
+- {Decision 1}
+- {Decision 2}
+
+**Reference design (if any):**
+
+**Your direction:** <!-- fill in here -->
 
 ---
+```
 
-Reply with your direction for each screen. You can:
-- Answer the decisions ("Screen 1: inline edit, block last-admin demotion")
-- Skip a screen ("skip Screen 3 — not needed for v1")
-- Add context ("reference the existing Reports share modal for Screen 2")
-- Point to inspiration ("Screen 4 should look like Notion's permission picker")
+Print:
+```
+Brief written to features/{feature_name}/{version}/design-brief.md
 
-I won't generate anything until you reply.
+Open it in your editor, fill in direction for each surface, then re-run:
+/design:design-handoff {spec path}
 ```
 
-**Wait for designer reply before proceeding.** Do not spawn any Figma agents until the designer has responded.
+**Stop here.** Do not spawn any Figma agents.
+
+### 3. Parse a completed brief
+When re-running and the brief has responses, extract direction per surface.
+Where a `Your direction:` field is blank or missing, note that surface as `[NEEDS CLARIFICATION]`
+and generate using best judgment for a non-technical NGO audience.
+
+---
+
+## Phase 2.9: Scout
+
+Spawn a Scout agent with this prompt:
+
+```
+You are reading a Figma file to establish baseline context for frame agents.
+
+Figma file key: {file_key}
+
+1. Call get_metadata on the file. Collect all existing frames: their names, node IDs, and x positions.
+2. If the file has no frames, return next_x = 0.
+3. If frames exist, call get_screenshot on each and note which belong to this feature.
+   Return the rightmost x position across all frames + 100px gap as next_x.
+4. Return this exact JSON:
+{
+  "file_key": "{file_key}",
+  "existing_frames": [{"name": "...", "node_id": "...", "x": 0}],
+  "next_x": 0,
+  "notes": "any relevant observations about canvas state"
+}
+```
 
-### Parse designer reply
-Read the reply and map each direction to its surface:
-- Extract copy/label decisions ("use 'Full access' not 'Admin'")
-- Note referenced screens or external inspiration
-- Note skipped surfaces
-- Note any specific layout preferences ("single-step modal", "use the existing empty state pattern")
+Wait for Scout to complete before spawning frame agents.
 
 ---
 
 ## Phase 3: Generate Designs in Figma
 
-### 1. Determine Figma page name
-Use `"{Feature Name} Designs"` as the page name (e.g. "RBAC Designs"). Check if it already exists using `mcp__figma__get_metadata` on file key `v8BYFkebTGQNuiRrCXWssa`.
+### Mode behaviour
+
+| Mode | Page | Fidelity | Variants | Prototype |
+|------|------|----------|----------|-----------|
+| Brainstorm | "Explorations" | Rough wireframe | 2–3 per surface | No |
+| Draft | "Designs" | Lo-fi wireframe | 1 per surface | No |
+| Ship | "Designs" | Full-fidelity | 1 per surface | Yes |
+
+### Frame naming
+- Ship / Draft: `S{n} · {Screen Name}` (e.g. `S1 · User Management`)
+- Brainstorm variants: `S{n}a · {Screen Name}`, `S{n}b · {Screen Name}`, `S{n}c · {Screen Name}`
+- States: `S{n}-{State}` (e.g. `S1-Empty`, `S1-Error`)
+
+### Frame agent prompt
+Spawn one agent per surface in parallel. Each **must** return this fixed JSON schema — no other format:
+
+```json
+{
+  "node_id": "string",
+  "frame_name": "string",
+  "screenshot_url": "string",
+  "decisions": ["string"],
+  "needs_clarification": ["string"]
+}
+```
 
-### 2. Spawn one Figma agent per surface (in parallel)
-For each surface (excluding skipped ones), spawn an agent with this context:
+Agent prompt template:
 
 ```
-You are a UX designer for Dalgo — an open-source data platform for non-technical NGO program managers.
+You are a UX designer for Dalgo — an open-source data platform for non-technical NGO program
+managers. Users are non-technical, on slow internet and old devices. Simplicity matters more
+than visual richness.
 
 Feature: {Feature Name}
 Screen: {Screen Name}
 Persona: {persona}
 Purpose: {purpose}
+Mode: {brainstorm | draft | ship}
 
 Designer direction:
-{designer's direction for this screen}
+{direction from design-brief.md, or "[NEEDS CLARIFICATION] — use best judgment for NGO audience"}
 
 User flow for this screen:
-{paste the flow block from Phase 1.5 for this surface — entry points, happy path, branch points, exit points}
-
-Scenario(s) this screen belongs to:
-{list scenario names from Phase 1.5 that include this screen}
-
-Dalgo Design System:
-- Primary color: #00897B (teal)
-- Font: Anek Latin
-- Icons: Lucide 16px
-- Cards: 1px border, 8px radius, 16px padding
-- Spacing: 4px grid, 24px page padding
-- Primary CTA: ghost variant, teal background (#00897B), white text
-- Secondary: outline button
-- Sentence case on all buttons ("Cancel" not "CANCEL")
-- Status colors: green #16a34a (on track), amber #d97706 (at risk), red #dc2626 (off track)
-- Never expose SQL, schema table names, or code to non-admin users
-- Lock icon + "Contact admin to change" for admin-only fields
-
-Key patterns to follow:
-{paste relevant excerpts from patterns.md for this surface type}
-
-Figma file: v8BYFkebTGQNuiRrCXWssa
-Page: {page name}
-Frame name: "{Screen Name}"
+{flow block from Phase 1.5}
+
+Design standards — read and apply in full:
+{full content of patterns.md}
+
+Constitution — never violate these rules:
+{full content of .claude/constitution.md}
+
+Figma file key: {file_key}
+Page: {page name — "Explorations" for brainstorm, "Designs" for draft/ship}
+Frame name: {frame name per naming convention above}
 Frame size: 1440×900px
-Position: x={calculated offset}, y=0
-
-Instructions:
-1. Invoke the /figma-use skill first — mandatory before calling use_figma
-2. Create the frame on the "{page name}" page (create the page if it doesn't exist)
-3. Name the frame exactly as "{Screen Name}" — this name is used to wire prototype connections in the next phase
-4. After creating, call get_screenshot on the created node and verify it matches the brief
-5. Return the node ID, frame name, and a one-line description of what was built
+Position: x={scout.next_x + (surface_index × 1540)}, y=0
+
+{brainstorm only: create 2–3 variants at x offsets of 0, 1540, 3080 from your starting position}
+
+Steps:
+1. Load skill://figma/figma-use/SKILL.md before calling use_figma — this is mandatory.
+2. Create the page if it does not exist.
+3. Create the frame at the specified position with the specified name.
+4. After creating, call get_screenshot on the created node.
+5. Record any design decisions made (label choices, layout choices, copy decisions).
+6. Record anything that needs the designer's input as [NEEDS CLARIFICATION].
+7. Return the fixed JSON schema — node_id, frame_name, screenshot_url, decisions[], needs_clarification[].
 ```
 
-Position frames left to right with 100px gaps: x=0, x=1540, x=3080, etc.
-
-### 3. Collect node IDs
-Wait for all agents to complete. Collect the node ID, frame name, and description for each frame.
+### Collect results
+Wait for all agents. Validate every response matches the fixed schema before proceeding.
+If an agent returns malformed output, re-prompt it once requesting the correct JSON.
 
 ---
 
-## Phase 3.5: Wire Prototype Connections
-
-Using the user flows and scenarios from Phase 1.5, add prototype connections between frames in Figma. This turns the static frames into a navigable, clickable prototype.
+## Phase 3.5: Wire Prototype Connections (ship mode only)
 
 ### 1. Build the connection map
-For each scenario, map out every connection:
+Using flows and scenarios from Phase 1.5:
 
 ```
 Scenario: {Scenario Name}
 Connections:
-- From: {Frame Name} | Trigger: {element clicked — e.g. "'Send invite' button"} → To: {Frame Name}
-- From: {Frame Name} | Trigger: {"Cancel" button click} → To: {Frame Name}
-- From: {Frame Name} | Trigger: {error condition} → To: {Frame Name}
+- From: {Frame Name} | Trigger: {element} → To: {Frame Name}
+- From: {Frame Name} | Trigger: Cancel → To: {Frame Name}
+- From: {Frame Name} | Trigger: {error} → To: {Frame Name}
 ```
 
-### 2. Invoke `/figma-use` skill
-Mandatory before calling `use_figma` for prototype wiring.
-
-### 3. Add connections via `use_figma`
-For each connection in the map, use `use_figma` to:
-- Select the trigger element on the source frame (button, link, overlay area)
-- Add a prototype interaction: `On click → Navigate to → {target frame node ID}`
-- For overlays/modals: use `Open overlay` instead of Navigate
-- For back/cancel flows: use `Navigate to` with `Back` or the specific target frame
+### 2. Add connections via use_figma
+Load skill://figma/figma-use/SKILL.md first (mandatory before calling use_figma).
 
-Wire all connections in one `use_figma` call per scenario where possible.
+For each connection:
+- Select the trigger element on the source frame
+- Add interaction: `On click → Navigate to → {target frame node ID}`
+- Overlays / modals: use `Open overlay` instead of Navigate
+- Back / cancel flows: `Navigate to` with the specific target frame node ID
 
-### 4. Set starting frames per scenario
-For each scenario, mark the first frame as the **starting point** of that named flow in Figma:
-- Use `use_figma` to set the flow start frame with the scenario name as the flow label
-- This creates named flows in Figma's prototype panel (e.g. "Invite a new team member")
+### 3. Set flow start frames
+For each scenario, mark the first frame as the starting point in Figma's prototype panel,
+labelled with the scenario name (e.g. "Invite a new team member").
 
-### 5. Collect wiring results
-For each scenario, confirm:
-- All connections were added successfully
-- Flow start frame is set
-- Note any connections that could not be wired (e.g. element not found in frame) for manual follow-up
+### 4. Record wiring results
+Note any connections that could not be wired for manual follow-up.
 
 ---
 
-## Phase 4: Design Review
+## Phase 4: Evaluator Loop (skip in brainstorm mode)
 
-For each created frame, run the design review checklist from `.claude/skills/design-review/checklist.md`. Specifically check:
+For each frame, spawn an evaluator agent:
 
-**Content & Copy:**
-- [ ] Sentence case on all buttons
-- [ ] No SQL, schema names, or code visible to non-admin users
-- [ ] No internal acronyms (RAG, blast radius) in UI copy
-- [ ] Placeholder text uses "e.g." not "Choose"
+```
+You are reviewing a Figma frame against Dalgo's design standards.
 
-**NGO User Specific:**
-- [ ] Screen purpose clear in 5 seconds
-- [ ] Creation flows are user-task-first (not data-model-first)
-- [ ] Admin-only fields are visually locked (lock icon)
+Frame: {frame_name} (node_id: {node_id})
+Screenshot: {screenshot_url}
 
-**Blast Radius (if applicable):**
-- [ ] "Used By" count shown if entity has dependents
-- [ ] Edit modal shows amber impact banner if entity is shared
-- [ ] Delete confirmation lists dependents as links when Used By > 0
+Review checklist:
+{full content of checklist.md}
 
-**Status & KPI (if applicable):**
-- [ ] RAG color is dominant visual signal (not just a text label)
-- [ ] Trend language is unambiguous
+Constitution (must never be violated):
+{full content of .claude/constitution.md}
 
-Produce a review table:
+Check the screenshot against every item. Return this exact JSON:
+{
+  "frame_name": "string",
+  "passed": true or false,
+  "failures": [
+    {"item": "checklist item text", "issue": "what is wrong", "fix": "specific correction"}
+  ]
+}
+```
 
+**If failures:** Send the failure list back to the frame agent that created this frame:
 ```
-| Screen | Node ID | Issues | Status |
-|--------|---------|--------|--------|
-| User management table | 11900:63 | None | ✅ Ready |
-| Invite user modal | 11901:63 | "Admin" label → "Full access" | ⚠ Fix needed |
+Your frame "{frame_name}" failed design review. Fix these issues and regenerate the frame,
+then return the updated JSON schema.
+
+Failures:
+{failures list}
 ```
 
+**Retry limit:** 3 rounds per frame. If still failing after round 3, mark the frame:
+`[REVIEW FAILED — manual fix needed]` and continue.
+
+**If passed:** Frame is final. Record it as passing.
+
+---
+
+## Phase 3.9: Consistency Spot-Check
+
+After all frames pass (or exhaust retries), spawn one consistency agent:
+
+```
+Take a screenshot of each frame listed below and compare them for visual consistency.
+
+Frames: {list of node_ids and frame names}
+
+Check for drift in:
+- Sidebar (width, active state style)
+- Header (height, element positions, org name display)
+- Page padding (should be --spacing-page-x 32px horizontal, --spacing-page-y 28px vertical)
+- Primary CTA button (colour, style)
+- Typography (heading sizes and weights)
+
+Return:
+{"consistent": true}
+— or —
+{"consistent": false, "issues": [{"frames": ["S1 · ...", "S2 · ..."], "property": "...", "description": "..."}]}
+```
+
+If drift is found, note it for the designer in Phase 5. Do not auto-fix.
+
 ---
 
 ## Phase 5: Designer Sign-off
 
-Present the review results and ask:
+Present results:
 
 ```
-Designs are ready on the "{page name}" Figma page.
+Designs ready on the "{page name}" page.
+
+| Frame | Node ID | Status |
+|-------|---------|--------|
+| S1 · User Management | ... | ✅ Passed |
+| S2 · Invite Modal    | ... | ⚠ [NEEDS CLARIFICATION] — role picker direction not provided |
+| S3 · Role Editor     | ... | 🔴 [REVIEW FAILED] — fix manually |
 
-Review summary:
-{review table}
+{if consistency issues}
+Consistency issues flagged:
+- S1 and S3: page padding differs
 
-{if issues exist}
-{N} screen(s) need attention before I update the spec:
-- {Screen}: {issue} → Suggested fix: {fix from patterns.md}
+{if [NEEDS CLARIFICATION] items}
+These were generated without your direction — confirm or redirect:
+{list of needs_clarification items per frame, with what was assumed}
 
 Options:
-1. Fix the issues and regenerate the flagged frames
-2. Accept as-is and note the issues in the spec for engineering to handle
-3. Revise a specific frame ("redo Screen 2 with X change")
+1. Approve — I'll write design.md and engineering can start
+2. Revise a frame: "redo S2 with inline role picker, not a modal"
+3. Brainstorm alternatives: "brainstorm S3"
 ```
 
-Wait for designer response before updating the spec.
+Wait for designer response before writing `design.md`.
 
 ---
 
-## Phase 6: Update the Spec
+## Phase 6: Write design.md
 
-Append a `## Design` section to the spec file:
+Write `features/{feature_name}/{version}/design.md` as the engineering handoff document:
 
 ```markdown
-## Design
+# {Feature Name} — Design ({Version})
 
-**Status:** {Ready for engineering / Pending fixes}
-**Figma page:** {URL to page}
+**Status:** Ready for engineering
+**Spec:** ../spec.md
+**Figma:** https://figma.com/file/{file_key}
 **Last updated:** {date}
 
-### Screens
+## Screens
 
-| Screen | Node ID | Figma Link | Status |
-|--------|---------|-----------|--------|
-| {Screen Name} | {node_id} | [View →]({figma_url}) | ✅ Ready |
+| Screen | Frame name | Node ID | Figma link | Status |
+|--------|-----------|---------|-----------|--------|
+| {Screen Name} | S1 · {Screen Name} | {node_id} | [View →](https://figma.com/file/{file_key}?node-id={node_id}) | ✅ Ready |
 
-### User Flows & Prototype
+## User Flows & Prototype
 
-| Scenario | Starting Frame | Prototype Link | Connections |
-|----------|---------------|----------------|-------------|
-| {Scenario Name} | {Frame Name} | [Preview →]({figma_prototype_url}) | {N} wired |
+| Scenario | Starting frame | Connections wired |
+|----------|---------------|-------------------|
+| {Scenario Name} | S1 · {Screen Name} | {N} |
 
-### Design Decisions
+## Design Decisions
 
-Decisions made during design brief that engineering must implement:
-- **Role labels:** Use "Full access / Can edit / Can view only" — not "Admin/Editor/Viewer"
-- **Last-admin protection:** Block role change that would remove the last org admin; show inline error
-- {other decisions from designer replies}
+{All decisions[] collected from frame agents, deduped and attributed to screen}
 
-### Known Issues
+## Known Issues
 
-{if any screens were accepted with issues}
-- {Screen}: {issue} — to be resolved in v2
+{Any [REVIEW FAILED] or unresolved [NEEDS CLARIFICATION] items}
 
-### Design Checklist
+## Figma
 
-- [ ] All screens reviewed against patterns.md
-- [ ] NGO user lens applied
-- [ ] Blast radius handled where applicable
-- [ ] Designer has signed off
+file_key: {file_key}
+```
+
+Then add a one-line pointer in `spec.md` if not already present:
+```markdown
+**Design:** [v{N}/design.md](v{N}/design.md)
 ```
 
 ---
 
 ## Phase 7: Signal Readiness
 
-Print:
-
 ```
-Design gate complete. Spec updated at {spec path}.
+Design gate complete.
 
 {N} screens designed → {M} passed review → {K} issues noted
 
-Next: /engineering/plan-feature {spec path}
-```
+design.md: features/{feature_name}/{version}/design.md
 
-If there are unresolved issues, print:
+Next: /engineering/plan-feature features/{feature_name}/{version}/spec.md
+```
 
+If open issues remain:
 ```
-⚠ Design gate has {K} open issue(s). Resolve before engineering starts,
-or run with known issues and track them in the spec.
+⚠ {K} issue(s) need manual attention before engineering starts.
+See design.md → Known Issues.
 
-Next: /engineering/plan-feature {spec path}
+Next: /engineering/plan-feature features/{feature_name}/{version}/spec.md
 ```
 
 ---
 
 ## Quality Checklist
 
-- [ ] Designer was given a brief and responded before any generation started (unless `--auto`)
-- [ ] Every screen has a node ID and was verified with a screenshot
-- [ ] User flows extracted for every surface (entry points, happy path, branches, exits)
-- [ ] Screens grouped into named scenarios
-- [ ] Prototype connections wired for all scenarios
-- [ ] Named flow start frames set per scenario in Figma prototype panel
-- [ ] Design review was run against the updated checklist
-- [ ] Designer signed off (or explicitly accepted issues)
-- [ ] Spec `## Design` section is complete with node IDs, scenario table, decisions, and known issues
+- [ ] Mode resolved (brainstorm / draft / ship)
+- [ ] Constitution loaded before any agent was spawned
+- [ ] Figma file key resolved (from `design.md` or newly created)
+- [ ] Design brief written or read (session was not blocked)
+- [ ] Scout ran and returned canvas state and `next_x`
+- [ ] All frame agents returned the fixed JSON schema
+- [ ] Evaluator loop ran for every frame (draft and ship modes)
+- [ ] Consistency spot-check ran across all final frames
+- [ ] Designer signed off
+- [ ] `design.md` written with node IDs, decisions, known issues, and `file_key`
+- [ ] `spec.md` updated with one-line pointer to `design.md`
 - [ ] Next step printed clearly
diff --git a/.claude/constitution.md b/.claude/constitution.md
new file mode 100644
index 0000000..f676520
--- /dev/null
+++ b/.claude/constitution.md
@@ -0,0 +1,50 @@
+# Dalgo — Product Constitution
+
+Non-negotiables. Every design and engineering decision must honour these.
+Files that restate these rules should reference this file instead.
+
+Referenced by: `.claude/skills/design-review/patterns.md` · `.claude/skills/design-review/checklist.md`
+· `.claude/commands/design/design-handoff.md` · `.claude/commands/engineering/plan-feature.md`
+
+---
+
+## Users
+
+Dalgo users are non-technical program managers, data coordinators, and field staff at small NGOs.
+Assume:
+- No SQL knowledge, no data engineering background
+- Slow internet (2G/3G common in the field)
+- Old devices (budget Android phones and laptops from 2018–2020)
+- Small teams — often one person manages the whole data workflow
+- English may not be their first language
+
+## Data Access Rules
+
+- **Never expose SQL** to non-admin users — not in UI copy, not in error messages, not in logs
+- **Never expose schema or table names** (e.g. `public.beneficiary_data`) to non-admin users
+- **Never expose internal code or stack traces** in user-facing messages
+- Admin-only fields must be **visually locked**: lock icon + "Contact your admin to change this"
+
+## Language & Copy
+
+- **Sentence case on all interactive labels** — "Create pipeline" not "CREATE PIPELINE"
+- **No internal acronyms** in user-facing copy — not RAG, blast radius, dbt, ELT, ETL
+- **No jargon** without a plain-English explanation alongside it
+- Error messages must state **what went wrong AND what to do next**
+- Success messages must be **specific** ("Report sent to 3 recipients" not "Done")
+- Loading states must be **specific** ("Syncing data..." not "Loading...")
+
+## Design Standards
+
+- Performance over visual richness — every added element must earn its place
+- Progressive disclosure — hide advanced options until the user needs them
+- Smart defaults — minimise required user input
+- Every screen must communicate its purpose within 5 seconds
+- Every destructive action requires explicit confirmation
+- Every empty state must have a message and a primary action CTA
+- Multi-tenant — users must only ever see their own organisation's data
+
+## Platform
+
+- Open source (AGPL-3.0) — no proprietary dependencies without team approval
+- ~20 partner NGOs, budget-constrained — no features requiring expensive infrastructure

From 0c6418dfe72515b54ff325cfca901ee7c9228df2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 17:49:37 +0000
Subject: [PATCH 05/10] Fix spec selection: resolve highest version from
 feature folder

When given a feature name or folder (e.g. access-control), the command
now scans all v{N}/ subdirectories and picks the highest version that
contains a spec.md, rather than hardcoding v1.

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 .claude/commands/design/design-handoff.md | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/.claude/commands/design/design-handoff.md b/.claude/commands/design/design-handoff.md
index 17023f2..6777697 100644
--- a/.claude/commands/design/design-handoff.md
+++ b/.claude/commands/design/design-handoff.md
@@ -6,8 +6,9 @@ Bridge a feature spec into Figma designs, then produce `design.md` so engineerin
 
 **Accepts:**
 - A spec file path: `features/access-control/v1/spec.md`
-- A feature folder: `features/access-control/v1/`
-- A feature name: `access-control` (looks for `features/access-control/v1/spec.md`)
+- A versioned folder: `features/access-control/v1/`
+- A feature folder: `features/access-control/` (selects the highest version with a `spec.md`)
+- A feature name: `access-control` (same as feature folder)
 
 **Flags:**
 - `--brainstorm` — 2–3 rough layout variants per screen on an "Explorations" page. No prototype, no `design.md`. Use when direction is still open.
@@ -30,12 +31,16 @@ Read `.claude/constitution.md` — these rules govern every phase and every agen
 Do not proceed until this file is loaded.
 
 ### 3. Locate the spec
-From the cleaned `$ARGUMENTS`, find the spec:
-- If it ends in `.md`, use it directly
-- If it's a folder, look for `spec.md` inside it
-- If it's a feature name, check `features/{name}/v1/spec.md` then `features/{name}/spec.md`
+From the cleaned `$ARGUMENTS`, resolve the spec using these rules in order:
 
-Derive `{feature_name}` and `{version}` (e.g. `v1`) from the path.
+1. **Ends in `.md`** — use it directly as the spec file.
+2. **Ends in `/v{N}/` or is a versioned folder** — look for `spec.md` inside it.
+3. **Feature folder or feature name** — list all `v{N}/` subdirectories inside
+   `features/{name}/`, sort by version number descending, and use the `spec.md`
+   from the highest version that contains one. If no versioned folder exists,
+   fall back to `features/{name}/spec.md`.
+
+Derive `{feature_name}` and `{version}` (e.g. `v1`, `v2`) from the resolved path.
 
 ### 4. Resolve the Figma file key
 Look for `features/{feature_name}/{version}/design.md`. If it exists, find the line:

From 303ab48303647a04f14f6569e6468482cd3fc400 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 17:55:07 +0000
Subject: [PATCH 06/10] Add design brief for access-control Spec A

Generated by running /design:design-handoff against
access-control-spec-A-role-system-2026-06-02.md. Documents 8 surfaces
with key decisions needed from the designer before Figma generation.

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 features/access-control/v1/design-brief.md | 192 +++++++++++++++++++++
 1 file changed, 192 insertions(+)
 create mode 100644 features/access-control/v1/design-brief.md

diff --git a/features/access-control/v1/design-brief.md b/features/access-control/v1/design-brief.md
new file mode 100644
index 0000000..209c683
--- /dev/null
+++ b/features/access-control/v1/design-brief.md
@@ -0,0 +1,192 @@
+# Design Brief — Access Control (Spec A) v1
+
+**Status:** Awaiting designer input
+**Spec:** access-control-spec-A-role-system-2026-06-02.md
+**Generated:** 2026-06-04
+
+Fill in your direction below each surface, then re-run:
+`/design:design-handoff features/access-control/v1/access-control-spec-A-role-system-2026-06-02.md`
+
+Leave a section blank to let me use best judgment for an NGO audience
+(I'll tag those decisions `[NEEDS CLARIFICATION]` in the output).
+
+---
+
+## Surface 1: Sidebar — Role-Adaptive Navigation
+
+**Who uses it:** All roles — Admin, Analyst, Member (each sees a different set of items)
+**What it does:** The left navigation rail that hides — not greys — items the user's role can't reach.
+
+**Capability map from spec (§5.3):**
+| Item | Admin | Analyst | Member |
+|------|-------|---------|--------|
+| Dashboards, Charts, Reports, Alerts | ✅ | ✅ | ✅ |
+| Data (Ingest / Transform / Warehouse) | ✅ Edit | ✅ Read-only | ❌ Hidden |
+| Pipelines / Orchestration | ✅ Edit | ✅ Read-only | ❌ Hidden |
+| Settings | ✅ Full | Groups only | Groups only |
+| Create buttons on content pages | ✅ | ✅ | ❌ Hidden |
+
+**Decisions needed:**
+- Should the three role states be shown as one Figma frame with a role toggle, or three separate frames (Admin / Analyst / Member)?
+- Does the sidebar have any visual indicator of the user's current role (badge, label in the footer area)?
+- Where does the "Settings" item live — bottom of nav rail or grouped with the main items?
+- What does the active state look like vs. hover state? Any reference to follow?
+
+**Reference design (if any):**
+
+**Your direction:** <!-- fill in here -->
+
+---
+
+## Surface 2: No Access Page
+
+**Who uses it:** Any user who navigates directly to a URL they don't have role access to (e.g., a Member trying to reach `/ingest`)
+**What it does:** Blocks unauthorized direct URL access; redirects from route middleware. Shows the org Admin contact.
+
+**Decisions needed:**
+- What information is shown? The spec says "org Admin contact" — should this be name + email, or just "contact your administrator"?
+- Is there a "Go to home" / "Back to dashboard" CTA?
+- Should this feel like a 404 (full-page blank) or an in-app message within the shell (sidebar still visible)?
+- Do we need separate states for "no access to this specific thing" vs. "you're not logged in" vs. "this doesn't exist"?
+
+**Reference design (if any):**
+
+**Your direction:** <!-- fill in here -->
+
+---
+
+## Surface 3: Settings — Restructured IA
+
+**Who uses it:** Admin (full), Analyst (Groups section only), Member (Groups they're in only)
+**What it does:** The consolidated Settings area with Admin-only globals (Warehouse, Appearance, Org defaults, Users) and shared-but-scoped sections (Groups).
+
+**Settings sections from spec (§7):**
+- Warehouse / Data connection (Admin only)
+- Appearance / Themes (Admin only)
+- Org defaults: default visibility floor + "allow public sharing" toggle (Admin only — inert until Spec B)
+- Users (Admin only)
+- Groups (scoped per role)
+
+**Decisions needed:**
+- How is Settings navigation structured? Left sidebar within Settings, tabs, or a single scrollable page with sections?
+- How are Admin-only sections presented to non-Admins — completely hidden, or visible with a lock and "Admin only" label?
+- The Org defaults section ships inert (toggles don't do anything until Spec B). Do we render the toggles greyed/disabled, or skip that section entirely in Spec A?
+- Should Settings be a full-page takeover (replaces main content area) or a slide-over panel?
+
+**Reference design (if any):**
+
+**Your direction:** <!-- fill in here -->
+
+---
+
+## Surface 4: Settings > Users
+
+**Who uses it:** Admin only
+**What it does:** Full user management — view all org users, invite new ones, change roles, delete users, and trigger ownership transfer.
+
+**Table columns from spec:** Name, Email, Role (Admin/Analyst/Member), Status (active/pending), Last active
+
+**Actions available:**
+- Invite user (CTA → modal)
+- Change a user's role (dropdown or edit flow)
+- Delete user (destructive — with confirmation)
+- Transfer ownership of resources when deleting a user who owns things
+
+**Decisions needed:**
+- Is role change done inline (dropdown in the table row) or via an edit modal?
+- Does the delete user action check for owned resources first and prompt a transfer before deletion, or is it a single confirmation?
+- Should pending invites (invited but not yet accepted) appear in the same table or a separate "Pending" tab/section?
+- What does the empty state look like when there are no other users yet?
+- Is ownership transfer triggered from here (on delete) or does it exist separately on resources? The spec mentions both — should this brief only cover the Settings > Users entry point?
+
+**Reference design (if any):**
+
+**Your direction:** <!-- fill in here -->
+
+---
+
+## Surface 5: Invite User Modal
+
+**Who uses it:** Admin (inviting new users directly without a resource share)
+**What it does:** Creates a new platform user and assigns them a role. No resource grant at this stage — pure onboarding. Only Admins can assign Analyst or Admin roles; Analyst/Member tier is the max others can grant (but this modal is Admin-only anyway).
+
+**Fields:** Name, Email, Role (Admin / Analyst / Member dropdown)
+
+**Decisions needed:**
+- Does the modal send an email invite immediately on submit, or is it just account creation?
+- What is the success state — toast only, or does the modal show a confirmation before closing?
+- Should the role dropdown show a description of each role to help the Admin choose (e.g., "Analyst — can build dashboards, read-only access to data infrastructure")?
+- If the email is already in the system, what happens?
+
+**Reference design (if any):**
+
+**Your direction:** <!-- fill in here -->
+
+---
+
+## Surface 6: Ownership Transfer
+
+**Who uses it:** Resource owner (self-initiated transfer) or Admin (override for governance or when a user leaves)
+**What it does:** Reassigns the owner of a resource from one user to another.
+
+**Two entry points from spec:**
+1. Resource action menu (owner or Admin acts on a specific resource)
+2. Settings > Users (Admin triggers when deleting a user who owns resources)
+
+**Decisions needed:**
+- Should this be a modal or an inline action? If modal: how is the new owner selected (user picker / search, or dropdown)?
+- Does this need a confirmation step before completing, given that ownership grants delete rights to the new owner?
+- For the Settings > Users entry point (deleting a user): is the transfer a blocking step before deletion completes, or optional?
+- Is the resource-menu entry point in scope for Spec A design, or just the Settings > Users entry point? (The spec mentions both but only Settings > Users ships functionally in Spec A)
+
+**Reference design (if any):**
+
+**Your direction:** <!-- fill in here -->
+
+---
+
+## Surface 7: Data Section — Analyst Read-Only State
+
+**Who uses it:** Analyst browsing Data infrastructure (Ingest / Transform / Warehouse / Pipelines / Orchestration)
+**What it does:** The Analyst can see the Data section but cannot create, edit, or delete anything. All write actions are removed.
+
+**Decisions needed:**
+- How is read-only conveyed to the Analyst? Options: (a) remove Create/Edit/Delete buttons entirely, (b) show them greyed with a tooltip "You have read-only access", (c) show a banner at the top of the page
+- Is there a persistent indicator that they're in read-only mode (e.g., a small "Read only" badge near the page title)?
+- Does this apply uniformly to all Data sub-sections (Ingest, Transform, Warehouse, Pipelines), or does each section look slightly different?
+- Should we design the read-only state for one representative Data section (e.g., Ingest) and note that it applies to all, or design each?
+
+**Reference design (if any):**
+
+**Your direction:** <!-- fill in here -->
+
+---
+
+## Surface 8: Migration Changelog Modal
+
+**Who uses it:** All users on their first login after the migration runs
+**What it does:** Explains what changed in the role model. Content differs per role — Admins, Analysts, and Members see different summaries.
+
+**Key changes to communicate per role:**
+- **Admin:** New three-role model; they keep full access; Settings has moved
+- **Analyst:** Loses Data infra write access → read-only; content access unchanged
+- **Member:** Replaces "Guest"; now sees all content as View-only in the interim
+
+**Decisions needed:**
+- Is this one modal with conditional content per role, or three distinct modal designs?
+- Should the modal show the full change list, or a condensed 2–3 bullet summary with a "Learn more" link?
+- Is there a "Don't show again" option, or just a dismiss button (one-time only)?
+- Should the modal include a CTA — e.g., "Go to Settings" for Admins, "Go to Dashboards" for Members?
+
+**Reference design (if any):**
+
+**Your direction:** <!-- fill in here -->
+
+---
+
+## Shared Components (no direction needed — will follow patterns.md)
+
+These will be implemented per existing design standards without needing your input:
+- **Role badge/chip** — Admin / Analyst / Member displayed as a small pill in the user table
+- **Admin-lock treatment** — lock icon + "Contact your admin to change this" for locked fields
+- **Permission-gated empty states** — when a section is hidden for a role, it simply isn't rendered (no greyed placeholder)

From 7dac0822542f37243f9498494503d64b401a7c77 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 18:23:17 +0000
Subject: [PATCH 07/10] Add design.md for access-control v1 with Figma file key

Records the Figma file key for the access-control v1 design work.

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 features/access-control/v1/design.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 features/access-control/v1/design.md

diff --git a/features/access-control/v1/design.md b/features/access-control/v1/design.md
new file mode 100644
index 0000000..d2f5c6b
--- /dev/null
+++ b/features/access-control/v1/design.md
@@ -0,0 +1,8 @@
+# Access Control — Design (v1)
+
+**Status:** In progress
+**Spec:** access-control-spec-A-role-system-2026-06-02.md
+
+## Figma
+
+file_key: viO3UsJicCOz3rwx4iocBL

From 92545226ac5205af34932768ef37424af53e6494 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 19:00:50 +0000
Subject: [PATCH 08/10] Rewrite design-handoff command: text-first brainstorm,
 generate_figma_design for frames
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Brainstorm mode now produces layout-directions.md (annotated text variants per
  surface) instead of trying to build Figma frames — fast and token-efficient
- Draft/ship mode picks from layout-directions.md before proceeding to Figma
- Frame agents now use figma-generate-design skill instead of raw Plugin API JS
- use_figma is reserved for prototype connection wiring only (Phase 3.5)
- Figma file key resolution skipped in brainstorm mode
- Quality checklist updated to reflect new phases

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 .claude/commands/design/design-handoff.md | 221 +++++++++++++++-------
 1 file changed, 148 insertions(+), 73 deletions(-)

diff --git a/.claude/commands/design/design-handoff.md b/.claude/commands/design/design-handoff.md
index 6777697..e83e3f0 100644
--- a/.claude/commands/design/design-handoff.md
+++ b/.claude/commands/design/design-handoff.md
@@ -11,9 +11,9 @@ Bridge a feature spec into Figma designs, then produce `design.md` so engineerin
 - A feature name: `access-control` (same as feature folder)
 
 **Flags:**
-- `--brainstorm` — 2–3 rough layout variants per screen on an "Explorations" page. No prototype, no `design.md`. Use when direction is still open.
-- `--draft` — One lo-fi wireframe per screen, one feedback round. No prototype wiring. Use when iterating on layout.
-- _(default, no flag)_ — Full-fidelity frames, prototype wired, `design.md` written. Use when design is settled and you're producing the engineering handoff.
+- `--brainstorm` — Produces `layout-directions.md`: 2–3 annotated text layout variants per surface for the designer to pick from. No Figma, no `design.md`. Use when direction is still open.
+- `--draft` — One lo-fi Figma frame per screen, one feedback round. No prototype wiring. Use when iterating on layout.
+- _(default, no flag)_ — Full-fidelity Figma frames, prototype wired, `design.md` written. Use when design is settled and you're producing the engineering handoff.
 
 ---
 
@@ -42,7 +42,7 @@ From the cleaned `$ARGUMENTS`, resolve the spec using these rules in order:
 
 Derive `{feature_name}` and `{version}` (e.g. `v1`, `v2`) from the resolved path.
 
-### 4. Resolve the Figma file key
+### 4. Resolve the Figma file key (skip in brainstorm mode)
 Look for `features/{feature_name}/{version}/design.md`. If it exists, find the line:
 ```
 file_key: {key}
@@ -79,7 +79,7 @@ Parse the spec for every user-facing screen, flow, modal, or component that need
 
 For each surface extract:
 - **Purpose:** what the user accomplishes
-- **Persona:** which Dalgo user type (admin, PM, analyst, viewer)
+- **Persona:** which Dalgo user type (admin, analyst, member)
 - **Key decisions:** things needing a designer's judgment before building
 - **Dependencies:** does this screen reference another surface?
 
@@ -130,7 +130,7 @@ Each scenario becomes a named prototype flow in Figma.
 Look for `features/{feature_name}/{version}/design-brief.md`.
 
 **If it exists and has content below any `Your direction:` line:** Read it, extract designer
-direction per surface, and continue directly to Phase 2.9.
+direction per surface, and continue directly to Phase 2.5.
 
 **If it's missing or blank:** Write the brief file (step 2) and stop.
 
@@ -138,9 +138,10 @@ direction per surface, and continue directly to Phase 2.9.
 Create `features/{feature_name}/{version}/design-brief.md`:
 
 ```markdown
-# Design Brief — {Feature Name} {Version}
+# Design Brief — {Feature Name} ({Version})
 
 **Status:** Awaiting designer input
+**Spec:** {spec path}
 **Generated:** {date}
 
 Fill in your direction below each surface, then re-run:
@@ -153,7 +154,7 @@ Leave a section blank to let me use best judgment for an NGO audience
 
 {for each surface:}
 
-## Surface: {Screen Name}
+## Surface {N}: {Screen Name}
 
 **Who uses it:** {persona}
 **What it does:** {purpose}
@@ -173,20 +174,85 @@ Print:
 ```
 Brief written to features/{feature_name}/{version}/design-brief.md
 
-Open it in your editor, fill in direction for each surface, then re-run:
+Open it, fill in direction for each surface, then re-run:
 /design:design-handoff {spec path}
 ```
 
-**Stop here.** Do not spawn any Figma agents.
+**Stop here.** Do not proceed to layout directions or Figma.
 
 ### 3. Parse a completed brief
 When re-running and the brief has responses, extract direction per surface.
 Where a `Your direction:` field is blank or missing, note that surface as `[NEEDS CLARIFICATION]`
-and generate using best judgment for a non-technical NGO audience.
+and use best judgment for a non-technical NGO audience.
 
 ---
 
-## Phase 2.9: Scout
+## Phase 2.5: Layout Directions
+
+Generate layout directions for every surface. This is a text-only step — no Figma yet.
+
+For each surface, produce **2–3 annotated layout variants** as structured text.
+Each variant should describe:
+- Overall layout (sidebar position, content zones, modal vs full-page)
+- Key UI elements and their placement
+- Copy decisions (labels, headings, CTAs, helper text)
+- How the designer direction (or best judgment) shaped the choice
+- One sentence on the trade-off vs the other variants
+
+Use this format per surface:
+
+```
+## {Screen Name}
+
+Designer direction: {direction from brief, or "[NEEDS CLARIFICATION] — using best judgment"}
+
+### Variant A — {short name}
+Layout: {description}
+Key elements: {list}
+Copy: {headings, CTAs, labels}
+Trade-off: {what this gains vs other variants}
+
+### Variant B — {short name}
+...
+
+### Variant C — {short name} (include only if meaningfully different)
+...
+
+**Recommended:** Variant {X} — {one sentence why, grounded in NGO audience and constitution rules}
+```
+
+Write the full output to `features/{feature_name}/{version}/layout-directions.md`.
+
+---
+
+### Brainstorm mode: stop here
+
+If mode is `--brainstorm`, print:
+
+```
+Layout directions written to features/{feature_name}/{version}/layout-directions.md
+
+Review the variants for each surface, then tell me which to build:
+"go with Variant B for surface 2, Variant A for the rest"
+
+Or run with --draft or no flag to proceed to Figma once you've picked.
+```
+
+**Stop here.** Do not proceed to Figma in brainstorm mode.
+
+---
+
+### Draft / Ship mode: pick variants
+
+If mode is `--draft` or ship (no flag):
+
+Check `layout-directions.md` for any designer pick annotations (e.g. "→ build this" or similar
+freeform notes added after the file was generated). If picks exist, use them. If not, use the
+Recommended variant for each surface and note it.
+
+---
+
+## Phase 2.9: Scout (draft and ship mode only)
 
 Spawn a Scout agent with this prompt:
 
@@ -197,8 +263,7 @@ Figma file key: {file_key}
 
 1. Call get_metadata on the file. Collect all existing frames: their names, node IDs, and x positions.
 2. If the file has no frames, return next_x = 0.
-3. If frames exist, call get_screenshot on each and note which belong to this feature.
-   Return the rightmost x position across all frames + 100px gap as next_x.
+3. If frames exist, return the rightmost x position across all frames + 100px gap as next_x.
 4. Return this exact JSON:
 {
   "file_key": "{file_key}",
@@ -212,23 +277,28 @@ Wait for Scout to complete before spawning frame agents.
 
 ---
 
-## Phase 3: Generate Designs in Figma
+## Phase 3: Generate Designs in Figma (draft and ship mode only)
+
+### Tool choice
+Use the `figma-generate-design` skill to build each frame. **Do not use raw Plugin API
+JavaScript via `use_figma` to construct frames** — that approach is fragile and expensive.
+`use_figma` is reserved for prototype connection wiring only (Phase 3.5).
+
+Load `skill://figma/figma-generate-design/SKILL.md` before spawning frame agents.
 
 ### Mode behaviour
 
-| Mode | Page | Fidelity | Variants | Prototype |
-|------|------|----------|----------|-----------|
-| Brainstorm | "Explorations" | Rough wireframe | 2–3 per surface | No |
-| Draft | "Designs" | Lo-fi wireframe | 1 per surface | No |
-| Ship | "Designs" | Full-fidelity | 1 per surface | Yes |
+| Mode | Page | Fidelity | Prototype |
+|------|------|----------|-----------|
+| Draft | "Designs" | Lo-fi wireframe | No |
+| Ship | "Designs" | Full-fidelity | Yes |
 
 ### Frame naming
-- Ship / Draft: `S{n} · {Screen Name}` (e.g. `S1 · User Management`)
-- Brainstorm variants: `S{n}a · {Screen Name}`, `S{n}b · {Screen Name}`, `S{n}c · {Screen Name}`
+- `S{n} · {Screen Name}` (e.g. `S1 · User Management`)
 - States: `S{n}-{State}` (e.g. `S1-Empty`, `S1-Error`)
 
 ### Frame agent prompt
-Spawn one agent per surface in parallel. Each **must** return this fixed JSON schema — no other format:
+Spawn one agent per surface in parallel. Each **must** return this fixed JSON schema:
 
 ```json
 {
@@ -251,41 +321,38 @@ Feature: {Feature Name}
 Screen: {Screen Name}
 Persona: {persona}
 Purpose: {purpose}
-Mode: {brainstorm | draft | ship}
+Mode: {draft | ship}
 
-Designer direction:
-{direction from design-brief.md, or "[NEEDS CLARIFICATION] — use best judgment for NGO audience"}
+Selected layout variant:
+{variant text from layout-directions.md}
 
 User flow for this screen:
 {flow block from Phase 1.5}
 
-Design standards — read and apply in full:
+Design standards — apply in full:
 {full content of patterns.md}
 
-Constitution — never violate these rules:
+Constitution — never violate these:
 {full content of .claude/constitution.md}
 
 Figma file key: {file_key}
-Page: {page name — "Explorations" for brainstorm, "Designs" for draft/ship}
-Frame name: {frame name per naming convention above}
+Page: "Designs"
+Frame name: {frame name per naming convention}
 Frame size: 1440×900px
 Position: x={scout.next_x + (surface_index × 1540)}, y=0
 
-{brainstorm only: create 2–3 variants at x offsets of 0, 1540, 3080 from your starting position}
-
 Steps:
-1. Load skill://figma/figma-use/SKILL.md before calling use_figma — this is mandatory.
-2. Create the page if it does not exist.
-3. Create the frame at the specified position with the specified name.
-4. After creating, call get_screenshot on the created node.
-5. Record any design decisions made (label choices, layout choices, copy decisions).
-6. Record anything that needs the designer's input as [NEEDS CLARIFICATION].
-7. Return the fixed JSON schema — node_id, frame_name, screenshot_url, decisions[], needs_clarification[].
+1. Load skill://figma/figma-generate-design/SKILL.md before designing.
+2. Create the "Designs" page if it does not exist.
+3. Build the frame using figma-generate-design guidance.
+4. After creating, call get_screenshot on the node.
+5. Record design decisions and any [NEEDS CLARIFICATION] items.
+6. Return the fixed JSON schema.
 ```
 
 ### Collect results
-Wait for all agents. Validate every response matches the fixed schema before proceeding.
-If an agent returns malformed output, re-prompt it once requesting the correct JSON.
+Wait for all agents. Validate every response matches the fixed schema.
+If an agent returns malformed output, re-prompt once requesting the correct JSON.
 
 ---
 
@@ -303,17 +370,20 @@ Connections:
 ```
 
 ### 2. Add connections via use_figma
-Load skill://figma/figma-use/SKILL.md first (mandatory before calling use_figma).
+Load `skill://figma/figma-use/SKILL.md` before calling `use_figma`.
+
+This is the only place `use_figma` is called — for adding prototype connections only,
+not for building frames.
 
 For each connection:
-- Select the trigger element on the source frame
+- Select the trigger element on the source frame by node ID
 - Add interaction: `On click → Navigate to → {target frame node ID}`
 - Overlays / modals: use `Open overlay` instead of Navigate
 - Back / cancel flows: `Navigate to` with the specific target frame node ID
 
 ### 3. Set flow start frames
 For each scenario, mark the first frame as the starting point in Figma's prototype panel,
-labelled with the scenario name (e.g. "Invite a new team member").
+labelled with the scenario name.
 
 ### 4. Record wiring results
 Note any connections that could not be wired for manual follow-up.
@@ -346,7 +416,7 @@ Check the screenshot against every item. Return this exact JSON:
 }
 ```
 
-**If failures:** Send the failure list back to the frame agent that created this frame:
+**If failures:** Send the failure list back to the frame agent:
 ```
 Your frame "{frame_name}" failed design review. Fix these issues and regenerate the frame,
 then return the updated JSON schema.
@@ -355,14 +425,12 @@ Failures:
 {failures list}
 ```
 
-**Retry limit:** 3 rounds per frame. If still failing after round 3, mark the frame:
+**Retry limit:** 3 rounds per frame. If still failing after round 3, mark the frame
 `[REVIEW FAILED — manual fix needed]` and continue.
 
-**If passed:** Frame is final. Record it as passing.
-
 ---
 
-## Phase 3.9: Consistency Spot-Check
+## Phase 3.9: Consistency Spot-Check (draft and ship mode only)
 
 After all frames pass (or exhaust retries), spawn one consistency agent:
 
@@ -373,7 +441,7 @@ Frames: {list of node_ids and frame names}
 
 Check for drift in:
 - Sidebar (width, active state style)
-- Header (height, element positions, org name display)
+- Header (height, element positions)
 - Page padding (should be --spacing-page-x 32px horizontal, --spacing-page-y 28px vertical)
 - Primary CTA button (colour, style)
 - Typography (heading sizes and weights)
@@ -390,52 +458,56 @@ If drift is found, note it for the designer in Phase 5. Do not auto-fix.
 
 ## Phase 5: Designer Sign-off
 
-Present results:
+### Brainstorm mode
+```
+Layout directions ready: features/{feature_name}/{version}/layout-directions.md
+
+{N} surfaces, {total} variants
 
+Review and tell me which variants to build, then re-run without --brainstorm.
 ```
-Designs ready on the "{page name}" page.
+
+### Draft / Ship mode
+```
+Designs ready — "Designs" page in Figma.
 
 | Frame | Node ID | Status |
 |-------|---------|--------|
-| S1 · User Management | ... | ✅ Passed |
-| S2 · Invite Modal    | ... | ⚠ [NEEDS CLARIFICATION] — role picker direction not provided |
-| S3 · Role Editor     | ... | 🔴 [REVIEW FAILED] — fix manually |
+| S1 · {Screen Name} | ... | ✅ Passed |
+| S2 · {Screen Name} | ... | ⚠ [NEEDS CLARIFICATION] — {what was assumed} |
+| S3 · {Screen Name} | ... | 🔴 [REVIEW FAILED] — fix manually |
 
 {if consistency issues}
 Consistency issues flagged:
 - S1 and S3: page padding differs
 
-{if [NEEDS CLARIFICATION] items}
-These were generated without your direction — confirm or redirect:
-{list of needs_clarification items per frame, with what was assumed}
-
 Options:
 1. Approve — I'll write design.md and engineering can start
 2. Revise a frame: "redo S2 with inline role picker, not a modal"
-3. Brainstorm alternatives: "brainstorm S3"
+3. Revisit layout directions: "brainstorm S3 again"
 ```
 
 Wait for designer response before writing `design.md`.
 
 ---
 
-## Phase 6: Write design.md
+## Phase 6: Write design.md (draft and ship mode only)
 
-Write `features/{feature_name}/{version}/design.md` as the engineering handoff document:
+Write `features/{feature_name}/{version}/design.md`:
 
 ```markdown
 # {Feature Name} — Design ({Version})
 
 **Status:** Ready for engineering
-**Spec:** ../spec.md
-**Figma:** https://figma.com/file/{file_key}
+**Spec:** {spec path}
+**Figma:** https://www.figma.com/design/{file_key}
 **Last updated:** {date}
 
 ## Screens
 
-| Screen | Frame name | Node ID | Figma link | Status |
-|--------|-----------|---------|-----------|--------|
-| {Screen Name} | S1 · {Screen Name} | {node_id} | [View →](https://figma.com/file/{file_key}?node-id={node_id}) | ✅ Ready |
+| Screen | Frame | Node ID | Figma link | Status |
+|--------|-------|---------|------------|--------|
+| {Screen Name} | S1 · {Screen Name} | {node_id} | [View →](https://www.figma.com/design/{file_key}?node-id={node_id}) | ✅ Ready |
 
 ## User Flows & Prototype
 
@@ -489,13 +561,16 @@ Next: /engineering/plan-feature features/{feature_name}/{version}/spec.md
 
 - [ ] Mode resolved (brainstorm / draft / ship)
 - [ ] Constitution loaded before any agent was spawned
-- [ ] Figma file key resolved (from `design.md` or newly created)
-- [ ] Design brief written or read (session was not blocked)
-- [ ] Scout ran and returned canvas state and `next_x`
-- [ ] All frame agents returned the fixed JSON schema
+- [ ] Figma file key resolved — or skipped for brainstorm mode
+- [ ] Design brief written or read
+- [ ] Layout directions written to `layout-directions.md`
+- [ ] Brainstorm mode stopped after layout-directions.md
+- [ ] Scout ran and returned canvas state and `next_x` (draft/ship only)
+- [ ] Frame agents used `figma-generate-design` skill — not raw use_figma JS
+- [ ] All frame agents returned the fixed JSON schema (draft/ship only)
 - [ ] Evaluator loop ran for every frame (draft and ship modes)
-- [ ] Consistency spot-check ran across all final frames
+- [ ] Consistency spot-check ran across all final frames (draft/ship only)
 - [ ] Designer signed off
-- [ ] `design.md` written with node IDs, decisions, known issues, and `file_key`
+- [ ] `design.md` written with node IDs, decisions, known issues, and `file_key` (draft/ship only)
 - [ ] `spec.md` updated with one-line pointer to `design.md`
 - [ ] Next step printed clearly

From ef32ee2674f0e2834b51922f49818ef8ddcf4fd1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 19:09:18 +0000
Subject: [PATCH 09/10] Add layout-directions.md for access-control v1

8 surfaces, 2-3 annotated text variants each with recommended picks.
Generated with best judgment for NGO audience (brief was blank).

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 .../access-control/v1/layout-directions.md    | 412 ++++++++++++++++++
 1 file changed, 412 insertions(+)
 create mode 100644 features/access-control/v1/layout-directions.md

diff --git a/features/access-control/v1/layout-directions.md b/features/access-control/v1/layout-directions.md
new file mode 100644
index 0000000..5664689
--- /dev/null
+++ b/features/access-control/v1/layout-directions.md
@@ -0,0 +1,412 @@
+# Layout Directions — Access Control v1
+
+**Status:** Awaiting designer picks
+**Spec:** access-control-spec-A-role-system-2026-06-02.md
+**Generated:** 2026-06-04
+
+All surfaces below are `[NEEDS CLARIFICATION]` — designer did not fill in `design-brief.md`.
+Variants generated using best judgment for a non-technical NGO audience.
+
+**To pick a variant:** Add `→ build this` after the variant heading, or note your direction
+below each surface. Then re-run: `/design:design-handoff features/access-control/v1/`
+
+---
+
+## Surface 1: Sidebar — Role-Adaptive Navigation
+
+Designer direction: [NEEDS CLARIFICATION] — using best judgment
+
+### Variant A — Single frame with role switcher
+
+Layout: Standard app shell (224px sidebar, 60px header). A role-switcher dropdown sits at the
+top of the sidebar below the org logo. Nav items below it react to the selected role — items
+the role can't reach vanish entirely. One Figma frame, but requires prototype interaction to
+demonstrate all three states.
+
+Key elements:
+- Org logo + name at top (header area of sidebar)
+- Role dropdown: "Viewing as: Admin ▾" — useful for design review
+- Nav items in order: Dashboards, Charts, Reports, Alerts, (separator), Data, Pipelines,
+  (separator), Settings
+- Member view: Data, Pipelines, Settings, and Create buttons all hidden
+- Active item: left border accent in brand-primary, background brand-primary-light
+- Settings: pinned at bottom of nav rail, separated by a divider
+
+Copy: Nav labels sentence case — "Dashboards", "Charts", "Reports", "Alerts", "Data", "Pipelines", "Settings"
+Trade-off: The role switcher is convenient for demos and review but adds a UI element that
+wouldn't exist in production. Requires interaction to show all three role states.
+
+### Variant B — Three separate frames (Admin / Analyst / Member) ← Recommended
+
+Layout: Three separate 1440×900 frames in Figma, one per role, side by side. Each shows the
+sidebar in that role's exact state — Admin sees everything, Analyst sees Data (read-only badge)
+and Pipelines but no Users in Settings, Member sees only content items. No role switcher UI.
+Role chip shown in the sidebar footer (user avatar + name + role badge).
+
+Key elements:
+- Frame 1 (Admin): All nav items. "Settings" at bottom. User footer: avatar + "Admin" chip in
+  brand-primary.
+- Frame 2 (Analyst): Data items present (read-only badge on the Data section label), Pipelines
+  present. Settings visible — only Groups accessible. User footer: "Analyst" chip in grey.
+- Frame 3 (Member): Dashboards, Charts, Reports, Alerts only. No Create buttons on content
+  pages. No Data, no Pipelines, no Settings. User footer: "Member" chip in grey.
+- Active item style: 3px left border in brand-primary, bg brand-primary-light (teal tint),
+  label in brand-primary.
+- Hover style: bg surface-hover (#f5f7f8), no border change.
+
+Copy: Same sentence-case nav labels. Footer shows "Priya M. · Admin" style.
+Trade-off: More frames, but unambiguously shows all three role states for both design review
+and engineering spec. Best for static handoff.
+
+**Recommended:** Variant B — Three separate frames are the clearest reference for engineers
+and the clearest demonstration of "hide, don't grey" for all three roles. No interactive
+assumption required.
+
+---
+
+## Surface 2: No Access Page
+
+Designer direction: [NEEDS CLARIFICATION] — using best judgment
+
+### Variant A — Full-page blank (no shell)
+
+Layout: Centered content on a plain bg (#f8fafb) with no sidebar or header. Lock icon (48px),
+heading "You don't have access to this page", subtext "Contact your administrator to request
+access", admin name + email as a mailto link, and a "Go to dashboards" CTA button.
+
+Key elements: Lock icon, heading, subtext, admin contact card (name + email), single CTA
+Copy: "You don't have access to this page. Contact [Admin Name] at [email] to request access."
+    CTA: "Go to dashboards"
+Trade-off: Clean and unambiguous, but disorients users because they lose the nav context and
+can't see where else to go.
+
+### Variant B — In-shell (sidebar + header visible) ← Recommended
+
+Layout: Normal app shell (Member's sidebar: Dashboards, Charts, Reports, Alerts; 60px header
+with org name and user avatar). Main content area shows the no-access message centred in the
+remaining space. The user can still navigate to pages they do have access to.
+
+Key elements:
+- Sidebar shows only the Member's permitted items (so they can immediately navigate away)
+- Header shows current page breadcrumb: "Data › Ingest" (wherever they tried to go)
+- Centered content block: Lock icon (40px), heading, subtext, admin contact, CTA
+- Admin contact card: name + email, displayed as a subtle card (border, border-radius-md)
+- CTA: primary button "Go to dashboards"
+
+Copy: Heading: "You don't have access to this page"
+    Body: "This section isn't available for your account. Contact [Admin Name] ([email]) if
+    you think you need access."
+    CTA: "Go to dashboards"
+Trade-off: Slightly more complex to render (requires shell), but far better for NGO users who
+are disoriented by a blank full-page error. They can see the nav and recover immediately.
+
+**Recommended:** Variant B — Keeping the shell visible is essential for low-technical-literacy
+users. A full-page blank is a dead end; in-shell gives an immediate recovery path.
+
+---
+
+## Surface 3: Settings — Restructured IA
+
+Designer direction: [NEEDS CLARIFICATION] — using best judgment
+
+### Variant A — Left sub-navigation within Settings ← Recommended
+
+Layout: Settings is a full-page takeover replacing the main content area (sidebar still
+visible). A secondary nav rail (180px) sits inside Settings on the left, listing the sections
+(Warehouse, Appearance, Org Defaults, Users, Groups). Admin sees all five; Analyst and Member
+see only Groups. Clicking a section loads it in the right content area (the remaining width).
+
+Key elements:
+- "Settings" as the page heading in the header area
+- Secondary nav: vertically stacked text links with active-state styling matching the main nav
+- Warehouse, Appearance, Org Defaults, Users: Admin-only — completely hidden from other roles
+- Groups: visible to all (scoped content per role)
+- Org Defaults section: toggles rendered but visually inert (greyed, labelled "Coming soon")
+- Active section: brand-primary left border, brand-primary-light background (matches main nav)
+
+Copy: Section labels: "Warehouse", "Appearance", "Org defaults", "Users", "Groups"
+    Org Defaults note: "These settings will take effect when resource sharing is enabled."
+Trade-off: Uses more horizontal space than tabs, but scales well as Settings grows. Familiar
+pattern to NGO users who have seen Google Workspace or Notion Settings.
+
+### Variant B — Horizontal tabs
+
+Layout: Settings page with horizontal tabs at the top: [Warehouse] [Appearance] [Org Defaults]
+[Users] [Groups]. Non-admin tabs hidden. Content below tabs.
+
+Key elements: Standard tab bar, content area beneath.
+Copy: Same section labels.
+Trade-off: Simpler, less real estate. But breaks when section count grows or labels get long.
+Harder to scan at a glance than a vertical list.
+
+### Variant C — Slide-over panel from right
+
+Layout: Settings opens as a right-side panel (640px wide) over the current page. The
+underlying page is dimmed. Secondary nav inside the panel.
+
+Key elements: Panel header "Settings", close button (×), secondary nav + content.
+Copy: Same.
+Trade-off: Panel approach keeps context (user sees what page they were on) but is a non-
+standard pattern for a Settings area with multiple sections and complex forms. Scroll behavior
+inside panels is awkward on low-resolution laptops (common in field). Not recommended.
+
+**Recommended:** Variant A — Left sub-nav is the established pattern for multi-section settings.
+It's predictable for NGO users, scales gracefully, and matches Dalgo's existing sidebar
+navigation style.
+
+---
+
+## Surface 4: Settings > Users
+
+Designer direction: [NEEDS CLARIFICATION] — using best judgment
+
+### Variant A — Table with inline role dropdown ← Recommended
+
+Layout: Full-page layout (Settings shell, left sub-nav active on "Users"). Fixed header with
+"Users" title, "Invite user" CTA (top right). Scrollable table below: Name, Email, Role,
+Status, Last active columns. Role column is an inline dropdown chip — click to change.
+"Pending" badge inline in Status column (not a separate tab).
+
+Key elements:
+- Page header: "Users" (text-3xl, bold) + subtext "Manage who has access to your organisation"
+- Invite user: primary CTA button (top right)
+- Table columns: Name + avatar, Email, Role (chip/dropdown), Status (Active/Pending badge),
+  Last active (relative time: "3 days ago")
+- Role chip colours: Admin = brand-primary background, Analyst = grey, Member = grey
+- Row hover: bg surface-hover; row action menu (⋯) on hover — shows "Delete user"
+- Delete: shows confirmation dialog before proceeding; if user owns resources, shows transfer
+  step first
+- Pending invites: shown in same table, Status = "Pending" chip in amber
+
+Copy: Heading: "Users" · Subheading: "Manage who has access to your organisation"
+    Role chips: "Admin", "Analyst", "Member"
+    Status chips: "Active" (green), "Pending" (amber)
+    Delete confirmation: "Delete [Name]? This will remove their access to Dalgo."
+Trade-off: Inline role change is fast for small teams (typical NGO: 5–15 users). Keeps the
+admin on the same page with minimal navigation.
+
+### Variant B — Table with edit-user modal
+
+Layout: Same table, but role column is read-only text. "Edit" icon in each row opens a modal
+with Name, Email, Role fields. Delete is a separate action in the row menu.
+
+Key elements: Same table, edit modal for role change.
+Trade-off: More clicks for a role change, but provides a more deliberate flow if orgs are
+concerned about accidental role changes. Slightly higher friction for small frequent updates.
+
+**Recommended:** Variant A — Inline dropdown is the right call for small NGO teams. Faster
+admin experience, less navigation, and the confirmation step on delete handles the "accidental"
+risk for the only truly destructive action.
+
+---
+
+## Surface 5: Invite User Modal
+
+Designer direction: [NEEDS CLARIFICATION] — using best judgment
+
+### Variant A — Single form with inline role descriptions ← Recommended
+
+Layout: Shadcn Dialog (max-w-md). Title "Invite user". Three fields: Name, Email, Role
+(dropdown). Role dropdown options include a short description below each role name. Submit
+sends the invite email immediately. Success: toast notification + modal closes. If email
+already exists: inline error below the Email field.
+
+Key elements:
+- Modal title: "Invite user"
+- Name field (optional — they can fill it themselves)
+- Email field (required, validated inline)
+- Role dropdown with descriptions:
+    Admin — Full access, can manage users and settings
+    Analyst — Can build dashboards; read-only on data infrastructure
+    Member — Can view content shared with them
+- Submit CTA: "Send invite" (primary button)
+- Cancel: text link "Cancel" or secondary button
+- Duplicate email: "A user with this email already exists. View their profile →"
+- Loading state on submit: "Sending..." with spinner
+- Success: toast "Invite sent to priya@partner.org"
+
+Copy: Modal title: "Invite user"
+    Email label: "Email address"
+    Role label: "Role"
+    CTA: "Send invite" / "Cancel"
+Trade-off: Single-step form keeps it simple. Role descriptions inline help the Admin make the
+right choice without leaving the modal.
+
+### Variant B — Two-step modal (user info → role select)
+
+Layout: Step 1 collects name + email; Step 2 is a full role-picker with detailed descriptions
+and capability tables. Progress dots at top. "Next →" / "← Back" / "Send invite".
+
+Trade-off: More deliberate — good if Admins regularly make wrong role choices. But adds
+friction that most small NGO admins don't need. Better suited as an onboarding flow for first
+few invites, not day-to-day user management.
+
+**Recommended:** Variant A — Single form. Role descriptions inside the dropdown give enough
+context. Two-step adds unnecessary length for an admin who already knows their team.
+
+---
+
+## Surface 6: Ownership Transfer
+
+Designer direction: [NEEDS CLARIFICATION] — using best judgment
+
+### Variant A — Modal with user search ← Recommended
+
+Layout: Shadcn Dialog (max-w-md). Triggered from either entry point: resource action menu
+(owner or Admin) or Settings > Users delete flow (Admin transfers before deletion).
+
+Entry point 1 (resource action menu): "Transfer ownership" option in the ⋯ menu on a resource.
+Entry point 2 (delete user): After Admin clicks "Delete [Name]", if user owns resources, a
+blocking step shows the transfer modal before deletion can proceed.
+
+Modal layout:
+- Title: "Transfer ownership" (Entry 1) or "Transfer [Name]'s resources" (Entry 2)
+- Resource name shown (Entry 1) or list of owned resources (Entry 2 — if >5, show count + scroll)
+- "New owner" field: searchable user picker (type to search org members)
+- Warning callout: "The new owner will be able to delete this resource."
+- CTA: "Transfer" (primary) / "Cancel"
+- Entry 2 blocking: "You must transfer all resources before deleting this user." Transfer CTA
+  changes to "Transfer and delete" after all resources are assigned.
+
+Copy: Title: "Transfer ownership" / "Transfer [Name]'s resources before deleting their account"
+    Warning: "The new owner will be able to delete this resource. This cannot be undone."
+    Entry 2 CTA: "Transfer and delete account"
+Trade-off: Modal with search scales to any org size. The blocking step on user deletion
+ensures no resources become ownerless.
+
+### Variant B — Inline resource-list with per-row owner picker
+
+Layout: Inside the delete confirmation, a full-page list of the user's resources with a
+dropdown per resource to assign a new owner. "Confirm all transfers → Delete user" CTA at
+bottom.
+
+Trade-off: More visual control for large resource sets, but overwhelming for the typical NGO
+admin who just needs to hand off a few dashboards. The modal (Variant A) with a search picker
+is more appropriate.
+
+**Recommended:** Variant A — Modal with user search is clean and works for both entry points.
+Blocking transfer before deletion is the right default — no orphaned resources.
+
+---
+
+## Surface 7: Data Section — Analyst Read-Only State
+
+Designer direction: [NEEDS CLARIFICATION] — using best judgment
+
+### Variant A — Remove all write actions (no indicator)
+
+Layout: Analyst visits e.g. "Ingest" page. It renders normally — table of sources, filters —
+but no "Add source" button, no edit icons on rows, no delete. The absence of controls
+communicates read-only implicitly.
+
+Trade-off: Cleanest UI. But Analysts who expect to see write controls will assume the page is
+broken, not that they lack permission. No positive confirmation of their access level.
+
+### Variant B — "Read only" badge + remove write actions ← Recommended
+
+Layout: Page header area includes a small "Read only" chip (text-xs, grey, with lock icon)
+next to the page title. All Create/Edit/Delete affordances removed. Applies uniformly to all
+Data sub-sections (Ingest, Transform, Warehouse, Pipelines, Orchestration).
+
+Key elements:
+- Page title: "Ingest" (text-3xl, bold) + "Read only" chip (Lock icon 12px + "Read only" text,
+  bg: color-surface, border: color-border, text: color-text-secondary, radius-sm)
+- No "Add source" button in the header CTA area
+- No edit/delete icons on table rows
+- Row hover still shows row-hover bg (table is still readable/interactive for reading)
+- Tooltip on the badge (hover): "Your role has read-only access to data infrastructure"
+
+Copy: Badge: "Read only"
+    Tooltip: "Your role has read-only access. Contact your admin to make changes."
+Trade-off: Persistent badge gives Analysts clear confirmation of their access level. Removes
+ambiguity between "broken page" and "intentional read-only". One badge design, applied
+uniformly — no need to design each sub-section differently.
+
+### Variant C — Dismissible banner at top of section
+
+Layout: Amber/info-tinted banner pinned below the header: "You have read-only access to Data
+infrastructure. Contact your admin to request edit access. [Dismiss ×]"
+
+Trade-off: Most explicit, but feels like an error state for a permanent role property. Analysts
+would dismiss it immediately and then wonder again why there are no edit buttons. Noisy for
+everyday use.
+
+**Recommended:** Variant B — Badge is the right middle ground. Removes all write actions
+cleanly (no confusion about broken UI) while giving a persistent, non-intrusive indication of
+why. Apply identically to all Data sub-sections — no per-section variation needed.
+
+---
+
+## Surface 8: Migration Changelog Modal
+
+Designer direction: [NEEDS CLARIFICATION] — using best judgment
+
+### Variant A — One modal, conditional content per role ← Recommended
+
+Layout: Shadcn Dialog (max-w-md). Shown once on first login after migration. Content block
+varies by role — same modal structure, different copy. Dismiss button only ("Got it"). No
+"Don't show again" toggle (it's already one-time only).
+
+Role: Admin
+- Title: "Your Dalgo just got an upgrade"
+- Bullet 1: "We've simplified to three roles: Admin, Analyst, and Member"
+- Bullet 2: "Your full access is unchanged — you now have formal user management in Settings"
+- Bullet 3: "Find all configuration under Settings, including the new Users page"
+- CTA: "Go to Settings" (primary) + "Dismiss" (secondary)
+
+Role: Analyst
+- Title: "A few things have changed"
+- Bullet 1: "You can still build dashboards, charts, and reports as before"
+- Bullet 2: "Your access to edit data pipelines and sources is now read-only"
+- Bullet 3: "If you need to make pipeline changes, contact your admin"
+- CTA: "Dismiss" (single CTA — they go to dashboards)
+
+Role: Member (previously Guest)
+- Title: "Welcome to the new Dalgo"
+- Bullet 1: "Your account has been updated — everything should look familiar"
+- Bullet 2: "You can view all dashboards, charts, and reports"
+- Bullet 3: "Your admin controls what you have access to"
+- CTA: "Go to dashboards" (primary) + "Dismiss"
+
+Key elements:
+- Modal icon: a small Dalgo logo or generic "update" sparkle icon (not an error icon)
+- 3 bullets max — no long prose, no tables
+- Role-specific CTA helps orient each user
+- No "Learn more" link (adds complexity; the bullets cover what matters)
+
+Copy: As above, per role.
+Trade-off: One modal component, three content variants. Simple to implement and maintain.
+Copy is short enough to hold per-role in a single component.
+
+### Variant B — Three distinct modal designs
+
+Layout: Separate modal designs for Admin, Analyst, Member. Enables more visual differentiation
+(e.g., Admin gets a richer design with Settings screenshot).
+
+Trade-off: Triple the design and engineering work for marginal benefit. The content difference
+is copy-level, not layout-level — Variant A handles it cleanly.
+
+**Recommended:** Variant A — One modal, three content variants. Short bullet lists, role-
+specific CTA. No "Learn more" — the 3 bullets capture everything the user needs to know.
+
+---
+
+## Summary Table
+
+| # | Surface | Recommended | Notes |
+|---|---------|-------------|-------|
+| 1 | Sidebar — Role-Adaptive Nav | Variant B — Three frames | One per role, footer chip |
+| 2 | No Access Page | Variant B — In-shell | Shell visible, recovery CTA |
+| 3 | Settings IA | Variant A — Left sub-nav | Full-page takeover, secondary nav |
+| 4 | Settings > Users | Variant A — Inline role dropdown | Fast for small teams |
+| 5 | Invite User Modal | Variant A — Single form + role descriptions | Simple, inline descriptions |
+| 6 | Ownership Transfer | Variant A — Modal + user search | Blocking step on user delete |
+| 7 | Data Section (Analyst) | Variant B — Read-only badge | Badge + remove write actions |
+| 8 | Migration Changelog | Variant A — Conditional content per role | 3 bullets, role-specific CTA |
+
+To proceed to Figma, either:
+- Accept all recommendations: "build the recommended variants"
+- Override specific surfaces: "go with Variant C for surface 3, recommended for the rest"
+
+Then re-run: `/design:design-handoff features/access-control/v1/`
+(without --brainstorm — the picks will be read from this file)

From 5f4d3ed2e66ea9edbc2129914678988f24346c4e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 4 Jun 2026 19:25:26 +0000
Subject: [PATCH 10/10] Update design.md with 9 Figma frames + add design
 pointer to spec

All frames built on the Designs page of viO3UsJicCOz3rwx4iocBL:
S1a/b/c Sidebar (3 role states), S2 No Access, S3 Settings IA,
S4 Settings > Users, S5 Invite Modal, S7 Data Analyst, S8 Migration Modal.

Known issue: S6 Ownership Transfer not yet built.

https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
---
 ...s-control-spec-A-role-system-2026-06-02.md |  1 +
 features/access-control/v1/design.md          | 76 ++++++++++++++++++-
 2 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/features/access-control/v1/access-control-spec-A-role-system-2026-06-02.md b/features/access-control/v1/access-control-spec-A-role-system-2026-06-02.md
index b400394..ff5fc4d 100644
--- a/features/access-control/v1/access-control-spec-A-role-system-2026-06-02.md
+++ b/features/access-control/v1/access-control-spec-A-role-system-2026-06-02.md
@@ -8,6 +8,7 @@
 **Date:** 2026-06-02
 **Replaces:** The role / sidebar / settings portions of the superseded rebuilt spec (`workdocs/access_control/access-control-v2-spec-rebuilt copy.md`). Do not build to that spec.
 **Pairs with:** Spec B — Resource Sharing (floor, direct shares, inheritance, share modal, groups, alerts, comments). Spec A ships first; Spec B follows.
+**Design:** [v1/design.md](design.md)
 
 ---
 
diff --git a/features/access-control/v1/design.md b/features/access-control/v1/design.md
index d2f5c6b..20bc91c 100644
--- a/features/access-control/v1/design.md
+++ b/features/access-control/v1/design.md
@@ -1,7 +1,81 @@
 # Access Control — Design (v1)
 
-**Status:** In progress
+**Status:** Ready for engineering
 **Spec:** access-control-spec-A-role-system-2026-06-02.md
+**Figma:** https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL
+**Last updated:** 2026-06-04
+
+## Screens
+
+| Screen | Frame | Node ID | Figma link | Status |
+|--------|-------|---------|------------|--------|
+| Sidebar — Admin | S1a · Sidebar Admin | 21:2 | [View →](https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL?node-id=21-2) | ✅ Ready |
+| Sidebar — Analyst | S1b · Sidebar Analyst | 22:2 | [View →](https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL?node-id=22-2) | ✅ Ready |
+| Sidebar — Member | S1c · Sidebar Member | 23:2 | [View →](https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL?node-id=23-2) | ✅ Ready |
+| No Access Page | S2 · No Access Page | 24:2 | [View →](https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL?node-id=24-2) | ✅ Ready |
+| Settings IA | S3 · Settings IA | 25:2 | [View →](https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL?node-id=25-2) | ✅ Ready |
+| Settings > Users | S4 · Settings > Users | 27:2 | [View →](https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL?node-id=27-2) | ✅ Ready |
+| Invite User Modal | S5 · Invite User Modal | 28:2 | [View →](https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL?node-id=28-2) | ✅ Ready |
+| Data Section (Analyst read-only) | S7 · Data Section Analyst | 29:2 | [View →](https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL?node-id=29-2) | ✅ Ready |
+| Migration Changelog Modal | S8 · Migration Changelog | 31:2 | [View →](https://www.figma.com/design/viO3UsJicCOz3rwx4iocBL?node-id=31-2) | ✅ Ready |
+
+## User Flows & Prototype
+
+| Scenario | Starting frame | Key connections |
+|----------|---------------|-----------------|
+| Onboard a new team member | S4 · Settings > Users | Invite user CTA → S5 modal → success → back to S4 |
+| Member hits a restricted URL | S1c · Sidebar Member | Direct-URL /ingest → S2 No Access → "Go to dashboards" CTA |
+| Role comparison | S1a · Sidebar Admin | Side-by-side with S1b (Analyst) and S1c (Member) |
+
+Prototype connections not yet wired — add manually in Figma or re-run after approval.
+
+## Design Decisions
+
+**Sidebar (S1a/b/c)**
+- Three separate frames (one per role) — clearest for engineering reference
+- Nav items hidden entirely when role cannot access (not greyed) — matches spec §5.3
+- "Read only" badge next to Data and Pipelines in Analyst view
+- Role chip in sidebar footer: Admin=brand-primary teal, Analyst/Member=grey
+- Active item: 3px left border in brand-primary, brand-light background tint
+
+**No Access Page (S2)**
+- In-shell layout (sidebar + header visible) — user can navigate away immediately
+- Header breadcrumb shows where they tried to go: "Data › Ingest"
+- Admin contact card with email shown explicitly
+- Single CTA: "Go to dashboards"
+
+**Settings IA (S3)**
+- Full-page takeover, sidebar still visible
+- Left sub-nav (180px) within Settings: Warehouse, Appearance, Org defaults, Users, Groups
+- Admin-only sections hidden entirely for Analyst/Member; only Groups visible
+- Org defaults renders with inert controls, labelled as activating in next release
+
+**Settings > Users (S4)**
+- Inline role chip/dropdown — fastest for small NGO teams
+- Pending invites in same table with amber "Pending" status chip
+- Delete action in row action menu (⋯), not inline
+
+**Invite User Modal (S5)**
+- Single-step: Name, Email, Role dropdown with inline role descriptions
+- CTA: "Send invite" — sends email immediately
+- Duplicate email: inline error below Email field
+- Success: toast, modal closes
+
+**Data Section — Analyst read-only (S7)**
+- All write actions absent (not greyed)
+- "Read only" chip next to page title
+- Applies uniformly to all Data sub-sections
+
+**Migration Changelog (S8)**
+- One modal, role-conditional copy (Admin variant shown)
+- 3 bullets, role-specific CTA: "Go to Settings"
+- One-time only
+
+## Known Issues
+
+- **S6 · Ownership Transfer not built** — needs a modal with user-search picker and a blocking transfer step in the delete-user flow. Add as a follow-up frame.
+- Prototype connections not wired — add manually in Figma or re-run after designer approval.
+- Frames are wireframe-quality — polish (icons, shadows, avatar images) should be refined in Figma before final engineering handoff.
 
 ## Figma