Design handoff v2 architecture proposal & patterns.md fixes#25
Open
siddhant3030 wants to merge 10 commits into
Open
Design handoff v2 architecture proposal & patterns.md fixes#25siddhant3030 wants to merge 10 commits into
siddhant3030 wants to merge 10 commits into
Conversation
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
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
…nts.css 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
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
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
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
Records the Figma file key for the access-control v1 design work. https://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky
…_design for frames - 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
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
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR documents the proposed v2 architecture for the design-handoff command and fixes critical correctness bugs in
patterns.md. The proposal resolves structural gaps identified in three rounds of research and aligns the design workflow with industry best practices (Figma Skills, spec-driven dev, evaluator loops).Changes
New: Design Handoff v2 Proposal (
design-handoff-v2-proposal.md)A comprehensive architecture proposal addressing:
Correctness bugs in the current command:
v8BYFkebTGQNuiRrCXWssa→ should be per-feature lookup)mcp__figma__get_metadata→ actual tools aremcp__<server-id>__get_metadata,use_figma,get_screenshot)~/Dalgo/FIGMA.mdStructural gaps:
Six design principles for v2:
.claude/constitution.md)design.md, don't append tospec.mdResolved decisions:
.claude/constitution.md(canonical, top-level)S{n} · {Screen Name}+S{n}-{State}(recommended)Design system integration:
tokens.css+components.css(source of truth) to Tailwind/Shadcnpatterns.mdand one policy conflict (button casing)Agent topology: Scout → parallel Frame agents → Evaluator loop → Consistency spot-check
Migration sequencing: P0 (make runnable), P1 (constitution + Skill), P2 (modes + async brief + topology)
Open questions: Confirm naming/brainstorm recommendations, resolve button-casing conflict, add RAG tokens to design system, decide on Skill authoring approach (manual vs. script-generated), secure engineering buy-in on constitution.
Updated:
patterns.md(critical fixes)Restructured as a Tailwind/Shadcn mapping document referencing
DalgoT4D/dalgo-design-systemas source of truth:--primary,text-muted-foreground) → design-system names (--color-brand-primary,--color-text-secondary, etc.)--spacing-page-x32px,--spacing-page-y28px)text-transform: uppercasein CSS vs. "sentence case" constitutionhttps://claude.ai/code/session_01LXZfCggxLVVUZDMk1acxky