better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/creative/creative-design-md.md

@@ -0,0 +1,189 @@
+---
+title: "Design Md — 编写/验证/导出 Google 的 DESIGN"
+sidebar_label: "Design Md"
+description: "编写/验证/导出 Google 的 DESIGN"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Design Md
+
+编写/验证/导出 Google 的 DESIGN.md token（设计令牌）规范文件。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/creative/design-md` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google` |
+| 相关 skill | [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# DESIGN.md Skill
+
+DESIGN.md 是 Google 的开放规范（Apache-2.0，`google-labs-code/design.md`），用于向编码 agent 描述视觉标识。一个文件包含：
+
+- **YAML 前置元数据** — 机器可读的设计 token（规范值）
+- **Markdown 正文** — 人类可读的说明，按规范章节组织
+
+Token 提供精确值。正文告诉 agent *为什么*这些值存在以及如何应用它们。CLI（`npx @google/design.md`）可对结构和 WCAG 对比度进行 lint 检查，对版本进行 diff 以检测回归，并导出为 Tailwind 或 W3C DTCG JSON。
+
+## 何时使用此 skill
+
+- 用户请求 DESIGN.md 文件、设计 token 或设计系统规范
+- 用户希望在多个项目或工具中保持一致的 UI/品牌风格
+- 用户粘贴了现有的 DESIGN.md，并要求进行 lint、diff、导出或扩展
+- 用户希望将样式指南移植为 agent 可消费的格式
+- 用户希望对其调色板进行对比度/WCAG 无障碍验证
+
+若仅需视觉灵感或布局示例，请改用 `popular-web-designs`。若需要从零开始设计一次性 HTML 产物（原型、幻灯片、落地页、组件实验室）时的*流程与品味*，请使用 `claude-design`。本 skill 专用于*正式规范文件*本身。
+
+## 文件结构
+
+```md
+---
+version: alpha
+name: Heritage
+description: Architectural minimalism meets journalistic gravitas.
+colors:
+  primary: "#1A1C1E"
+  secondary: "#6C7278"
+  tertiary: "#B8422E"
+  neutral: "#F7F5F2"
+typography:
+  h1:
+    fontFamily: Public Sans
+    fontSize: 3rem
+    fontWeight: 700
+    lineHeight: 1.1
+    letterSpacing: "-0.02em"
+  body-md:
+    fontFamily: Public Sans
+    fontSize: 1rem
+rounded:
+  sm: 4px
+  md: 8px
+  lg: 16px
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 24px
+components:
+  button-primary:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "#FFFFFF"
+    rounded: "{rounded.sm}"
+    padding: 12px
+  button-primary-hover:
+    backgroundColor: "{colors.primary}"
+---
+
+## Overview
+
+Architectural Minimalism meets Journalistic Gravitas...
+
+## Colors
+
+- **Primary (#1A1C1E):** Deep ink for headlines and core text.
+- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
+
+## Typography
+
+Public Sans for everything except small all-caps labels...
+
+## Components
+
+`button-primary` is the only high-emphasis action on a page...
+```
+
+## Token 类型
+
+| 类型 | 格式 | 示例 |
+|------|--------|---------|
+| 颜色 | `#` + 十六进制（sRGB） | `"#1A1C1E"` |
+| 尺寸 | 数字 + 单位（`px`、`em`、`rem`） | `48px`、`-0.02em` |
+| Token 引用 | `{path.to.token}` | `{colors.primary}` |
+| 字体排版 | 包含 `fontFamily`、`fontSize`、`fontWeight`、`lineHeight`、`letterSpacing`、`fontFeature`、`fontVariation` 的对象 | 见上方 |
+
+组件属性白名单：`backgroundColor`、`textColor`、`typography`、`rounded`、`padding`、`size`、`height`、`width`。变体（hover、active、pressed）是**独立的组件条目**，使用相关键名（`button-primary-hover`），而非嵌套结构。
+
+## 规范章节顺序
+
+章节均为可选，但已存在的章节**必须**按以下顺序排列。重复标题将导致文件被拒绝。
+
+1. Overview（别名：Brand & Style）
+2. Colors
+3. Typography
+4. Layout（别名：Layout & Spacing）
+5. Elevation & Depth（别名：Elevation）
+6. Shapes
+7. Components
+8. Do's and Don'ts
+
+未知章节会被保留，不会报错。未知 token 名称在值类型有效时可被接受。未知组件属性会产生警告。
+
+## 工作流：编写新的 DESIGN.md
+
+1. **询问用户**（或推断）品牌基调、强调色和字体方向。若用户提供了网站、图片或风格描述，将其转换为上述 token 结构。
+2. **编写 `DESIGN.md`**，使用 `write_file` 写入项目根目录。始终包含 `name:` 和 `colors:`；其他章节可选但建议添加。
+3. **使用 token 引用**（`{colors.primary}`）在 `components:` 章节中引用颜色，而非重复输入十六进制值。保持调色板单一来源。
+4. **进行 lint 检查**（见下文）。在返回前修复所有断开的引用或 WCAG 失败项。
+5. **若用户有现有项目**，同时将 Tailwind 或 DTCG 导出文件写入文件旁（`tailwind.theme.json`、`tokens.json`）。
+
+## 工作流：lint / diff / 导出
+
+CLI 为 `@google/design.md`（Node）。使用 `npx`，无需全局安装。
+
+```bash
+# 验证结构 + token 引用 + WCAG 对比度
+npx -y @google/design.md lint DESIGN.md
+
+# 比较两个版本，发现回归时失败（exit 1 = 存在回归）
+npx -y @google/design.md diff DESIGN.md DESIGN-v2.md
+
+# 导出为 Tailwind 主题 JSON
+npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
+
+# 导出为 W3C DTCG（Design Tokens Format Module）JSON
+npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
+
+# 打印规范本身 — 在注入 agent prompt 时很有用
+npx -y @google/design.md spec --rules-only --format json
+```
+
+所有命令均接受 `-` 作为 stdin。`lint` 在出现错误时返回 exit 1。若需要以结构化方式报告结果，请使用 `--format json` 标志并解析输出。
+
+### Lint 规则参考（7 条规则的检查内容）
+
+- `broken-ref`（错误）— `{colors.missing}` 指向不存在的 token
+- `duplicate-section`（错误）— 同一 `## 标题` 出现两次
+- `invalid-color`、`invalid-dimension`、`invalid-typography`（错误）
+- `wcag-contrast`（警告/信息）— 组件 `textColor` 与 `backgroundColor` 的对比度，对照 WCAG AA（4.5:1）和 AAA（7:1）
+- `unknown-component-property`（警告）— 超出上述白名单范围
+
+当用户关注无障碍性时，请在摘要中明确指出 — WCAG 检查结果是使用 CLI 最重要的理由。
+
+## 常见陷阱
+
+- **不要嵌套组件变体。** `button-primary.hover` 是错误的；应将 `button-primary-hover` 作为同级键。
+- **十六进制颜色必须加引号。** 否则 YAML 会在 `#` 处出错，或将 `#1A1C1E` 等值截断。
+- **负数尺寸也需要加引号。** `letterSpacing: -0.02em` 会被解析为 YAML flow — 应写为 `letterSpacing: "-0.02em"`。
+- **章节顺序是强制的。** 若用户以随机顺序提供正文，在保存前须重新排列为规范列表顺序。
+- **`version: alpha` 是当前规范版本**（截至 2026 年 4 月）。该规范标记为 alpha — 请关注破坏性变更。
+- **Token 引用通过点分路径解析。** `{colors.primary}` 有效；`{primary}` 无效。
+
+## 规范来源
+
+- 仓库：https://github.com/google-labs-code/design.md（Apache-2.0）
+- CLI：npm 上的 `@google/design.md`
+- 生成的 DESIGN.md 文件的许可证：取决于用户项目所使用的许可证；规范本身为 Apache-2.0。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/creative/creative-excalidraw.md

@@ -0,0 +1,210 @@
+---
+title: "Excalidraw — 手绘风格 Excalidraw JSON 图表（架构图、流程图、时序图）"
+sidebar_label: "Excalidraw"
+description: "手绘风格 Excalidraw JSON 图表（架构图、流程图、时序图）"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Excalidraw
+
+手绘风格 Excalidraw JSON 图表（架构图、流程图、时序图）。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/creative/excalidraw` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `Excalidraw`, `Diagrams`, `Flowcharts`, `Architecture`, `Visualization`, `JSON` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Excalidraw 图表 Skill
+
+通过编写标准 Excalidraw 元素 JSON 并保存为 `.excalidraw` 文件来创建图表。这些文件可以直接拖放到 [excalidraw.com](https://excalidraw.com) 进行查看和编辑。无需账号、无需 API 密钥、无需渲染库——只需 JSON。
+
+## 使用场景
+
+生成 `.excalidraw` 文件，用于架构图、流程图、时序图、概念图等。文件可在 excalidraw.com 打开，或上传以获取可分享链接。
+
+## 工作流程
+
+1. **加载此 skill**（已完成）
+2. **编写元素 JSON**——一个 Excalidraw 元素对象数组
+3. **保存文件**——使用 `write_file` 创建 `.excalidraw` 文件
+4. **可选上传**——通过 `terminal` 运行 `scripts/upload.py` 获取可分享链接
+
+### 保存图表
+
+将元素数组包裹在标准 `.excalidraw` 信封中，并使用 `write_file` 保存：
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "hermes-agent",
+  "elements": [ ...your elements array here... ],
+  "appState": {
+    "viewBackgroundColor": "#ffffff"
+  }
+}
+```
+
+保存到任意路径，例如 `~/diagrams/my_diagram.excalidraw`。
+
+### 上传以获取可分享链接
+
+通过终端运行位于此 skill 的 `scripts/` 目录中的上传脚本：
+
+```bash
+python skills/diagramming/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw
+```
+
+此脚本将上传到 excalidraw.com（无需账号）并打印可分享的 URL。需要安装 `cryptography` pip 包（`pip install cryptography`）。
+
+---
+
+## 元素格式参考
+
+### 必填字段（所有元素）
+`type`、`id`（唯一字符串）、`x`、`y`、`width`、`height`
+
+### 默认值（可省略——会自动应用）
+- `strokeColor`: `"#1e1e1e"`
+- `backgroundColor`: `"transparent"`
+- `fillStyle`: `"solid"`
+- `strokeWidth`: `2`
+- `roughness`: `1`（手绘风格）
+- `opacity`: `100`
+
+画布背景为白色。
+
+### 元素类型
+
+**矩形（Rectangle）**：
+```json
+{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }
+```
+- `roundness: { "type": 3 }` 表示圆角
+- `backgroundColor: "#a5d8ff"`, `fillStyle: "solid"` 表示填充色
+
+**椭圆（Ellipse）**：
+```json
+{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }
+```
+
+**菱形（Diamond）**：
+```json
+{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }
+```
+
+**带标签的形状（容器绑定）**——创建一个绑定到形状的文本元素：
+
+> **警告：** 不要在形状上使用 `"label": { "text": "..." }`。这不是有效的 Excalidraw 属性，会被静默忽略，导致形状显示为空白。必须使用下方的容器绑定方式。
+
+形状需要在 `boundElements` 中列出文本，文本需要通过 `containerId` 反向指向形状：
+```json
+{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80,
+  "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+  "boundElements": [{ "id": "t_r1", "type": "text" }] },
+{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25,
+  "text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e",
+  "textAlign": "center", "verticalAlign": "middle",
+  "containerId": "r1", "originalText": "Hello", "autoResize": true }
+```
+- 适用于矩形、椭圆、菱形
+- 设置 `containerId` 后，Excalidraw 会自动将文本居中
+- 文本的 `x`/`y`/`width`/`height` 为近似值——Excalidraw 加载时会重新计算
+- `originalText` 应与 `text` 保持一致
+- 始终包含 `fontFamily: 1`（Virgil 手绘字体）
+
+**带标签的箭头**——同样使用容器绑定方式：
+```json
+{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
+  "points": [[0,0],[200,0]], "endArrowhead": "arrow",
+  "boundElements": [{ "id": "t_a1", "type": "text" }] },
+{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20,
+  "text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e",
+  "textAlign": "center", "verticalAlign": "middle",
+  "containerId": "a1", "originalText": "connects", "autoResize": true }
+```
+
+**独立文本**（仅用于标题和注释——无容器）：
+```json
+{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20,
+  "fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Hello", "autoResize": true }
+```
+- `x` 为左边缘。若要在位置 `cx` 处居中：`x = cx - (text.length * fontSize * 0.5) / 2`
+- 不要依赖 `textAlign` 或 `width` 来定位
+
+**箭头（Arrow）**：
+```json
+{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
+  "points": [[0,0],[200,0]], "endArrowhead": "arrow" }
+```
+- `points`：相对于元素 `x`、`y` 的 `[dx, dy]` 偏移量
+- `endArrowhead`：`null` | `"arrow"` | `"bar"` | `"dot"` | `"triangle"`
+- `strokeStyle`：`"solid"`（默认）| `"dashed"` | `"dotted"`
+
+### 箭头绑定（将箭头连接到形状）
+
+```json
+{
+  "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0,
+  "points": [[0,0],[150,0]], "endArrowhead": "arrow",
+  "startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] },
+  "endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] }
+}
+```
+
+`fixedPoint` 坐标：`top=[0.5,0]`、`bottom=[0.5,1]`、`left=[0,0.5]`、`right=[1,0.5]`
+
+### 绘制顺序（z 轴顺序）
+- 数组顺序 = z 轴顺序（第一个 = 最底层，最后一个 = 最顶层）
+- 按顺序逐步输出：背景区域 → 形状 → 其绑定文本 → 其箭头 → 下一个形状
+- 错误做法：所有矩形，然后所有文本，然后所有箭头
+- 正确做法：bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ...
+- 始终将绑定文本元素紧接在其容器形状之后
+
+### 尺寸规范
+
+**字体大小：**
+- 正文文本、标签、描述的最小 `fontSize`：**16**
+- 标题和大标题的最小 `fontSize`：**20**
+- 次要注释的最小 `fontSize`：**14**（谨慎使用）
+- 绝不使用低于 14 的 `fontSize`
+
+**元素尺寸：**
+- 带标签的矩形/椭圆最小尺寸：120x60
+- 元素之间至少留 20-30px 间距
+- 优先使用数量少、尺寸大的元素，而非大量细小元素
+
+### 颜色调色板
+
+完整颜色表见 `references/colors.md`。快速参考：
+
+| 用途 | 填充色 | 十六进制 |
+|-----|-----------|-----|
+| 主要 / 输入 | 浅蓝色 | `#a5d8ff` |
+| 成功 / 输出 | 浅绿色 | `#b2f2bb` |
+| 警告 / 外部 | 浅橙色 | `#ffd8a8` |
+| 处理 / 特殊 | 浅紫色 | `#d0bfff` |
+| 错误 / 关键 | 浅红色 | `#ffc9c9` |
+| 备注 / 决策 | 浅黄色 | `#fff3bf` |
+| 存储 / 数据 | 浅青色 | `#c3fae8` |
+
+### 使用技巧
+- 在整个图表中保持一致的颜色调色板
+- **文本对比度至关重要**——不要在白色背景上使用浅灰色。白色背景上文本颜色最低值：`#757575`
+- 不要在文本中使用 emoji——Excalidraw 的字体无法渲染
+- 深色模式图表，见 `references/dark-mode.md`
+- 更多示例，见 `references/examples.md`