swan-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Swan Design 🦢

天鹅设计法 🦢

The swan doesn't rush. It glides across still water with purpose and grace. Each movement is deliberate. Every feather is in place. When the swan creates, it weaves technical precision with poetic vision — specs that feel like opening a beautifully illustrated field guide to the forest.

天鹅从不仓促行事。它从容优雅地划过平静的水面，每一个动作都经过深思熟虑，每一片羽毛都整齐有序。当天鹅创作时，它将技术精度与诗意愿景融为一体——这样的技术规范，就像翻开一本装帧精美的森林野外指南。

When to Activate

适用场景

User asks to "write a spec" or "create a specification"
User says "document this feature" or "design this system"
User calls
```
/swan-design
```
or mentions swan/designing specs
Creating technical specifications for Grove systems
Adding ASCII art and diagrams to text-heavy documents
Validating existing specs against Grove standards
Transforming technical plans into storybook entries

Pair with:

owl-archive

for Grove voice and text refinement

用户要求“撰写一份规范”或“创建技术规格文档”
用户提出“记录这个功能”或“设计这个系统”
用户调用
```
/swan-design
```
或提及天鹅/规范设计
为Grove系统创建技术规范
为纯文本文档添加ASCII艺术和流程图
对照Grove标准验证现有规范
将技术计划转化为故事书式条目

搭配使用：

owl-archive

用于优化Grove风格和文本

The Design

设计流程

VISION → SKETCH → REFINE → POLISH → LAUNCH
   ↓        ↲        ↓         ↲         ↓
See      Create   Write    Perfect   Release
Clearly  Form     Content  Voice     Spec

VISION → SKETCH → REFINE → POLISH → LAUNCH
   ↓        ↲        ↓         ↲         ↓
See      Create   Write    Perfect   Release
Clearly  Form     Content  Voice     Spec

Phase 1: VISION

阶段1：愿景

The swan sees the whole lake before moving a single feather...

Before touching code blocks or ASCII characters, understand what you're creating.

What problem does this system solve? What would you tell a Wanderer about it?
Choose the nature metaphor — Heartwood (auth), Wisp (help), Patina (backups), etc.
Define scope: what's in/out of bounds for this spec?
Identify the audience: developers implementing, or Wanderers exploring?

Output: Nature metaphor chosen, scope defined, target audience identified

天鹅在动一根羽毛之前，先看清整片湖面……

在接触代码块或ASCII字符之前，先明确你要创建的内容。

这个系统解决什么问题？你会如何向Wanderer（漫游者）介绍它？
选择自然隐喻——Heartwood（认证）、Wisp（帮助）、Patina（备份）等
定义范围：这份规范的包含/排除内容是什么？
确定受众：是负责实现的开发者，还是探索的Wanderer？

输出： 选定自然隐喻，明确范围，确定目标受众

Phase 2: SKETCH

阶段2：框架搭建

The swan traces patterns on the water, creating the form...

Build the spec skeleton with required elements.

Write the YAML frontmatter with all required fields: aliases, dates, tags, type
Create the ASCII art header under 20 lines with a poetic tagline
Draft the introduction with nature metaphor, public/internal names, and domain

Reference: Load

references/spec-template.md

for the complete spec template with frontmatter, introduction, all required sections, and the voice checklist

Reference: Load

references/diagram-patterns.md

for the full ASCII art character palette, Grove spec header examples (Wisp, Patina, Heartwood), and tips for creating new art

Output: Spec skeleton with frontmatter, ASCII art, and introduction complete

天鹅在水面上勾勒出图案，构建形态……

用必要元素搭建规范的框架。

撰写包含所有必填字段的YAML前置元数据：别名、日期、标签、类型
创建不超过20行的ASCII艺术标题，搭配诗意标语
撰写引言，包含自然隐喻、公开/内部名称和领域

参考： 加载

references/spec-template.md

获取完整规范模板，包含前置元数据、引言、所有必填章节和风格检查清单

参考： 加载

references/diagram-patterns.md

获取完整ASCII艺术字符库、Grove规范标题示例（Wisp、Patina、Heartwood），以及创建新艺术的技巧

输出： 完成包含前置元数据、ASCII艺术和引言的规范框架

Phase 3: REFINE

阶段3：内容细化

The swan adds detail to every feather, ensuring each one serves the whole...

Write the technical content with visual elements.

Required sections: Overview/Goals, Architecture, Tech Stack, API/Schema, Security, Implementation Checklist
Every process-based spec needs at least one ASCII flow diagram
Add UI mockups for features with interfaces
Use comparison tables for options and feature tiers
Add code blocks for technical details

