# smyw(show me you want)spec 格式 spec 是一个 JSON 对象。只有 `title` 加上 `pages` / `flows` / `backend` 至少其中一项是必需的,其余字段都可选。 ~~~jsonc { "title": "任务管理:用标签替代分类", // 预览标题 "summary": "一两段话说明这次改动", // 画布左侧「这次改什么」,可换行 "stage": "prototype", // prototype(未实现)| implementing | done(实现后回顾) "version": 1, // 每次根据反馈修改后 +1 "versionNote": "本轮修改的一句话摘要", // 可选:多版本下拉框里展示的本轮说明 "theme": { "primary": "#4F46E5", "radius": "6px" }, // 可选:覆盖自动从项目 globals.css 提取的主题变量 "changes": [ // 变更要点(写进反馈,供 Agent 对照) { "area": "frontend", "change": "added", "text": "新增标签管理页" } ], // area: frontend | backend | data | api | flow | other;也可以直接写字符串 "questions": [ // 需要用户拍板的问题 { "id": "q-color", "q": "标签要支持颜色吗?", "options": ["需要", "不需要"] } ], "pages": [ Page ], "flows": [ Flow ], "backend": [ Module ] } ~~~ ## 改动标注(所有层级通用) 页面、节点、流程、步骤、后端模块和条目都可以带这些字段: | 字段 | 含义 | |---|---| | `change` | `added` / `removed` / `modified`,不写就是不变 | | `before` | 只在 modified 时使用:被修改字段的**旧值**,例如 `{"label": "添加", "fn": null}`。`null` 表示改动前没有这个字段 | | `movedTo` | 写在旧位置节点上(`change: "removed"`),指向新位置节点的 id | | `movedFrom` | 写在新位置节点上(`change: "added"`),指向旧位置节点的 id | | `note` | 一句话说明为什么改,会显示在元素下方(左侧显示删除的说明,右侧显示新增和修改的说明) | 渲染规则:左侧"改动前"隐藏 added 节点,并对 modified 节点套用 before;右侧"改动后"隐藏 removed 节点。颜色:左侧红色实线 = 删除/移出,红色虚线 = 修改前;右侧绿色实线 = 新增/移入,绿色虚线 = 修改后。 父节点被删除或新增时,子节点**不要**再逐个标注:预览只给最外层改动的模块画框编号(黄 = 修改,绿 = 新增,红 = 删除),里面的内容在点开详情后展示。 预览里的「改动单元」= 整页新增/删除的页面,或祖先都没改动的、最外层的改动节点。每个单元在画布上有一个编号,在左侧清单里有一条。 ## Page ~~~jsonc { "id": "inbox", "name": "工单工作台 · 打开一张工单", "route": "/tickets/:id", "width": 1440, // 画布上这一屏的宽度(像素),默认 1280 "change": "modified", "note": "...", "root": Node, // 一般是 { "id": "...", "type": "page", "children": [...] } "overlays": [ Node ] // 弹层:dialog / alert-dialog / drawer / popover / preview-card / tooltip / menu / context-menu / toast;各自用 trigger 指向打开它的元素 id(toast 可省略) } ~~~ **一个 page = 用户看到的一整屏**(例如「侧栏 + 主面板」),按真实布局画:`root.layout: "row"`,侧栏 `w: "1/4"`。不同路由或模式才拆成不同的 page。 整页新增:`change: "added"`,左侧显示"改动前不存在"。整页删除:`change: "removed"`,右侧显示"将被删除"。 ## Node(线框元素) | 字段 | 说明 | |---|---| | `id` | 稳定、有语义、整个 spec 内唯一 | | `type` | 见下表 | | `label` | 显示的文字:按钮文字、标题、字段名、容器标题(用界面上真实的名字) | | `component` | 代码里对应的组件 / 文件,如 `" TicketQueue.vue"`。顶层区域都要写,用户靠它把框和真实模块对上 | | `text` | 输入框的占位文字或示例值;其他类型显示为灰色说明 | | `fn` | 函数/行为/接口占位:`onClick → openEditor()`、`GET /api/tags` | | `children` | 子节点(容器类型) | | `layout` | `col`(纵向)/ `row`(横向)/ `grid`(配合 `cols`) | | `cols` | `layout: "grid"` 时的列数(数字,默认 2) | | `w` | 宽度:`"1/4"` `"1/3"` `"1/2"` `"2/3"` `"3/4"` `"full"`,或 flex 权重数字 | | `variant` | 按钮类:`primary` / `secondary` / `danger` / `ghost` / `icon` | | `items` | nav / tabs / list / menu / context-menu / select / combobox / autocomplete / radio-group / menubar / navigation-menu / toggle-group 的条目。条目可以是字符串,也可以是 `{"label": "...", "change": "added"}` | | `columns` | table 的列,格式同 items(适合表达"新增一列、删掉一列") | | `rows` | table 的占位行数,默认 2 | | `lines` | text 的灰色占位行数 | | `trigger` | overlay 节点:打开它的按钮 / 链接 id;多个按钮打开同一个弹层时写成数组,如 `["ai-edit", "reply-polish"]`。画布上会从每个按钮画一条弯曲连线到弹层 | | `value` | `progress` / `meter` / `slider` 的当前值,0–100,如 `72`;预览画成对应的条 | **type 取值** smyw 用 **Base UI** 作为组件框架。`type` 优先写 Base UI 的原语(完整映射、每个组件的 anatomy 见 [`base-ui.md`](base-ui.md)): - 弹层:`dialog` `alert-dialog` `drawer` `popover` `preview-card` `tooltip` `menu` `context-menu` `toast` - 表单 / 控件:`button` `input` `textarea` `field` `fieldset` `form` `checkbox` `checkbox-group` `switch` `radio-group` `select` `combobox` `autocomplete` `number-field` `otp-field` `slider` `toggle` `toggle-group` `upload` - 容器 / 导航:`tabs` `accordion` `collapsible` `toolbar` `menubar` `navigation-menu` `scroll-area` `section` `row` `col` `grid` `card` `list` `item` `nav` `header` `footer` `sidebar` `panel` `group` `page` - 展示:`avatar` `progress` `meter` `separator` `heading` `text` `image` `table` `chart` `stat` `badge` `tag` `icon` `link` - 旧类型(继续可用,但新方案优先用对应的 Base UI 类型):`modal` → `dialog`,`radio` → `radio-group`,`divider` → `separator` - `toggle` 与 `switch` 不同:`toggle` 是 Base UI 的 Toggle(可按下的按钮),开 / 关设置用 `switch`;旧方案里用 `toggle` 表示开关的,迁移到 `switch` - `placeholder`:带斜纹的虚线框。只用于「这里将来会有内容」之类的占位;**没改动的模块不要用它**,画成真实模块、不展开 children 即可(显示「内容不变,未展开」) `row` `nav` `toolbar` `header` `footer` `item` `menubar` `navigation-menu` `toggle-group` 默认横向排列。 ## 交互(on / hidden / states) 让「▶ 演示」模式能真的点,也让画布能画出连线和单独面板。 | 字段 | 说明 | |---|---| | `on` | 点击这个元素后发生什么,数组:`[{ "action": "...", "target": "id", "state": "..." }]`,可以写多条(依次执行) | | `hidden` | `true` = 默认不显示。被 toggle / show 指向时,画布上画成旁边的单独面板并连线,原位置留「在这里展开」的槽位;没人指向时表示「按条件出现」,演示模式左侧可以手动打开 | | `states` | 这个元素的其他样子:`{ "状态名": { 要覆盖的字段 } }`,如 `{ "open": { "label": "▾ 已结束 57" } }` | | `state` | 当前状态名(不写 = 默认样子) | action: | action | 效果 | target | |---|---|---| | `open` | 打开弹层(dialog / modal 居中变暗、drawer 右侧滑出、menu / popover 贴着按钮);target 是普通元素时等于 show | 必填 | | `close` | 关闭弹层 | 可省略,默认关闭自己所在的弹层 | | `navigate` | 跳到另一个 page | page id | | `toggle` | 展开 / 收起(hidden 元素或弹层) | 必填 | | `show` / `hide` | 显示 / 隐藏 | 必填 | | `state` | 切换状态;写了 state 就切到它,没写就在几个状态间轮换 | 可省略,默认自己 | | `back` | 关闭最上层弹层,或回到上一屏 | — | 弹层上的 `trigger` 等价于触发按钮上的 `{ "action": "open" }`,两种写一种就行。 ```jsonc { "id": "g-worker", "type": "button", "label": "✓ worker · 46 秒", "on": [{ "action": "toggle", "target": "td-node" }] }, { "id": "td-node", "type": "section", "label": "这个 agent 说了什么", "hidden": true, "children": [ ... ] }, { "id": "ac-btn", "type": "button", "label": "验收通过", "states": { "done": { "label": "已验收", "variant": "ghost" } }, "on": [{ "action": "state", "target": "ac-btn", "state": "done" }] } ``` ## Base UI 组件 smyw 的组件框架是 **Base UI**(`@base-ui/react`,v1.9.0)。spec 的 `type` 就是 Base UI 原语的名字;`component` 写实现时要写的 Base UI 组件,例如: ```jsonc { "id": "invite", "type": "button", "label": "邀请成员", "component": "