SystemOne
Unifying a multi-platform design system from audit to architecture — across 3 platforms with no shared tokens, no component documentation, and 3 different hex values for the same brand green.
225+
Tokens across three(3) products into one system.
context
The platform divergence problem
OneCart runs three customer-facing platforms: Marketplace Web, Marketplace Mobile App, and the Shopper App (used by personal shoppers fulfilling orders). No shared tokens. No component documentation. No shared design language. The platforms were a mess, and the gap between the digital experience and the updated brand identity was getting wider.
I pitched SystemOne to leadership because nobody else was going to. I built the case, designed and ran the audit, defined the architecture, and led the transition into implementation.
Problem
Three platforms, no shared system
Buttons, inputs, product cards, navigation — all looked different, behaved differently, and were named differently across the three platforms.
Brand inconsistency
The brand's green had three different hex values across platforms. Neutrals diverged even further. The digital products didn't match the updated brand guidelines, and the platforms didn't match each other.
Duplicated effort
Each platform team built and maintained its own version of the same components. A button redesign meant three separate implementations with no guarantee they'd align.
Interaction fragmentation
Components that looked similar behaved differently. A form field error showed below the input on Shopper, below the input on Marketplace App, and as a toast on Marketplace Web. Someone switching between apps would encounter three different feedback patterns for the same action.
Constraints
Key Constraints
No existing documentation or component inventory — everything had to be audited from live products and Figma files. No dedicated design system team; this ran alongside active product work on Spotlight. Three distinct codebases with different tech stacks. The Shopper App serves a fundamentally different user (personal shoppers vs. customers), so full visual unification wasn't always appropriate. Brand guidelines had recently been updated but the digital products hadn't caught up.
Research & Design Strategy
The Component Audit
I designed a structured audit covering 7 component families and 2 foundation layers (colour and typography) across all three platforms. Each family was scored on visual similarity (1–5), behavioural similarity (1–5), and consolidation potential.
High similarity, high impact — unify first: Product Cards (visual 4+, impact 5), Typography (visual 5), Information Cards (visual 4). Nearly identical across platforms and used everywhere. Straight into the universal tier.
Low similarity, high impact — consolidate carefully: Colour (visual 3.5, impact 5), Buttons (visual 3.25, impact 4), Forms (visual 3.25, impact 4), Alerts (visual 3, impact 4). Visually and behaviourally divergent across platforms, but too critical to ignore. These needed the audit data to guide how they came together.
Low similarity, low impact — don't force it: Modals & Bottom Sheets (visual score 2.7, business impact 3). Most fragmented, but also least critical. Not worth the consolidation effort in the first phase.
What the data showed:
A one-size-fits-all consolidation wouldn't work: Some components were nearly identical across platforms (Search Input scored 5). Others were deeply fragmented (Icon Button scored 1, Action Modals scored 2).
Behavioural divergence was often worse than visual divergence: Forms looked similar (score 3) but their active and error states varied significantly (score 2–3). The behavioural scores caught problems the visual scores missed entirely.
Business impact didn't always track with similarity: Modals had the lowest visual similarity (2.7) but also the lowest business impact (3). Product cards had high similarity (4+) and the highest business impact (5). So prioritisation had to factor in both.
Strategy: Three-Tier Classification
I defined three tiers based on the audit scores:
- Universal (similarity 4–5): Components functionally and visually equivalent across all platforms. Single source of truth. Examples: Search Input (score 5), Primary/Secondary/Ghost Buttons (score 4), Information Cards (score 4).
- Product-Specific: Same purpose, structurally different requirements per product. Shared base architecture with controlled variation. Examples: Product Cards (shared base + signature variants for Marketplace and Shopper), Hamburger Menu (different content per app).
- Device-Specific: Platform constraints (mobile vs. web) drive legitimate divergence. Designed independently but follow shared token foundations. Examples: Marketplace Web navigation (desktop-specific), Bottom sheet behaviour (mobile-only).
If the audit scored a component 4–5, it belonged in the universal tier. If it scored 1–2, forcing unification would create a component that's correct nowhere. The Icon Button was the clearest example — Marketplace uses a rounded, stroked, outlined pattern and Shopper uses a borderless, cornerless, outline-free pattern. Merging them would mean Shopper's minimal UI gets a bordered button that doesn't belong, or Marketplace loses the visual weight its buttons need.
Solution
Foundations First
With 9 component families audited and limited bandwidth, sequencing mattered. I started with colour and typography before touching any components. Every component depends on these foundations — building components first means hard-coding values that get refactored once tokens land.
Colour: The brand's primary green existed as three different hex values (#BCDDB5 on Marketplace, #D6F1DA on Shopper for Green 100 alone). Neutrals were worse — Grey/Neutral 600 scored just 2 across platforms. The digital colours didn't match the updated brand guidelines. Colour scored 5 on business impact, the highest in the entire audit.
Typography: Visual alignment already scored 5 — the platforms were close. But there was no shared typescale; each pulled from its own definitions. Codifying a single token-driven typescale was low effort since things were already nearly aligned, and it meant every component built afterward would pick up correct typography automatically.
Both foundations are now implemented in design and code. When the first component — the button — was built, it inherited correct colour and type values from day one instead of hard-coding them.
Component Decisions in Practice
Behavioural standardisation: Most design system audits compare how components look. I added a behavioural layer because the audit data kept showing that visual similarity masked interaction problems. Forms looked similar (visual score 3) but active state behaviour scored 2 — on Shopper, the background and border stay the same on focus. On Marketplace App, the background stays but the border disappears. On Marketplace Web, the background disappears and the border turns green. Error handling was just as fragmented. The decision was to standardise interaction per device type (mobile vs. web) rather than forcing identical behaviour everywhere.
Shared base, signature variants: For components like Product Cards — highest business impact, appearing on every major surface — the audit showed a dual nature. Some parts were common across platforms (image, name, price, tag), others were structurally unique (Marketplace needs vendor logos and 18+ badges; Shopper needs substitute states and multiple action buttons). The approach: a single shared base component with optional slots, plus signature variants per product. One mega-component handling every variation would need conditional logic for badges, substitute states, and quantity controls — unmaintainable for everyone using it.
Button — first component, fully token-driven: The button is SystemOne's first production component and the proof of concept for the architecture. Four variants (primary, secondary, ghost, icon), four states each (default, hover, active, disabled), every visual property consuming tokens — no hard-coded values. Built in Figma and code in parallel, with the React component pulling directly from buttonTokens so design and code stay in sync by construction, not by discipline.
Token Architecture
SystemOne's foundations use a two-layer token system: global primitives (raw values with no opinion about usage) and semantic tokens (purpose-driven mappings). Components never reference primitives directly — they consume semantic tokens, so a change at the primitive level cascades correctly through everything.
The system started with zero structured tokens and three different hex values for the same brand green. The current system has 225+ tokens across 10 collections:
- Colour (113 tokens) — 52 global primitives mapped to 61 semantic tokens. The largest collection, reflecting colour's role as the highest-impact foundation in the audit.
- Spacing (47 tokens) — 15 global primitives mapped to 32 semantic tokens. Semantic tokens cover layout, component padding, and spacing relationships.
- Typography (25 tokens) — Global tokens for the unified Campton typescale: 3 weights, 11 sizes.
- Border-radius (22 tokens) — 9 global primitives mapped to 13 semantic tokens for component-level radius decisions.
- Border-width (12 tokens) — 4 global primitives mapped to 8 semantic tokens.
- Icon (6 tokens) — Global sizing tokens for icon scale.
Global primitives → Semantic tokens → Component consumption: green-100 (#00DF88) → action.primary-default → Button primary fill. If OneCart's brand green changes, updating the green-100 primitive updates every semantic token that references it, which updates every component consuming those tokens. No component needs individual editing.
Impact
Outcomes
Current state
SystemOne has been validated through two production deployments. The Marketplace Web and Mobile apps went through a full design overhaul using SystemOne foundations and the button component across all surfaces. Spotlight OMS adopted SystemOne foundations and the button for its Phase 1 redesign — the first internal product built on the system from the ground up.
The audit itself was the first comprehensive component inventory OneCart had ever done — 7 families + 2 foundations across 3 platforms. The three-tier classification model is now the framework for all component decisions. The unified colour palette (55 values across 6 ramps) and typography scale (Campton, 3 weights, 11-step size scale) are live in both design and code. The two-layer token architecture is operational in Figma and code, and the button component — primary, secondary, ghost, icon variants — ships with every property token-driven, no hard-coded values.
Target metrics (ongoing): Design-to-code visual variance ≤5%. Component coverage ≥90%. Design handoff velocity ≥30% improvement from token-driven specs.
reflection
Conclusion
The platforms were diverging and nobody was tracking the cost because there was no inventory to measure against. The audit turned a vague sense that “things don't look consistent” into specific scores, severity ratings, and a prioritised action plan.
The most important decision was auditing behaviour alongside visuals. Visual audits are straightforward — screenshot components side by side. Behavioural audits require interacting with live products across platforms and documenting how things respond, not just how they look. That extra layer caught problems that would have shipped as “unified” components that actually confused users.
Building Spotlight on SystemOne from day one proved the token-driven approach works — the hard-coded value problem the audit identified doesn't exist in Spotlight's codebase.
If I were starting again, I'd push for engineering representation in the audit from day one. The technical alignment and migration difficulty scores are still pending joint review for some families, and having engineering earlier would have given a more complete picture. The design-side audit was thorough, but SystemOne succeeds or fails at the code level.
One principle this project reinforced: systems thinking isn't about making everything the same. The three-tier model doesn't eliminate platform differences — it classifies them so the team knows which differences are bugs and which are features.