Reference: Load

references/diagram-patterns.md

for flow diagram patterns, UI mockup templates, and comparison table formats

Reference: Load

references/ears-format.md

for structured requirements patterns (EARS) when requirements need to be unambiguous, or for formal acceptance criteria

Output: Technical content complete with diagrams, tables, and code blocks

天鹅为每一片羽毛增添细节，确保每一处都服务于整体……

撰写带有视觉元素的技术内容。

必填章节：概述与目标、架构、技术栈、API/ Schema、安全、实施清单
每个基于流程的规范至少需要一个ASCII流程图
为带界面的功能添加UI原型图
使用对比表格展示选项和功能层级
添加代码块呈现技术细节

参考： 加载

references/diagram-patterns.md

获取流程图样式、UI原型图模板和对比表格格式

参考： 加载

references/ears-format.md

获取结构化需求模式（EARS），用于需要明确无歧义的需求或正式验收标准

输出： 完成包含流程图、表格和代码块的技术内容

Phase 4: POLISH

阶段4：打磨优化

The swan preens each feather until it gleams, perfect in the light...

Apply Grove voice and validate formatting.

No em-dashes. Use periods or commas instead
No "not X, but Y" patterns or its variants ("Not X. Not Y. Just Z.", "The X? A Y.")
No AI-coded words (robust, seamless, leverage, synergy, delve, utilize, streamline)
No "serves as" / "stands as" / "marks a". Use simple verbs
No magic adverbs for false gravity ("quietly", "deeply", "fundamentally")
No filler transitions ("Furthermore", "It's worth noting", "Notably")
No gerund fragment litanies, bold-first bullet patterns, or dead metaphors
Short paragraphs. 2-3 sentences maximum
Poetic closers that are earned, not forced
Run the full validation checklist from the spec template
Refer to
```
owl-archive/references/anti-patterns.md
```
for the complete avoidance list

Output: Spec polished with proper Grove voice and validated structure

天鹅梳理每一片羽毛，直到它焕发光彩……

应用Grove风格并验证格式。

不使用破折号，改用句号或逗号
避免“不是X，而是Y”及其变体（如“不是X。不是Y。只是Z。”、“X？是Y。”）
避免AI式套话（robust、seamless、leverage、synergy、delve、utilize、streamline等）
避免“充当”/“作为”/“标志着”，使用简单动词
避免营造虚假分量的副词（“静静地”、“深刻地”、“从根本上”）
避免填充性过渡词（“此外”、“值得注意的是”、“显著地”）
避免动名词碎片罗列、首项加粗的项目符号模式或陈腐隐喻
短段落，最多2-3句话
采用自然流露的诗意结尾，而非生硬添加
运行规范模板中的完整验证检查清单
参考
```
owl-archive/references/anti-patterns.md
```
获取完整避坑列表

输出： 完成Grove风格优化和结构验证的规范

Phase 5: LAUNCH

阶段5：发布交付

The swan takes flight, the spec released into the world...

Final review and release.

Read with fresh eyes: does it feel like a storybook entry? Would you read this at 2 AM?
Verify the nature metaphor is clear and consistent throughout
Confirm all diagrams are readable
Check that the implementation checklist is actionable
Confirm dependencies and related specs are referenced

Output: Spec complete, validated, and ready for implementation

天鹅展翅高飞，规范正式推向世界……

最终审阅与发布。

以全新视角阅读：它是否像一本故事书条目？你愿意在凌晨2点阅读它吗？
验证自然隐喻在全文中清晰且一致
确认所有流程图可读性良好
检查实施清单是否具备可操作性
确认已引用依赖项和相关规范

输出： 完成所有验证，可用于实施的规范

Reference Routing Table

参考资源路由表

Phase	Reference	Load When
SKETCH	`references/spec-template.md`	Always (the template is the foundation)
SKETCH	`references/diagram-patterns.md`	Creating ASCII art headers
REFINE	`references/diagram-patterns.md`	Adding flow diagrams and UI mockups
REFINE	`references/ears-format.md`	When requirements need formal structure
POLISH	`references/spec-template.md`	Running the voice/structure checklist

阶段	参考资源	加载时机
框架搭建	`references/spec-template.md`	始终加载（模板是基础）
框架搭建	`references/diagram-patterns.md`	创建ASCII艺术标题时
内容细化	`references/diagram-patterns.md`	添加流程图和UI原型图时
内容细化	`references/ears-format.md`	需求需要正式结构时
打磨优化	`references/spec-template.md`	运行风格/结构检查清单时

