Big Mobility
Logistics
Design System
[ Outcome ]
I'm building a component system in collaboration with the development team, using Claude AI and Figma. To manage multiple brands flexibly down the line, I split the work into a token library and a component library. For the component library, I created a dedicated reference document for Claude's coding tool, so developers can hand off component work to Claude with minimal token usage and accurate results. Throughout this process, building a developer-friendly structure has been the top priority, so a small development team can work across multiple services at once.
Architecture Built for AI to Read, Not Just Humans
Big Mobility set out to build services quickly with AI-assisted coding, so I started by setting up foundation tokens: color, text, radius, and spacing, then built semantic tokens for each brand on top of them. Since the AI needed to read exact values directly, I defined every value in detail. I then connected Claude through Figma MCP and tested whether it correctly recognized the token data, verifying the structure firsthand. The biggest decision point was whether to manage the token and component libraries as one file. Anticipating that more services would need type-specific library management down the line, I split them from the start.
Two Token Layers, Built for AI to Parse
I designed tokens across two layers: foundation tokens and semantic tokens. Foundation tokens defined primitive values like color, text, radius, and spacing. On top of that, I built semantic tokens by mode, reflecting each brand's different primary color. I split these layers this granularly because AI cannot infer values the way a human can from context. Each token needed a clearly defined role and value, so Claude could reference the correct token when generating code.
Accessibility and Layout, Documented for AI
Color tokens went beyond just being created. I calculated the WCAG contrast ratio for each one against its actual background and documented the grade. Text was also fully defined through style tokens for size and weight, and icons, shadows, and blur effects were managed as tokens rather than individual values, so nothing inside a component ever referenced an arbitrary value, only defined tokens.
I applied the same rigor to layout, documenting the grid system with clear column and gutter rules. The grid isn't used directly in screen work today, but I prepared it so that when building new service screens with Claude Code down the line, the AI could reference this document and work from a consistent layout standard.
A Component Library Structured for Handoff
For the base library, I adopted Ark UI at the development team's request. The Claude handoff document includes the tech stack shared with the dev team, a token guide, and a component inventory with direct Figma node links for each component. This inventory lets Claude jump straight to the component it needs without reading through the entire component library, which reduces token usage and speeds up response time. I split the pages into Common, Mobile, and Dashboard. Shared elements are used across every service, but mobile and dashboard differ in both layout and how they're used, so despite the extra work on my end, I chose this structure to keep it clear for designers, developers, and AI alike.
A System Still Being Built, Live at Vinyl UI
The token and component structure I've walked through is being documented in real time at Vinyl UI. As new brands come on board, I'm continuing to build out the library so each one can move from concept to screen faster.