Design System
2025
Migrating a map-centric design system across 10 products: Leading the strategy when there was no playbook
Overview
I led the design system migration strategy for a suite of 10 mission-critical SaaS products, moving from a partially documented ArcGIS design system to MUI React. The hardest problem was one nobody had anticipated: MUI has no mapping components. For a suite of map-centric applications, this was not a minor gap. I audited the existing system, defined the migration roadmap, aligned chief-level stakeholders, and built a practical bridge solution to keep map components functional during the transition
Problem area
A legacy system no one fully understood, and a migration that threatened to break everything
When I joined, the migration from ArcGIS Calcite to MUI React had already been decided by engineering. The reasoning was sound: MUI offered better documentation, active community support, and modern React components. But the full cost of leaving ArcGIS had not been mapped. The existing system had three problems the team was living with daily. Components were only partially documented, forcing developers to reverse-engineer behaviour every time they needed to reuse something. There were no coded implementations, so every sprint meant rebuilding from scratch. And nobody had a clear picture of which components existed, which were redundant, and which were critical with no MUI equivalent. The migration would solve the documentation problem. But it would introduce a new one: every product in the suite was map-centric, and MUI had no mapping components at all. Moving forward without a solution meant breaking the core functionality of 10 live products.
Solutions
Phase 1: Making the invisible visible: auditing a system nobody fully understood
ArcGIS DS- What we lost
Map specific components built in, popups, toolbars, coordinate picker, designed for GIS
Poor documentations, no coded implementatons, forcing developers to reverse engineer
Constant custom CSS, every sprint meant rebuilsing components from scratch
MUI DS - What we gained
Excellen documentation, coded components, active community support
Modern react components, buttons, forms, navigation all work out of the box, for faster development
Zero mapping components, new DS is generic, does not include GIS specific patterns.
Components audit and migration plan
Phase 2: A practical bridge, not a perfect solution
With the roadmap approved, the immediate question was what to do about the mapping components. Rebuilding them fully in MUI would take months of engineering time. I proposed a middle path: build a small library of HTML and CSS mapping components that use the same MUI design tokens, embeddable directly into ArcGIS. This is a workaround, not a permanent fix. ArcGIS HTML and CSS has its own structure and full customisation has limits. Developers still need to get involved for complex implementations. But it moved the team from months of custom engineering per component to a reusable, token-aligned starting point. Three components have been shipped and are being reused across multiple products including the logistics platform
01
Manual & Automated Visual Audit
I manually ran an audit on the fully library and later used AI as an assistant to help me inspect the style gaps between ArcGIS and MUI. And so, I created a checklist to extract visual features and flag errors in padding, radius, and color.
Matching of visual heirarchy design
02
Visual Governance
I designed the target UI in Figma using semantic tokens (border.corner-radius.round, color.border.3, color.foreground.1) to ensure perfect parity with the core app.
MUI design tokens and variants to redesign mapping components
03
The Token Bridge
I used AI to translate those Figma specs into clean, native HTML. And shared it with mappers to embed directly into ArcGIS.
AI Assissted design system
Pop-up ArcGIS component example: Redesign using new DS tokens and coded to HTML
Sucess Metrics
A migration strategy that gave the team direction, and a bridge solution that reduced engineering effort
3 HTML components shipped
Map components built and reused across multiple products, with developer support for implementation.
Next steps
Work in Progress
Machine readable DS & Governance
Helping design team ship code directly, by testing the DS and migrating it not a machine readable DS. We run multiple test to understand why the same prompt generate different results. The test concluded that, the token name and documentations are not built for machines to understand. Token naming have to be aligned with the LLM system to help it better read our documentations and JSON files.
Machine readable design system
Enable rapid prototyping for LLM by convert current documentation into machine readable JSON.
