Pull → Design → Align → Push → Evolve

A bi-directional loop between design and development. Clients request UI into their Figma or AI tooling. It arrives as structured, editable, token-enforced components. Changes propagate in both directions. The system keeps itself honest.

This is not a one-way handoff. Design informs code. Code constrains design. The plugin enforces the contract between them at every step.

Pull

Clients start from the ShopFront core — not a blank Figma file. Components, tokens, and patterns enter their workspace on demand, as they need them.

Files stay intentional. Nothing is pulled in speculatively. Everything in a client's file is there because they put it there.

Components arrive complete. Request a button and the full component set lands in the file with its corresponding variables, type styles, and placeholder icons — nothing else to wire up. Variables can then be adjusted from the Figma variable panel, the ShopFront plugin, or the design system GUI configuration (coming soon).

Component catalog

The component library is the storefront. Every component is browsable, inspectable, and requestable. Clients browse by category or use case, find what they need, and add it directly to their file.

The bridge is flexible. When a client clicks "Add to Figma" on a component, the request can travel through the ShopFront plugin, the Figma Console MCP, or any other MCP the client prefers — any of them will instance the component token-bound and ready to use, directly in their Figma file.

On-demand instancing

Components are never bulk-imported. A client building a PDP gets PDP components. A client building a blog gets editorial components. The file only ever contains what's in active use — which makes every subsequent Align run faster and more meaningful.

The plugin also supports direct search. Type a component name, select a variant, it appears in the current frame.

Requested component sets don't land on a blank canvas — each one places itself on an appropriately named page, organised in keeping with the design system structure and naming conventions. An atom lands on the Atoms page under its category; a molecule lands on Molecules; a section on Sections. If the page doesn't exist yet, the plugin creates it. The result: a client's file mirrors the structure of the system itself, automatically.

Use-case kits Coming soon

For common page types, kits will batch the request. "Add PDP kit" will fire the component requests for the 10–12 components that make up a standard product detail page — the same as clicking them individually, but in one action.

• PDP kit — gallery, product title region, variant picker, buy box, accordion, availability
• Collection kit — product cards, filters, pagination, section headers
• Editorial kit — hero, content blocks, testimonials, email signup

Design

Once components are in the file, clients configure their brand and compose layouts. They're working within the system — or around it, depending on their needs.

Brand configuration happens through the plugin's theme controller: primary and neutral color scales, type choices, spacing scale, border radius. These map directly to the token system, so every component in the file responds immediately.

Clients can explore freely. New layouts, custom arrangements, combinations the system didn't anticipate — all valid. Align exists precisely to handle what design exploration produces. The system doesn't need to predict every outcome; it just needs to be able to normalize it.

Design guardrails

Design inside the system is intentional — not random, not reactive. Only a small set of decisions are truly foundational, and those get deliberate attention up front:

• Colors and color ramps — picked and defined once, not re-invented per screen. The ramp sets the tone; every surface, text, and border token resolves from it.
• Typefaces and the type scale — chosen deliberately. Every text style in the system is a node on that scale, not a one-off font size.
• Spacing and radius — a single token ladder. If a value isn't on the ladder, either the ladder is wrong or the decision is.

Every other decision is a choice from the variables already in place — not an invention. If a needed value genuinely doesn't exist, a new variable can be added, or an existing one updated, but that's a deliberate act with a reason behind it. Re-architecting the variables without diligence is how systems drift. Done well, you shouldn't need to — it's fine-tuning, not rebuilding.

Inside those guardrails, there's wide room for creativity. Unique layouts, bespoke compositions, expressive patterns — the system doesn't constrain what gets designed, only what gets designed with. The underlying structure is what makes the output legible to both humans and AI agents. The more consistent the foundations, the better the tooling works on top of them.

Align

Before anything becomes code, the plugin runs an alignment pass. This is the critical step. It normalises the design back to system truth — every token bound, every component valid, every value intentional.

Align runs in two passes so the designer stays in control without getting bogged down.

Each pass is a sequence of discrete skills — small, single-purpose routines the plugin executes in order. Each skill owns one slice of the contract. Together they normalise the file into a state the code generator can read deterministically:

