Intent-Based Naming

Intent-Based Naming is the practice of labeling every token according to the role it plays in the product rather than the visual property it currently holds. text.danger tells the system this value signals an error state. surface.raised tells the system this background sits one layer above the default canvas. space.section.tight tells the system exactly how much breathing room belongs between major content blocks. The name itself becomes the decision. When Figma AI or Claude Design reads the file it no longer measures pixels or guesses context. It reads the map you gave it and follows the rules you actually encoded. This turns your design system from decorative documentation into the source code the machine compiles against in 2026.

It is not creating a semantic layer that still points back to visual primitives like gray.900 or blue.500. Many teams in 2024 congratulated themselves for adding text.primary as an alias while leaving the original visual tokens visible in the same library. The machine sees both and picks whichever matches its training data best. It is not using clever but opaque names that only make sense inside your Slack channels. hero.red or angry.orange might win the design review but they give zero usable information to an AI generator. It is not a one-time find-and-replace job you do before the product launch and then ignore. Without constant governance new tokens creep back into visual naming patterns and the whole system rots again within months.

Shopify Polaris demonstrates the approach done right. Their tokens read like background.critical.subtle, text.success.primary, border.focused.default, and interactive.primary. When Claude Design scans a Polaris file it knows to reach for text.negative any time it needs an error state because the name contains the intent instead of a hue. Material Design 3 follows the same logic with error, error-container, on-error, surface-variant, and primary-fixed. Each name maps to a functional need first and a color second. A concrete counterexample happened at a Series B fintech company in late 2024. Their library used neutral.800 for body text, brand.600 for links, and red.500 for errors with no hierarchy. Figma AI generated checkout flows that cheerfully painted error messages in brand purple because nothing in the structure told it brand.600 was marketing only. After a four-week migration to intent-based names like text.primary, text.negative, action.destructive.fill, and border.error the AI output matched the system on first generation. GitHub Primer adds another data point with fg.default, fg.muted, fg.subtle, and canvas.inset. The AI stops inventing new colors once the names remove all ambiguity. These real systems prove that intent-based naming is not theory. It is the difference between generations that feel on-brand and generations that feel like they were designed by someone who only saw your color palette for thirty seconds.

Use intent-based naming the moment your system will be consumed by AI tools or shared across more than one squad. Deploy it before you connect any 2026 design agent that builds flows from prompts. Roll it out during system audits at companies the size of Atlassian or Shopify where one sloppy token can poison thousands of screens. It becomes mandatory once your brand palette might change because updating a primitive value automatically updates every intent token that references it. Start the work by opening your production file, searching for every raw hex value, and replacing it with a token that describes its job. Do this before you add any new components.

Do not use it during the first two weeks of brand exploration when you are still testing twelve reds against each other. The names will lock in decisions you have not actually made yet. Skip it entirely on one-off landing pages, freelance logo work, or hackathon experiments that ship in 72 hours and never see AI or code. If your team still argues about what counts as a warning versus an error state then fix the product language before you codify it into tokens. Otherwise you will only document confusion at scale.

The payoff is immediate once the machine can read the library. An AI tool given intent-based tokens treats your decisions as law. It stops mixing marketing purple into form errors. It stops inventing hover states that contradict your focus styles. It stops treating every detached one-off as a new rule. The names become self-documenting instructions that travel with every generated component. Teams that adopt this pattern report fewer revision cycles, faster engineering handoff, and design systems that survive brand refreshes instead of fighting them. Implementation requires discipline but no full rebuild. Audit the top ten components, replace hardcoded values, collapse duplicate variants into named properties, then document the naming convention in plain text a prompt engineer can copy into their next request.

Watch what happens when you feed two versions of the same file to Figma AI. The intent-based version produces output that feels like it came from your team. The visual-based version produces confident garbage that looks perfectly polished until you notice every error state is now pink. The difference is not the pixels. The difference is whether the machine received your decisions or had to guess them from colored rectangles.

text.danger beats red.600 every single time the machine has to make a decision.