stitch-design-system

Name: stitch-design-system
Author: gabelul

github.com/gabelul设计与 UI4749 次安装14 周前更新

代码仓库

关于 stitch-design-system

一项分析 Stitch 设计并生成项目实现文件的技能，包括 CSS 设计令牌、Tailwind 配置和扩展设计文档，适合作为后续组件生成和设计系统更新的基础。

主要功能

01生成 CSS 自定义属性
02创建 Tailwind v4 主题 CSS
03生成扩展版 DESIGN.md
04包含浅色与深色令牌
05提取 Stitch 设计数据

适用场景

01以 Stitch 设计启动代码项目
02在 Stitch 设计变更后更新令牌
03组件生成前准备设计基础

MCP 相关

它使用 Stitch MCP 工具获取项目主题和界面，再分析返回的设计数据以生成代码文件。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gabelul/stitch-kit --skill stitch-design-system

安装后在 Claude Code 中输入/stitch-design-system确认已加载。

附带文件resources/tokens-template.css

详细介绍

Stitch → 设计系统代码产物

你是一名设计系统工程师。你分析 Stitch 设计并生成代码产物，而不只是文档。design-md 技能会生成便于人类阅读的 Markdown 文件，而此技能会生成可直接导入代码库的文件：支持深色模式的 CSS 自定义属性、Tailwind v4 配置和排版令牌。

请先使用此技能，再使用 stitch-nextjs-components 或 stitch-svelte-components。 生成的令牌将成为后续所有组件生成工作的基础。

何时使用此技能

在以下情况下使用此技能：

从 Stitch 设计开始新项目
用户提到“设计令牌”“CSS 变量”“深色模式令牌”或“Tailwind 配置”
在使用框架转换技能前运行，以确保设计一致性
Stitch 设计更新后，更新现有项目的设计系统

此技能生成的内容

三个输出文件：

文件	用途
`design-tokens.css`	CSS 自定义属性——在框架的全局 CSS 中导入此文件
`tailwind-theme.css`	Tailwind v4 `@theme` 块——粘贴到 `globals.css` 中
`DESIGN.md`	扩展版设计文档（比 `design-md` 更丰富，包含深色模式和动画令牌）

第 1 步：获取 Stitch 设计

发现命名空间——运行 list_tools，查找 Stitch MCP 前缀。
获取屏幕——使用 projectId 和 screenId 调用 [prefix]:get_screen。

下载 HTML——运行：

bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"

视觉参考——查看 screenshot.downloadUrl，了解完整设计意图。

如果存在多个屏幕，请全部获取。运行 [prefix]:list_screens 并逐一获取，以确保令牌集涵盖设计中的每种模式。

第 1.5 步：读取项目 DesignTheme（权威依据）

解析 HTML 前，从 Stitch API 获取权威设计数据。这样无需猜测——API 会提供准确的主色、字体和完整的语义颜色映射。

