Leapfrog Design System · @leapfrog/ui-core

How it all flows

From a Figma frame to a pinned commit in production — every stage, every gate, and who holds each key. Eight stages, one direction, no step skipped.

Figma→ Specs & tokens→ Builder lanes→ CI gates→ Company mirror→ Production

This deck is styled with the system's own tokens — color.brand.primary #005390, the Nunito Sans UI stack, and the 10px uppercase label convention — pulled from tokens/leapfrog.tokens.json.

Stage 1 · Intake

Three doors in, one shape out

Design work enters from three sources and converges into the same machine-readable form: component specs and tokens. Nothing enters as loose opinion.

Source

Figma Design

Token and component extraction from the source files — Leapfrog › Design System 2 and Leapfrog – V3. Evidence lives in docs/extraction-notes.md and per-component *-figma-audit.md files.

Source

Figma Make

Generated apps audited for reusable patterns — e.g. domains/invoices/figma-make-audit.md, the SimpleAP prototype lineage.

Source

App handoffs

Product apps file generic design decisions (SimpleAP → docs/ds-handoff/). Intake accepts product-neutral patterns and rejects app-specific content.

↓

Converges into

Specs + tokens

components/**/*.yaml component specs and tokens/leapfrog.tokens.json — tokens first, then intent, then atomic classification.

Stage 2 · Develop

Two lanes, one protected main

Work happens in isolated worktrees on named branches. Neither lane touches main directly — it's the stable integration base.

ds-builder lane

ds-builder/<topic>

Owns fundamentals: tokens, src/ui runtime, Storybook stories in src/review, public API surface. Registered in CloudOps builders/ds-builder.md.

Frontier lane

codex/frontier-<topic>

Experiments that consume only public contracts — exports, tokens, CSS, API report. Never DS internals. Files promotion requests instead of editing fundamentals.

In practice

13 live worktrees

Each branch checked out in its own worktree beside the canonical repo — enterprise grid, typed filters, IA graph, storybook remediation, release prep.

