(Re) Designing A Design System for LLMs

What the audit found

• 72%

  Variables shown in every Figma picker

• 23%

  Semantic tokens holding raw values, 106 of 457

• 10%

  Variables with a description

• 7 of 9

  Button component sets with no description

• 100

  Components with a complete A11Y block: 783 facts across 30 success criteria

• 14

  Keys in a fixed order: role, name, state, keys, focus, target, group, announce, timing, errors, purpose, signal, alt, reduced

• 30

  WCAG success criteria covered, with an index that lets an agent check one criterion across all 100 components

• Review note

  This describes internal authoring targets and audit results, not an accessibility conformance statement. Any external, customer-facing or regulatory claim based on this work goes through Kinective's Legal team before it is relied on or published. One contrast defect on form-control borders is still open.

More components

Components are built and continuing to be built in React and Vue with Code Connect. The next set includes Alert, Card, Checkbox Group, Drawer, Field and Popover.

Hosting

Publish the generated docs on the company's internal site. The pages job is ready.

Distribution

An agent kit on the internal package registry, an org-wide Claude skill, and steering packs for the engineering teams' AI tools.

Pilot measurement

Baseline and day-90 numbers for prototype rework, time to a correct screen, and library adoption.

z-index tokens

Layering roles and values are drafted and ready for review.

• Technical

  Two frameworks stay. React and Vue both had to get identical markup from one component contract, so nothing could be built for one and ported to the other.

• Org

  The Figma file was being edited by people and by scripts at the same time. An undo on the design side rolls back a script's writes with no notification, so every script re-checks a node before changing it.

• Time

  Six weeks from a clean-sheet Figma file to a working code foundation, with the first AI-built component due from the pilot team before the end.

• Regulatory

  Accessibility requirements are written per component and checked in CI, and they are internal targets. Any customer-facing conformance claim goes through Legal first.

• Decision 01

  Figma owns looks, the repo owns behavior

  Split the source of truth in two, and generate everything else

  Figma is the source of truth for visuals and structure: five variable collections, 806 variables, 100 components, light and dark modes. The repository is the source of truth for accessibility and behavior: 783 accessibility facts and the Ark UI mapping. A build script turns both into tokens, the contract JSON, the docs for agents and the MCP server. Nothing that can be generated is written by hand.

  Trade-off

  A change on either side can now fail a build, so the pipeline has to be as reliable as any other build step.

• Decision 02

  Token names describe their role

  Name tokens for what they're for, and keep primitives private

  Prism 1.0 names encoded the component and the colour, like ui/button/teal/text. Prism 2.0 has 341 private primitives and 465 public semantic tokens named for their role: bg/primary/default, bg/primary/hover, fg/primary. An agent that has seen one can guess the next, and nothing needs renaming when a client theme changes the hue. Primitives are never emitted as CSS, so reaching for color/blue/600 gets nothing and the checker flags it.

  Trade-off

  101 tokens had to be renamed in Figma partway through, and the repo re-aligned with them.

• Decision 03

  One file teaches an agent the system

  Give agents one thing to read first, and check that it's true

  design.md is the file an agent reads at the start of every session. It holds the design guidance, a priority order, the three-plane depth model, 16 anti-patterns, a 10-point checklist and every token and component name, in about 8,000 tokens. Values are left out to keep it small. A test confirms every name in it exists, and an MCP server with six read-only tools answers the questions an agent would otherwise guess at.

  Trade-off

  The name check caught the file itself telling agents to use a variable the regrid had renamed. Prose goes stale the same way code does.

• Decision 04

  Device size is one attribute

  Set the device once, and let every token resolve for it

  Size variants, Xs to Lg, set importance within a screen. Device modes set the size for the device: Desktop, Touch, Kiosk and Mobile, on one attribute. An agent writes a component once and Prism sizes it for each device, so a kiosk-sized region can sit inside a desktop layout. Keeping the two separate meant no extra sizes like 2Xs and 3Xl.

  Trade-off

  Font size and line height scale at different rates across modes, so 43 typography pairings drift outside Desktop. The corrected values are generated; four new line-height primitives are still needed in Figma.

• Decision 05

  Accessibility as data

  Write the requirement once, in the repo, and copy it everywhere

  Every one of the 100 components carries an accessibility block: 14 keys in a fixed order, from role and name through state, focus, target size and reduced motion. That is 783 facts across 30 success criteria, kept in one repo-owned file and swept into every Figma component description, the generated docs and the contract JSON. A fix made once reaches every screen using that component.

  Trade-off

  A contrast defect on form-control borders is open on 22 components. Darkening the stroke made every pairing pass and looked wrong, so it was reverted and allowlisted with an expiry date.

