{
  "id": "contrast-ratio",
  "type": "foundation",
  "status": "published",
  "name": {
    "zh": "对比度",
    "en": "Contrast Ratio"
  },
  "aliases": [
    "对比度",
    "文字对比度",
    "可读性对比",
    "WCAG 对比",
    "看不清",
    "contrast ratio",
    "color contrast"
  ],
  "category": [
    "Color",
    "Foundation"
  ],
  "description": {
    "zh": "前景与背景的亮度比值，衡量文字是否看得清。WCAG 2.1 给出硬性门槛：正文 AA 4.5:1、AAA 7:1，大号文字降到 3:1 与 4.5:1。APCA 按字重与字号给出更贴近感知的建议值。先算比值再选色，不要靠肉眼验收。",
    "en": "The luminance ratio between foreground and background — the measure of whether text can be read. WCAG 2.1 sets hard floors: 4.5:1 for AA body, 7:1 for AAA, dropping to 3:1 and 4.5:1 for large text. APCA refines this by weight and size against perception. Compute the ratio before picking colours; never sign off by eye."
  },
  "use_when": [
    {
      "zh": "正文、标签、按钮文字需要满足无障碍基线",
      "en": "Body copy, labels and button text must meet accessibility floors"
    },
    {
      "zh": "深浅主题切换后需要重新验证文字可读性",
      "en": "Text legibility must be re-verified after a theme switch"
    },
    {
      "zh": "灰阶辅助文字（muted）容易不知不觉掉到 3:1 以下",
      "en": "Greyscale muted text silently drops below 3:1"
    }
  ],
  "avoid_when": [
    {
      "zh": "装饰性大字或纯图形标识（另有非文本对比 3:1 要求）",
      "en": "Decorative display type or pure graphics — non-text contrast rules apply instead"
    },
    {
      "zh": "被禁用的控件文字（WCAG 明确豁免）",
      "en": "Disabled control text — explicitly exempt in WCAG"
    },
    {
      "zh": "把 AAA 当作所有界面的强制标准，导致设计空间过窄",
      "en": "Mandating AAA everywhere and strangling the design space"
    }
  ],
  "tags": [
    "color",
    "foundation",
    "accessibility",
    "readability"
  ],
  "api": [
    "WCAG 2.1",
    "APCA",
    "contrast-ratio()"
  ],
  "framework_names": [
    {
      "framework": "W3C",
      "name": "WCAG 2.1 — Contrast (Minimum)",
      "url": "https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html"
    },
    {
      "framework": "W3C",
      "name": "APCA",
      "url": "https://www.myndex.com/APCA/"
    },
    {
      "framework": "CSS",
      "name": "contrast-ratio()",
      "url": "https://drafts.csswg.org/css-color-5/#contrast-ratio",
      "note": {
        "zh": "颜色 5 草案中的比值函数",
        "en": "The ratio function in CSS Color 5"
      }
    }
  ],
  "variants": [
    {
      "id": "aa-body",
      "name": {
        "zh": "AA 正文",
        "en": "AA body text"
      },
      "note": {
        "zh": "4.5:1，绝大多数界面的默认门槛",
        "en": "4.5:1 — the default floor for most UI"
      }
    },
    {
      "id": "aaa",
      "name": {
        "zh": "AAA 高标",
        "en": "AAA"
      },
      "note": {
        "zh": "7:1，长文与老年用户场景",
        "en": "7:1 — long-form and older audiences"
      }
    },
    {
      "id": "large",
      "name": {
        "zh": "大号文字豁免",
        "en": "Large text exception"
      },
      "note": {
        "zh": "≥24px 或 18.66px 粗体，门槛降到 3:1",
        "en": "≥24px or 18.66px bold drops the floor to 3:1"
      }
    }
  ],
  "anatomy": [
    "前景色（Foreground）",
    "背景色（Background）",
    "对比比值（Ratio）",
    "达标徽章（Pass badges）"
  ],
  "related": [
    {
      "id": "semantic-color",
      "relation": "used_with"
    },
    {
      "id": "color-palette",
      "relation": "used_with"
    },
    {
      "id": "elevation",
      "relation": "used_with"
    }
  ],
  "demo": {
    "component": "contrast-ratio",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "sources": [
    {
      "name": "W3C — Understanding Contrast (Minimum)",
      "url": "https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html"
    },
    {
      "name": "APCA — Advanced Perceptual Contrast Algorithm",
      "url": "https://www.myndex.com/APCA/"
    },
    {
      "name": "WebAIM — Contrast Checker",
      "url": "https://webaim.org/resources/contrastchecker/"
    }
  ],
  "implementation": {
    "css": [
      "color-mix()",
      "oklch()",
      "contrast-ratio()",
      "@media (prefers-contrast: more)"
    ],
    "notes": {
      "zh": "比值算法：先 sRGB 转线性亮度 Y，再 (L1+0.05)/(L2+0.05)。正文锁 4.5:1，大号锁 3:1；辅助文字不要靠降低透明度凑层级，改用 ink-2 色阶。高对比主题用 prefers-contrast: more 或独立角色表。交付前对文字角色两两抽查，尤其是 muted 与 line。",
      "en": "The formula: convert sRGB to linear luminance Y, then (L1+0.05)/(L2+0.05). Lock body text at 4.5:1 and large text at 3:1. Do not fake hierarchy with opacity — use the ink-2 step instead. High-contrast themes come from prefers-contrast: more or a dedicated role table. Spot-check every text role pair before shipping, muted and line especially."
    }
  },
  "prompts": {
    "basic": {
      "zh": "检查界面对比度：保证正文、标题、辅助文字与背景的对比比值达到 WCAG AA。",
      "en": "Check interface contrast — body, headings and captions must meet WCAG AA against their backgrounds."
    },
    "design": {
      "zh": "对比度规范：正文 ≥4.5:1，大号文字（≥24px 或 18.66px 粗体）≥3:1，AAA 场景 7:1 / 4.5:1；边框与图标属非文本对比 ≥3:1；禁用态豁免但需可辨识；高对比主题单独取值表。颜色选择先过比值再进稿。",
      "en": "Contrast spec: body ≥4.5:1; large text (≥24px or 18.66px bold) ≥3:1; AAA targets 7:1 and 4.5:1. Borders and icons need non-text contrast ≥3:1. Disabled states are exempt but must stay recognisable. High contrast uses its own value table. Compute ratios before colours enter the design."
    },
    "implementation": {
      "zh": "实现一个对比度工具函数 relativeLuminance(hex) 与 contrastRatio(a, b)，在 Storybook 或设计系统文档里对每个语义色组合跑断言；CSS 侧用 @media (prefers-contrast: more) 切换高对比角色值。CI 可对 token 表做批量校验，输出不达标的组合清单。",
      "en": "Ship relativeLuminance(hex) and contrastRatio(a, b) helpers and assert every semantic pair in Storybook or the design-system docs. Switch high-contrast role values with @media (prefers-contrast: more). Have CI batch-check the token table and list failing pairs."
    },
    "agent": {
      "zh": "在当前项目中实现对比度。\n先检查现有组件体系和 Design Token，优先复用当前组件。\n要求：\n- 文字组合过 WCAG AA（正文 4.5:1 / 大号 3:1）\n- 提供比值计算与达标判定工具函数\n- 高对比主题走独立角色表或 prefers-contrast\n保持现有项目视觉风格。不要新增不必要依赖。\n尊重 prefers-reduced-motion。\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement contrast ratio in the current project.\nInspect the existing component system and design tokens first; reuse what is already there.\nRequirements:\n- Text pairs pass WCAG AA (4.5:1 body, 3:1 large)\n- Helpers for ratio computation and pass/fail judgement\n- High contrast via its own role table or prefers-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."
    }
  }
}