Kirky-X/maliang

maliang (马良) —— 设计系统技能

脚本调用约定：python3 scripts/… 中的相对路径以本 skill 的安装目录为基准（CWD 假设）。 在用户项目中执行时，一律以 {SKILL_DIR} 绝对路径调用，如 python3 {SKILL_DIR}/scripts/ui-graph.py …；--target/--framework-file 等输入参数显式指向用户项目路径，禁止把 skill 自带的 examples/ 当作分析目标。

十三个子命令覆盖 UIUX 全生命周期(研究→定义→设计→实现→验证→交付→迭代,总图见 references/meta/lifecycle.md):design-md(创建 DESIGN.md,含领域探索与决策账本)→ redesign(改版现有 UI)→ explore(方向未定时多方案发散-比较-收敛)→ draw-md(页面级 UI markdown)· component(单组件 brief)→ preview(预览验证)→ critique(可用性评审)→ draw-harmony/draw-flutter/draw-element(框架代码)→ ui-graph(UI 关系管理)· ip(IP 形象)/ip-handbook(IP 视觉手册)。

• design-md(上游)— 产出 prose-first 的 DESIGN.md(YAML token + Markdown 设计理由,Google Labs agent-first 格式)。支持"创建、应用、验证、导出"四个动作。解决"设计系统是什么、为什么"。
• redesign(上游旁路)— 改版现有 UI,10 维审计(含 SEO 与追踪、产物一致性) + 保留规则。支持 Refresh / Restructure / Rebuild / Deslop 四模式。解决"现有设计如何变好"。
• draw-md(中游)— 从 DESIGN.md 产出页面级硬 token UI markdown(布局章节 + 组件参数表,颜色/字体/间距全引用 token,RGBA + HEX)。解决"每个页面/组件具体怎么实现"。
• preview(验证)— 使用 Element Plus 框架对 draw-md 产出进行实时预览验证,支持 iOS/Android 设备外壳。解决"效果对不对"。
• critique(验证·深评)— Nielsen 10 启发式 0-4 评分 + persona 走查 + 认知负荷清单,产出评分快照/趋势/backlog。解决"好不好用"。UI 合规/a11y 清单读 references/meta/web-interface-guidelines.md; 产品 UI craft 纪律与严格评审/去 slop 深流程见 references/interface-design/（原独立 skill 并入）
• draw-harmony(下游)— 将 draw-md 逻辑 UI 转换为 HarmonyOS(ArkTS)框架实现。解决"HarmonyOS 代码怎么写"。
• draw-flutter(下游)— 将 draw-md 逻辑 UI 转换为 Flutter 框架实现。解决"Flutter 代码怎么写"。
• draw-element(下游)— 将 draw-md 逻辑 UI 转换为 Element Plus 框架实现。解决"Element Plus 代码怎么写"。
• ui-graph(关系管理)— 从 ui-markdown/ 产出 ui-relationships.json(层级 + 跳转) + ui-hash-state.json(哈希基线) + ui-implementation-map.json(逻辑 UI ↔ 实现映射)。解决"页面关系怎么管、变更怎么追、实现缺口在哪"。
• ip(IP 形象)— 基于 DESIGN.md 调性构造 prompt,优先调用 text_to_image API 生成图片,fallback 输出结构化 prompt 文档。解决"项目 IP 形象怎么生"。
• ip-handbook(IP 视觉手册)— 8 模块产出规格(三视图/动作延展/表情包/字体/色彩/版式/周边物料/通用要求),2K 高清 3:4。解决"IP 视觉系统怎么落地"。

子命令路由

🔴 CHECKPOINT:无 DESIGN.md 时,严禁直接进入 draw-md / draw-* 下游子命令 —— 必须先走 design-md 建立设计系统,否则产出的 UI markdown 与框架代码无 token 可引用。