调用 get_project，并传入 projects/[projectId]
检查是否存在 designMd——如果存在，它就是 Stitch 自动生成的完整 Markdown 设计系统文档。解析其中的排版规则、色彩理念、组件模式、间距指南及注意事项。这是最有价值的单个字段。
提取 namedColors——一个包含 40 多个令牌的语义颜色映射，可直接获取预先计算好的完整颜色系统：
- Primary：primary、on_primary、primary_container、on_primary_container、primary_fixed、primary_fixed_dim
- Secondary：secondary、on_secondary、secondary_container、on_secondary_container
- Tertiary：遵循相同模式
- Surfaces：surface、surface_dim、surface_bright、surface_container_lowest、surface_container_low、surface_container、surface_container_high、surface_container_highest、surface_tint、surface_variant
- Utility：background、on_background、on_surface、on_surface_variant、outline、outline_variant
- States：error、on_error、error_container、on_error_container
- Inverse：inverse_surface、inverse_on_surface、inverse_primary
提取结构化值： | DesignTheme 字段 | → CSS 令牌 | 映射 | |---|---|---| | customColor | --color-primary | 十六进制种子值 — 但如果有 namedColors.primary，优先使用 | | overridePrimaryColor | --color-primary | 优先级高于 customColor | | overrideSecondaryColor | --color-secondary | 精确的十六进制覆盖值 | | overrideTertiaryColor | --color-tertiary | 精确的十六进制覆盖值 | | overrideNeutralColor | --color-neutral | 表面层级的基色 | | backgroundLight | --color-background（浅色） | 浅色模式页面背景 | | backgroundDark | --color-background（深色） | 深色模式页面背景 | | headlineFont | --font-sans / 标题 | 将枚举映射为 font-family 字体栈（见下表） | | bodyFont | --font-body | 将枚举映射为 font-family 字体栈 | | labelFont | --font-label | 将枚举映射为 font-family 字体栈 | | roundness | --radius-md 基准值 | ROUND_FOUR=4px，ROUND_EIGHT=8px，ROUND_TWELVE=12px，ROUND_FULL=9999px（ROUND_TWO 也存在，但已弃用/未使用） | | spacingScale | 间距乘数 | 0=紧凑（基准值 2px），1=较紧凑（基准值 4px），2=常规（基准值 4px），3=宽松（基准值 8px） | | spacing | --space-* 覆盖值 | 可选的间距令牌名称 → CSS 值映射（例如 {"sm": "8px"}）——如果存在，则替代 spacingScale | | typography | --text-* / --font-* 覆盖值 | 可选的级别名称（h1、body 等）→ Typography 令牌映射（fontFamily、fontSize、fontWeight、letterSpacing、lineHeight） | | colorVariant | 用于确定调色板方案 | 例如，FIDELITY 表示保持品牌颜色，VIBRANT 表示提高饱和度 |

字体枚举 → CSS font-family 映射：

Stitch 枚举	CSS 字体系列
`INTER`	`'Inter', system-ui, sans-serif`
`DM_SANS`	`'DM Sans', system-ui, sans-serif`
`GEIST`	`'Geist', system-ui, sans-serif`
`SPACE_GROTESK`	`'Space Grotesk', system-ui, sans-serif`
`MANROPE`	`'Manrope', system-ui, sans-serif`
`PLUS_JAKARTA_SANS`	`'Plus Jakarta Sans', system-ui, sans-serif`
`WORK_SANS`	`'Work Sans', system-ui, sans-serif`
`IBM_PLEX_SANS`	`'IBM Plex Sans', system-ui, sans-serif`
`RUBIK`	`'Rubik', system-ui, sans-serif`
`SORA`	`'Sora', system-ui, sans-serif`
`EPILOGUE`	`'Epilogue', system-ui, sans-serif`
`NUNITO_SANS`	`'Nunito Sans', system-ui, sans-serif`
`LEXEND`	`'Lexend', system-ui, sans-serif`
`PUBLIC_SANS`	`'Public Sans', system-ui, sans-serif`
`SOURCE_SANS_3`	`'Source Sans 3', system-ui, sans-serif`
`SOURCE_SANS_THREE`	`'Source Sans 3', system-ui, sans-serif` — 已弃用的别名，建议使用 `SOURCE_SANS_3`
`MONTSERRAT`	`'Montserrat', system-ui, sans-serif`
`HANKEN_GROTESK`	`'Hanken Grotesk', system-ui, sans-serif`
`ARIMO`	`'Arimo', system-ui, sans-serif`
`BE_VIETNAM_PRO`	`'Be Vietnam Pro', system-ui, sans-serif`
`SPLINE_SANS`	`'Spline Sans', system-ui, sans-serif`
`METROPOLIS`	`'Metropolis', system-ui, sans-serif` — 已弃用，没有直接替代项
`JETBRAINS_MONO`	`'JetBrains Mono', ui-monospace, monospace`
`GOOGLE_SANS_CODE`	`'Google Sans Code', ui-monospace, monospace`
`SPACE_MONO`	`'Space Mono', ui-monospace, monospace`
`BEBAS_NEUE`	`'Bebas Neue', system-ui, sans-serif` — 窄体展示字体
`ANTON`	`'Anton', system-ui, sans-serif` — 窄体展示字体
`ARCHIVO_NARROW`	`'Archivo Narrow', system-ui, sans-serif` — 窄体
`EB_GARAMOND`	`'EB Garamond', Georgia, serif`
`LITERATA`	`'Literata', Georgia, serif`
`SOURCE_SERIF_4`	`'Source Serif 4', Georgia, serif`
`SOURCE_SERIF_FOUR`	`'Source Serif 4', Georgia, serif` — 已弃用的别名，建议使用 `SOURCE_SERIF_4`
`LIBRE_CASLON_TEXT`	`'Libre Caslon Text', Georgia, serif`
`NEWSREADER`	`'Newsreader', Georgia, serif`
`DOMINE`	`'Domine', Georgia, serif`
`NOTO_SERIF`	`'Noto Serif', Georgia, serif`
`PLAYFAIR_DISPLAY`	`'Playfair Display', Georgia, serif` — 编辑风格展示字体
`BODONI_MODA`	`'Bodoni Moda', Georgia, serif` — 编辑风格展示字体

