Documentation et gouvernance des jetons

Why Token Governance Matters

Establishing a Naming Convention

/*
  Naming convention: --{category}-{role}-{variant}

  Categories: color, spacing, font, radius, shadow, motion
  Roles: action, surface, text, border, feedback
  Variants: primary, secondary, muted, inverse, hover, active, disabled

  Examples:
  --color-action-primary
  --color-action-primary-hover
  --color-feedback-error
  --color-surface-overlay
  --spacing-layout-section
  --font-heading-weight
*/

Token Categories and Taxonomy

// tokens/taxonomy.js
const TOKEN_CATEGORIES = {
  color: ['brand', 'neutral', 'feedback', 'surface', 'text'],
  typography: ['family', 'size', 'weight', 'lineHeight', 'tracking'],
  spacing: ['layout', 'component', 'inset'],
  shape: ['radius'],
  elevation: ['shadow'],
  motion: ['duration', 'easing']
};

// Validate a new token name
function validateTokenName(name) {
  const [cat] = name.split('-');
  return Object.keys(TOKEN_CATEGORIES).includes(cat);
}

Writing Token Documentation

// tokens/documented.js
module.exports = {
  'color-action-primary': {
    value: '#3b82f6',
    description: 'Primary interactive action color. Use for buttons, links, and focus rings.',
    usage: ['bg-action-primary', 'text-action-primary', 'border-action-primary'],
    doNot: 'Do not use for decorative elements. Use color-brand-accent instead.'
  },
  'color-feedback-error': {
    value: '#dc2626',
    description: 'Error state color. Use for validation messages and destructive actions.',
    usage: ['text-feedback-error', 'border-feedback-error'],
    doNot: 'Do not use for warnings. Use color-feedback-warning instead.'
  }
};

Change Control Process

/* Deprecation example: renaming a token */

/*
  DEPRECATED: --color-primary is deprecated.
  Use --color-action-primary instead.
  Will be removed in v3.0 (target: 2026-09-01)
*/
:root {
  --color-primary: var(--color-action-primary); /* alias */
  --color-action-primary: #3b82f6;              /* canonical */
}

/* Linting rule to warn on deprecated token usage */

Linting Token Usage

// .eslintrc.js
module.exports = {
  plugins: ['tailwindcss'],
  rules: {
    'tailwindcss/no-arbitrary-value': 'warn',
    'tailwindcss/classnames-order': 'warn',
    'tailwindcss/no-contradicting-classname': 'error'
  }
};

// .stylelintrc.json
{
  "rules": {
    "color-no-hex": [true, {
      "message": "Use a CSS variable token instead of a raw hex value"
    }]
  }
}

Token Versioning Strategy

// tokens/CHANGELOG.md
/*
  ## v2.1.0 — 2026-06-15
  ### Added
  - color-action-ghost: new ghost button surface color
  - motion-duration-slow: 500ms for large layout transitions

  ## v2.0.0 — 2026-05-01
  ### BREAKING
  - Renamed: --color-primary → --color-action-primary
    Migration: replace all var(--color-primary) with var(--color-action-primary)
  - Removed: --color-accent (unused after brand refresh)
*/

Design-Developer Token Sync

// scripts/sync-tokens.js
// Run after exporting tokens from Figma Token Studio
const figmaTokens = require('./tokens/figma-export.json');

const tailwindColors = {};
Object.entries(figmaTokens.color).forEach(([key, token]) => {
  // Convert Figma token format to Tailwind format
  const cssVarName = '--color-' + key.replace(/\./g, '-');
  tailwindColors[key.replace(/\./g, '-')] =
    'var(' + cssVarName + ')';
});

console.log('Synced', Object.keys(tailwindColors).length, 'color tokens');

Token Governance Roles

/*
  Token Change Request Template (GitHub PR description)

  ## Token Change Request

  **Type**: [ ] Add  [ ] Modify  [ ] Deprecate  [ ] Remove

  **Token name**: color-action-destructive

  **Proposed value**: #dc2626

  **Rationale**: Needed for delete button component.
  Existing danger token is for form validation only.

  **Impact**: 0 existing usages (new token)

  **Design approval**: @designlead
*/

Auditing Token Coverage

// scripts/token-coverage-audit.js
const fs = require('fs');
const glob = require('glob');

const hardcodedColorRegex = /#[0-9a-fA-F]{3,8}|rgb\(|hsl\(/g;
const arbitraryColorRegex = /\[#[0-9a-fA-F]{3,8}\]/g;

const files = glob.sync('src/**/*.{html,jsx,tsx,css}');
let totalViolations = 0;

files.forEach(file => {
  const content = fs.readFileSync(file, 'utf-8');
  const matches = [...(content.match(hardcodedColorRegex) || [])];
  if (matches.length) {
    console.log(file + ':', matches.length, 'violations');
    totalViolations += matches.length;
  }
});

console.log('Total violations:', totalViolations);

Living Documentation With Storybook

// stories/Tokens/ColorPalette.stories.jsx
const SEMANTIC_COLORS = [
  { name: 'Action Primary', cls: 'bg-action-primary', var: '--color-action-primary' },
  { name: 'Feedback Error', cls: 'bg-feedback-error', var: '--color-feedback-error' },
  { name: 'Surface Base', cls: 'bg-surface-base border', var: '--color-surface-base' }
];

export default { title: 'Design Tokens/Colors' };

export const SemanticPalette = () => (
  <div class="grid grid-cols-3 gap-4 p-6">
    {SEMANTIC_COLORS.map(c => (
      <div key={c.name}>
        <div class={c.cls + ' h-16 rounded-lg mb-2'} />
        <p class="text-sm font-medium">{c.name}</p>
        <code class="text-xs text-gray-500">{c.var}</code>
      </div>
    ))}
  </div>
);

Quick Check

Lesson Recap