Case study · personal rebuild
IDEM: ten faults in a system I would have called working
IDEM is my own design system. A token pipeline that syncs from Figma, builds through Style Dictionary, and emits CSS, JavaScript and JSON for light and dark. Storybook documents it. A site consumes it with no hardcoded values anywhere. It has run for months, and if you had asked me about it I would have said it was in good shape.
What it did not have was the layer above the tokens. Tokens are values. A button is not a value: it has variants, states, a shape, and rules about which value goes where. That knowledge lived in my head and in Figma, and nowhere a script could read it. So I built it. A contract for each component, as data rather than prose. A guardrail that reads the contract. A check that diffs the contract against the Figma file.
The first thing it found was that two token files had never been compiled. Spacing and typography were authored, versioned, and shown in Storybook, and the build emitted no CSS variable for any of them. Every component needing padding, radius or a type size had nothing to reach for. The files were not wrong. Nothing had ever asked them a question, and a file that is never built is never wrong.
The second was mine. I wrote the button's contract carefully, from the token files, and never opened the design. It was wrong in four places. The design draws a pill and I had specified a rounded rectangle, so anything built to my contract was the wrong shape. Every check passed the whole time, because every check compared the contract with the code, and the design was not in the conversation.
The third is the one I think about. A font weight bound to a variable that is in no collection in the file. It resolves to the right number, so the design renders correctly and looks fine. But editing the real token would have done nothing to the button, and no export would ever have listed the variable it actually used. Right value, correct rendering, wrong wiring. Nothing that compares values could find it, because the value was right.
Ten faults in two days. Also: 188 contrast failures in the pages that document the system, because they are styled with hardcoded hex rather than the tokens they teach. And a primary button with no focus state at all, identical to its resting state in both modes, which is a conformance failure sitting in the source everything else is built from.
None of this needed anything clever. It needed something to ask questions the system had never been asked. That is the part worth taking away. A token layer can only be checked against itself: names resolve, modes agree, nothing is hardcoded. All of that was true of IDEM throughout. The component layer is the first thing that has to actually consume the tokens, and consumption is what tests them.
I should be straight about the shape of this. IDEM is greenfield, it is mine, and most of what I found was my own work. That is the argument rather than a caveat. If a system one person designed and maintains, with a real pipeline and real guardrails, hides ten faults until something looks, then a system a team built over three years hides more. The difference is not care. It is that nobody has built the thing that would ask.
If you have tokens and no layer above them, that's where I'd start: a small set of components, at a fixed price.