以这些作为基准。 然后仅针对 API 未提供的值使用 HTML 分析（步骤 2）：动效/过渡时长、精确的像素间距值、阴影定义，以及 namedColors 集合之外的其他颜色。

如果有 namedColors， 则完全跳过步骤 2 中的颜色提取——API 的颜色映射权威且完整。只需从 HTML 补充动效、像素间距值和阴影。

如果有 designMd， 将其作为 DESIGN.md 输出（步骤 5）的基础。不要重写，而是补充 CSS 变量名称、Tailwind 映射和实现说明。

步骤 2：从 HTML 中提取补充值

如果步骤 1.5 提供了 namedColors 和 designMd，HTML 中只需提取以下内容：

动效

使用的过渡时长（或推断：微交互为 150ms，面板为 300ms）
缓动样式（linear、ease-out、类似弹簧的效果）

像素间距值

设计中使用的精确间隙/内边距值
阴影定义

其他颜色（少见）

仅当设计使用了 namedColors 中没有的颜色时才提取——检查渐变、叠加层或自定义强调色。

如果步骤 1.5 未提供 namedColors（没有 designMd 的旧项目），则改为完整提取 HTML：

颜色（备用方案）

从 <head> 中的 Tailwind 配置识别每种不同的颜色，或根据截图推断。为每种颜色确定语义角色和使用频率。目标是提取 8–12 个语义令牌。

字体排印（备用方案）

字体系列（标题、正文、等宽字体——如有）
字号比例（设计中实际使用的 px 或 rem 值）
使用的字重
行高

间距与几何属性（备用方案）

基础间距单位（通常为 4px 或 8px）
边框圆角值
阴影定义

第 3 步：生成 `design-tokens.css`

创建包含完整浅色和深色模式令牌集的 design-tokens.css。

命名约定：

--color-* — 颜色令牌
--font-* — 字体排印
--spacing-* — 间距比例
--radius-* — 边框圆角
--shadow-* — 立体效果
--motion-* — 动画时长

模板（当 API 提供 namedColors 时——首选）：

/* =============================================================
   Design Tokens — extracted from Stitch project: [Project Name]
   Generated by stitch-design-system skill
   Source: DesignTheme API (namedColors) + HTML supplementary
   ============================================================= */

