Design a Tailwind token governance model mapping design decisions, linting rules, and…
- User
Design a Tailwind token governance model mapping design decisions, linting rules, and compiler tweaks.
Assistant
The user wants a "Tailwind token governance model" that maps three specific things:
- Design Decisions: The high-level visual language (colors, spacing, typography, etc.).
- Linting Rules: How code quality and consistency are enforced (ESLint, Stylelint).
- Compiler Tweaks: How Tailwind processes the CSS (PostCSS, configuration).
This is essentially a request for a system design or architecture document for managing Design Tokens within a Tailwind CSS ecosystem, bridging the gap between design tools (Figma) and code, and ensuring consistency through automation.
Target Audience: Developers, Design System Engineers, and perhaps Technical Product Managers. Goal: Create a structured approach to defining, implementing, and governing tokens.
Key Components of the Model:
- The Core: The Token Source of Truth. Where do the values live? (JSON, YAML, Figma Tokens plugin).
- The Transformation Layer (Compiler/Build Time): How do raw tokens become CSS variables or Tailwind config?
- The Application Layer (Tailwind Config): How does Tailwind consume these?
- The Enforcement Layer (Linting): How do we stop people from using arbitrary values or hard-coded hex codes?
- The Governance Process: Who changes what and when?
Drafting the Structure:
-
Phase 1: The Taxonomy (Design Decisions)
- Need to categorize tokens: Primitive (Global) vs. Semantic (Alias) vs. Component.
- Example:
blue-500(Primitive) vs.primary-button-bg(Semantic).
-
Phase 2: The Pipeline (Compiler Tweaks)
- This is where the magic happens.
- Tools:
style-dictionaryortoken-transformer. - Output: Needs to feed into
tailwind.config.js. - Compiler Tweak: Using CSS variables (custom properties) instead of static values in the config to allow for theming and dark mode without re-compiling.
-
Phase 3: The Guardrails (Linting Rules)
- This is crucial for "Governance."
- Rule 1: Ban arbitrary values (e.g.,
top-[123px]). - Rule 2: Ban hard-coded colors in CSS.
- Rule 3: Enforce specific naming conventions.
-
Phase 4: The Matrix (Mapping)
- I need to visualize how a decision in Figma maps to a config in Tailwind, a rule in ESLint, and a variable in CSS.
Refining the Content:
- Design Decisions: Let's use a concrete example. A design system usually has a scale (spacing 0-20) and semantics (padding-xs).
- Compiler Tweaks: Mention
theme()function vs CSS variables. The modern way is generating CSS variables via Tailwind'saddUtilitiesor just defining them in:rootand referencing them in the config. - Linting:
eslint-plugin-tailwindcssis the standard here.
Structuring the Output:
I will organize this into a "Governance Matrix" model. It will look like a system architecture diagram but described in text/markdown.
- Visualizing the Model: A conceptual overview.
- Layer 1: The Source of Truth (Design Decisions): Token taxonomy.
- Layer 2: The Transformation Engine (Compiler Tweaks): The automated pipeline.
- Layer 3: The Enforcement Agency (Linting Rules): Code quality gates.
- Layer 4: The Governance Lifecycle: The human process (PRs, versioning).
- Concrete Example: A walkthrough of changing a primary color.
Self-Correction/Critique during drafting:
- Initial thought: Just list config settings.
- Correction: The prompt asks for a governance model. That implies process and enforcement, not just configuration. I need to emphasize how decisions are enforced.
- Refining "Compiler Tweaks": It's not just Tailwind config. It's about how the config is generated. Using Style Dictionary to generate the Tailwind config is a "best practice" for governance.
Final Polish: Use tables to make the mappings clear. Use code blocks for examples of the config and linting rules. Ensure the tone is professional and architectural.
Let's build the response.
- Title: The T3 Governance Model (Tokens, Tailwind, Testing).
- Core concept: Tokens as inputs, Tailwind as the API, Linting as the Policy.
Detailed breakdown of the "Compiler Tweaks" section: Instead of hardcoding values in
tailwind.config.js, we should use a script that readstokens.jsonand generates the config. Or better, use CSS variables for everything so Tailwind acts merely as a utility generator for syntax, while the values remain dynamic.- Tweak: JIT engine configuration (separator changes, prefixing).
- Tweak: Content glob (preventing unused styles vs. safelisting).
Detailed breakdown of "Linting":
no-arbitrary-values: Crucial for governance.classnames-order: Hygiene.enforce-shorthand: Performance/Readability.
Let's write it out. This proposal outlines a governance model for Tailwind CSS called the "Semantic Token Pipeline." It treats design tokens not just as variables, but as an enforced contract between Design (Figma), Code (Tailwind Config), and Quality Assurance (Linting).
The model is divided into three distinct layers: Taxonomy (Structure), Enforcement (Linting), and Synthesis (Compilation).
The Governance Model Architecture
1. The Taxonomy Layer: Mapping Design Decisions
To govern design tokens, we must first classify them. We move away from generic names (like
blue-500) toward a Semantic + Component structure.The Decision Map:
Token Category Naming Convention Design Decision Mapping Example Usage Primitive (Global) {namespace}-{scale}Raw palette values (rarely used directly in code). color-blue-500,spacing-4Semantic (Alias) {element}-{property}-{variant}Context-specific meaning. text-primary,bg-danger,border-focusComponent (Composite) {component}-{element}-{state}Specific UI implementation. btn-bg-hover,input-border-errorGovernance Rule: Designers define Primitives. The Design System Team defines Semantics. Product Developers consume Components.
2. The Enforcement Layer: Linting Rules
We use
eslint-plugin-tailwindcssand custom rules to enforce the taxonomy. This prevents "drift" where developers introduce arbitrary values that break the visual system.A. The "No Magic Numbers" Rule (Enforce Token Usage)
Objective: Ban arbitrary values (e.g.,
top-[123px]) and raw colors (e.g.,text-[#ffffff]). Implementation: Disallow any class that uses square brackets, forcing the developer to use a defined token.// .eslintrc.js rules: { 'tailwindcss/no-arbitrary-value': 'error', 'tailwindcss/no-custom-classname': [ 'error', { // Only allow classes defined in the config or whitelist specific patterns whitelist: ['^(hover|focus|active):.*$'] } ] }B. The "Design Hierarchy" Rule (Contextual Validation)
Objective: Prevent layout-breaking tokens in specific contexts. Implementation: Use
eslint-plugin-tailwindcss'sclassnames-orderandno-contradicting-classnames, but add a custom heuristic:- Constraint: Disallow
gap-{n}onflex-colcontainers if specific vertical rhythm rules are strict. - Constraint: Disallow Primitive colors (e.g.,
blue-500) anywhere outside of specific "Brand" components. All other UI must use Semantic tokens (bg-surface,text-on-surface).
// tailwind.config.js > safelist (or lack thereof) // Explicitly avoid safelisting to force tree-shaking and intentionality.C. The "Readability" Rule
Objective: Enforce logical grouping of utility classes for easier code review. Implementation: Enforce consistent sorting: Layout -> Typography -> Visuals -> State.
// prettier.config.js module.exports = { tailwindConfig: './tailwind.config.js', // Forces: flex (Layout) -> text (Typography) -> bg (Visual) -> hover (State) }
3. The Synthesis Layer: Compiler Tweaks
The compiler (
tailwind.config.js) is the bridge between raw design decisions and the resulting CSS. We tweak the compiler to automate governance.A. JIT (Just-In-Time) Constraints
Objective: Prevent the CSS file from ballooning while ensuring backward compatibility. Tweak: Enable JIT mode but strictly configure the
contentarray to prevent accidental class generation from strings in code that aren't actually classes.// tailwind.config.js content: [ './src/**/*.{html,js,ts,jsx,tsx}', // Path governance: Don't scan random config files where strings might be interpreted as classes ],B. Dynamic Token Injection (The Bridge)
Objective: Automate the sync between Design Tools (Figma/Style Dictionary) and Tailwind. Tweak: Instead of hardcoding values in
theme, we import a generated JSON file from the Design System package. This ensures that if a Designer changesbrand-primary, the code breaks if the token isn't updated, rather than silently using an old value.// tailwind.config.js const designTokens = require('@company/design-system/tokens.json'); module.exports = { theme: { extend: { colors: { // Direct mapping: Semantic Name -> Primitive Value ...designTokens.colors.semantic, }, spacing: { // Remapping layout grid to spacing scale ...designTokens.spacing.layout } } } }C. The "Opinionated Prefix" Strategy
Objective: Visually distinguish governed tokens from one-off escapes. Tweak: Use a prefix (e.g.,
ds-) for all design system classes.ds-text-heading(Governed)custom-float-animation(Not governed, allowed in specific modules) This allows governance rules to targetds-*classes specifically in the linter.
The Governance Workflow (Mapping Diagram)
This matrix maps the lifecycle of a design decision to the enforcement mechanism.
Design Decision Governance Phase Linting Rule Compiler Tweak "Update Primary Brand Color" 1. Token Update N/A (Pre-code) tokens.jsonis updated. Compiler reads new value."Use new color in Button" 2. Implementation Developer types text-blue-500. Linter Error: "Use Semantic tokentext-brand."N/A "Fixing the Linter Error" 3. Correction Developer changes to text-brand. Linter: Pass.Compiler injects CSS variable var(--color-brand)."Adding a specific micro-layout" 4. Exception Developer tries gap-[13px]. Linter Error: "Arbitrary value."Developer must add 13pxto config as a valid token or use standardgap-3."Handling Dark Mode" 5. Variant Developer uses dark:bg-brand.Compiler uses mediaorclassstrategy to swap the CSS variable root.Summary of the Token Model
To implement this model, your repository structure should look like this:
/tokens/: JSON files exported from Figma (Source of Truth)./scripts/build-tokens.js: Transforms JSON into CSS Variables and a Tailwind Config object.tailwind.config.js: Consumes the generated config. Sets strictcontentpaths..eslintrc.js: Bans arbitrary values and enforces class ordering.
By treating Tailwind as a rendering engine for tokens rather than a utility-first free-for-all, you maintain governance while retaining developer velocity.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.