Workspace → Configure → Design ↔ Code → Generate → Scale

Each client gets a dedicated project workspace with its own configuration, connected to the ShopFront design-system codebase. That configuration drives output directly in their repo, AI tools generate against their code (not generic templates), and Figma stays attached to the same system through MCP workflows.

This is not a handoff model. It is one governed system with two interfaces (code + design) and one source contract (tokens, atoms, components, sections) that both humans and AI must follow.

Client workspace

Every client starts with a dedicated ShopFront project workspace. That workspace has two connected assets: (1) their brand configuration for the entire codebase, and (2) live access to the ShopFront design-system repo (tokens, atoms, components, sections).

The workspace is the operating boundary. AI tools, design workflows, and deployment scripts all run against this client-specific context, not a shared generic template.

Because the configuration is project-scoped, token decisions apply consistently across all generated UI in that repo: same ramps, same type scale, same spacing ladder, same component contracts.

Client project model

The component library remains the source catalog, but usage is client-bound: each project workspace references the same canonical DS inventory while applying that client's own configuration values.

This gives agencies and brands strict output control: one system foundation, many branded workspaces, each with its own reusable brand key.

Design-system access inside that workspace

Teams can pull DS components directly into implementation work without forking patterns. The same atoms/components/sections that power the DS are consumable in client repos, so "net new" UI is assembled from governed primitives instead of copied snippets.

When teams need Figma context, those same components can be imported into the client Figma file still attached to system tokens and structure.

AI entry points

Clients can point Claude Code (and similar agent tools) directly at their own repository. Agents compose from the shared DS contracts already available in that workspace, which reduces reinvention and blocks style drift.

• Repo-first AI — generate inside the client's codebase, not an external sandbox
• System-first composition — consume existing tokens, atoms, components, sections
• Guarded generation — less hallucination because valid building blocks are explicit

Configure

Configuration is global and project-owned. The client sets brand color, type, spacing, radius, and semantic roles once, and those values drive their codebase directly.

This is where agencies lock output quality: foundational design decisions become executable tokens instead of per-page styling choices.

When the configuration updates, generated UI and manually composed UI both move together because they reference the same token contract.

Global brand controls

The configuration defines enforceable system behavior across channels:

• Color system — brand ramps and semantic mappings for surfaces, text, borders, actions, states
• Type system — fonts, hierarchy, role-based style mappings
• Shape and spacing system — radius ladder and spacing ladder that components consume by default

These controls are intentionally global so brand expression is consistent whether the output is hand-authored, AI-generated, or exported to Figma and back.

Design ↔ Code sync

Clients can import components to Figma fully attached to the system, edit in design, then push changes back into their code workflow through their own MCP-enabled agent tooling.

The objective is not pixel export. It is contract continuity: design edits still reference the same component IDs, props, and token bindings expected by the code system.

The sync workflow keeps roundtrips safe by checking structure before code updates are accepted:

• Component identity check — instances still map to known DS components
• Token binding check — values are bound to approved variable families
• Property contract check — variant/boolean/enum settings stay within allowed props
• Structure check — layout and naming remain machine-readable for automation
• Drift check — deviations between design and code contracts are surfaced before push

Anything deterministic can be normalized automatically; anything ambiguous is surfaced for human approval before code-side actions run.

Import to Figma

When components are imported, they land system-attached by default:

• Components instance from canonical DS mappings
• Tokens and text roles resolve to client workspace configuration
• Design assets stay compatible with downstream MCP automations

Edit and push back

After design edits, MCP workflows can push approved changes back to code with guardrails:

• Validate changed components against code contracts
• Preserve token semantics through roundtrip
• Generate patch-ready outputs for repo workflows

MCP workflow checks

Client-owned workflows should always verify:

• Token integrity — no raw style values replacing configured semantics
• Component integrity — no detached/off-contract substitutions
• Property integrity — props remain valid for mapped code components
• Deploy integrity — outputs are safe to merge into the client repo

Generate + ship

Teams run generative tools directly on their own repositories. Because workspace config and DS contracts are already present, generated UI can stay system-compliant without reinvention.

AI on client repo

Agent workflows target the client's codebase as the runtime source of truth:

• Read existing DS components and local project composition patterns
• Use configured tokens and semantic roles already defined for that client
• Generate diffs against real repository files and standards
• Avoid hallucinated component APIs by using registry-backed mappings

This keeps AI output grounded in what the team actually ships, not what a model guesses should exist.

System-safe generation

Typical outputs include:

• Net-new UI composed from existing atoms/components/tokens
• Themed implementation code aligned to client configuration
• Patchable repo changes ready for review and merge workflows

The design system remains the constraint layer: generation composes with known primitives instead of inventing incompatible ones.

Themed deployment

The same configured token key can be applied across multiple ShopFront-built properties. New sites conform to the same brand spec without re-theming from scratch.

Scale

Once a client workspace is configured and connected, that setup becomes a reusable brand key for future builds, campaigns, and sibling sites.

Teams can still request net-new components when needed, but most expansion happens by reusing the same governed system across additional experiences.

• Brand consistency at scale — multiple sites can adopt one client token key
• Faster launches — new pages and sites start system-aligned by default
• Lower AI risk — generated UI inherits the same standards every time

This is the core value for brands and agencies: tight control over outputs, faster production, and predictable quality whether work is human-authored or AI-assisted.

Operational snapshot

Current focus is client-owned workspace execution with governed AI output and Figma roundtrip support.

Roadmap

Next builds in priority order:

1. Roundtrip hardening — tighten MCP validation for design edits pushed back to code
2. Client workflow templates — packaged MCP flows for agency teams
3. Brand key portability — faster apply/reapply of client config across ShopFront-built sites
4. Catalog-to-Figma ergonomics — smoother direct import actions for day-to-day design operations
5. Generation guardrail telemetry — clearer visibility into how AI outputs comply with system contracts