Design Tokens and AI Context: What DESIGN.md Teaches Us

Most design teams write documentation the way most companies build data pipelines: reactively, incompletely, and optimistically. Then something downstream breaks — an AI coding assistant ignores your brand guidelines, a new developer ships components in the wrong typeface, a Shopee campaign goes live with off-brand button colours — and everyone acts surprised.

Lisa Demchenko’s piece on UX Collective about writing DESIGN.md files for Claude landed differently for me than it probably was intended. It reads as a guide for AI prompt hygiene. What it actually is: an argument for treating your design system as structured, queryable context — the same discipline that separates a functional data warehouse from a folder of spreadsheets with feelings.

Your Design System Is a Schema, Not a Style Guide

Demchenko’s core argument is that a DESIGN.md file should tell the story of your product — not just list hex codes and font names, but explain why decisions were made, what constraints they operate under, and how components relate to each other. Sound familiar? That is exactly what good data schema documentation does.

The parallel matters because it reframes the problem. Most Southeast Asian brand teams treat design documentation as a delivery artefact — something produced at the end of a project and promptly ignored. But if you are asking AI tools like Claude or Cursor to help generate UI components, write CSS, or audit designs for consistency, the quality of that context file is now a direct input to output quality. Garbage in, generic out.

For a regional retailer running storefronts across Lazada, Shopee, and a native app simultaneously, this is not academic. Each platform has its own UI conventions, and the only thing preventing brand entropy at scale is a design context file that is precise enough for a machine — or a new contractor in Ho Chi Minh City — to work from without a two-hour briefing.

Color as Data: The M&M’s Lesson in Intentionality

Rita Kind-Envy’s deep dive into M&M’s colour history on UX Collective is the kind of piece you file under “useful, unexpected.” The short version: M&M’s colour decisions — from the original mix ratios to the 1995 public vote that introduced blue — were never purely aesthetic. They were deliberate manipulations of consumer perception, appetite signalling, and brand differentiation.

What’s useful here is the underlying principle: every colour in your design system is making a claim about your brand’s relationship with your customer. The problem is that most design systems document what colours are used, not what they are doing. A DESIGN.md file forces you to articulate the latter.

This matters acutely in Southeast Asia, where colour carries cultural weight that Western design frameworks routinely underestimate. Red and gold signal prosperity across much of the region but can read as aggressive in specific contexts. White carries mourning associations in several markets. A design system that documents only the hex value — not the intent and the constraints — is a liability waiting to manifest in a campaign.

---

Writing DESIGN.md That Actually Scales Across Platforms

If you are going to build this file properly, the structure needs to survive multi-platform reality. Three things Demchenko’s framework gets right that are worth implementing immediately:

1. State your constraints explicitly. Not just “we use Inter” but “we use Inter because it supports Thai, Vietnamese, and Bahasa Indonesia character sets without fallback degradation.” The constraint is the instruction. An AI tool that understands why a decision was made is far less likely to suggest a swap that breaks your multilingual interface.

2. Document component relationships, not just components. A primary button does not exist in isolation — it exists in relationship to your card component, your modal hierarchy, and your mobile tap-target size standards. On mobile-first markets where 70–80% of e-commerce sessions run on mid-range Android devices, tap targets below 44px are a measurable conversion drag. That relationship needs to be in the file.

3. Version your decisions. Design systems evolve. If your DESIGN.md records that you moved from a rounded to a sharp corner radius in Q3 2025 because user testing showed sharper corners performed better on Shopee product cards, that decision history becomes audit trail and institutional memory simultaneously — especially when your agency partner turns over.

The Real Cost of Undocumented Design Intent

Here is where I will push back gently on how this conversation usually goes in agency circles. The value of a well-written DESIGN.md is not primarily about making AI tools work better. That is a welcome side effect. The real value is that writing it forces your design team to have decisions they have been deferring.

In data work, we see this constantly: teams that cannot document their pipeline logic clearly almost always have pipeline logic that is unclear. The documentation exercise surfaces the ambiguity. Design is no different. If you cannot write a single crisp sentence explaining why your primary CTA is that specific shade of orange — not the adjacent one, that one — you probably do not have a fully formed answer yet.

The discipline of writing for a machine audience (whether that is Claude, a new developer, or a Figma auto-layout rule) is that machines do not tolerate vagueness politely. They either follow instructions literally and produce something wrong, or they fill the gaps with their own assumptions. Either way, you find out what you did not actually decide.

For Southeast Asian teams managing campaigns across six markets and three languages, that ambiguity compounds fast.

---

Where does this leave us? The brands that will build genuine design consistency at scale — across platforms, markets, and AI-assisted workflows — are not the ones with the prettiest Figma files. They are the ones who treated their design system as structured, intentional, queryable context from the start. The question worth sitting with: if you handed your DESIGN.md to Claude today and asked it to build a product page, what would come back?

grzzly works with growth teams across Southeast Asia to build the kind of design and data infrastructure that holds together under pressure — across platforms, markets, and whatever AI workflow comes next. If your design system is more vibe than architecture, we should talk. Let’s talk