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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "6 · 按钮 Button",
  "slug": "mobile-button",
  "name": "按钮 Button",
  "semanticTypeCandidates": [
    "button",
    "action"
  ],
  "variantDimensions": [
    {
      "name": "type",
      "values": [
        "primary",
        "default",
        "text",
        "danger"
      ]
    },
    {
      "name": "size",
      "values": [
        "large",
        "default",
        "small"
      ]
    },
    {
      "name": "block",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "type": "primary",
      "size": "large",
      "label": "主按钮（移动端默认档）"
    },
    {
      "type": "default",
      "size": "default",
      "label": "次按钮"
    },
    {
      "type": "text",
      "size": "default",
      "label": "文字按钮"
    },
    {
      "type": "danger",
      "size": "large",
      "label": "危险按钮"
    }
  ],
  "anatomy": {
    "button": "根元素，用原生 button，圆角取令牌",
    "label": "按钮文字，单行不换行",
    "icon": "可选图标或加载指示器，与文字间距 4px",
    "block": "可选块级形态，撑满容器宽度"
  },
  "structurePatterns": {
    "type": "primary / default / text / danger",
    "size": "large（44px 高，移动端默认）/ default（36px）/ small（28px）"
  },
  "usageHints": [
    "触发一个即时动作",
    "高度不小于 44px 的档位用于主操作区；小尺寸档只用于行列内联操作",
    "按下反馈用 :active 背景色变化，不做位移缩放（避免长按抖动）",
    "loading 期间重复点击不触发第二次事件",
    "仅有图标时必须给 aria-label"
  ],
  "doNotInvent": [
    "按钮内多行文字的排版规则",
    "长按（long-press）的附加行为"
  ],
  "unknowns": [
    "图标与文字同时存在时的最小宽度",
    "危险按钮是否需要二次确认"
  ],
  "interaction": [
    "高度不小于 44px 的档位用于主操作区；小尺寸档只用于行列内联操作",
    "按下反馈用 :active 背景色变化，不做位移缩放（避免长按抖动）",
    "loading 期间重复点击不触发第二次事件"
  ],
  "accessibility": [
    "使用原生 button，天然可聚焦、可键盘触发",
    "仅有图标时必须给 aria-label",
    "loading 时置 aria-busy=\"true\" 且 disabled（避免重复提交）"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "type",
        "type": "'primary' | 'default' | 'text' | 'danger'",
        "default": "'default'",
        "desc": "变体 type：主次层级靠颜色与边框区分（规格 §6.3）",
        "required": false
      },
      {
        "name": "size",
        "type": "'large' | 'default' | 'small'",
        "default": "'default'",
        "desc": "变体 size；large 为 44px 移动端默认档（规格 §6.3）",
        "required": false
      },
      {
        "name": "block",
        "type": "boolean",
        "default": "false",
        "desc": "块级形态，撑满容器宽度（规格 §6.2）",
        "required": false
      },
      {
        "name": "disabled",
        "type": "boolean",
        "default": "false",
        "desc": "置灰且不响应点击（规格 §6.4）",
        "required": false
      },
      {
        "name": "loading",
        "type": "boolean",
        "default": "false",
        "desc": "显示加载指示器并阻止重复触发（规格 §6.4）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "click",
        "params": "—",
        "desc": "点击时触发（disabled / loading 时不触发）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "按钮文字（规格 §6.2）"
      },
      {
        "name": "icon",
        "desc": "可选图标或加载指示器，与文字间距 4px（规格 §6.2）"
      }
    ]
  },
  "variantClasses": {
    "type": {
      "primary": [
        ".kole-m-btn--primary"
      ],
      "default": [
        ".kole-m-btn--default"
      ],
      "text": [
        ".kole-m-btn--text"
      ],
      "danger": [
        ".kole-m-btn--danger"
      ]
    },
    "size": {
      "large": [
        ".kole-m-btn--large"
      ],
      "default": [],
      "small": [
        ".kole-m-btn--small"
      ]
    },
    "block": {
      "false": [],
      "true": [
        ".is-block"
      ]
    }
  },
  "demos": [
    {
      "id": "primary",
      "group": "01 组件类型",
      "title": "主按钮",
      "desc": "一个区域里只放一个主按钮；移动端默认用 large 档（44px 高）。",
      "variant": "type=primary / size=large"
    },
    {
      "id": "default",
      "group": "01 组件类型",
      "title": "次按钮",
      "desc": "白底描边，与主按钮并排时表示次要动作。",
      "variant": "type=default"
    },
    {
      "id": "text",
      "group": "01 组件类型",
      "title": "文字按钮",
      "desc": "无背景无边框，用于弱操作（如「跳过」「查看详情」）。",
      "variant": "type=text"
    },
    {
      "id": "danger",
      "group": "01 组件类型",
      "title": "危险按钮",
      "desc": "删除类动作用错误色；不要和主按钮同屏并列出现两次。",
      "variant": "type=danger"
    },
    {
      "id": "sizes",
      "group": "02 组件状态",
      "title": "三档尺寸",
      "desc": "large 44px 给主操作区，default 36px 给表单，small 28px 只用于行列内联。",
      "variant": "size=small | default | large"
    },
    {
      "id": "disabled",
      "group": "02 组件状态",
      "title": "禁用",
      "desc": "置灰且不响应；禁用原因要写在按钮附近，别只靠置灰暗示。",
      "variant": "disabled=true"
    },
    {
      "id": "loading",
      "group": "02 组件状态",
      "title": "加载中",
      "desc": "显示指示器并置 aria-busy，重复点击不再触发（点按钮切换）。",
      "variant": "loading=true"
    }
  ],
  "related": [
    {
      "slug": "actionsheet",
      "why": "需要从一个入口提供多个操作时用动作面板；单个即时动作才用按钮"
    },
    {
      "slug": "cell",
      "why": "整行进入下级用单元格；单个动作才用按钮"
    }
  ]
}