Making a design system machine-readable for AI-supported work

As part of my work at ELCA Informatics, I audited the design token foundation behind a complex design system: mature Android, iOS, and global token libraries already in active use. Android went through the audit first and set the pattern the other two libraries were then measured against. The libraries had grown in ways that made them hard to verify with confidence. Token scopes were broad or inconsistent, descriptions were incomplete or missing, naming had small inconsistencies, and changelog structures differed from library to library.

For a human designer, most of that was manageable. For an AI-supported workflow, it was a blocker. An AI agent can only reason reliably about a design system when the system exposes its intent clearly, through names, scopes, modes, descriptions, and documented decisions.

The libraries could not be rebuilt from scratch. They were live design-system assets with platform-specific logic, existing components, and downstream consumers, spanning three related but different foundations: global tokens as the platform-agnostic source layer, and separate Android and iOS implementations.

Every change had to be safe, reversible in reasoning, and explicitly documented. Typography and accessibility sizing needed particular care. Accessibility values could not be touched casually, and any token deletion had to be treated as high risk unless consumer usage was fully validated.

I framed this as more than a token cleanup. The real goal was to make the design system AI-ready: structured enough that humans, engineers, and AI agents could inspect it, understand it, and make controlled changes without guesswork.

That meant treating the token layer as an interface. Names became part of the API. Scopes became guardrails. Descriptions became machine-readable intent. Changelog rows and reference cards became the governance layer that made every decision traceable. The process followed a strict pattern throughout: read-only analysis first, a preview before every change, explicit approval before anything was written, small verifiable changes, and documentation for every update.

I started with Android, since it set the pattern the other two libraries would be measured against, then moved through the same process for iOS and the global token layer: auditing collections, modes, scopes, descriptions, naming patterns, missing values, aliases, and potential orphan tokens. For iOS, the audit covered 375 local variables across two collections. I cleaned non-typography scopes, removed unwanted modes, added missing descriptions, verified light/dark and default/accessibility modes, and left typography values untouched. One confirmed orphan token was deleted; 85 further candidates were deliberately left in place, since local usage alone wasn’t strong enough evidence for deletion without a separate consumer audit.

For the global token layer, I verified 265 variables, focusing on making the platform-agnostic foundation dependable: complete descriptions, no overly broad scopes, no missing mode values, no unresolved aliases, and documented reasoning wherever a mapping was intentionally unusual. Across all three libraries, I aligned the changelog into one consistent governance format, and used reference cards as stable evidence inside each library, since direct links to variables aren’t reliable long-term documentation. I did this work with Codex, OpenAI’s coding agent, as the AI-supported half of the workflow: scanning for patterns, comparing structures across libraries, flagging inconsistencies, generating safe previews, and verifying results after each approved change.

Two things stood out working this way. Codex was genuinely fast, and that speed mattered specifically because the system was large and interconnected: it could hold the shape of hundreds of tokens across three libraries at once and surface relationships a manual pass would have taken far longer to notice. But it also made mistakes, confidently enough that I couldn’t take its output at face value. I stayed in the driving seat throughout. Nothing was written without my review, and the process was AI-supported, never AI-designed.

I later turned this workflow into a written playbook: read first, preview every change, write only after explicit approval, and verify afterward. It is the reason three libraries this size could move without a single unreviewed change reaching production.

The audit turned the token foundation from a visually usable system into something more explicit, inspectable, and governance-ready. The iOS library finished with 375 documented variables: zero empty descriptions, zero duplicate names, zero missing mode values. The global token library finished with 265 documented variables, similarly clean, with every intentional exception documented rather than left ambiguous.

The more important outcome wasn’t the numbers themselves. Working this way with Codex changed what I could actually hold in my head at once: it helped surface connections and inconsistencies across hundreds of tokens and three libraries that would have been easy to miss scanning manually, while I stayed responsible for judging what those connections meant. The system now exposes enough structure and intent that an AI agent can inspect it, understand naming and scope decisions, propose changes, and have its results verified against a documented baseline, safely, rather than by guesswork.