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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "37 · 排版 Typography",
  "confidence": "high",
  "slug": "mobile-typography",
  "name": "排版 Typography",
  "semanticTypeCandidates": [
    "typography",
    "text",
    "paragraph"
  ],
  "variantDimensions": [
    {
      "name": "level",
      "values": [
        "title",
        "body",
        "assist",
        "secondary"
      ]
    },
    {
      "name": "ellipsis",
      "values": [
        "false",
        "true"
      ]
    },
    {
      "name": "copyable",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "level": "title",
      "label": "标题（17px / 600）"
    },
    {
      "level": "body",
      "label": "正文（16px / 400，移动端基准）"
    },
    {
      "level": "assist",
      "label": "辅助说明（14px / 次级色）"
    },
    {
      "level": "secondary",
      "label": "次要信息（11px / 三级色）"
    }
  ],
  "anatomy": {
    "typography": "根元素，横向承载「文字 + 可选复制按钮」",
    "text": "文字本体，层级、省略、换行都在它身上生效；默认插槽与 text prop 二者取一（text 优先）",
    "copy": "复制按钮（原生 button），仅 copyable=true 时出现；热区 44px，负外边距吸收不撑高行"
  },
  "structurePatterns": {
    "level": "title / body / assist / secondary（字号与字色全部走令牌）",
    "ellipsis": "false 换行 / true 单行省略（省略号在行尾）",
    "copyable": "false 纯展示 / true 右侧出现复制按钮"
  },
  "usageHints": [
    "把一段文字按信息层级（标题 / 正文 / 辅助 / 次要）成套地表达，并可选单行省略与一键复制",
    "移动端正文基准 16px（桌面端 14px），层级只分四级：再细分会让差异小于字号可辨阈值",
    "组件本体是静态的：根与文字节点不带指针语义，也不进键盘序列",
    "复制动作由宿主完成 —— 组件不读系统剪贴板，只回传 copy 事件",
    "省略形态下读屏仍能读到完整文字（text-overflow 只截视觉，不改可访问名）"
  ],
  "doNotInvent": [
    "富文本与 Markdown 渲染（换行、加粗、链接、代码块一律由宿主负责）",
    "多行省略（line-clamp）与「展开全文」交互",
    "字号缩放 / 用户字号偏好档位",
    "复制失败的兜底提示（宿主自行组合轻提示）"
  ],
  "unknowns": [
    "secondary 层级是否应使用 11px（当前取 --kole-m-font-size-caption）而不是 12px",
    "复制按钮在「已复制」态停留多久（当前不自动回退，由宿主控制）",
    "省略态是否需要在长按气泡里显示全文"
  ],
  "interaction": [
    "组件本体是静态的：根与文字节点不带指针语义，也不进键盘序列",
    "唯一的交互元素是复制按钮：热区 44×44px，一次轻点触发 copy 事件",
    "复制动作由宿主完成：组件不读系统剪贴板，组件只回传事件并在宿主置 copied=true 后渲染反馈",
    "ellipsis=true 时只做单行省略：被截断的内容不提供展开入口"
  ],
  "accessibility": [
    "根是普通容器，文字由读屏按文档流朗读；层级只改视觉，不改语义标签",
    "省略形态下读屏仍能读到完整文字",
    "复制按钮是原生 button 且带 aria-label，名称随状态在「复制」与「已复制」之间切换"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "level",
        "type": "'title' | 'body' | 'assist' | 'secondary'",
        "default": "'body'",
        "desc": "变体 level：文字层级（规格 §37.3）",
        "required": false
      },
      {
        "name": "ellipsis",
        "type": "boolean",
        "default": "false",
        "desc": "变体 ellipsis：单行省略，省略号在行尾（规格 §37.3）",
        "required": false
      },
      {
        "name": "copyable",
        "type": "boolean",
        "default": "false",
        "desc": "变体 copyable：右侧出现复制按钮（规格 §37.3）",
        "required": false
      },
      {
        "name": "copyText",
        "type": "string",
        "default": "'复制'",
        "desc": "复制按钮的常态文字，同时作为 aria-label（规格 §37.6）",
        "required": false
      },
      {
        "name": "copiedText",
        "type": "string",
        "default": "'已复制'",
        "desc": "copied=true 时复制按钮的文字（规格 §37.4）",
        "required": false
      },
      {
        "name": "text",
        "type": "string",
        "default": "''",
        "desc": "文字内容；与默认插槽二选一，text 优先（规格 §37.2 text）",
        "required": false
      },
      {
        "name": "copied",
        "type": "boolean",
        "default": "false",
        "desc": "状态 copied：宿主写剪贴板成功后置 true（规格 §37.4）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "copy",
        "params": "—",
        "desc": "点击复制按钮时触发；真正的剪贴板写入由宿主完成（规格 §37.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "文字内容（与 text 二选一；text 优先）"
      }
    ]
  },
  "variantClasses": {
    "level": {
      "title": [
        ".kole-m-typography--title"
      ],
      "body": [
        ".kole-m-typography--body"
      ],
      "assist": [
        ".kole-m-typography--assist"
      ],
      "secondary": [
        ".kole-m-typography--secondary"
      ]
    },
    "ellipsis": {
      "false": [],
      "true": [
        ".kole-m-typography--ellipsis"
      ]
    },
    "copyable": {
      "false": [],
      "true": [
        ".kole-m-typography--copyable"
      ]
    }
  },
  "demos": [
    {
      "id": "levels",
      "group": "01 组件类型",
      "title": "四个层级",
      "desc": "标题 / 正文 / 辅助 / 次要：字号与字色全部走令牌，层级差异一眼可辨而不靠颜色深浅硬撑。",
      "variant": "level=title|body|assist|secondary"
    },
    {
      "id": "paragraph",
      "group": "01 组件类型",
      "title": "段落正文",
      "desc": "默认不省略，长文本按容器宽度换行；行高取 1.5，比桌面端的 1.4 更宽以便手指阅读定位。",
      "variant": "level=body"
    },
    {
      "id": "ellipsis",
      "group": "02 组件状态",
      "title": "单行省略",
      "desc": "ellipsis=true：超宽截断、省略号在行尾；读屏仍能读到完整文字，被截断的内容不提供展开入口。",
      "variant": "ellipsis=true"
    },
    {
      "id": "copyable",
      "group": "02 组件状态",
      "title": "可复制",
      "desc": "copyable=true：复制按钮热区 44px；点一下标记已复制，组件不读剪贴板，写入由宿主完成。",
      "variant": "copyable=true"
    }
  ],
  "related": [
    {
      "slug": "mobile-link",
      "why": "文字需要可点击跳转时用链接，排版只负责层级与省略、不承担点击语义"
    },
    {
      "slug": "mobile-tag",
      "why": "行内状态标记用标签，不要用排版加粗加色来表达状态"
    },
    {
      "slug": "cell",
      "why": "带副标题的两行列表信息用单元格（标题 + 说明一次成组），单个文字层级才用排版"
    }
  ]
}