{
  "id": "semantic-color",
  "type": "foundation",
  "status": "published",
  "name": {
    "zh": "语义色",
    "en": "Semantic Color Token"
  },
  "aliases": [
    "语义色",
    "语义色 token",
    "角色色",
    "主题色变量",
    "换肤",
    "semantic color",
    "color token"
  ],
  "category": [
    "Color",
    "Foundation"
  ],
  "description": {
    "zh": "按用途而非色相命名的颜色变量：bg、surface、text、muted、accent、danger。组件只认角色，主题切换时在映射层换指向即可，不必改组件。浅色、深色、高对比、品牌皮肤都是同一套角色的不同取值表。",
    "en": "Colour variables named by purpose, not hue: bg, surface, text, muted, accent, danger. Components consume roles only, so a theme switch re-points the mapping layer instead of touching components. Light, dark, high-contrast and brand skins are simply different value tables over the same roles."
  },
  "use_when": [
    {
      "zh": "需要浅色 / 深色双主题或可换肤",
      "en": "Light and dark themes, or skinnable branding, are required"
    },
    {
      "zh": "组件库要跨产品复用，颜色含义必须稳定",
      "en": "A component library ships across products and colour meaning must stay stable"
    },
    {
      "zh": "无障碍要求高对比主题或强制配色",
      "en": "Accessibility demands a high-contrast or forced-colours theme"
    }
  ],
  "avoid_when": [
    {
      "zh": "单页营销稿，颜色即最终视觉，无需抽象",
      "en": "A one-page campaign where the colour is the final visual"
    },
    {
      "zh": "角色名起得比色值还多（--color-card-header-icon-hover）",
      "en": "More role names than actual colours — --color-card-header-icon-hover"
    },
    {
      "zh": "把插画专用色也塞进语义层",
      "en": "Illustration-only colours forced into the semantic layer"
    }
  ],
  "tags": [
    "color",
    "foundation",
    "tokens",
    "theme"
  ],
  "api": [
    ":root",
    "color-scheme",
    "CSS custom properties"
  ],
  "framework_names": [
    {
      "framework": "CSS",
      "name": "color-scheme",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme",
      "note": {
        "zh": "让 UA 控件跟随浅深主题",
        "en": "Lets UA controls follow the theme"
      }
    },
    {
      "framework": "CSS",
      "name": ":root",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/:root"
    },
    {
      "framework": "Tailwind CSS",
      "name": "@theme / dark:",
      "url": "https://tailwindcss.com/docs/dark-mode"
    }
  ],
  "variants": [
    {
      "id": "dual",
      "name": {
        "zh": "浅深双主题",
        "en": "Light / dark dual"
      },
      "note": {
        "zh": "同一角色两套取值，.dark 下整体切换",
        "en": "Two value tables per role, swapped under .dark"
      }
    },
    {
      "id": "high-contrast",
      "name": {
        "zh": "高对比",
        "en": "High contrast"
      },
      "note": {
        "zh": "收紧明度差，边界与文字加强",
        "en": "Tightened lightness gaps, heavier borders and text"
      }
    },
    {
      "id": "brand",
      "name": {
        "zh": "品牌覆盖",
        "en": "Brand override"
      },
      "note": {
        "zh": "只换 accent 与少数角色，其余不动",
        "en": "Swap accent and a few roles; leave the rest alone"
      }
    }
  ],
  "anatomy": [
    "语义名（Token name）",
    "角色值（Role value）",
    "主题映射（Theme mapping）"
  ],
  "related": [
    {
      "id": "color-palette",
      "relation": "used_with"
    },
    {
      "id": "contrast-ratio",
      "relation": "used_with"
    },
    {
      "id": "elevation",
      "relation": "used_with"
    }
  ],
  "demo": {
    "component": "semantic-color",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "sources": [
    {
      "name": "Material Design — Color roles",
      "url": "https://m3.material.io/styles/color/roles"
    },
    {
      "name": "MDN — color-scheme",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme"
    },
    {
      "name": "W3C — CSS Custom Properties",
      "url": "https://www.w3.org/TR/css-variables-1/"
    }
  ],
  "implementation": {
    "css": [
      ":root",
      "color-scheme",
      "--color-bg",
      "--color-surface"
    ],
    "notes": {
      "zh": "分两层：色阶层（--color-primary-500）与角色层（--color-accent: var(--color-primary-600)）。组件只允许引用角色层。深色主题覆盖角色层取值并加 color-scheme: dark，让滚动条与表单控件同步变暗。高对比主题独立一张表，不要在深色表上继续堆 if。强制配色场景再补 forced-colors 适配。",
      "en": "Two layers: the ramp (--color-primary-500) and the role layer (--color-accent: var(--color-primary-600)). Components may only reference roles. The dark theme overrides role values and sets color-scheme: dark so scrollbars and form controls follow. High contrast gets its own table — do not pile conditionals onto the dark one. Add forced-colors handling where the OS palette applies."
    }
  },
  "prompts": {
    "basic": {
      "zh": "建立语义色 Token：用 bg / surface / text / muted / accent / danger 等角色名定义颜色变量，并支持深浅主题。",
      "en": "Define semantic colour tokens — bg, surface, text, muted, accent, danger roles with light and dark themes."
    },
    "design": {
      "zh": "语义色规范：角色层固定为 bg、surface、raised、text、muted、line、accent、danger；浅深主题各一张取值表，组件不感知主题；accent 全局唯一，danger 只用于破坏性操作；所有文字角色对当前底色过 WCAG AA；禁止在组件里出现 #hex。",
      "en": "Semantic colour spec: role layer fixed to bg, surface, raised, text, muted, line, accent, danger. One value table per theme; components stay theme-agnostic. A single global accent; danger reserved for destructive actions. Every text role passes WCAG AA against its background. No #hex inside components."
    },
    "implementation": {
      "zh": "用 CSS 自定义属性实现：:root { --color-bg: #fafaf7; --color-surface: #fff; --color-text: #17150f; --color-accent: var(--color-primary-600); }，.dark { --color-bg: #121210; … } 并设 color-scheme: dark。Tailwind 通过 @theme inline 映射 bg-bg、text-text 等工具类。主题切换只换 class。",
      "en": "Implement with CSS custom properties: :root { --color-bg: #fafaf7; --color-surface: #fff; --color-text: #17150f; --color-accent: var(--color-primary-600); } and .dark { --color-bg: #121210; … } with color-scheme: dark. Map into Tailwind via @theme inline for bg-bg / text-text utilities. Theming is a class swap."
    },
    "agent": {
      "zh": "在当前项目中实现语义色。\n先检查现有组件体系和 Design Token，优先复用当前组件。\n要求：\n- bg / surface / text / muted / accent / danger 角色层\n- 浅深双主题取值表，组件不写死色值\n- 配 color-scheme，组合对比度过 AA\n保持现有项目视觉风格。不要新增不必要依赖。\n尊重 prefers-reduced-motion。\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement semantic colour in the current project.\nInspect the existing component system and design tokens first; reuse what is already there.\nRequirements:\n- A role layer of bg / surface / text / muted / accent / danger\n- Light and dark value tables; components never hard-code colours\n- color-scheme set and pairings pass AA contrast\nKeep the project's existing visual style. Do not add unnecessary dependencies.\nRespect prefers-reduced-motion.\nRun existing project checks when done and list the modified files."
    }
  }
}