This repository is the single source of truth for design standards across all Bread Cooperative apps — Solidarity Fund, Stacks, and Safety Net. It is structured to be used both by human designers/developers and by AI tools like Claude Code to generate accurate, on-brand UI designs in Figma.
- Designers building screens in Figma for any Bread app
- Developers implementing UI from designs
- AI tools (Claude Code + Figma MCP) generating or editing designs programmatically
bread-design-system/
├── README.md ← you are here
├── CLAUDE.md ← machine-readable rules for Claude Code
├── setup/
│ └── getting-started.md ← how to set up Claude Code + Figma for Bread design work
├── design-system.md ← master: foundations + shared components + golden rules
└── apps/
├── solidarity-fund.md ← Solidarity Fund–specific design standards
├── stacks.md ← Stacks–specific design standards
└── safety-net.md ← Safety Net design standards (TBD)
| File | Link | File key |
|---|---|---|
| Bread Design System | Open in Figma | OYtf96ROFhou9nHezG5SOD |
| Solidarity Fund | Open in Figma | B6pfKFiU3oVQRq7ACKcTmf |
| Stacks | Open in Figma | CsleaPTgZVQXwkYnfUnUSE |
| Phosphor Icons | Open in Figma | 6chsKsbGWGpNhjynYv1XXZ |
- Never build components from scratch — always pull from the Bread Design System Figma file using
importComponentByKeyAsync - Never detach component instances — adjust only through exposed component properties
- Use the right button per sub-app — each app has its own button colour. See
design-system.md→ Golden Rule 3 for the full table with component keys - Phosphor icons — always import directly from the Phosphor community file (
6chsKsbGWGpNhjynYv1XXZ), never via the Design System file - Card/modal shells — built ad-hoc per flow following the standard spec in
design-system.md
Claude Code can read these files automatically and use them to generate Figma designs that match the Bread design system precisely. See setup/getting-started.md for the full setup guide.
The CLAUDE.md file in this repo is auto-read by Claude Code when you open the project — it contains the condensed critical rules and required tool configuration.
⚠️ Never commit your Figma MCP token to this repo. SeeCLAUDE.mdfor token setup instructions.
Whenever a new component is added to Figma, or an existing component is updated, the relevant .md file in this repo must be updated before the component is used in production designs.
| Change in Figma | File to update |
|---|---|
New component added to the DS file (OYtf96ROFhou9nHezG5SOD) |
design-system.md — add to the relevant section with component key, set key, and variants |
| New Stacks-specific component or pattern | apps/stacks.md |
| New Solidarity Fund-specific component or pattern | apps/solidarity-fund.md |
| New Safety Net component or pattern | apps/safety-net.md |
| Button variant added or renamed | design-system.md → Section 2.1 + CLAUDE.md → button table |
| New nav bar variant or withdrawal module state | design-system.md → Section 3 |
| New color token or Figma paint style | design-system.md → Section 1.2 |
| New text style | design-system.md → Section 1.1 |
| Known gap resolved | design-system.md → Section 7 (remove from Known Gaps) |
| Naming issue fixed in Figma | design-system.md → Section 8 (remove from Naming Issues) |
For every new Figma component, record:
- Component name — exact name as it appears in Figma
- DS Page — which page it lives on (
1:7,1:10, etc.) - Default variant key — the key used with
importComponentByKeyAsync - Component set key — for reference (do not use for import)
- Number of variants and their names
- Usage rule — when to use this component vs. alternatives
Use Claude Code with the figma-use skill to query the DS file directly:
/figma-use
List all components on the Buttons page (1:7) of the Bread Design System file
(OYtf96ROFhou9nHezG5SOD) with their node IDs and component keys.