04 — 토큰 이름 변경 deprecation: alias·warn·codemod

{
  "color": {
    "primary": {
      "$value": "{color.blue.500}",
      "$type": "color",
      "$description": "Primary action color (Buttons, links, focus rings)"
    },
    "brand": {
      "$value": "{color.primary}",
      "$type": "color",
      "$description": "@deprecated Use color.primary instead. Will be removed in v2.0.",
      "$extensions": {
        "com.org.deprecated": {
          "since": "1.5.0",
          "replacement": "color.primary",
          "removeIn": "2.0.0"
        }
      }
    }
  }
}

// packages/panda-preset/src/index.ts
import { definePreset } from '@pandacss/dev';
import tokens from '@org/tokens/panda';
import deprecated from '@org/tokens/deprecated.json';
 
export default definePreset({
  name: '@org/panda-preset',
  theme: {
    extend: {
      tokens: tokens.tokens,
      semanticTokens: {
        colors: {
          ...tokens.semanticTokens.colors,
          // Deprecated alias — warn on read
          ...(process.env.NODE_ENV !== 'production'
            ? wrapDeprecated(deprecated)
            : deprecated),
        },
      },
    },
  },
});
 
function wrapDeprecated(map: Record<string, any>) {
  const out: Record<string, any> = {};
  for (const [name, value] of Object.entries(map)) {
    out[name] = {
      ...value,
      // Panda extension that hooks read
      $extensions: {
        'com.org.warn': () =>
          console.warn(
            `[@org/tokens] color.${name} is deprecated. ` +
            `Use color.${value.$extensions['com.org.deprecated'].replacement} instead. ` +
            `Will be removed in ${value.$extensions['com.org.deprecated'].removeIn}.`
          ),
      },
    };
  }
  return out;
}

// packages/tailwind-preset/src/index.ts
import type { Config } from 'tailwindcss';
import tokens from '@org/tokens/tailwind';
 
const deprecatedColors = new Set(['brand']);
 
export default {
  theme: {
    extend: {
      colors: new Proxy(tokens.colors, {
        get(target, prop: string) {
          if (deprecatedColors.has(prop) && process.env.NODE_ENV !== 'production') {
            console.warn(
              `[@org/tailwind-preset] colors.${prop} is deprecated. ` +
              `Use colors.primary instead.`
            );
          }
          return target[prop];
        },
      }),
    },
  },
} satisfies Partial<Config>;

// .eslintrc.cjs (사용자 측이 깔 수 있음)
module.exports = {
  rules: {
    'no-restricted-syntax': [
      'warn',
      {
        selector: 'Literal[value=/^(bg|text|border)-brand-/]',
        message: 'colors.brand is deprecated. Use colors.primary.',
      },
    ],
  },
};

import type { Transform } from 'jscodeshift';
 
const RENAME_MAP: Record<string, string> = {
  'color.brand': 'color.primary',
  'colors.brand': 'colors.primary',
  '--color-brand': '--color-primary',
};
 
const TAILWIND_CLASS_MAP: Record<string, string> = {
  'bg-brand': 'bg-primary',
  'text-brand': 'text-primary',
  'border-brand': 'border-primary',
};
 
const transform: Transform = (file, api) => {
  const j = api.jscodeshift;
  const root = j(file.source);
 
  // 1) String literals — Panda recipe, CSS-in-JS
  root.find(j.Literal).forEach((path) => {
    const value = path.node.value;
    if (typeof value !== 'string') return;
 
    // "color.brand" 같은 토큰 reference
    for (const [from, to] of Object.entries(RENAME_MAP)) {
      if (value === from || value.includes(from)) {
        path.node.value = value.replaceAll(from, to);
      }
    }
 
    // Tailwind class — "bg-brand-500" → "bg-primary-500"
    for (const [from, to] of Object.entries(TAILWIND_CLASS_MAP)) {
      const regex = new RegExp(`\\b${from}-(\\d+)\\b`, 'g');
      path.node.value = (value as string).replace(
        regex,
        (_, num) => `${to}-${num}`,
      );
    }
  });
 
  // 2) Template literals — `bg-brand-${shade}`
  root.find(j.TemplateLiteral).forEach((path) => {
    path.node.quasis.forEach((q) => {
      for (const [from, to] of Object.entries(TAILWIND_CLASS_MAP)) {
        q.value.raw = q.value.raw.replaceAll(from, to);
        q.value.cooked = q.value.cooked?.replaceAll(from, to);
      }
    });
  });
 
  return root.toSource({ quote: 'single' });
};
 
export default transform;

# 한 번에 마이그레이션
pnpm dlx @org/codemods v2/rename-brand-to-primary "src/**/*.{ts,tsx,css}"

#!/usr/bin/env node
import { run as jscodeshift } from 'jscodeshift/src/Runner';
import { resolve } from 'node:path';
 
const [, , transformName, ...paths] = process.argv;
const transformPath = resolve(
  __dirname,
  `transforms/${transformName}.js`,
);
 
jscodeshift(transformPath, paths, {
  parser: 'tsx',
  extensions: 'ts,tsx,js,jsx,css',
  verbose: 1,
});

{
  "name": "@org/codemods",
  "bin": "./dist/bin.js",
  "scripts": {
    "test": "vitest"
  }
}

packages/codemods/
└── src/v2/rename-brand-to-primary/
    ├── transform.ts
    ├── transform.test.ts
    └── __fixtures__/
        ├── input.tsx
        └── output.tsx

---
"@org/tokens": major
"@org/react": major
---
 
**BREAKING**: `color.brand`를 제거합니다.
 
v1.5에서 deprecated 되었습니다. 마이그레이션:
 
```bash
pnpm dlx @org/codemods v2/rename-brand-to-primary "src/**/*.{ts,tsx,css}"

---

## Figma 측 마이그레이션

토큰은 *디자인 도구에도* 살아 있다. Tokens Studio 또는 Figma Variables의 이름도 같이 옮겨야 한다.

```mermaid
sequenceDiagram
    participant FE as Figma 디자이너
    participant TS as Tokens Studio
    participant GH as GitHub (tokens)
    participant SD as Style Dictionary
    participant USER as 사용자 앱

    FE->>TS: brand → primary로 rename
    TS->>GH: push to tokens.json
    GH->>SD: 빌드 트리거
    SD->>GH: dist/ 업데이트 (alias 포함)
    GH->>USER: npm publish v1.5
    Note over USER: alias 유지 → 사용자 코드 안 깨짐