如何向StyleKit贡献新风格:STYLE_ADDITION_CHECKLIST六大必备源完整流程

原创2026-11-01 16:56:101,938 阅读

如何向StyleKit贡献新风格:STYLE_ADDITION_CHECKLIST六大必备源完整流程

想给开源设计工具 StyleKit(一个收录 149 种网页与 UI 设计风格、每种都附带可复制的 AI 提示词、设计 tokens 与组件配方的项目)贡献新风格,却不知道从哪下手?别慌。这篇指南把 docs/STYLE_ADDITION_CHECKLIST.md 里的官方流程,翻译成人话:一次完整的新风格贡献,需要 6 个新建文件 + 6 个注册表登记,只要按「六大必备源」一步步走完,你的风格就能被 AI 稳定读取和应用。

StyleKit 项目封面:收录 149 种 UI 设计风格、设计 tokens 与组件配方的开源设计工具

💡 核心关键词:StyleKit 贡献新风格 · 六大必备源 · STYLE_ADDITION_CHECKLIST · 设计 tokens · 组件配方


一、先认识「六大必备源」

一个风格在 StyleKit 里不是「一个文件」,而是一组互相咬合的文件。只要任意一个源缺失、slug 对不上,这个风格就不算完整。docs/STYLE_AUTHORING.md 的「Required Sources」把它们定义为 6 类,每个源都包含「定义文件 + 注册表登记」两部分:

# 必备源 定义文件(新建) 注册表登记(修改)
1 风格定义 lib/styles/{slug}.ts lib/styles/registry.ts
2 轻量元数据 — lib/styles/meta-registry.ts
3 设计 tokens lib/styles/{slug}-tokens.ts lib/styles/tokens-registry-data.ts
4 组件配方 lib/recipes/{slug}.ts lib/recipes/registry.ts
5 封面资源 public/styles/{slug}.svg —
6 展示页面 app/styles/{slug}/showcase/ —

加上风格自带的预览模块 lib/style-preview/styles/{slug}.tsx(含 coverPreview)和两个预览登记表,就凑齐了清单里说的「7 新建 + 6 修改」。


二、开发环境搭建:一键跑通本地

贡献前先本地起服务。技术栈是 Next.js 16 + TypeScript(严格模式)+ Tailwind CSS 4,包管理器固定用 pnpm。

# Clone the repo
git clone https://gitcode.com/gh_mirrors/styl/stylekit.git
cd stylekit

# 安装依赖(必须用 pnpm)
pnpm install

# 启动开发服务器
pnpm dev

打开 localhost:3000 看到风格库画廊,就说明环境 OK 了。多数 UI 工作不需要数据库凭据,可以跳过 .env 配置。


三、贡献前预检:Pre-Flight 清单

动笔前,先把这几项想清楚(来自 docs/STYLE_ADDITION_CHECKLIST.md 的 Pre-Flight):

  • [ ] 确定 slug(小写 kebab-case,例如 warm-dashboard,全文统一)
  • [ ] 准备 3–5 个主色(带 hex)
  • [ ] 找出 5–10 个标志性视觉特征
  • [ ] 确定 styleType:visual | layout | both
  • [ ] 选一个 category:modern | classic | expressive | cultural | functional

⚠️ slug 是全流程的「身份证号」:风格定义、tokens、配方、封面、路由必须用完全一致的 slug,错一个字都会挂测试。


四、六大必备源逐个拆解

源 1:风格定义文件 📝

lib/styles/{slug}.ts 是整个风格的「大脑」,导出一个 DesignStyle 对象。可参考现成例子 lib/styles/warm-dashboard.ts,它定义了 slug、name/nameEn、description、cover、colors(primary/secondary/accent[])、keywords(中文搜索词)、philosophy(设计哲学)、doList(必须做的 6–8 条)、dontList(禁止的 4–6 条)、各组件 code 片段、globalCss、aiRules 与 examplePrompts。

StyleKit 设计风格示例:neo-brutalist 新野兽派风格的视觉预览参考

源 2:设计 tokens 文件 🎨

lib/styles/{slug}-tokens.ts 是给 AI 直接消费的 Tailwind 映射。用 lib/styles/token-defaults.ts 里的 createStyleTokens()(深合并提供默认值),只覆盖和默认不同的字段:

  • colors:background / text / button(风格专属色)
  • forbidden:永远不能用的类
  • required:必须用到的类(需在每种配方变体与参数组合里出现)
import { createStyleTokens } from "./token-defaults";

export const myStyleTokens = createStyleTokens({
  colors: { background: { primary: "bg-black" } },
  border: { radius: "rounded-none" },
  forbidden: { classes: ["rounded-lg"], patterns: [], reasons: {} },
  required: { button: ["font-mono"], card: ["border-2"], input: ["bg-transparent"] },
});

源 3:组件配方文件 🧩