用户意图	子命令	完整流程
创建 / 生成 DESIGN.md(从代码/截图/访谈)	design-md	references/commands/design-md.md
应用 DESIGN.md 到前端代码	design-md	references/commands/design-md.md
lint / diff / 导出 / 验证 DESIGN.md	design-md	references/commands/design-md.md
🔷 改版 / 重设计现有 UI(Refresh/Restructure/Rebuild/Deslop 去AI味)	redesign	references/commands/redesign.md
🔷 方向性微调(bolder 更大胆 / quieter 更安静 / distill 更精炼,保持视觉世界不变,redesign 轻档前置)	redesign	references/commands/redesign.md
🔷 单个组件 brief(做个按钮 / 单个输入框 / toast 等单元素,8 状态硬门)	component	references/commands/component.md
产出页面级 UI markdown(token 表 + 页面规格)	draw-md	references/commands/draw-md.md
跨页面复用组件(导航栏 / dock)规格化	draw-md	references/commands/draw-md.md
🔷 方向未定,先比较多套方案再定稿(布局/密度/人格/交互模型真不同,默认 3 至多 5)	explore	references/commands/explore.md
🔴 预览 UI markdown 效果(设备外壳 + Element)	preview	references/commands/preview.md
🔷 可用性评审 / 评分(Nielsen+persona 走查+认知负荷)	critique	references/commands/critique.md
🔴 将 UI markdown 转换为 HarmonyOS(ArkTS)代码	draw-harmony	references/commands/draw-harmony.md
🔴 将 UI markdown 转换为 Flutter(Dart)代码	draw-flutter	references/commands/draw-flutter.md
🔴 将 UI markdown 转换为 Element Plus(Vue 3)代码	draw-element	references/commands/draw-element.md
🔷 生成 / 查询 UI 关系图(层级 + 跳转 + 哈希 + 实现映射)	ui-graph	references/commands/ui-graph.md
🔷 查询跳转目标未生成 / 异常跳转 / 未实现页面 / 规格↔代码语义漂移(功能缺失/写死值/架构偏离)	ui-graph	references/commands/ui-graph.md
🔷 基于 DESIGN.md 生成 IP 形象(API 优先,fallback prompt)	ip	references/commands/ip.md
🔷 生成 IP 视觉手册(三视图/动作/表情/字体/色彩/版式/周边)	ip-handbook	references/commands/ip-handbook.md

🔴 标记的行需先确认 draw-md 产出存在;preview/draw-* 无 UI markdown 输入时应在子命令流程内 fallback 引导用户回退到 draw-md。用户未指定目标框架时,draw-* 先查用户项目已有前端栈(有 → 跟随该栈并说明假设;无 → 按 framework/INDEX.md「框架选型指南」按场景推荐,经用户确认后再进)。🔷 标记的行属新增能力,critique 需先有 preview 产出或可访问页面,ui-graph 需先有 draw-md 产出,ip/ip-handbook 需先有 DESIGN.md。

进入子命令后,按其流程文档执行。检查点、边界情形、交付核对清单均在各子命令文档内 —— 本路由器不含流程主体。

任务规模分档(轻档 / 全档)

档位	判据	流程
轻档	项目已有 DESIGN.md,且改动范围 = 单组件(component 子命令)或单页局部调整	不重走 design-md 与全页清单流程:直接 draw-md 改目标页(单组件走 component)+ preview 抽查该页/该组件
全档	新项目 / 新页面类型 / 多页改动 / 方向未定(先 explore)/ 无 DESIGN.md	完整链路 design-md → draw-md → preview → draw-*

轻档不是门禁豁免。以下不可裁剪项任何档位完整执行:

1. a11y 检查 — aria-label、触控目标 ≥44px、对比度、prefers-* 偏好(CRITICAL 类,见 references/meta/rules-priority.md 冲突裁决规则 4,不可妥协);
2. preview 硬门禁 — validate-draw-md 检查与 preview 评审 disposition 照常;轻档的「抽查」指只跑改动页,不是跳过或降阈值。唯一例外:用户明说不需要预览时按 preview.md「跳过条件(显式 opt-out)」跳过渲染与评审,validate 检查照跑,交付说明挂 DEGRADED 横幅;
3. draw-md 硬约束(token 引用 / 暗色引用 / 动效 ≤400ms)随改动页逐条过(见 references/commands/draw-md.md 约束汇总)。

无 DESIGN.md 时的轻档请求按「失败模式与 fallback」第一行处理:引导先走 design-md,分档不提供例外。

无人值守与 CHECKPOINT 降级

判据:用户明说「你定 / 直接做」,或会话无人值守(用户缺席、不响应)时,CHECKPOINT 不逐点阻塞。仅当「缺的信息会改变核心方向、且推断不出来」时才集中问一次;改得回来的细节自己决定并说明假设。