• Decision 06

  Zero errors is the floor, not the bar

  Check output automatically, and review quality separately

  An output checker runs 11 rules over anything an agent produces: unknown tokens, literal colours, raw px values, hardcoded durations, fallbacks on Prism tokens. Prism's own code passes every rule, and on a sample prototype the new checker finds 71 issues where the old one found 28. Passing doesn't mean a screen is well designed, so a separate blind review scores quality against six scenarios and 40 complaint tags.

  Trade-off

  The review store has no results yet. The first real A/B reviews come from the pilot project.

Xs

24 · 36 · 56 · 32

Sm

32 · 48 · 72 · 40

Md

40 · 64 · 96 · 48, the default

Lg

48 · 96 · 144 · 56

Radius

1× · 1.5× · 2.25× · 1.25× on the same ramp, so corners and borders scale with the control

Learn the system at session start

1.0: no machine-readable entry point; a hand-written steering file described an older version. 2.0: design.md, the rules plus the complete vocabulary, in about 8,000 tokens.

Pick a colour for a primary button

1.0: choose among hue-named, component-scoped tokens, a raw primitive, or a hex. 2.0: one role token. Primitives aren't reachable.

Know the hover and disabled states

1.0: look at the picture; seven of nine button sets had no description. 2.0: get_component_parts returns the bindings per part, per state.

Make it accessible

1.0: general knowledge. 2.0: the variant-to-ARIA mapping, keys, focus and target size for this exact component.

Support a kiosk

1.0: separate kiosk typography modes, and the controls didn't follow. 2.0: set one attribute. Every token resolves for the device.

Know it got it right

1.0: wait for a designer's review. 2.0: run the checker. CI runs it too.

Token drift

A Figma variable changed without a release. Clean.

Name drift

A CSS name that no longer matches Figma's code syntax. 465 of 465 match. Clean.

API drift

A Figma variant with no code prop, or the reverse. Clean.

A11y

Contract violations and malformed A11Y blocks. 6 of 8 invariants run.

Code Connect

A shipped component with no template, or a template binding a prop that doesn't exist. Clean.

State visuals

2,338 state rows across 1,766 parts. Failing: 66 component sets, the app-shell templates and documentation utilities, aren't in the inventory yet.

Typography

Leading ratio broken by a density change. Failing: 43 drifts, with the 37 corrected values already emitted by the gate.

Output rules

11 rules over Prism's own code, and 8 fixtures proving each rule fires. Clean.

Ark pin

The installed Ark UI differs from the version the accessibility facts were written against. Clean.

Allowlist

Accepted exceptions past their expiry date. Clean.

The Figma API

Native timing and easing variables are read-only to plugins, so every motion change routes through the Figma agent from a written spec. Writing descriptionMarkdown wipes the description. The setter HTML-escapes and the getter doesn't unescape, so one description reached ". Cloning a variant silently drops its property references, which broke 48 variants across Button and Icon Button until a screenshot showed a missing icon. We now test what the API actually does and check every change in a separate step.

Values that only worked on Desktop

Pin input borrowed a spacing token for its cell and a control token for its slot. They coincide at Desktop and diverge by 2x at Touch, so the active cell looked enormous. Radius and border tokens had four mode values, and only Kiosk had been filled in. Checks now compare related tokens with each other, and components get their own size tokens when they need them.

Hand-written docs went stale

The Foundations pages said 87 component sets when there were 97, and a Color page claimed zero contrast failures while the audit found four. The repo's own exports once missed about 130 live variables, so an agent reading them saw a smaller system and could conclude a token didn't exist. Counts are generated by the build now.

Style Dictionary didn't work for Prism

Tested at v5.5.2, it rendered duration values as [object Object] and dropped letter-spacing from typography composites. Prism needs both, so we wrote our own generator. It also guarantees CSS names match Figma exactly.

Misleading browser measurements

Sampling a colour right after switching theme returns the mid-transition value, so the component looks like it isn't switching. A focus-ring check measured nothing, because the test's focus call never engaged :focus-visible. Ark's hidden attribute loses to any part rule that sets display, so Checkbox painted its check and its indeterminate dash on top of each other. We turn off transitions before measuring, use real key presses, and count visible elements in the page.

Design judgment versus a contrast target

Darkening border/control made all four contrast pairings pass, and it looked wrong. It was reverted the same day, with the history kept as a decision. In another case a hand-picked value met 3:1 while evenly spaced values only reached 2.96:1. When a token must meet a contrast target, we now set that value first and adjust the neighbouring values around it.