/* ---- Light mode (default) ---- */
:root {
  /* Colors: Direct mapping from Stitch namedColors API response */
  --color-primary:          [namedColors.primary];
  --color-on-primary:       [namedColors.on_primary];
  --color-primary-container: [namedColors.primary_container];
  --color-secondary:        [namedColors.secondary];
  --color-on-secondary:     [namedColors.on_secondary];
  --color-tertiary:         [namedColors.tertiary];
  --color-on-tertiary:      [namedColors.on_tertiary];
  --color-error:            [namedColors.error];
  --color-on-error:         [namedColors.on_error];
  --color-background:       [namedColors.background];
  --color-on-background:    [namedColors.on_background];
  --color-surface:          [namedColors.surface];
  --color-on-surface:       [namedColors.on_surface];
  --color-surface-variant:  [namedColors.surface_variant];
  --color-on-surface-variant: [namedColors.on_surface_variant];
  --color-surface-container: [namedColors.surface_container];
  --color-surface-container-low: [namedColors.surface_container_low];
  --color-surface-container-high: [namedColors.surface_container_high];
  --color-surface-container-highest: [namedColors.surface_container_highest];
  --color-outline:          [namedColors.outline];
  --color-outline-variant:  [namedColors.outline_variant];
  --color-inverse-surface:  [namedColors.inverse_surface];
  --color-inverse-on-surface: [namedColors.inverse_on_surface];
  --color-inverse-primary:  [namedColors.inverse_primary];
  --color-surface-tint:     [namedColors.surface_tint];

  /* Typography */
  --font-sans:    [font-family-stack];   /* Heading and UI font */
  --font-body:    [font-family-stack];   /* Body text font (may equal --font-sans) */
  --font-mono:    [monospace-stack];     /* Code, technical content */

  /* Type scale */
  --text-xs:   0.75rem;   /* 12px */
  --text-sm:   0.875rem;  /* 14px */
  --text-base: 1rem;      /* 16px */
  --text-lg:   1.125rem;  /* 18px */
  --text-xl:   1.25rem;   /* 20px */
  --text-2xl:  1.5rem;    /* 24px */
  --text-3xl:  1.875rem;  /* 30px */
  --text-4xl:  2.25rem;   /* 36px */

  /* Spacing scale (base 4px) */
  --space-1:  0.25rem;   /* 4px */
  --space-2:  0.5rem;    /* 8px */
  --space-3:  0.75rem;   /* 12px */
  --space-4:  1rem;      /* 16px */
  --space-6:  1.5rem;    /* 24px */
  --space-8:  2rem;      /* 32px */
  --space-12: 3rem;      /* 48px */
  --space-16: 4rem;      /* 64px */

  /* Geometry */
  --radius-sm: [value];  /* Small elements: badges, chips */
  --radius-md: [value];  /* Buttons, inputs */
  --radius-lg: [value];  /* Cards, panels */
  --radius-xl: [value];  /* Modals, drawers */
  --radius-full: 9999px; /* Pills, avatars */

  /* Shadows */
  --shadow-sm: [value];  /* Subtle card lift */
  --shadow-md: [value];  /* Dropdown, tooltip */
  --shadow-lg: [value];  /* Modal, sheet */

  /* Motion tokens */
  --motion-duration-fast:   150ms;   /* Hover states, micro interactions */
  --motion-duration-base:   250ms;   /* Typical UI transitions */
  --motion-duration-slow:   400ms;   /* Page-level, large panel */
  --motion-ease-default:    cubic-bezier(0.4, 0, 0.2, 1);  /* Material ease */
  --motion-ease-out:        cubic-bezier(0, 0, 0.2, 1);    /* Entries */
  --motion-ease-in:         cubic-bezier(0.4, 0, 1, 1);    /* Exits */
  --motion-ease-spring:     cubic-bezier(0.34, 1.56, 0.64, 1); /* Bouncy open */
}

/* ---- Dark mode ---- */
/* Applied via .dark class (Next.js + next-themes) or [data-theme="dark"] (Svelte) */
.dark,
[data-theme="dark"] {
  --color-background:       [dark-hex];
  --color-surface:          [dark-hex];
  --color-surface-elevated: [dark-hex];
  --color-primary:          [dark-hex];  /* Same hue, lighter for dark bg contrast */
  --color-primary-hover:    [dark-hex];
  --color-primary-fg:       [dark-hex];
  --color-secondary:        [dark-hex];
  --color-secondary-fg:     [dark-hex];
  --color-text:             [dark-hex];
  --color-text-muted:       [dark-hex];
  --color-text-disabled:    [dark-hex];
  --color-border:           [dark-hex];
  --color-border-focus:     [dark-hex];
  --color-error:            [dark-hex];
  --color-success:          [dark-hex];
  --color-warning:          [dark-hex];
  /* Typography, spacing, geometry, motion tokens: unchanged in dark mode */
}

第 4 步：生成 `tailwind-theme.css`

对于使用 Tailwind v4（没有 tailwind.config.js）的项目，生成一个 @theme 块。

重要： Tailwind v4 在 CSS 中使用 @theme，而不是 JS 配置文件。将令牌映射到 Tailwind 的命名空间：

/* tailwind-theme.css — paste into your globals.css or import it */
@import "tailwindcss";

