The token table that should not have used tokens

Date: 2026-11-08. Context: adding a dark theme to Storybook (commit b13bded).

What happenedCopy Anchor Link

The Storybook "Tokens" page renders a table with TokenTable, a small React component styled with Panda's css(). Its cell border was neutral.900, dark blue, invisible on a dark background. The fix looked trivial. It took four attempts.

1. Add a token. A new border.subtle: "rgb(128 128 128 / 0.35)", translucent so it reads on both backgrounds. tsc and oxlint were happy. The browser ignored it: the border stayed Storybook's.
2. Find out why. Storybook styles docs tables with a selector like .docs table tr td. Panda emits one single-class rule per declaration (.bd-c_border\.subtle). Storybook's selector is more specific and sits outside any @layer, so it wins. Panda's rules never reached the element.
3. Opt out of Storybook's styles with the sb-unstyled class. Now the border was ours, but the text turned black on dark: we had switched off the theme's colors too.
4. color: inherit. No effect. The theme color does not come from the container but from selectors like .docs p and .docs li. Getting readable text back meant re-implementing Storybook's typography, in two color schemes.

Then a step back: remove every Panda style from the table. It is a bare <table> that Storybook colors by itself, in light and dark. Only the color swatch keeps a Panda class, because that is our content.

What we learnedCopy Anchor Link

The table is not a design-system component. It is part of a page owned by another typographic system, Storybook's. The right answer was to not use css() at all. The instinct instead was to add things: a token, an escape class, an inherit. Each one was "almost right" and each one added complexity to the design system to serve a documentation need.

It is the same principle as scoping the CSS reset to .vektos, seen from the other side. The reset rule says: the design system must not restyle the host page. This one says: the design system should not even try to style the host page. It owns its components, nothing else.

What it means for VektosCopy Anchor Link

1. The first move was exactly what an agent would do. Facing a constraint (strictTokens rejecting a raw value), the easy way out was to add a token to the config. Formally fine: the config is where raw values are legal by definition. tsc passes, lint passes, the grader reports zero violations. In substance, the design system was inflated for a one-off. None of the five control layers would catch it.

2. The grader cannot tell "good code" from "token-heavy code". The final table has fewer css() calls than the first version and is better. A grader rewarding token usage would point the wrong way. Ours counts raw values, so on this case it is neutral: zero violations before and after. That is correct, but the temptation to add a "token coverage" metric will come up, and this is the counter-example.

The reverse also shows up here: the swatch uses style={{ background: row.value }}, a raw value that is right (it displays the token's own value). Run the grader on the design system and that is a false positive. There is no way today to mark a raw value as intentional.

3. Cost measures the road, not only the destination. The final code is clean, but it took four iterations. An agent would have spent four rounds of tokens. This is why cost per run is the second metric: two agents reaching the same code are not equivalent if one spent four times as much. It also hints at what good agent context contains: not just "here are the tokens" but also "when not to use css()". The Introduction page has three rules, all about what to do. It lacks one about what not to do.

Follow-upsCopy Anchor Link