Portable Design Systems Across Any AI
A tutorial by Brian Greenbaum. Featured in the OTF curated resource library.
The Portability Problem
Most developers use multiple AI coding tools: Cursor for daily development, Claude Code for complex refactoring, Lovable for quick prototypes, v0.dev for component generation. Each tool produces slightly different output — different color values, inconsistent spacing, varying component structures.
The result: design inconsistency. A button generated in Cursor looks different from one generated in Claude Code. Your spacing system diverges across tools. Your brand identity gets diluted.
The solution: a portable design system that every AI tool reads and follows. Instead of configuring each tool separately, you define your design language once and carry it everywhere.
Design Tokens as Source of Truth
Design tokens are the foundation of a portable design system.
Define your token taxonomy
Create a structured JSON file defining all design decisions: colors (primary, secondary, neutrals), spacing (4px grid), typography (fonts, sizes, weights), borders, shadows, and animation values. This file is your design system's DNA.
{
"color": {
"primary": { "value": "#5046E5", "hsl": "244 75% 58%" },
"secondary": { "value": "#1A1A2E", "hsl": "240 27% 14%" },
"foreground": { "value": "#F0EDE6", "hsl": "38 30% 92%" },
"muted": { "value": "#A09DAB", "hsl": "253 7% 65%" }
},
"spacing": {
"unit": "4px",
"scale": [0, 4, 8, 12, 16, 24, 32, 48, 64]
},
"typography": {
"heading": { "family": "Space Grotesk", "weight": 700 },
"body": { "family": "DM Sans", "weight": 400 }
}
}Generate CSS variables
Transform tokens into CSS custom properties. This is the universal format that every web-based AI tool understands. Include the tokens in your index.css and reference them throughout your project.
Create a Tailwind config
Map tokens to your tailwind.config.ts. This ensures Tailwind utilities align with your design tokens. All AI-generated code that uses Tailwind classes will automatically use your token values.
Write the conventions document
Create an AGENTS.md that references your tokens and describes how to use them. Include component patterns, spacing rules, and naming conventions. This is what AI tools read to produce consistent output.
Building a Portable System
A truly portable design system has three layers:
Layer 1: Token Definition — The JSON file defining all design values. This is tool-agnostic and human-readable. It's the single source of truth.
Layer 2: Platform Transforms — Scripts that convert tokens into platform-specific formats: CSS variables for web, Swift values for iOS, Kotlin values for Android. Tools like Style Dictionary automate this.
Layer 3: Convention Documents — AGENTS.md, .cursorrules, and similar files that tell AI tools how to use the tokens. These include component patterns, spacing rules, and do's/don'ts.
When you switch between AI tools, you carry all three layers. The tokens ensure visual consistency, the transforms handle platform differences, and the convention documents guide AI behavior.
Tool-Specific Adapters
Cursor: .cursorrules
Include your design token reference, component patterns, and Tailwind conventions. Cursor reads this file with every prompt, ensuring generated code follows your design system.
Claude Code: AGENTS.md
Reference your design tokens JSON, include example components, and describe your CSS variable naming convention. Claude Code reads AGENTS.md automatically from the project root.
Lovable / Bolt.new: Project Description
Include your color palette, font choices, and component examples in the initial project description. These tools use the prompt as their primary context source.
v0.dev: System Prompt
Paste your design token summary and component conventions into v0's system prompt. Include your color palette as hex values and reference specific Tailwind classes.
Maintenance and Evolution
A portable design system is a living artifact. Here's how to maintain it:
Version your tokens: Treat the token JSON like code — version control it, review changes in PRs, and tag releases. When you update a color value, every platform and tool should get the update.
Automate transforms: Use CI/CD to regenerate platform-specific files whenever tokens change. A commit to the token file should automatically update CSS variables, Tailwind config, and convention documents.
Audit regularly: Every month, compare AI-generated output across your tools. If a tool is drifting from your design system, update its adapter (convention document) with more specific instructions.
Document decisions: When you add or change a token, document why. 'Changed primary from #3B82F6 to #5046E5 because the original blue was too similar to competitor X's brand.' This context helps future you (and your AI tools) make consistent decisions.