CHECKPOINT 类别	无人值守时默认动作
方向 / 提案确认(design-md 0b/0c、explore 方向清单)	按证据与推荐直接推进;explore 仍实体化 3 个方向、三张首屏缩到 480px 并排自选并写明理由;任务明确只要一个方向时不问也不做对比页
提取 / 盘点确认(token 提取、页面清单)	按现场证据取值并标置信(✅/⚠️/❓,写法见 design-md「提取路径置信标记」);清单按默认规则生成
交付前确认(preview / critique 行动确认)	按门禁与证据结果推进,交付说明首行挂降级横幅;preview 跳过不属于自选动作——仅用户明说时按 preview.md「跳过条件(显式 opt-out)」允许,无人值守一律照跑
素材 / API 类确认(ip 等)	API 不可用走既有 fallback;产物按新路径落盘不覆盖

呈现纪律:交付说明首行挂 ⚠️ DEGRADED: unattended（<原因>）(沿用 critique/preview 既有 DEGRADED 形状,不引入第二模式);自选决定与理由逐条写入设计说明;看不了图时写明「未验证实际视觉」、不给视觉打分;没有可运行环境时不说交互已通过。用户回归后按其意见修订,修订走决策回写。

弱 runtime 与跨 agent 降级

与上一节互补:无人值守表管用户缺席轴,本表管运行能力轴(无 subagent / 非主流模型 / 上下文小的 runtime)。

按吃紧程度逐级降级,降级牺牲流程,不牺牲硬约束(a11y 检查、token 引用、G01–G46 CRITICAL 门、真实资产协议不豁免):

1. explore 多方向并行 → 串行:每方向开工前只读 DESIGN.md 契约与自己那张方向卡,不参考已做的方向;
2. 仍吃紧 → 主方向 1 份完整规格 + 其余方向轻量卡(只写方向卡 7 栏 + 首屏骨架),比较页降为方向卡并排;
3. references 只读当前子命令「meta 文档加载时序」的必读列,不全读;
4. draw-md 大批量页面先交 P0 页(见 default-pages),其余页方向确认后分批;
5. 检查点问答改为产出里的 assumption 清单(gate 文件与 CHECKPOINT 降级语义照旧——见上一节,两者共用)。

版本检查

本节让用户知道 maliang skill 有没新版本。确定性逻辑(节流判定 / 版本比较 / 记录)在 scripts/version-check.py,状态文件默认 ~/.maliang/version-check(--state 可改);agent 只跑命令与 git ls-remote。

使用本 skill 时先跑 python3 {SKILL_DIR}/scripts/version-check.py due;输出 skip:* 直接跳过本节。输出 due 时:

1. 运行 git -C {SKILL_DIR} ls-remote --tags --refs --sort=-v:refname origin 'v*',取第一行 tag 传给 python3 {SKILL_DIR}/scripts/version-check.py compare <tag>(--current 缺省读本仓 SKILL.md frontmatter);
2. compare 输出 same(含 tag 不符合 vX.Y.Z 形状——按没有标签处理)就不用提;输出 newer 时先完成用户的任务,结束时告诉用户「maliang 有新版本 vX.Y.Z,更新见 https://github.com/Kirky-X/maliang/releases ,需要时运行 git -C {SKILL_DIR} pull --ff-only;不想再收到提醒,运行 python3 {SKILL_DIR}/scripts/version-check.py record off」;
3. 无论查到什么,以实际结果收尾:python3 {SKILL_DIR}/scripts/version-check.py record ok(查到了)或 record failed(断网/沙箱禁网,7 天后再试)。

是否更新由用户决定,不自动执行更新,不下载任何文件。

meta 文档加载时序(阶段 × 必读)

规范层 references/meta/ 不要求一次全读——按所处阶段加载,规划类工作不加载执行期文档:

