From ae0c91dddf3ce9cc2594884e44575ccc3ae49afa Mon Sep 17 00:00:00 2001 From: "zanwei.guo" Date: Mon, 23 Mar 2026 18:09:34 +0800 Subject: [PATCH] chore: initialize design-dna skill repo with bilingual README Made-with: Cursor --- .gitignore | 7 + LICENSE | 21 ++ README.md | 100 +++++++++ README.zh-CN.md | 100 +++++++++ SKILL.md | 104 ++++++++++ references/generation-guide.md | 209 +++++++++++++++++++ references/schema.md | 366 +++++++++++++++++++++++++++++++++ 7 files changed, 907 insertions(+) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 README.md create mode 100644 README.zh-CN.md create mode 100644 SKILL.md create mode 100644 references/generation-guide.md create mode 100644 references/schema.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c823857 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +.DS_Store +Thumbs.db +*.log +.idea/ +.vscode/ +*.swp +*.swo diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..8e6d197 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 the design-dna authors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..03edbb5 --- /dev/null +++ b/README.md @@ -0,0 +1,100 @@ +# design-dna + +**Language / 语言:** [English](README.md) · [简体中文](README.zh-CN.md) + +--- + +An [Agent Skill](https://agentskills.io) for coding agents (Cursor, Claude Code, Codex, and [many others](https://github.com/vercel-labs/skills#supported-agents)). It provides a structured workflow to **extract**, **document**, and **apply** visual design identity as machine-readable “Design DNA” across three dimensions: design tokens, qualitative style, and visual effects. + +Install from this repository with the open [`skills` CLI](https://github.com/vercel-labs/skills). Discover more skills at [skills.sh](https://skills.sh/). + +## What it does + +| Dimension | Role | +|-----------|------| +| **Design system** | Measurable tokens: color, typography, spacing, layout, shape, elevation, motion, components | +| **Design style** | Qualitative perception: mood, visual language, composition, imagery, interaction feel, brand voice | +| **Visual effects** | Beyond “plain CSS”: Canvas, WebGL, 3D, particles, shaders, scroll-driven motion, cursor effects, SVG animation, glassmorphism, etc. | + +The skill drives a **three-phase** workflow: + +1. **Structure** — Surface the full schema and field meanings (see `references/schema.md`). +2. **Analyze** — From screenshots, images, or URLs, produce a **complete JSON profile** (every field filled; conflicts noted). +3. **Generate** — Given DNA JSON plus content, implement the design (default: self-contained HTML/CSS/JS), following `references/generation-guide.md`. + +Phases can be used alone or chained (e.g. analyze → generate). + +## Installation + +Requires [Node.js](https://nodejs.org/) (for `npx`). After you publish this repo to GitHub under `OWNER/REPO`: + +```bash +# Install into detected agents (interactive) +npx skills add OWNER/REPO + +# Example once your repo is github.com/your-username/design-dna +npx skills add your-username/design-dna + +# Cursor only, non-interactive, global (user-wide) install +npx skills add your-username/design-dna -a cursor -g -y +``` + +**Preview skills in the repo without installing:** + +```bash +npx skills add https://github.com/OWNER/REPO --list +``` + +**Install from a local clone:** + +```bash +npx skills add /path/to/design-dna -a cursor -y +``` + +Paths after install depend on the agent; for Cursor, see [Cursor Skills docs](https://cursor.com/docs/context/skills) (often under `~/.cursor/skills/` for global installs). + +## Repository layout + +``` +design-dna/ +├── SKILL.md # Skill entry: frontmatter + agent instructions +├── references/ +│ ├── schema.md # Full JSON field list and semantics +│ └── generation-guide.md # How to turn DNA into implementation + QA +├── README.md # This file (English) +├── README.zh-CN.md # Chinese README +├── LICENSE +└── .gitignore +``` + +`SKILL.md` uses relative links into `references/`; keep that structure when forking or republishing. + +## When the agent should use this skill + +The skill’s `description` in `SKILL.md` lists trigger phrases. In short, use it when the user wants any of: + +- A **design structure / schema** for “Design DNA” +- **Analysis** of references (images, screenshots, URLs) into structured JSON +- **Generation** of UI from an existing DNA JSON +- **Visual effects** called out explicitly (WebGL, particles, shaders, scroll scenes, etc.) + +## Compatibility + +- Follows the [Agent Skills specification](https://agentskills.io). +- Installable via [`vercel-labs/skills` CLI](https://github.com/vercel-labs/skills) to [supported agents](https://github.com/vercel-labs/skills#supported-agents). + +## skills.sh leaderboard + +[skills.sh](https://skills.sh/) ranks skills using **anonymous, aggregated** install telemetry from the `skills` CLI ([docs](https://skills.sh/docs)). There is no separate “submit” step: publishing a public GitHub repo and sharing the `npx skills add owner/repo` command is how people discover and install your skill. + +## Security + +Review any skill before installing. This repository contains only Markdown instructions and references—no executable scripts. For reporting security issues in dependencies you use locally, follow your organization’s process; general guidance appears on [skills.sh docs](https://skills.sh/docs). + +## Contributing + +Issues and pull requests are welcome. For substantive behavior changes, update `SKILL.md` and any affected files under `references/` so the skill stays internally consistent. + +## License + +MIT — see [LICENSE](LICENSE). diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..123d302 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,100 @@ +# design-dna + +**Language / 语言:** [English](README.md) · [简体中文](README.zh-CN.md) + +--- + +面向编程智能体（Cursor、Claude Code、Codex 等，完整列表见 [skills CLI 文档](https://github.com/vercel-labs/skills#supported-agents)）的 [Agent Skill](https://agentskills.io)。它提供一套结构化流程，把视觉设计身份整理成可机读的「Design DNA」，并覆盖三个层面：**设计系统（可度量 token）**、**设计风格（定性感受）**与**视觉特效（非常规纯 CSS 的表现）**。 + +可通过开源 [`skills` CLI](https://github.com/vercel-labs/skills) 从本仓库安装。更多技能见 [skills.sh](https://skills.sh/)。 + +## 功能概览 + +| 维度 | 说明 | +|------|------| +| **设计系统** | 可度量 token：色彩、字体、间距、版式、形状、层级、动效、组件等 | +| **设计风格** | 定性描述：情绪、视觉语言、构图、图像风格、交互气质、品牌语气等 | +| **视觉特效** | 超出「普通 CSS」的实现：Canvas、WebGL、3D、粒子、着色器、滚动驱动动效、光标效果、SVG 动画、玻璃拟态等 | + +技能内置 **三阶段** 工作流： + +1. **结构** — 展示完整 schema 与各字段含义（见 `references/schema.md`）。 +2. **分析** — 根据截图、图片或 URL，输出 **字段齐全的 JSON 画像**（无空字段；多参考冲突时注明主方案与变体）。 +3. **生成** — 在已有 DNA JSON + 内容的前提下落地实现（默认：自包含 HTML/CSS/JS），并遵循 `references/generation-guide.md` 中的质量检查。 + +各阶段可单独使用，也可串联（例如：分析 → 生成）。 + +## 安装 + +需要本机已安装 [Node.js](https://nodejs.org/)（用于 `npx`）。将本仓库发布到 GitHub 后，假设仓库为 `OWNER/REPO`： + +```bash +# 安装到 CLI 检测到的智能体（交互式） +npx skills add OWNER/REPO + +# 示例：仓库为 github.com/your-username/design-dna +npx skills add your-username/design-dna + +# 仅 Cursor、非交互、安装到用户全局目录 +npx skills add your-username/design-dna -a cursor -g -y +``` + +**只列出仓库内技能、不安装：** + +```bash +npx skills add https://github.com/OWNER/REPO --list +``` + +**从本地路径安装：** + +```bash +npx skills add /path/to/design-dna -a cursor -y +``` + +安装后的具体路径因智能体而异；Cursor 请参阅 [Cursor Skills 文档](https://cursor.com/docs/context/skills)（全局安装常见位置为 `~/.cursor/skills/`）。 + +## 仓库结构 + +``` +design-dna/ +├── SKILL.md # 技能入口：YAML 头信息 + 智能体执行说明 +├── references/ +│ ├── schema.md # 完整 JSON 字段与语义 +│ └── generation-guide.md # 从 DNA 到实现与自检 +├── README.md # 英文说明 +├── README.zh-CN.md # 本文件（中文） +├── LICENSE +└── .gitignore +``` + +`SKILL.md` 通过相对路径引用 `references/`；Fork 或再发布时请保持该目录关系。 + +## 何时应加载本技能 + +`SKILL.md` 的 `description` 中列出了英文触发词。概括而言，适合在用户需要以下任一能力时使用： + +- 查看或讲解 **Design DNA 的结构 / schema** +- 根据 **参考图、截图或网页 URL** 做结构化 **分析并输出 JSON** +- 在已有 **DNA JSON** 的前提下 **生成界面或原型** +- 明确涉及 **视觉特效**（WebGL、粒子、着色器、滚动场景等）的分析或实现 + +## 兼容性 + +- 符合 [Agent Skills 规范](https://agentskills.io)。 +- 可通过 [`vercel-labs/skills` CLI](https://github.com/vercel-labs/skills) 安装到 [其支持的智能体](https://github.com/vercel-labs/skills#supported-agents)。 + +## 与 skills.sh 排行榜的关系 + +[skills.sh](https://skills.sh/) 上的排序依据 `skills` CLI 上报的 **匿名聚合安装数据**（见[官方说明](https://skills.sh/docs)），**没有**单独的「提交上架」流程。将仓库公开到 GitHub，并在 README 或文章中分享 `npx skills add owner/repo`，即完成对外发布；安装量提升后，更容易在排行榜中被看到。 + +## 安全说明 + +安装任何技能前请自行审阅仓库内容。本仓库仅包含 Markdown 说明与参考文档，**不包含**可执行脚本。若需报告与生态相关的安全问题，可参考 [skills.sh 文档](https://skills.sh/docs)中的指引。 + +## 贡献 + +欢迎提 Issue 与 Pull Request。若修改技能行为，请同步更新 `SKILL.md` 及 `references/` 下相关文件，保持文档与行为一致。 + +## 许可证 + +MIT — 见 [LICENSE](LICENSE)。 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..3445a96 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,104 @@ +--- +name: design-dna +description: >- + Extract, define, and apply design DNA across three dimensions: design system + (tokens), design style (qualitative feel), and visual effects (Canvas, WebGL, + 3D, particles, shaders, scroll effects, etc.). Use this skill when: (1) a user + wants to see the full 3-dimension design structure/schema, (2) a user provides + images, screenshots, or URLs of reference designs and wants them analyzed into + a structured JSON profile covering all three dimensions, (3) a user has a + Design DNA JSON and content and wants a design generated from it, or (4) any + combination of these phases. Triggers on "design DNA", "extract design style", + "analyze design", "design tokens from reference", "generate design from JSON", + "design system from screenshot", "design profile", "style guide JSON", + "visual effects analysis", "design with effects", "3d design analysis". +--- + +# Design DNA + +A 3-phase workflow for extracting, structuring, and applying design identity across three dimensions: + +1. **Design System** — measurable tokens (color, typography, spacing, layout, shape, elevation, motion, components) +2. **Design Style** — qualitative perception (mood, visual language, composition, imagery, interaction feel, brand voice) +3. **Visual Effects** — special rendering (Canvas, WebGL, 3D, particles, shaders, scroll effects, cursor effects, SVG animations, glassmorphism, etc.) + +## Phases + +### Phase 1: Structure — Output the Schema + +When the user asks for the structural dimensions or schema: + +1. Read [references/schema.md](references/schema.md) +2. Present the full schema with field descriptions +3. Explain the three dimensions and their roles: + - **design_system**: What you can measure — exact hex values, pixel sizes, rem scales + - **design_style**: What you can feel — mood, personality, composition strategy + - **visual_effects**: What you can see but can't express in CSS alone — WebGL scenes, particle systems, shader distortions, scroll-driven animations +4. Ask if the user wants to customize or extend any dimensions + +### Phase 2: Analyze — Extract DNA from References + +When the user provides images, screenshots, or links representing a target design style: + +1. Read [references/schema.md](references/schema.md) for the full field list +2. For each reference provided: + - If image/screenshot: analyze visual properties directly + - If URL: fetch and analyze the page's visual design +3. For every field in the schema, extract or infer a value from the references +4. When multiple references conflict, note the dominant pattern and mention variants +5. Output a complete Design DNA JSON — every field populated, no empty strings +6. After output, ask: "Want to adjust any values before using this for generation?" + +**Analysis approach per dimension:** + +#### Dimension 1: design_system +- **color**: Extract dominant palette via visual sampling. Primary by area dominance, secondary by supporting role, accent by CTA usage. Map neutral scale from lightest background to darkest text. +- **typography**: Identify font families by visual characteristics (geometric, humanist, serif class). Estimate scale ratios from heading/body size relationships. +- **spacing**: Assess density by element proximity. Measure rhythm by section gap consistency. +- **layout**: Identify grid by content alignment patterns. Note max-width, column count, asymmetry. +- **shape**: Measure border-radius by comparing to element height. Note border and divider presence. +- **elevation**: Classify shadow softness, spread, and layering approach. +- **motion**: If observable (video/interactive), note easing curves and duration feel. + +#### Dimension 2: design_style +- Synthesize holistic impressions — mood, personality, composition strategy +- Compare against genre archetypes (SaaS, editorial, brutalist, etc.) +- Note ornamentation level and whitespace philosophy + +#### Dimension 3: visual_effects +- **From code**: Scan for ``, WebGL contexts, Three.js/Pixi.js imports, GSAP/Lottie usage, custom shaders, IntersectionObserver scroll triggers, SVG `` elements +- **From screenshots**: Describe visible effects that go beyond standard CSS — glowing particles, 3D object renders, noise textures, gradient animations, parallax depth, cursor trails, text distortions, glassmorphic surfaces. Note these in `composite_notes` when exact implementation can't be determined. +- **From video/interaction demos**: Note scroll behaviors, hover distortions, transition choreography, loading sequences +- Set `enabled: false` for any effect category not present in the reference +- Rate `overview.effect_intensity` and `overview.performance_tier` based on what's observed + +### Phase 3: Generate — Apply DNA to Content + +When the user provides DNA JSON + content to design: + +1. Read [references/generation-guide.md](references/generation-guide.md) +2. Parse the DNA JSON and extract all tokens across three dimensions +3. Build CSS custom properties from `design_system` values +4. Apply `design_style` qualitative fields to guide subjective design decisions +5. When the design needs assets or source materials, fetch them from the original source whenever possible. If the user provided a URL, retrieve the real asset from that URL instead of recreating, approximating, or substituting it. +6. Implement `visual_effects` using appropriate technologies: + - Lightweight effects → CSS animations, SVG, vanilla JS + - Medium effects → Canvas 2D, GSAP, Lottie + - Heavy effects → Three.js, custom GLSL shaders, Pixi.js +7. Generate the design output (default: self-contained HTML with inline CSS/JS) +8. Run quality checks from the generation guide + +**If the user provides only content without DNA JSON**, ask whether to: +- Analyze a reference first (go to Phase 2) +- Use a described style (extract DNA from description, then generate) + +## Phase Combinations + +Users may invoke any combination: +- **Phase 1 only**: "Show me the design structure/schema" +- **Phase 2 only**: "Analyze this design" (with images/links) +- **Phase 2 → 3**: "Analyze this design and build me a landing page in the same style" +- **Phase 1 → 2 → 3**: Full pipeline +- **Phase 3 only**: User already has DNA JSON + +Detect which phase(s) are needed from context and execute accordingly. diff --git a/references/generation-guide.md b/references/generation-guide.md new file mode 100644 index 0000000..29fd737 --- /dev/null +++ b/references/generation-guide.md @@ -0,0 +1,209 @@ +# Generation Guide + +How to use a completed Design DNA JSON to generate designs in Phase 3. Covers all three dimensions. + +## Priority Order + +When generating a design from DNA JSON + content: + +1. **Color & Typography** — define 80% of visual identity +2. **Spacing & Layout** — structural rhythm +3. **Shape & Elevation** — surface treatment +4. **Design Style qualitative fields** — mood, personality, composition approach +5. **Visual Effects** — special rendering layer (Canvas, WebGL, shaders, etc.) +6. **Motion & Interaction** — enhance after static layout and effects are solid + +## Dimension 1: design_system → Code + +### Tailwind CSS / Utility-First +``` +color.primary.hex → --color-primary / bg-[hex] +typography.font_families → font-family config +spacing.scale → spacing config values +shape.border_radius → rounded-{sm|md|lg|full} +elevation.levels → shadow-{sm|md|lg} +``` + +### Plain CSS / CSS Variables +Generate a `:root` block with all design tokens: +```css +:root { + --color-primary: {color.primary.hex}; + --color-secondary: {color.secondary.hex}; + --color-accent: {color.accent.hex}; + --font-heading: {typography.font_families.heading}; + --font-body: {typography.font_families.body}; + --radius-sm: {shape.border_radius.small}; + --radius-md: {shape.border_radius.medium}; + --radius-lg: {shape.border_radius.large}; + --shadow-low: {elevation.levels.low}; + --shadow-med: {elevation.levels.medium}; + --shadow-high: {elevation.levels.high}; + --ease: {motion.easing}; + --duration-micro: {motion.duration_scale.micro}; + --duration-normal: {motion.duration_scale.normal}; + --duration-macro: {motion.duration_scale.macro}; + /* ... map all tokens */ +} +``` + +### Component Decisions +- `components.button_style` → button classes and variants +- `components.card_style` → card container treatment +- `components.navigation_pattern` → nav component choice +- `interaction_feel.hover_behavior` → :hover / :focus states +- `motion.easing` + `motion.duration_scale` → transition properties + +## Dimension 2: design_style → Subjective Decisions + +| DNA Field | Guides | +|---|---| +| aesthetic.mood | Overall emotional feeling — warm tones, cool precision, etc. | +| visual_language.whitespace_usage | padding/margin generosity | +| visual_language.contrast_level | How much elements pop vs. blend | +| composition.hierarchy_method | What tool to use for emphasis | +| composition.balance_type | Symmetric layout vs. dynamic asymmetry | +| imagery.graphic_elements | Decorative SVGs, gradients, patterns | +| brand_voice_in_ui.tone | Microcopy phrasing | +| interaction_feel.microinteraction_density | How many hover/click effects | + +## Dimension 3: visual_effects → Special Rendering + +### Technology Selection by Performance Tier + +| Tier | Technologies | When to Use | +|---|---|---| +| **lightweight** | CSS animations, SVG SMIL, vanilla JS | `overview.performance_tier` = "lightweight" | +| **medium** | Canvas 2D, GSAP, Lottie, anime.js | `overview.performance_tier` = "medium" | +| **heavy** | Three.js, custom GLSL, Pixi.js, WebGL | `overview.performance_tier` = "heavy" | + +### Implementation Patterns + +#### Background Effects +``` +"none" → skip +"gradient-animation" → CSS @keyframes on linear-gradient or conic-gradient +"noise-field" → Canvas 2D with Perlin/simplex noise +"mesh-gradient" → SVG or canvas interpolation +"video-bg" →