• Variable audit — walks every node, checks every fill, stroke, and border against the correct variable family (Surface/*, Text/*, Border/*). Unbound raw values are rebound; mis-bound values are flagged.
• Text style audit — confirms every text node was applied through a named style via setTextStyleIdAsync. Direct fontSize, fontWeight, or fontFamily properties are replaced with the closest matching style.
• Spacing & radius audit — resolves raw padding, gap, itemSpacing, and corner radius values to Base/Space/* and Settings/Radius/* tokens.
• Component integrity — checks every instance against the registry. Detached instances, deprecated components, and off-system atoms are swapped to their canonical counterparts where a swap is known, or surfaced for review where it isn't.
• Drift detection — flags components that exist in the Figma file but not in the codebase, and vice versa. Drift is the silent failure mode that breaks generation, so it's audited separately.
• Redundancy scan — identifies duplicate atoms that are functionally equivalent under different names. A "Pill" that is a Badge with different padding is collapsed back to the Badge.
• Structural audit — verifies auto-layout direction, sizing modes, and naming conventions match the component contract. A frame that should be HUG but sits on FIXED is corrected.
• Accessibility pass — contrast ratios against the active scheme, alt text on image fills, tap target sizing on interactive atoms.

Everything the skills can resolve without ambiguity flows to the auto-fix pass. Everything that requires a judgment call flows to the review pass.

Auto-fix pass

Deterministic fixes are applied silently, no approval needed:

• Hardcoded hex fills → correct Surface/*, Text/*, Border/* variable bindings
• Raw padding and spacing numbers → Base/Space/* variables
• Raw border radius → Settings/Radius/* variables
• Direct fontSize / fontWeight on text nodes → text style application
• Deprecated component swaps (e.g. old Button/Primary → Button / Fill)

Review pass

Anything that can't be fixed deterministically surfaces as a single consolidated list. The designer resolves, approves, and moves on:

• Off-system components with no known swap
• Detached instances
• Variable family mismatches requiring context to resolve
• Structural anomalies outside system patterns

What gets checked

The Align audit covers 31 compliance checks across four areas:

• Fill bindings — every fill must reference a system variable, not a raw color
• Text styles — every text node must use a named text style from the DS
• Spacing and radius — all padding, gap, and corner radius values must use design tokens
• Component integrity — no detached instances, no deprecated components, no off-system atoms

Push

Once a file has passed Align, the design maps cleanly to code. No translation, no guesswork. Because every component is known and every token is bound, generation is a mapping exercise — not an interpretation problem.

Page manifest

The plugin reads the current page or selection and builds a structured manifest:

• Each component instance is matched to its registry entry via figmaId
• Property overrides are read (state, layout, size, booleans)
• Bound token values are captured
• Layout structure — section order, nesting — is preserved

The manifest is a complete, machine-readable description of the page. Code generation reads from the manifest, not directly from Figma.

Code output

From the manifest, the generator produces:

• Liquid sections — Shopify section files with correct schema, settings, and component composition
• React / JSX — component composition for headless or custom front-ends
• Settings schema — Shopify section schema JSON derived from component props and content fields

The DS code components are the source of truth. The generator maps from manifest → known component → existing code file. No new code is synthesised from scratch.

Token export

The client's configured token values — their brand colors, type choices, spacing scale — export as a CSS custom properties file. Drop it into their theme and every component in the system responds.

Evolve

When something is missing — a component variant, a new atom, a pattern that doesn't exist yet — the loop doesn't break. It routes the gap back as a request.

Clients submit a request with context: what they need, where it would be used, the use case. The request enters the ShopFront approval workflow.

• Approved — built properly in the core system (code first, Figma generated from code), flows back to the requesting client and optionally to all licensees
• Modified — a variant or adaptation is built that satisfies the use case within system patterns
• Denied — too specific, duplicates an existing pattern, or outside scope — logged to ds-decisions.md with rationale

This is how the system grows without drifting. Every addition passes the same gate as the original components. The loop closes, the file updates, and the client picks up where they left off.

What's built

The loop is largely operational. The steps below reflect current build status.

Roadmap

Next builds in priority order:

1. Catalog "Add to Figma" buttons — website → server → plugin pipeline, closes the Pull gap
2. Pre-push Align skill — fast 2-pass version (auto-fix + review) optimised for pre-generation, not full audit
3. Page manifest reader — plugin skill that walks the page tree and resolves figmaIds against the component registry
4. Token export — CSS custom properties file from the client's configured token values
5. Code generator — manifest → Liquid section files + schema JSON, starting with Shopify