lib/recipes/{slug}.ts 是组件配方:按钮、卡片、输入框至少要有,导航、徽章、表格等可选。用 lib/recipes/factory.ts 的 createStyleRecipes() 和一堆助手(sizeParam、fullWidthParam、interactiveParam、buttonSlots、variant 等)来描述尺寸/内边距参数、变体与交互状态,AI 据此生成可复制的组件代码。

源 4:注册表登记 📚(6 处,别漏一个)

定义文件建好后,要在对应注册表「挂号」,风格才会出现在库里:

注册表 加什么
lib/styles/registry.ts import + styles 数组追加 styleName
lib/styles/meta-registry.ts stylesMeta 追加条目(slug/name/cover/color…)
lib/styles/tokens-registry-data.ts import + "{slug}": styleNameTokens
lib/recipes/registry.ts import + "{slug}": styleNameRecipes
lib/style-preview/registry.ts import + {slug} 条目
lib/style-preview/delivery.ts 懒加载器 + stylePreviewSlugs 追加 {slug}

源 5:封面资源 🖼️(关键)

public/styles/{slug}.svg,尺寸固定 1200x630。注意:必须画出迷你 UI 组件(四角布局:卡片、按钮、徽章、表单 + 中央标题区),不能只写风格名。清单给了参考样例:neo-brutalist.svg(硬阴影+网格)、neumorphism.svg(浮雕软阴影)、dark-academia.svg(皮革纹理+金边)。

源 6:展示页面 + 预览模块 ✨

app/styles/{slug}/showcase/ 下要两个文件:

  • page.tsx:动态加载包装器(带 loading 骨架)
  • _content.tsx:加 "use client",至少 400–600 行、12 个以上分区、2 个以上 useState(导航、Hero、色板、排版、按钮、卡片、表单、Tabs、徽章、进度、Alerts、表格、引用、分隔、do/don't 汇总、Footer)

同时 lib/style-preview/styles/{slug}.tsx 要导出人工批准过的预览渲染器,必含 coverPreview,支持时再加 button/card/input。

StyleKit 设计风格预览:glassmorphism 玻璃拟态风格的高清视觉示例


五、统一发布流程:用 publishStyle 一次写完

别手动散着改一堆注册表。可信的发布入口只有一个 seam——lib/style-publication/ 的 publishStyle:

import { publishStyle } from "@/lib/style-publication";

const result = await publishStyle(input, process.cwd());

它接收一个 StyleScaffoldInput,先 plan 后 commit:规划并校验所有生成文件与 6 个注册表投影,全部通过才写入;一旦 commit 失败,自动回滚已写入的内容(含生成文件)。input 必须包含一个明确编写、产品批准的 previewModule(带 coverPreview)——发布器不会替你「脑补」一个通用预览。

清单里那些注册表项,在这里更像是review 断言或手动恢复步骤,而不是独立的发布操作。


六、验证清单:提交前全绿才敢提 PR

按 docs/STYLE_ADDITION_CHECKLIST.md 的 Verification 阶段:

# 类型检查
npx tsc --noEmit

# 配方契约(required / forbidden 校验)
pnpm run check:recipe-lint

# 单测(styles-consistency / style-assets / recipes-integrity 自动跑)
pnpm test

# 本地起服务做视觉检查
pnpm run dev

然后访问三个页面手动确认:/styles(画廊里有你的封面)、/styles/{slug}(文档页加载)、/styles/{slug}/showcase(所有分区渲染),并测一遍移动端 / 平板 / 桌面响应式。提交 PR 前再补一轮本地验证(pnpm run lint、pnpm run security:secrets、pnpm build),CI 会跑同样的检查。


七、六大常见错误速查表 ❗

清单末尾专门列了「Common Mistakes」,新手最常踩这 6 个坑:

坑 一句话解法
忘记展示页 page.tsx 和 _content.tsx 两个都要建
封面只有文字 封面必须画 UI 组件,不能只有风格名
缺 coverPreview 预览模块里必含 coverPreview
slug 不一致 所有文件用完全相同的 slug
漏加 import 记得在对应注册表里加导入与条目
展示页没交互 加 useState(tabs / 下拉 / 分页等)

八、快速复制模板 + 总结

清单提供了一键建文件骨架的命令(把 {slug} 换成你的风格名):

mkdir -p app/styles/{slug}/showcase
touch lib/styles/{slug}.ts
touch lib/styles/{slug}-tokens.ts
touch lib/recipes/{slug}.ts
touch app/styles/{slug}/showcase/page.tsx
touch app/styles/{slug}/showcase/_content.tsx
touch public/styles/{slug}.svg

一句话总结: 向 StyleKit 贡献新风格 = 把「六大必备源」按 slug 严格对齐地建齐(风格定义 / tokens / 配方 / 注册表登记 / 封面 / 展示页 + 预览模块),用 publishStyle 一次发布,再把类型检查、配方 lint 和单测跑全绿。照着 docs/STYLE_ADDITION_CHECKLIST.md 走,你的风格就能稳稳进入那 149 种风格的设计库。🚀

登录后查看全文
stylekit