Architecture

One repo, two front doors, boring PR review

The core architectural decision: there is no design branch versus dev branch. There is one design-system repo, and every path — Figma sync, code sync, brand updates — converges on the same reviewable pull request flow your team already uses.

GitHub — design-system repo

source of truth · main protected · schema, tokens, components, brand, context

Figma plugin

designers · design-sync/* PRs

CLI + Claude Code / Cursor

developers · dev-sync/* PRs

Published packages

@org/design-tokens · @org/design-assets

Product app repos

web, iOS, android, marketing — consume via package, never edit source

Sync flow

Both a designer's Figma session and a developer's code scan reduce to the same shape: a branch, a PR, a diff and impact summary, ordinary review.

Designer

Figma plugin

Runs Sync

opens a design-sync/<date>-<summary> PR with a generated diff + impact summary

Developer

CLI / Claude Code / Cursor

Runs scan

opens a dev-sync/<name> PR proposing components/tokens found in code

Design System Lead

Ordinary PR review

Approves & merges

CI publishes @org/design-tokens, @org/design-assets — versioned

Product repos

package manager

Pull latest

consume via published package — never edit source directly

Repository structure

figma-plugin/designer front door — nav, selection, persistence

schema/shared TS types + JSON Schema — imported by plugin, CLI, export

brand-kit/framework-independent brand/asset pipeline, testable without Figma

cli/design-system CLI — sync, scan, brand:generate, context:generate

packages/tokens/Style Dictionary build — CSS vars, JS, iOS, Android outputs

packages/assets/published brand-kit outputs

packages/ui/(later) code component library, once contracts stabilize

context/generated — AGENTS.md, CLAUDE.md, .cursor/rules/, copilot-instructions.md

docs/generated — foundations.md, components.md, patterns.md, CHANGELOG.md

.github/workflows/PR validation, package publish on merge, drift-check cron

Separate consumer repos never edit source — they depend on published packages: web-app/, ios-app/, marketing-site/.

AI-tool-agnostic context

One canonical rules.json is rendered into every format a given AI tool actually reads. Never hand-edit the rendered files — edit the source and re-export.

AGENTS.mdEmerging cross-tool convention — canonical default

CLAUDE.mdClaude Code

.cursor/rules/*.mdcCursor

.github/copilot-instructions.mdGitHub Copilot

Brand Kit pipeline output

One source logo + palette, versioned under /brand/<version>/. Re-runnable from the plugin, the CLI, or CI whenever the brand changes.

·favicon.ico, favicon-16/32/192.png
·apple-touch-icon.png (+ precomposed variants)
·manifest.json PWA icon set
·iOS AppIcon.appiconset (if iOS is a selected surface)
·Android adaptive icon layers (if Android is selected)
·Open Graph / social preview card
·Logo lockup variants — light/dark/monochrome
·brand-assets.json — every generated file + source hash

Roles, mapped to GitHub permissions — no bespoke auth

Role	Maps to	Can do
Viewer	Read access	View Govern dashboard, docs, search
Designer	Write access, Figma plugin	Bootstrap, propose via design-sync/* PRs
Developer	Write access, CLI/AI-tool skill	Propose via dev-sync/* PRs, consume packages
Design System Lead	Repo maintainer	Approve/merge PRs, promote candidates, deprecate
Owner / Manager	Repo admin (or Viewer + dashboard)	Everything above, read-only, via Govern dashboard