widget-design git:20260817.c5cdd0eA

Immutable. This exact content is served forever at /api/v1/blob/ec928d29b2ed9094.

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

# 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）——交互
  都要即时反馈，禁止无响应的装饰按钮。

## 组合成板（看板）

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

## 反模式

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