@theme {
  /* Wire Tailwind color utilities to your CSS variables */
  --color-background: var(--color-background);
  --color-surface: var(--color-surface);
  --color-primary: var(--color-primary);
  --color-primary-hover: var(--color-primary-hover);
  --color-text: var(--color-text);
  --color-text-muted: var(--color-text-muted);
  --color-border: var(--color-border);

  /* Fonts */
  --font-sans: var(--font-sans);
  --font-mono: var(--font-mono);

  /* Radius */
  --radius-sm: var(--radius-sm);
  --radius-md: var(--radius-md);
  --radius-lg: var(--radius-lg);

  /* Animation duration utilities */
  --animate-duration-fast: var(--motion-duration-fast);
  --animate-duration-base: var(--motion-duration-base);
  --animate-duration-slow: var(--motion-duration-slow);
}

对于 Tailwind v3 项目（带有 tailwind.config.js），则使用提取的十六进制值直接生成一个 tailwind.config.js 代码段。

第 5 步：生成 `DESIGN.md`

生成一份扩展版设计文档。它包含标准 design-md 技能中的所有章节，并额外包含：

# Design System: [Project Name]

> Generated by stitch-design-system from Stitch project [ID]
> Screens analyzed: [list]

## 1. Visual Theme & Atmosphere
[Mood, density, aesthetic philosophy — 2-3 sentences]

## 2. Color Palette & Roles
| Token | Light | Dark | Role |
|-------|-------|------|------|
| --color-primary | #... | #... | Main CTA, key actions |
| --color-background | #... | #... | Page background |
| ... | | | |

## 3. Typography
- **Heading font**: [Family, weights used, where]
- **Body font**: [Family, weights used, where]
- **Type scale**: xs (12px) → sm (14px) → base (16px) → lg (18px) → ... → 4xl (36px)

## 4. Geometry & Elevation
- **Border radius**: sm [Xpx] | md [Xpx] | lg [Xpx] | xl [Xpx]
- **Shadows**: [describe the elevation system]

## 5. Motion System
- **Micro** (hovers, toggles): [duration]ms [easing]
- **Meso** (panels, drawers): [duration]ms [easing]
- **Macro** (page transitions): [duration]ms [easing]
- **Spring** (playful elements): cubicOut spring

## 6. Stitch Prompt Copy-Paste Block
Use this block in every Stitch prompt for design consistency:

[主色：NAME（#HEX）] — 用于按钮和关键操作 [背景：#HEX] — 简洁且[情绪形容词] [字体排印：FONT NAME] — 标题使用 [字重]，正文使用常规字重 [美学风格：2–3 个形容视觉风格的形容词] [边框圆角：SIZE — 圆润／锐利／胶囊形元素]


## 7. Dark Mode Notes
[Specific notes on how the dark theme differs — any color roles that change significantly, any elements that need special treatment in dark mode]

第 6 步：输出与集成

将这三个文件写入项目根目录（或用户指定的位置）：

design-tokens.css
tailwind-theme.css
DESIGN.md

然后告知用户如何使用它们：

对于 Next.js：

// app/globals.css
@import '../design-tokens.css';
@import '../tailwind-theme.css';

对于 SvelteKit：


@import '$lib/design-tokens.css';

对于 Stitch 工作流：

将 DESIGN.md 中的第 6 节复制到每个 Stitch 提示词中，以确保生成的屏幕设计保持一致。

故障排除

问题	解决方法
无法确定深色模式的十六进制值	使用浅色模式的色相，稍微降低饱和度，并将亮度提高 30–40%
字体未加载	在 `design-tokens.css` 中添加 Google Fonts `@import`
混淆 Tailwind v3 和 v4	检查 `package.json`——v4 使用 `"tailwindcss": "^4"`，且没有配置文件
令牌未生效	确保在组件 CSS 之前导入 `design-tokens.css`

与其他技能集成

在使用 stitch-nextjs-components 或 stitch-svelte-components 之前运行此技能
框架技能会导入 design-tokens.css，而不是将值硬编码
DESIGN.md 第 6 节会提供给 stitch-loop，以确保多页面设计一致

参考资料

resources/tokens-template.css — 包含所有令牌类别的完整模板

支持 Markdown

登录后评论