# Your naming convention is an API now

> Names used to be craft. Now they're the query surface.

Published 2026-08-07.

For most of design systems history, naming conventions were an internal virtue. Good names made the Figma file navigable and the code review pleasant. Bad names cost you some onboarding time and an occasional Slack argument. Either way, the stakes were comfort.

Then the consumer changed. An AI agent working against your design system doesn't browse it the way a human does; it queries it. It reads token names, component names, prop names, and file paths, and it infers structure, meaning, and intent from them. Every name is now an endpoint. Your naming convention, the thing that used to be craft pride, is functionally an API contract, and it's being called thousands of times a day by a consumer that never asks clarifying questions.

color.foreground tells an agent something gray.950 never will. The first name carries a role: this is what sits in front, whatever the theme does. The second carries a position on a lightness ramp and nothing else. A human reading gray.950 in context fills the gap instantly. An agent fills it from the average of the internet, which is to say, from everyone else's design system instead of yours.

This reframe has teeth. Run your names through it and patterns that felt fine start looking like bugs.

Cleverness is a bug. The palette named after painters, the spacing scale named after coffee sizes: charming for humans, noise for a machine trying to infer a system. Whimsy doesn't compress into a rule.

Inconsistency is a bug. btn-primary here, buttonSecondary there, ButtonTertiary in the new package. A human sees three eras of your codebase and forgives. An agent sees three naming systems and guesses which applies. Wrong a third of the time isn't a style problem, it's a defect rate.

Ambiguity is a bug. What does color.gray.medium apply to? Text? Borders? Disabled icons? If the name doesn't say, the answer lives in tribal memory, and agents don't attend your standups.

The test I use is one sentence: could an agent predict your next token's name from your last twenty? If yes, your convention is a real grammar: subject, role, modifier, state, in a stable order, with a closed vocabulary. If no, what you have is a pile of precedents. A grammar generalizes; precedents just accumulate.

Building the grammar isn't exotic. Decide the axes that matter (category, role, variant, state), fix their order, and close the word list: one word for each concept, no synonyms. If disabled is the word, muted and inactive are banned. Write the pattern down in ten lines at the top of the token file, because that paragraph is itself machine-readable context: an agent that reads the rule applies the rule. Then enforce it the boring way, with a linter in CI, because a naming convention that lives on goodwill is one sprint from decay.

Two objections worth answering. "This makes names boring." Yes. That's the feature. Boring is what predictable looks like from the inside; save the poetry for the product, not the plumbing. "We'd have to rename half our system." Probably not: rename at the semantic layer, alias the old names during a deprecation window, and let the compile step keep shipping stable outputs while sources clean up. The renovation is calmer than it sounds.

Here's the compounding part. Names are the cheapest layer of machine-readable meaning you own. Before MCP servers, before spec pipelines, before any new infrastructure, a coherent naming grammar upgrades every single interaction an agent has with your system, because names are in everything: the tokens, the props, the file tree, the docs. It's the layer with no procurement cost and no platform dependency. Just discipline.

Craft was the era when good names made colleagues happy. This is the era when good names make your system legible to the things building on top of it. Same skill. Bigger blast radius.

The free starter kit at tokenstoagents.ai/kit includes the naming-grammar worksheet: axes, word list, and the ten-line rule block to paste into your token file.