阶段(子命令)	动手前必读	按需查阅
design-md(创建系统)	product-reasoning.md、philosophy.md(Phase 1 prose 前必读)、principles.md、ux-laws.md(定律层“为什么”)	token-provenance.md(Phase 0d 决策表 + token 溯源)、dials.md、spec-schema.md、analytics-events.md(埋点事件表)、content-guide.md、templates/README.md(选型四步)、data-floor.md(数据型产品 Phase 0a 必过:绑定表+冷启动台词)、workbench-structures.md(11 结构判定)
redesign(改版)	ai-tells.md、rules-priority.md	dials.md、accessibility.md、surface-modes.md、ux-rules.md
explore(方向未定多方案比较)	dials.md、surface-modes.md、token.md	ai-tells.md(豁免总则)、ux-rules.md、workbench-structures.md(数据型界面发散前判主副结构);开工前 python3 {SKILL_DIR}/scripts/style-ledger.py check(跨项目外观账本,重复底色/字族主动避开,不阻塞)
draw-md(产出页面规格)	token.md、ai-tells.md	surface-modes.md、visual-assets.md、copy-strategy.md(Persuade 页面文案策略)、templates/INDEX.md、ux-rules.md、llm-behavior.md(长产物防截断)、performance.md、alignment.md(对齐轴/同排等高,G44/G45)、workbench-structures.md(步骤 2.7 结构判定)、data-floor.md(步骤 2.7 数据底座绑定表)、app-screen-floor.md(Operate/Data 模式数据屏地板);开工前 python3 {SKILL_DIR}/scripts/style-ledger.py check(跨项目外观账本,不阻塞)
preview(验证交付)	numbered-gates.md(编号门禁 G01–G46,交付与否决层)、ai-tells.md(豁免总则)、performance.md	token-provenance.md(A 组溯源判定留痕)、ux-rules.md、accessibility.md、content-guide.md、hardening.md(生产化加固)
critique(可用性深评)	surface-modes.md、principles.md	accessibility.md、ux-rules.md、day-two-blacklist.md(第四问·定义级 audit)
draw-harmony/flutter/element	performance.md、accessibility.md、polish-craft.md(微雕手艺,多数条目 web-only)	token.md(命名回填)、ux-rules.md
ip / ip-handbook	product-reasoning.md	content-guide.md

元规则:rules-priority.md 与 philosophy.md 是全阶段裁决层,冲突时优先于各阶段文档;lifecycle.md 是全生命周期总图(七段×载体×检查点);theory-router.md 是理论判断辅助层(自动判阶 + 段×理论模型包 + 触发条件 + 复合规则),任何段需要用理论模型推理/归因/说服时按需加载,其详尽层 design-theory-models.md 只按锚点查、不全读;llm-behavior.md 在产出 > 2 屏的长文档时必读。

通用

• 不确定用哪个? 先 design-md。没有 DESIGN.md 就无法产出可靠的 draw-md 硬 token,更无法进行框架适配。
• 完整流程链路(每步产出 = 下步输入): design-md(→.maliang/DESIGN.md) → draw-md(→.maliang/ui-markdown/.md) → preview(→.maliang/preview/preview_.html) → critique(→评分快照) → draw-harmony/draw-flutter/draw-element(→框架代码);迭代经 redesign/ui-graph 回流 decisions 账本。
• 维度规范(色 / 字 / 图 / 距 / 角 / 线 / 布局 / 对齐 / 海拔)在 references/dimensions/ 下(含 color-palettes 调色板库、design-systems 参考设计系统、glass-effect/glass-advanced 液态玻璃配方、texture 纹理预算(一页一纹理族/透明度 token 化)、elevation 表面海拔、alignment 对齐轴/同排等高/凸起关系、h5-frame H5 手机专属页容器契约);设计原则在 references/meta/principles.md,十三个子命令共享参考,不在本路由器重复。桌面页到手机上的六条机械故障见 references/meta/mobile-floor.md。
• 模板墙在 references/templates/:14 种设计语言(液态玻璃/M3 Expressive/Fluent 2/Bento/瑞士编辑/OLED 暗色/数据仪表盘等) + 整页模式(编辑分栏/纵深长廊/Dashboard 风格集/移动端五式/滚动图带/AI 工作台) + 落地页编排 + 性格方向卡;选型走 README 四步路由 + variation-engine 七轴组合 + 跨次构建记忆(build-log + CSS 盖章,≥5 轴相同即重选)。
• 交付物骨架模板在 template/:DESIGN.md 骨架 / ui-markdown 页面骨架 / IP prompt 契约 / A11y 实测记录,复制填充用——骨架字面形态的唯一 canonical 在各文件,填法与校验规则在对应子命令文档;与模板墙分工(选型参考 vs 落盘起点)见 template/README.md。
• 术语库在 [`ref…

[truncated for translation]