{"record":{"id":"6b1de5e58dfc1bdf","repo":"CherryHQ/cherry-studio","slug":"theme-contract-compatibility-color-token-over","errorCode":null,"errorMessage":"[theme-contract] compatibility color ${token} overlaps the canonical color contract","messagePattern":"\\[theme-contract\\] compatibility color (.+?) overlaps the canonical color contract","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/ui/scripts/validate-theme-contract.ts","lineNumber":335,"sourceCode":"  const shadcnVariables = new Set<string>(SHADCN_VARIABLE_TOKENS)\n  const shadcnVariableNames = new Set<string>(SHADCN_VARIABLE_TOKENS.map((token) => `--${token}`))\n  const productVariableNames = new Set<string>(CHERRY_PRODUCT_VARIABLE_TOKENS.map((token) => `--${token}`))\n  const canonicalColors = new Set<string>([...SHADCN_COLOR_TOKENS, ...CHERRY_PRODUCT_COLOR_TOKENS])\n\n  for (const token of CHERRY_PRODUCT_VARIABLE_TOKENS) {\n    if (shadcnVariables.has(token)) {\n      throw new Error(`[theme-contract] product variable ${token} overlaps the official Shadcn contract`)\n    }\n  }\n\n  for (const token of CHERRY_PRODUCT_COLOR_TOKENS) {\n    if (!productVariables.has(token)) {\n      throw new Error(`[theme-contract] Tailwind product color ${token} is missing from the product contract`)\n    }\n  }\n  for (const token of COMPATIBILITY_COLOR_TOKENS) {\n    if (canonicalColors.has(token)) {\n      throw new Error(`[theme-contract] compatibility color ${token} overlaps the canonical color contract`)\n    }\n  }\n  assertCompatibilityTokensDeclared(\n    'compatibility semantic colors',\n    COMPATIBILITY_SEMANTIC_COLOR_TOKENS,\n    sources.providerColors,\n    'tokens/colors/providers.css'\n  )\n  assertCompatibilityTokensDeclared(\n    'compatibility status colors',\n    COMPATIBILITY_STATUS_COLOR_TOKENS,\n    sources.statusLegacyColors,\n    'tokens/colors/status-legacy.css'\n  )\n\n  const shadcnRootDeclarations = buildDeclarationMap([['shadcn.css', sources.shadcn]], ':root')\n  assertRequiredDeclarations('Shadcn contract in shadcn.css', shadcnRootDeclarations, SHADCN_VARIABLE_TOKENS, '--')\n  for (const declaration of extractDeclarations(sources.shadcn, 'shadcn.css')) {","sourceCodeStart":317,"sourceCodeEnd":353,"githubUrl":"https://github.com/CherryHQ/cherry-studio/blob/726446b54cd69ffe51a276638672f6d95ca0768c/packages/ui/scripts/validate-theme-contract.ts#L317-L353","documentation":"Thrown by validateThemeContractSources when a token in COMPATIBILITY_COLOR_TOKENS (the frozen, shrink-only legacy Tailwind compatibility surface) also appears in the canonical color surface (SHADCN_COLOR_TOKENS or CHERRY_PRODUCT_COLOR_TOKENS). Compatibility tokens are a separate legacy namespace and must not overlap canonical colors, otherwise the same name would mean two different things depending on context.","triggerScenarios":"Adding 'background' (a canonical color) to COMPATIBILITY_SEMANTIC_COLOR_TOKENS; reintroducing a legacy utility name that has since become canonical.","commonSituations":"Reviving an old Tailwind utility class without checking it now collides with a canonical token; growing the compatibility list when it is supposed to shrink only.","solutions":["Pick a distinct compatibility-only name that does not appear in SHADCN_COLOR_TOKENS or CHERRY_PRODUCT_COLOR_TOKENS.","If the canonical role is what you actually want, remove the token from COMPATIBILITY_COLOR_TOKENS and use the canonical color instead.","Re-run `pnpm --filter @cherrystudio/ui theme:check`."],"exampleFix":"// before — theme-contract.ts\nexport const COMPATIBILITY_SEMANTIC_COLOR_TOKENS = ['background', ...] as const\n// 'background' is in SHADCN_COLOR_TOKENS -> collision\n// after — use a compatibility-only name\nexport const COMPATIBILITY_SEMANTIC_COLOR_TOKENS = ['legacy-surface', ...] as const","handlingStrategy":"validation","validationCode":"// Compatibility tokens must not collide with canonical colors.\nconst canonical = new Set([...SHADCN_COLOR_TOKENS, ...CHERRY_PRODUCT_COLOR_TOKENS])\nconst overlap = COMPATIBILITY_COLOR_TOKENS.filter((t) => canonical.has(t))\nif (overlap.length) throw new Error(`compatibility tokens overlap canonical: ${overlap.join(', ')}`)","typeGuard":null,"tryCatchPattern":"try {\n  validateThemeContractSources(sources)\n} catch (error) {\n  if (error instanceof Error && /compatibility color .* overlaps the canonical color contract/.test(error.message)) {\n    console.error(error.message)\n    process.exitCode = 1\n    return\n  }\n  throw error\n}","preventionTips":["Treat COMPATIBILITY_COLOR_TOKENS as shrink-only: prefer removing over adding.","Before adding a compatibility token, verify it is absent from SHADCN_COLOR_TOKENS and CHERRY_PRODUCT_COLOR_TOKENS.","Use a distinct legacy-only name to avoid future canonical collisions."],"tags":["theme-contract","css","build","validation","registry","compatibility"],"backgroundTag":null,"analyzedSha":"726446b54cd69ffe51a276638672f6d95ca0768c","analyzedAt":"2026-08-12T17:30:37.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}