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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "15 · 步骤条 Steps",
  "slug": "mobile-steps",
  "name": "步骤条 Steps",
  "semanticTypeCandidates": [
    "steps",
    "wizard",
    "progress"
  ],
  "variantDimensions": [
    {
      "name": "direction",
      "values": [
        "horizontal",
        "vertical"
      ]
    },
    {
      "name": "status",
      "values": [
        "wait",
        "process",
        "finish",
        "error"
      ]
    }
  ],
  "representativeVariants": [
    {
      "direction": "horizontal",
      "status": "process",
      "label": "横向（进行中）"
    },
    {
      "direction": "horizontal",
      "status": "finish",
      "label": "横向（已完成）"
    },
    {
      "direction": "horizontal",
      "status": "error",
      "label": "横向（含失败）"
    },
    {
      "direction": "vertical",
      "status": "process",
      "label": "纵向（标题较长）"
    }
  ],
  "anatomy": {
    "steps": "根容器，横向排列",
    "steps__item": "单个步骤",
    "steps__dot": "序号点 / 勾选标记",
    "steps__label": "步骤标题",
    "steps__line": "连接线"
  },
  "structurePatterns": {
    "direction": "horizontal / vertical",
    "status": "wait（未开始）/ process（进行中）/ finish（已完成）/ error"
  },
  "usageHints": [
    "横向展示多步流程的当前进度（如「提交 → 审核 → 完成」）",
    "纯展示组件，步骤本身不可点（这是设计如此，不是缺失）",
    "步骤过多时横向可滚动（容器 overflow-x: auto）",
    "容器 role=\"list\"，每步 role=\"listitem\"",
    "aria-current=\"step\" 标出当前步",
    "状态不只靠颜色（进行中加粗 + 已完成用勾选字符）"
  ],
  "doNotInvent": [
    "步骤之间的动画过渡",
    "点击步骤跳转的规则"
  ],
  "unknowns": [
    "纵向步骤条的推荐间距",
    "标题最多几行"
  ],
  "interaction": [
    "纯展示组件，步骤本身不可点（这是设计如此，不是缺失）",
    "步骤过多时横向可滚动（容器 overflow-x: auto）"
  ],
  "accessibility": [
    "容器 role=\"list\"，每步 role=\"listitem\"",
    "aria-current=\"step\" 标出当前步",
    "状态不只靠颜色（进行中加粗 + 已完成用勾选字符）"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "direction",
        "type": "'horizontal' | 'vertical'",
        "default": "'horizontal'",
        "desc": "变体 direction：横向或纵向排列（规格 §15.3）",
        "required": false
      },
      {
        "name": "steps",
        "type": "Array<{ label, status }>",
        "default": "[]",
        "desc": "步骤数据；status ∈ wait / process / finish / error（规格 §15.3）",
        "required": false
      }
    ],
    "events": [],
    "slots": [
      {
        "name": "default",
        "desc": "额外的自定义步骤（追加在 steps 之后）"
      }
    ]
  },
  "variantClasses": {
    "direction": {
      "horizontal": [],
      "vertical": [
        ".kole-m-steps--vertical"
      ]
    },
    "status": {
      "wait": [],
      "process": [
        ".kole-m-steps__item--process"
      ],
      "finish": [
        ".kole-m-steps__item--finish"
      ],
      "error": [
        ".kole-m-steps__item--error"
      ]
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "横向步骤",
      "desc": "三种状态并列展示：已完成带勾选、进行中加粗并用品牌色实心点。",
      "variant": "direction=horizontal"
    },
    {
      "id": "error",
      "group": "01 组件类型",
      "title": "含失败步骤",
      "desc": "失败步骤用错误色 + 感叹号，状态同时写在文字里 —— 不只靠颜色传达。",
      "variant": "status=error"
    },
    {
      "id": "four-steps",
      "group": "01 组件类型",
      "title": "四步流程",
      "desc": "步骤较多时横向平铺，标题短、点不被挤压。",
      "variant": "direction=horizontal · 4 步"
    },
    {
      "id": "vertical",
      "group": "02 组件状态",
      "title": "纵向步骤",
      "desc": "标题较长时改纵向：连接线变竖线，标题可以换行。",
      "variant": "direction=vertical"
    }
  ],
  "related": [
    {
      "slug": "cell",
      "why": "步骤条展示流程进度；具体每一步的详情入口用单元格列出来"
    },
    {
      "slug": "mobile-tag",
      "why": "单条记录的状态用标签；只有多步流程才用步骤条"
    },
    {
      "slug": "mobile-divider",
      "why": "步骤之间靠连接线表达先后关系，不要用分割线替代"
    }
  ]
}