{
  "slug": "icon",
  "end": "react",
  "curated": true,
  "summary": "React 端图标组件：name 查表渲染内联 SVG，size/tone/spin 走类名，label 决定它是图片还是装饰。",
  "usage": [
    "入参解构为 { name = '', size = 'default', tone = 'default', spin = false, label = '', color = '', icon = '★', children = null, onClick }，前三个决定外观（Icon.jsx:72-82）。",
    "查表函数 parsePaths(name) 把路径串 'SM…|FM…' 解析成 [{ mode, d }]，返回 null 表示未命中；viewBox 由 viewBoxOf(name) 从数据层取（Icon.jsx:26,57-70）。",
    "className 由数组拼接：基类 kole-icon-icon 加 SIZE_CLASS[size] 与 TONE_CLASS[tone]（不在表内则为空串），spin 为真再加 --spin，最后 filter(Boolean) 去空（Icon.jsx:26-41,86-93）。",
    "尺寸关键字有 small/default/large/xlarge 四档；传非关键字（如 '18px'、数字 18）时不加尺寸类，改写 style.fontSize（数字会被补成 px）（Icon.jsx:27-32,97-100）。",
    "内容优先序是三层：name 命中渲染内联 <svg width=\"1em\">；未命中只认 children；name 为空时用 children，没有 children 才退到 icon 字段的字形字符（Icon.jsx:83-84,106-142）。",
    "onClick 直接挂在根 span 上；示例里图标放在 button 内部时并不依赖它，事件由按钮承担（Icon.jsx:81,145；示例 icon-ex-6）。"
  ],
  "bestPractices": [
    "color 优先于 tone：两者同传时 tone 的类仍会加上但被内联 style.color 覆盖，写一处即可（Icon.jsx:11-13,95-96）。",
    "未命中的 name 不会抛错也不会显示「找不到」图标，只会渲染成空（无 children 且 name 非空时 content 为 null）；排查空白图标时先核对名字是否在 311 名表里（Icon.jsx:110-142）。",
    "label 只影响 a11y 属性，不改变图形；读取同一张图做装饰时务必不传 label，否则读屏器会多念一次（Icon.jsx:77,104）。",
    "数据表 KOLE_ICON_DATA 由 tools/inject-icon-table.mjs 注入，注释明确写「勿手改」；要加图标请改 .design_library/kole-ui/icons/registry.json 后重跑注入（Icon.jsx:18-22）。"
  ],
  "apiCarrier": {
    "kind": "props",
    "note": "React 端 API 是九个 props 加一个 onClick：name/icon 决定图形来源，size/tone/color/spin 决定外观，label 决定无障碍语义，children 是未命中时的内容回退；没有 ref 句柄与具名插槽。",
    "table": [
      {
        "name": "name",
        "type": "string，默认 ''",
        "desc": "图标名（311 名表内查），命中渲染内联 SVG"
      },
      {
        "name": "size",
        "type": "'small' | 'default' | 'large' | 'xlarge' | <CSS 长度>，默认 'default'",
        "desc": "关键字加尺寸类；非关键字写 style.fontSize（数字补 px）"
      },
      {
        "name": "tone",
        "type": "'default' | 'brand' | 'secondary' | 'danger' | 'success' | 'warning'，默认 'default'",
        "desc": "语义色，default 不产生类即继承父级文字色"
      },
      {
        "name": "spin",
        "type": "boolean，默认 false",
        "desc": "为真时加 --spin 类，仅表示进行中"
      },
      {
        "name": "label",
        "type": "string，默认 ''",
        "desc": "无障碍名称；有值输出 role=\"img\" + aria-label，无值输出 aria-hidden"
      },
      {
        "name": "color",
        "type": "string，默认 ''",
        "desc": "任意 CSS 颜色，写内联 style.color，优先于 tone"
      },
      {
        "name": "icon",
        "type": "string，默认 '★'",
        "desc": "历史字段，字形字符；仅在 name 为空且无 children 时使用"
      },
      {
        "name": "children",
        "type": "ReactNode，默认 null",
        "desc": "内容回退：name 未命中时渲染它（不猜图标、不抛错）"
      },
      {
        "name": "onClick",
        "type": "(e) => void",
        "desc": "挂在内层 span 上的点击回调；语义强调用外层按钮承载"
      },
      {
        "name": "kole-icon-icon",
        "type": "className",
        "desc": "根 span 基类名"
      },
      {
        "name": "kole-icon-icon__svg",
        "type": "className",
        "desc": "内联 SVG 的类名"
      },
      {
        "name": "kole-icon-icon__glyph",
        "type": "className",
        "desc": "字形字符容器类名（icon 字段路径）"
      }
    ]
  },
  "a11y": [
    "label 有值时根节点带 role=\"img\" 与 aria-label，读屏器按图片播报名称（示例里的「校验通过」「加载中」）；不传 label 则带 aria-hidden=\"true\"，纯装饰不进序列（Icon.jsx:77,104）。",
    "内联 SVG 固定 aria-hidden=\"true\" 加 focusable=\"false\"，语义只由外层 span 表达，不会双重播报（Icon.jsx:113-120）。",
    "图标不是热区：实际场景里图标放进 <button aria-label=\"新建\">，键盘可达与焦点环由 button 提供（示例 icon-ex-6）。",
    "tone 只改颜色，演示里始终与文字或 label 同时出现，不把颜色当唯一信息通道（Icon.jsx:35-41）。"
  ],
  "resources": [
    {
      "file": "frameworks/Icon.jsx",
      "kind": "React 组件",
      "desc": "Icon.jsx —— React 实现：props 签名、注入数据表、parsePaths/viewBoxOf 与三层内容优先序"
    },
    {
      "file": "frameworks/Icon.css",
      "kind": "样式文件",
      "desc": "Icon.css —— 组件 import 的 .kole-icon-icon 变体类与场景类"
    }
  ],
  "exampleIds": [
    "icon-ex-1",
    "icon-ex-3",
    "icon-ex-4",
    "icon-ex-5",
    "icon-ex-6",
    "icon-ex-7"
  ],
  "notes": [
    "props 解构与默认值：frameworks/Icon.jsx:72-82",
    "parsePaths 与 viewBoxOf：frameworks/Icon.jsx:57-70",
    "类名拼接与 size 双路径：frameworks/Icon.jsx:86-100",
    "内容优先序：frameworks/Icon.jsx:106-142",
    "a11y 分流：frameworks/Icon.jsx:104",
    "数据表注入来源与「勿手改」：frameworks/Icon.jsx:18-22",
    "consumedApi.classes 里出现 className（Icon.jsx:86,114,141,145）是 JSX 属性名而非类名，未进 table。"
  ]
}