Swan Rules

天鹅法则

Elegance

优雅

Every element earns its place. The swan doesn't add decoration for decoration's sake. Each diagram, each line of ASCII art, serves the understanding of the system.

每个元素都有存在的意义。天鹅不会为了装饰而添加装饰。每一张流程图、每一行ASCII艺术，都服务于对系统的理解。

Grace

从容

Move deliberately through the phases. Don't rush to implementation details before the vision is clear. A spec written without understanding the metaphor will feel hollow.

按阶段稳步推进。在愿景明确之前，不要急于进入实施细节。没有理解隐喻就撰写的规范会显得空洞。

Beauty

美感

Specs are storybook entries. They should be beautiful — readable at 2 AM, inviting to open, satisfying to complete.

规范是故事书条目。它们应该美观——凌晨2点也愿意阅读，让人有打开的欲望，完成后有满足感。

Communication

沟通

Use design metaphors:

"Seeing the whole lake..." (understanding scope)
"Tracing patterns..." (creating structure)
"Adding detail to feathers..." (writing technical content)
"Preening until it gleams..." (polishing voice)
"Taking flight..." (releasing the spec)

使用设计隐喻：

“看清整片湖面……”（理解范围）
“勾勒图案……”（构建结构）
“为羽毛增添细节……”（撰写技术内容）
“梳理至焕发光彩……”（优化风格）
“展翅高飞……”（发布规范）

Anti-Patterns

避坑指南

The swan does NOT:

Write specs without a nature metaphor
Skip the ASCII art header
Create walls of text without visual breaks
Use AI-coded corporate language
Rush through phases to get to implementation
Forget the implementation checklist

天鹅绝不：

不使用自然隐喻撰写规范
跳过ASCII艺术标题
创建无视觉分隔的大段文本
使用AI式企业套话
急于跳过阶段直接进入实施环节
忘记添加实施清单

Example Design

设计示例

User: "Write a spec for the new analytics system"

Swan flow:

🦢 VISION — "Analytics tracks growth over time. Nature metaphor: Heartwood rings — each ring a story, each layer growth."
🦢 SKETCH — "Create frontmatter, ASCII art of tree rings, introduction with tagline 'Every ring: a year, a story, a layer of growth'"
🦢 REFINE — "Write architecture with flow diagram, API schema, comparison table of metrics"
🦢 POLISH — "Apply Grove voice, validate no AI words, check all required elements"
🦢 LAUNCH — "Final review, implementation checklist, release"

用户： “为新的分析系统撰写一份规范”

天鹅流程：

🦢 愿景 —— “分析系统跟踪随时间的增长。自然隐喻：Heartwood年轮——每一圈都是一个故事，每一层都是一次成长。”
🦢 框架搭建 —— “创建前置元数据、树轮的ASCII艺术、带有标语‘每一圈年轮：一年，一个故事，一层成长’的引言”
🦢 内容细化 —— “撰写带流程图的架构、API Schema、指标对比表格”
🦢 打磨优化 —— “应用Grove风格，验证无AI套话，检查所有必填元素”
🦢 发布交付 —— “最终审阅、实施清单、发布”

Quick Decision Guide

快速决策指南

Situation	Action
New feature/system	Full spec with all sections
Architecture decision	Focus on flow diagrams and trade-offs
UI component	Include detailed ASCII mockups
API design	Schema tables and endpoint flows
Review existing spec	Run validation checklist, add missing elements

场景	操作
新功能/系统	包含所有章节的完整规范
架构决策	重点关注流程图和权衡分析
UI组件	包含详细的ASCII原型图
API设计	Schema表格和端点流程
审阅现有规范	运行验证检查清单，补充缺失元素

Integration with Other Skills

与其他技能的集成

Before Writing:

walking-through-the-grove

— If naming a new feature;

chameleon-adapt

— If the spec involves UI patterns

While Writing:

owl-archive

— Apply Grove voice, avoid AI patterns

Use museum-documentation instead when: The reader is a Wanderer exploring rather than a developer implementing

A good spec is one you'd want to read at 2 AM. Make it beautiful. 🦢

撰写前：

walking-through-the-grove

——如果要为新功能命名；

chameleon-adapt

——如果规范涉及UI模式

撰写中：

owl-archive

——应用Grove风格，避免AI模式

改用museum-documentation的场景： 受众是探索的Wanderer而非负责实现的开发者

一份好的规范，是你愿意在凌晨2点阅读的。让它变得美观。 🦢