aurora-admin/.design_library/kole-ui-mobile/components/mobile-badge.json

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "9 · 徽标 Badge",
  "slug": "mobile-badge",
  "name": "徽标 Badge",
  "semanticTypeCandidates": [
    "badge",
    "indicator",
    "count"
  ],
  "variantDimensions": [
    {
      "name": "shape",
      "values": [
        "dot",
        "number",
        "text"
      ]
    },
    {
      "name": "standalone",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "shape": "number",
      "standalone": "false",
      "label": "数字角标（挂在图标右上角）"
    },
    {
      "shape": "dot",
      "standalone": "false",
      "label": "红点（只表示有新内容）"
    },
    {
      "shape": "text",
      "standalone": "false",
      "label": "短文字角标"
    },
    {
      "shape": "number",
      "standalone": "true",
      "label": "独立使用（不挂靠内容）"
    }
  ],
  "anatomy": {
    "badge": "根元素，可包裹子元素（角标形态）也可独立使用",
    "count": "数字或短文字",
    "dot": "红点形态（无内容）",
    "wrap": "被包裹的内容（图标 / 头像 / 按钮）"
  },
  "structurePatterns": {
    "shape": "dot / number / text",
    "standalone": "false（包裹在子元素上）/ true（独立使用）"
  },
  "usageHints": [
    "在图标或头像右上角标出数量或状态（红点 / 数字 / 短文字）",
    "角标本身不可点（可点的是被包裹的元素）",
    "角标不改变被包裹元素的布局尺寸（绝对定位）",
    "数字角标配 aria-label（如「12 条未读」），否则读屏只读出数字",
    "纯装饰红点 aria-hidden=\"true\""
  ],
  "doNotInvent": [
    "角标内容的动画（出现 / 消失）"
  ],
  "unknowns": [
    "max 的默认取值（本实现取 99）",
    "独立使用时是否需要背景色"
  ],
  "interaction": [
    "角标本身不可点（可点的是被包裹的元素）",
    "角标不改变被包裹元素的布局尺寸（绝对定位）"
  ],
  "accessibility": [
    "数字角标配 aria-label（如「12 条未读」），否则读屏只读出数字",
    "纯装饰红点 aria-hidden=\"true\""
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "shape",
        "type": "'dot' | 'number' | 'text'",
        "default": "'number'",
        "desc": "变体 shape：红点 / 数字 / 短文字（规格 §9.3）",
        "required": false
      },
      {
        "name": "count",
        "type": "number",
        "default": "0",
        "desc": "数字角标的数值；为 0 且未开启 showZero 时整个角标隐藏（规格 §9.4）",
        "required": false
      },
      {
        "name": "max",
        "type": "number",
        "default": "99",
        "desc": "数值上限；超过时显示 max+（规格 §9.4 overflow）",
        "required": false
      },
      {
        "name": "text",
        "type": "string",
        "default": "''",
        "desc": "变体 shape=text 时显示的短文字（规格 §9.3）",
        "required": false
      },
      {
        "name": "standalone",
        "type": "boolean",
        "default": "false",
        "desc": "变体 standalone：独立使用，不挂靠在被包裹内容上（规格 §9.3）",
        "required": false
      },
      {
        "name": "showZero",
        "type": "boolean",
        "default": "false",
        "desc": "数值为 0 时是否仍显示角标（规格 §9.4 hidden）",
        "required": false
      }
    ],
    "events": [],
    "slots": [
      {
        "name": "default",
        "desc": "被包裹的内容（图标 / 头像 / 按钮），standalone=true 时不渲染（规格 §9.2 wrap）"
      }
    ]
  },
  "variantClasses": {
    "shape": {
      "dot": [
        ".kole-m-badge--dot"
      ],
      "number": [],
      "text": [
        ".kole-m-badge--text"
      ]
    },
    "standalone": {
      "false": [],
      "true": [
        ".kole-m-badge--standalone"
      ]
    }
  },
  "demos": [
    {
      "id": "number",
      "group": "01 组件类型",
      "title": "数字角标",
      "desc": "挂在图标右上角，绝对定位不改变图标占位；数值读屏可用 aria-label 补全（如「12 条未读消息」）。",
      "variant": "shape=number"
    },
    {
      "id": "dot",
      "group": "01 组件类型",
      "title": "红点",
      "desc": "只表示「有新内容」不带数量，因此对读屏隐藏（装饰性标记）。",
      "variant": "shape=dot"
    },
    {
      "id": "text",
      "group": "01 组件类型",
      "title": "短文字",
      "desc": "宽度随文字增长，用于「新 / 热 / 限时」这类状态，不是数字计数。",
      "variant": "shape=text"
    },
    {
      "id": "overflow",
      "group": "02 组件状态",
      "title": "超上限",
      "desc": "数值超过 max 时显示 max+（本实现 max 默认 99），避免角标被长数字撑破。",
      "variant": "状态 overflow"
    },
    {
      "id": "standalone",
      "group": "02 组件状态",
      "title": "独立使用",
      "desc": "standalone=true 时不挂靠任何内容，常用于列表标题或段落前。",
      "variant": "standalone=true"
    },
    {
      "id": "hidden",
      "group": "02 组件状态",
      "title": "数值为 0",
      "desc": "未开启 showZero 时为 0 不渲染（is-hidden），图标回到干净状态；右侧为对照。",
      "variant": "状态 hidden"
    }
  ],
  "related": [
    {
      "slug": "tabbar",
      "why": "标签栏项上的未读提示就该用徽标，而不是把数字写进标签文字里"
    },
    {
      "slug": "mobile-tag",
      "why": "标签承载文字语义与关闭动作，徽标只承载计数与红点，两者不要互相替代"
    },
    {
      "slug": "cell",
      "why": "单元格右侧的状态文字用 value 就够了，只有需要强调计数时才叠徽标"
    }
  ]
}