Add project plans for brand colours, typography, workflow, and Figma migration
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
150
plans/workflow.md
Normal file
150
plans/workflow.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Workflow Plan — Figma + Code + Storybook
|
||||
|
||||
## Problem
|
||||
|
||||
We have three tools — Figma (design), code (React/Tailwind/TypeScript), and Storybook (component dev/docs/testing) — plus MCP servers for both Figma and Storybook. We need a clear process for how these connect as we build components, and what tooling/skills are worth adding to streamline things.
|
||||
|
||||
---
|
||||
|
||||
## Two Entry Points, One Loop
|
||||
|
||||
Components can start from either direction — the key is that both converge on the same verification and linking steps.
|
||||
|
||||
### Entry A: Design-First (Figma → React)
|
||||
|
||||
Richie has designed a component in Figma. We implement it in code.
|
||||
|
||||
1. **Inspect** — `get_design_context` on the Figma node returns reference code, a screenshot, and metadata.
|
||||
2. **Extract tokens** — `get_variable_defs` pulls colours, spacing, typography values. Cross-check against `tokens.css` to confirm tokens exist or flag gaps.
|
||||
3. **Check existing components** — Storybook MCP `get-documentation` lists what we've already built. Reuse before rebuilding.
|
||||
4. **Build** — React component with TypeScript props, Tailwind utilities via `cn()`, tokens from `tokens.css`.
|
||||
5. **Story** — Write stories using Storybook MCP `get-storybook-story-instructions` to match current conventions. Cover default, variants, edge cases.
|
||||
6. **Test** — Storybook MCP `run-story-tests` for rendering + a11y. Fix violations before moving on.
|
||||
7. **Visual verify** — `get_screenshot` from Figma vs Storybook preview. Compare side-by-side.
|
||||
8. **Link** — `add_code_connect_map` to link the Figma component to the React component.
|
||||
9. **Embed** — Add `addon-designs` parameter to the story pointing back to the Figma source.
|
||||
|
||||
### Entry B: Code-First (React → Figma)
|
||||
|
||||
Claude builds a component from a description or reference. We push it to Figma for Richie to review.
|
||||
|
||||
1. **Build** — React component in code, using design tokens from `tokens.css`.
|
||||
2. **Story** — Write stories, verify in Storybook (same as steps 5-6 above).
|
||||
3. **Push to Figma** — `use_figma` to create the component/frame/variants. The claude2figma skills enforce token binding here — no hardcoded values.
|
||||
4. **Verify** — `get_screenshot` to confirm it landed correctly.
|
||||
5. **Link** — `add_code_connect_map` to bridge it back.
|
||||
6. **Embed** — Add `addon-designs` parameter to the story.
|
||||
|
||||
We used this flow when creating the typography specimen frame.
|
||||
|
||||
### The Shared End State
|
||||
|
||||
Regardless of entry point, every finished component has:
|
||||
- A React implementation with typed props and Tailwind styling
|
||||
- Storybook stories with autodocs, variants, and a11y coverage
|
||||
- A Figma representation using bound tokens/variables
|
||||
- A Code Connect link bridging the two
|
||||
- An `addon-designs` embed in its story for side-by-side comparison
|
||||
|
||||
---
|
||||
|
||||
## Where Storybook Fits in Both Directions
|
||||
|
||||
Storybook isn't just for docs — with its MCP server it becomes the **verification layer** in both directions:
|
||||
|
||||
| Capability | MCP Tool | When to use |
|
||||
|---|---|---|
|
||||
| List existing components | `list-all-documentation` | Before building anything — check what exists |
|
||||
| Get component API | `get-documentation` | When composing or extending existing components |
|
||||
| Story conventions | `get-storybook-story-instructions` | When writing new stories — ensures consistency |
|
||||
| Visual preview | `preview-stories` | After building — visual confirmation in-context |
|
||||
| Test + a11y | `run-story-tests` | After every component build — catches violations early |
|
||||
|
||||
### Addon: `@storybook/addon-designs`
|
||||
|
||||
Embeds Figma frames directly in the Storybook addon panel. Each story can link to its Figma source:
|
||||
|
||||
```tsx
|
||||
parameters: {
|
||||
design: {
|
||||
type: 'figma',
|
||||
url: 'https://www.figma.com/design/mrabO6AtxN3ektGiTk0I9c/ResearchInsights?node-id=...',
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
This creates a permanent link between implementation and design intent — developers see the spec alongside the rendered component without switching tools.
|
||||
|
||||
Both addons are installed and registered in `.storybook/main.ts`.
|
||||
|
||||
---
|
||||
|
||||
## Code Connect — The Bridge Layer
|
||||
|
||||
Code Connect is the most important piece we haven't set up yet. It links Figma components to their React implementations, so:
|
||||
|
||||
- `get_design_context` returns our actual component code instead of generic markup
|
||||
- Designers see real implementation details in Figma's Dev Mode
|
||||
- The mapping grows as we build — each new component strengthens the bridge
|
||||
|
||||
**Setup:**
|
||||
1. As we build each component, call `add_code_connect_map` with label "React"
|
||||
2. For existing components, use `get_code_connect_suggestions` to get AI-suggested mappings
|
||||
3. Periodically run `get_code_connect_map` to audit coverage
|
||||
|
||||
---
|
||||
|
||||
## Skills and Tooling to Add
|
||||
|
||||
### Adopt now
|
||||
|
||||
| Skill | What it does | Why |
|
||||
|---|---|---|
|
||||
| **claude2figma** (4 skills) | Preflight reads all tokens/styles/components before writing; Component Rules enforces library instance usage; Style Binding binds colours/text/spacing to variables with QA; Reference Interpreter parses design references into structured briefs | Directly solves token fidelity when writing to Figma. Prevents hardcoded values. |
|
||||
| **Built-in /simplify** | Three parallel review agents check reuse, quality, efficiency | Already available. Run after building each component. |
|
||||
| **Built-in /review** | Code correctness review | Already available. Run before committing. |
|
||||
| **Built-in /verify** | Launches the app and confirms the change works visually | Already available. Use for visual confirmation. |
|
||||
|
||||
### Evaluate
|
||||
|
||||
| Skill | What it does | Verdict |
|
||||
|---|---|---|
|
||||
| **Storybook docs skill** (thebushidocollective) | Generates comprehensive Storybook docs with MDX, autodocs, JSDoc | Test whether it adds value beyond Storybook MCP's built-in `get-storybook-story-instructions`. May be redundant. |
|
||||
| **A11y audit skill** | WCAG compliance, screen reader support, keyboard navigation | The Storybook a11y addon + `run-story-tests` already covers per-component checks. An audit skill would add value for periodic full-system sweeps. |
|
||||
|
||||
### Skip
|
||||
|
||||
| Skill | Why skip |
|
||||
|---|---|
|
||||
| **frontend-design** (Anthropic) | We're implementing an existing NSW design system, not making creative aesthetic choices |
|
||||
| **awesome-design-md** | We have our own design language from Figma |
|
||||
| **React specialist subagent** | CLAUDE.md already covers these conventions |
|
||||
|
||||
---
|
||||
|
||||
## The Component Build Checklist
|
||||
|
||||
Regardless of entry point, every component should pass through these gates:
|
||||
|
||||
```
|
||||
[ ] Design reference exists (Figma frame OR code-first build)
|
||||
[ ] Tokens checked (get_variable_defs vs tokens.css — flag gaps)
|
||||
[ ] Existing components checked (Storybook MCP list-all-documentation)
|
||||
[ ] React component built (TypeScript, Tailwind, cn(), forwardRef)
|
||||
[ ] Stories written (default + variants + edge cases + autodocs)
|
||||
[ ] Tests pass (Storybook MCP run-story-tests, including a11y)
|
||||
[ ] Visual verified (Figma screenshot vs Storybook side-by-side)
|
||||
[ ] Figma representation exists (designed by Richie OR pushed via use_figma)
|
||||
[ ] Code Connect linked (add_code_connect_map, label: React)
|
||||
[ ] Figma embed in story (addon-designs parameter)
|
||||
[ ] /simplify run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **claude2figma skills** — Installed (4 skills in `.claude/skills/`)
|
||||
- **Storybook addons** — `addon-designs` + `addon-mcp` installed and registered
|
||||
- **Code Connect** — Link as we build, regardless of entry point
|
||||
- **Build order** — Start with primitives, work up to composites then layouts
|
||||
Reference in New Issue
Block a user