Shared files (package.json, .storybook/*, src/ui/index.ts, the API report) require explicit PR notes — they're the cross-lane contract surface.

Stage 3 · Validate

Nine gates, every PR, in order

CI runs a deterministic chain — a change that breaks fidelity, contracts, or the export surface never reaches review. Sonar tracks the consumable surface separately.

validate_specs.rb→ check:generated→ typecheck→ check:storybook→ check:frontier→ check:package→ check:api→ check:changeset→ check:release-readiness

Inside check:storybook

Build + fidelity + a11y gate + spec-trace + interaction contracts + interaction tests.

Inside check:package

Consumption, token/grid/rendering contracts, export-surface parity — keeps review-only organisms out of the runtime API.

Inside check:release-readiness

Source boundaries, runtime promotion rules, CSS contracts, IA dependency audit.

Stage 4 · Review & merge

Storybook is the courtroom

Storybook is the canonical review environment; the review checklist covers tokens, atoms, molecules, and AI-readiness. Merging isn't the finish line — readiness is.

Review

Storybook + checklist

npm run storybook; a11y addon, test runner, docs. Checklist: docs/review-checklist.md.

→

Merge

Into protected main

Per the two-lane merge policy. Main stays deployable.

→

Maturity recorded

component-readiness.yaml

Consumers gate adoption on this file — not on the merge.

Readiness ladder

draft→ beta→ design-approved→ stable

Stage 5 · Version

Changesets keep the ledger

Every governed public-surface change carries a changeset even while the package is private. The API Extractor report is the drift alarm on the public surface.

Patch

Fixes & fidelity

Bug fixes, visual fidelity corrections, docs.

Minor

Additive surface

New components, variants, additive props, new tokens.

Major

Breaking surface

Removed exports, renamed props, changed defaults, removed token paths. Minimum one minor of deprecation first.

Publishing is deliberately blocked — "private": true. release:packages is provenance-ready and waiting on the @pp/* registry decision (CloudOps #13). Until then, versioning is bookkeeping for the future package.

Stage 6 · Promote to company

The mirror proposes. It never pushes.

After CI passes on canonical main, a workflow opens (or updates) a sync PR against the company repo. Your devs decide when it lands. The commit SHA is the contract.

Trigger

CI green on main

Canonical Leapfrog DS repo (origin slug rename pending).

→

mirror-company.yml

Sync branch updated

mirror/canonical-main pushed by leapfrog-mirror-bot; PR opened into company main. No direct pushes, no tags mirrored, no ref deletion.

→

Company repo

Procurementpartners/design-system

Devs merge deliberately. Consumers pin only after the sync PR merges.

Canonical remains the source of truth; the company repo is read-only for DS workflow purposes.

Stage 7 · Governed release

CloudOps binds it, Dave signs it

A governed release is a coordination record, not just a deploy. Every builder lane accounts for itself before anything promotes.

1 · Assign

Release ID

releases/<domain>/<id>/ created by Cloud Ops.

→

2 · Account

All lanes contribute

Every builder submits a contribution or not-applicable. No silent lanes.

→

3 · Reconcile

Evidence assembled

Notes, manifest, evidence vs actual commits and deployments.

→

4 · Human gate

Dave approves

The one non-automatable step, by design.

→

5 · Promote

QA + snapshot

Immutable source tag, QA promotion, bundled company publication under the same ID, smoke verification, rollback pointers.

Stage 8 · Consume & deploy

Pinned SHA in, adapter out

Apps take the system as a pinned read-only submodule behind an app-owned adapter. Feature code sees @/ui — never the raw system, never AG Grid directly.

The pin

design-system/ submodule

The commit SHA is the contract. Upgrades are deliberate: bump → pnpm sync:design-system → typecheck/test/build → visual QA vs Storybook → commit pointer + generated files together.

→

The boundary

App adapter src/ui/

Feature code imports @/ui only. No design-system/**, no AG Grid packages, no scaffolding leaks.

→

The surface

Vercel from main

Storybook + Frontier deploy per the deployment policy: health checks, smoke table, rollback runbook.

Future model (documented, not yet live): pnpm add @leapfrog/ui-core@<approved-version> once the registry decision lands.

The whole board

One direction, eight stages

Intake

Figma Design · Figma Make · app handoffs → specs + tokens

→

Develop

ds-builder/* + codex/frontier-* worktrees

→

Validate

9-gate CI chain + Sonar

→

Review

Storybook → merge → readiness ladder

↓

Version

Changesets · API report · publish blocked

→

Mirror

Sync PR to company repo — proposed, never pushed

→

Release

CloudOps record → Dave approves → QA + snapshot

→

Consume

Pinned submodule + adapter → Vercel production

Authority never travels with the work: automation proposes and validates at every stage; the promote step is human.

System view · Node editor workspace

The architecture, wired

Every system as a node, every contract as a wire. Drag nodes, pan the canvas, zoom with the buttons — the wires follow.

Design Code Governance Deploy

Figma Design

Leapfrog › DS 2 · V3 source files

token + component extractions

Figma Make

Generated app prototypes

pattern audits

App handoffs

SimpleAP → docs/ds-handoff/

generic decisions

Canonical repo

Leapfrog DS repo · tokens · specs · src/ui · src/review · API report

intake

lane PRs

builder contributions

main → DS surface

GitHub Actions

ci.yml · 9-gate chain + Sonar

pull requests

green main

Mirror bot

mirror-company.yml · leapfrog-mirror-bot · proposes, never pushes

green main

sync PR

Company repo

Procurementpartners/design-system · devs merge deliberately

sync PR

pinned SHA

CloudOps

Builder registry · release records · environment registry

lane contributions

release evidence

approval

QA promotion

Dave · final authority

The one non-automatable node

evidence

approve / revise / defer

SimpleAP · ap-automation

design-system/ submodule pin · src/ui adapter boundary

pinned SHA

app deploy

BVS apps

AG Grid · Gauge consumers

pinned SHA

app deploy

Vercel

DS surface (Storybook + Frontier) · app environments · smoke + rollback

DS surface from main

app deployments

production

Known drift · July 2026

Four things that will bite the first real release

naming · decided

Consolidating to Leapfrog

Decision made: Convergence is decommissioned — Leapfrog only. Pending cleanup: rename the GitHub origin (Convergence_Design_System → Leapfrog), retire the convergence-design-system.vercel.app alias, and align the deployment-policy doc with the registry on leapfrog-design-system.vercel.app.

process

The release path is unexercised

No DS change has ever flowed through a CloudOps release end-to-end — every record so far marks ds-builder not-applicable. The bundled company publication step exists only on paper.

distribution

Package consumption is aspirational

pnpm add @leapfrog/ui-core is documented as preferred but publishing is disabled — blocked on the @pp/* registry decision (CloudOps #13).

tooling

No publish workflow exists

Release governance requires a tag/publish CI workflow before flipping private: false. Only ci.yml and mirror-company.yml exist today.

Cheapest first fix: land the Leapfrog consolidation — rename the origin, drop the convergence alias, and align the docs — so the first real release record starts on one canonical name.

For the product & technology teams