{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "19 · 图标 Icon",
  "confidence": "high",
  "slug": "mobile-icon",
  "name": "图标 Icon",
  "semanticTypeCandidates": [
    "icon",
    "glyph"
  ],
  "variantDimensions": [
    {
      "name": "size",
      "values": [
        "small",
        "default",
        "large",
        "xlarge"
      ]
    },
    {
      "name": "tone",
      "values": [
        "default",
        "brand",
        "secondary",
        "danger",
        "success",
        "warning"
      ]
    },
    {
      "name": "spin",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "size": "default",
      "tone": "default",
      "label": "行内图标（继承父级文字色）"
    },
    {
      "size": "large",
      "tone": "brand",
      "label": "主色功能图标"
    },
    {
      "size": "large",
      "tone": "danger",
      "label": "错误 / 警告图标"
    },
    {
      "size": "xlarge",
      "tone": "secondary",
      "label": "空状态大图标"
    },
    {
      "size": "large",
      "tone": "brand",
      "spin": "true",
      "label": "进行中（旋转）"
    }
  ],
  "anatomy": {
    "icon": "根元素，一个固定边长的内联盒子，负责尺寸与颜色",
    "glyph": "字形节点，纯符号或内联 SVG，不带语义",
    "label": "可选的无障碍名称，有值时图标成为「有语义的图」，无值时对读屏隐藏",
    "size": "四档边长（small 16 / default 20 / large 24 / xlarge 32）",
    "tone": "颜色来源（继承父级或取语义色）"
  },
  "structurePatterns": {
    "size": "small 16px / default 20px / large 24px / xlarge 32px",
    "tone": "default 继承父级文字色；brand / secondary / danger / success / warning 取语义色",
    "spin": "true 时持续旋转，reduced-motion 下停止",
    "glyph": "内联 SVG（24 网格为默认；253 个图标按 viewBox 例外表渲染），描边宽 1.5"
  },
  "usageHints": [
    "用一个字形表达状态或动作（选中、警告、返回、更多）",
    "图标自身不是热区；可点时由父级按钮提供不小于 44×44 的点击区",
    "图标与相邻文字的间距取 4px（与按钮内图标一致）",
    "spin=true 在 prefers-reduced-motion: reduce 下停止旋转（无障碍硬要求）",
    "同一行内图标与文字基线对齐（vertical-align: -0.125em），避免文字被顶高",
    "name 找不到时渲染默认插槽；既无 name 也无插槽时不渲染，不抛错"
  ],
  "doNotInvent": [
    "图标资源清单（本仓库不引图标字体，字形由各端内置表或内联 SVG 提供）",
    "图标更换 / 过渡动画",
    "点击图标自身触发动作"
  ],
  "unknowns": [
    "业务侧自定义字形的注册方式",
    "图标与文字组合时的推荐最小间距（本实现取 4px）",
    "mp-weixin 目标对 CSS 遮罩（uni-app 端的字形承载方式）的支持程度 —— 本仓库门禁只覆盖静态与编译，不覆盖小程序渲染"
  ],
  "interaction": [
    "图标自身不是热区；可点时由父级按钮提供不小于 44×44 的点击区",
    "图标与相邻文字的间距取 4px（与按钮内图标一致）",
    "spin=true 在 prefers-reduced-motion: reduce 下停止旋转（无障碍硬要求）",
    "同一行内图标与文字基线对齐（vertical-align: -0.125em），避免文字被顶高"
  ],
  "accessibility": [
    "label 有值时 role=\"img\" + aria-label，读屏读出该名称",
    "label 为空时 aria-hidden=\"true\"，纯装饰不进读屏序列",
    "图标不得作为唯一信息载体：颜色变化必须伴随文字或 label",
    "语义色图标与背景的对比度不低于 3:1（WCAG 1.4.11 非文本对比）",
    "内置字形表注入的 SVG 自身带 aria-hidden（语义由根元素的 role / aria-label 承担，避免读屏重复播报）"
  ],
  "glyphSource": {
    "spec": ".design_library/kole-ui/icons/ICON-SPEC.md",
    "injector": "tools/inject-icon-table.mjs",
    "runtime": ".design_library/kole-ui/icons/core.js",
    "note": "各端只保留 KOLE_ICON_TABLE 标记块，内容由注入器填（终态表：别名在注入时已折叠）。数据不手抄，避免 6 端漂移。",
    "legacyNames": [
      "check",
      "close",
      "star",
      "warn",
      "info",
      "arrow",
      "plus",
      "minus",
      "more"
    ]
  },
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "name",
        "type": "string",
        "default": "''",
        "desc": "图标名（kebab-case）；别名已折叠进内置表，直接查即可。空或找不到时渲染默认插槽（规格 §19.2 glyph）",
        "required": false
      },
      {
        "name": "size",
        "type": "'small' | 'default' | 'large' | 'xlarge' | string",
        "default": "'default'",
        "desc": "变体 size：四档边长 16/20/24/32；四档关键字之外的值原样当 CSS 长度（规格 §19.3）",
        "required": false
      },
      {
        "name": "tone",
        "type": "'default' | 'brand' | 'secondary' | 'danger' | 'success' | 'warning'",
        "default": "'default'",
        "desc": "变体 tone：default 继承父级文字色，其余取语义色（规格 §19.3 列四档，图标系统冻结规格 §4.1 扩到六档）",
        "required": false
      },
      {
        "name": "spin",
        "type": "boolean",
        "default": "false",
        "desc": "变体 spin：持续旋转，仅表示「进行中」（规格 §19.4）",
        "required": false
      },
      {
        "name": "label",
        "type": "string",
        "default": "''",
        "desc": "无障碍名称；有值时 role=img，无值时 aria-hidden（规格 §19.6）",
        "required": false
      }
    ],
    "events": [],
    "slots": [
      {
        "name": "default",
        "desc": "自定义字形（内联 SVG 等）；name 未命中内置表时使用（规格 §19.2 glyph）"
      }
    ]
  },
  "variantClasses": {
    "size": {
      "small": [
        ".kole-m-icon--small"
      ],
      "default": [
        "--kole-m-icon-size"
      ],
      "large": [
        ".kole-m-icon--large"
      ],
      "xlarge": [
        ".kole-m-icon--xlarge"
      ]
    },
    "tone": {
      "default": [],
      "brand": [
        ".kole-m-icon--brand"
      ],
      "secondary": [
        ".kole-m-icon--secondary"
      ],
      "danger": [
        ".kole-m-icon--danger"
      ],
      "success": [
        ".kole-m-icon--success"
      ],
      "warning": [
        ".kole-m-icon--warning"
      ]
    },
    "spin": {
      "false": [],
      "true": [
        ".kole-m-icon--spin"
      ]
    }
  },
  "demos": [
    {
      "id": "sizes",
      "group": "01 组件类型",
      "title": "四档尺寸 + 任意值",
      "desc": "small 16 用于标签内，default 20 用于行内，large 24 用于操作区，xlarge 32 用于空状态；四档关键字之外传任意 CSS 长度（写内联 --kole-m-icon-size）。",
      "variant": "size=small | default | large | xlarge | 28px"
    },
    {
      "id": "tone",
      "group": "01 组件类型",
      "title": "语义色",
      "desc": "default 继承父级文字色；brand / secondary / danger / success / warning 取语义色，语义色必须伴随文字说明（不得只靠颜色传意）。",
      "variant": "tone=default | brand | secondary | danger | success | warning"
    },
    {
      "id": "spin",
      "group": "01 组件类型",
      "title": "旋转",
      "desc": "仅用于「进行中」，不代表成功；开启减弱动态效果后自动停止。",
      "variant": "spin=true"
    },
    {
      "id": "inline",
      "group": "02 组件状态",
      "title": "行内跟随文字",
      "desc": "图标默认继承所在文字块的颜色，因此换一行文字就换一种颜色，不需要额外 tone；与文字同基线（vertical-align: -0.125em），间距 4px。",
      "variant": "tone=default（继承）"
    },
    {
      "id": "aria",
      "group": "02 组件状态",
      "title": "无障碍名称",
      "desc": "有 label 时 role=img 会被读屏读出；无 label 时 aria-hidden 跳过，避免读屏念出无意义的符号。",
      "variant": "label='' / label='有设备未授权'"
    },
    {
      "id": "tappable",
      "group": "02 组件状态",
      "title": "可点目标",
      "desc": "图标自身 24px，必须包进 44px 的按钮才是可点目标 —— 点击热区不靠图标撑；图标自身不绑点击，状态由父级按钮的类驱动。",
      "variant": "父级 button（44px）"
    },
    {
      "id": "scenes",
      "group": "03 组合用法",
      "title": "实际场景",
      "desc": "底部标签栏（选中态换色）、单元格右侧箭头、空状态大图标 —— 三种最常见落位，图标都只负责显示。",
      "variant": "TabBar / Cell / 空状态"
    },
    {
      "id": "legacy",
      "group": "03 组合用法",
      "title": "既有 9 名向后兼容",
      "desc": "check / close / star / warn / info / arrow / plus / minus / more 九个历史名字继续可用：warn→warning、info→info-circle、arrow→chevron-right 走别名，其余六个本身就是主名。",
      "variant": "name=9 个历史名"
    },
    {
      "id": "gallery",
      "group": "03 组合用法",
      "title": "图标总览",
      "desc": "按注入的字形表铺满网格（canonical 主名 + 别名折叠后的全部名字），用于检索；网格只读，不承担点击。",
      "variant": "全部注入名"
    }
  ],
  "related": [
    {
      "slug": "mobile-button",
      "why": "图标要触发动作时用按钮（按钮提供 44px 热区与 aria-label）；图标只负责显示"
    },
    {
      "slug": "mobile-badge",
      "why": "需要在图标右上角标数量或红点时用徽标包裹图标；图标本身不承载计数"
    },
    {
      "slug": "mobile-loading",
      "why": "表示「正在加载」这一整体状态（含文案与遮罩）时用加载；图标只提供旋转的视觉"
    }
  ]
}