---
name: widget-design
description: 看板与对话内联 widget 卡片的设计与使用规范——何时主动生成活卡片、怎么写 data、卡面与布局原则（活卡片设计规范）。触发：用户要求可视化/看板/交互卡片，或回答包含数值对比、清单、流程、行情、时序数据时。
---

# Widget 设计规范

MusePi 的 widget 是**活卡片**：渲染在对话内联或看板网格里，带真实数据和交互，
而不是静态文字排版。`widget` 工具负责生成（参数表见工具描述），本 skill 负责
**判断何时用、怎么设计得像样**。

## 何时主动用（不等用户说"可视化"）

- **数值/对比**：个税、费用换算、指标对比、价格/汇率 → `calc`/`metric`/`ticker`/`fx`
- **清单/流程**：待办、检查项、打卡 → `todo`；专注计时 → `pomodoro`
- **行情/时序**：股价/汇率实时盯盘 → `stocks`/`fx`/`kline`/`heatwall`/`indextape`
- **系统状态**：时钟 + 三市状态 → `clock`；仪表读数 → `gauge`
- **介绍/媒体**：产品介绍视频 → `video`（可填 B站 bvid）；音乐 → `music`
- **历史/事实**：历史上的今天 → `history`（真实数据源自动刷新）
- **调参观察**：用户需要拖滑杆看效果 → `slider`（噪声/抖动/频率）
- **相册/合集**：多张图 → `gallery`

**不要**用于：普通文字回答、逐行代码解释、文件列表、破坏性/阻塞输入流程、
大型长驻应用。

## 怎么写 data

- 字段可省略——缺省值自动补齐（如 `calc` 缺 `mode` 默认 `post`）。
- 数据卡（fx/stocks/history）**自动拉真实数据**（60s 刷新），data 里只需
  `chip`/`title`/`pairs`/`rows` 等描述性字段——**不要**在 data 里塞快照值。
- 内容有真实信息就填真实信息（`video` 填真实 bvid/url；`music` 填真实曲目），
  不要给演示假数据。
- `title` 可选，默认组件名；写有辨识度的标题（如"今日汇率"而非"汇率卡"）。

## 卡面原则（组件即卡）

- **每个组件自带卡面**（深色渐变/浅色磨砂/蓝色系）——不要给卡片再套外框。
- 尺寸：宽 340×200 起（网格 92×44，最小 172×76，画布 1092）；数据多的卡
  拉高（如 history/fx/stocks 常用 560+ 高），视频/音乐卡常用 4:3。
- 卡内滚动：列表内容超卡高时用卡内滚动（history 事件列表），不要撑破卡片。
- 聚焦交互：点击封面播放（video）、拖滑杆（slider）、勾选（todo）——交互
  都要即时反馈，禁止无响应的装饰按钮。
- **渲染提示**：聊天内联与看板画布共用同一卡面——内联宽度随消息自适应；
  看板上卡片受 ChromaGrid 组光效（鼠标 RGB 色散光晕）氛围影响，暗色大卡
  读感好——卡面数据完整是主体，光效只是氛围，不要为光效改变配色。

## 自定义 HTML 组件（html 类型）

`html` 卡是"自由面"——sandbox 内运行你的 HTML/CSS/JS，覆盖内置组件
之外的场景（统计面板、流程可视化、复合交互）。写得像 kimiwork
blueprint 组件一样可用的要点：

### 结构（自包含单文件）
- **一个 `<style>` + body 内一个根元素**；所有 CSS 写进 `<style>`
  （沙箱无外部 CSS 文件）。
- 根元素撑满视口：`html, body { height: 100%; margin: 0; }`，内容用
  flex/grid 布局——**不要固定像素宽**（卡尺寸可变）。
- 数据从 `window.__WIDGET_DATA__` 读（agent 塞的 `data` 字段），不要
  硬编码。

### 样式
- **两套主题**（深色为主）：`.omp-theme-dark body { … }` +
  `.omp-theme-light body { … }`，所有有颜色的元素都要两套（铁律，
  宿主热切换会重建 iframe）。
- 深底配浅字、浅底配深字（对比度 ≥4.5:1）；设了 `background` 的元素
  必须同时设 `color`。
- 配色用 CSS 变量组织（`:root { --bg; --fg; --accent }`，两套主题换值），
  比到处硬编码好维护；字号 12-14px，卡内边距 12-16px。

### 交互（JS）
- 按钮/滑杆/勾选**即时反馈**（hover/点击态），禁止无响应装饰。
- 需要外部数据：**先取好注入 data**（沙箱禁第三方 fetch）；`<img src="https://…">`
  可用（不回读字节，不受 CORS 限制）。
- 高度自适应：内容变化后
  `parent.postMessage({ type: "omp-widget-resize", mountId: window.DaimonCanvas.mountId, height: document.documentElement.scrollHeight }, "*")`
  ——宿主自动跟随，别让内容溢出卡片。
- 主题切换宿主重建 iframe，无需自己监听。

### 检查清单
- [ ] 两套主题都有、对比度够
- [ ] 数据来自 `__WIDGET_DATA__` 而非硬编码
- [ ] 布局自适应卡尺寸（flex/grid，无固定像素墙）
- [ ] 交互有反馈、高度上报正确
- [ ] 总长 ≤64KB

## 组合成板（看板）

- 一屏 3-4 卡：数据类并排（fx + stocks + history），媒体类单独大卡
  （music/video）。
- 相关数值放一组：时钟 + 市场状态、汇率 + 走势。
- 卡与卡之间留 12px gutter，右缘对齐画布右缘。
- 任务一致性：卡片带 `task` 元数据时任务必须与卡展示内容直接相关
  （如汇率卡任务="刷新汇率"），禁止挂无关作业。

## 反模式

- ❌ 用大段文字描述本来可以可视化的数值/清单。
- ❌ 给组件卡再套边框/卡片壳（组件本身就是卡）。
- ❌ 把过时快照写进 data（能自动刷新的数据让组件自己拉）。
- ❌ 塞满一屏卡片没有主次（一个主题 ≤ 4 卡）。