简介这是一份面向Web前端开发者、UI/UX设计师及开源项目贡献者的综合性设计资源库聚焦于开放协作式Web开发实践解决设计素材复用、代码参考与项目结构学习等实际需求。压缩包共187个文件总计98.27MB涵盖56个文本文件含配置说明、技术文档与README、50个JPG/PNG/JPEG图片网页视觉素材、26个XMind思维导图网站架构与功能规划、17个DOCX文档如《2016最受欢迎的开源项目》《高并发下的HashMap》等技术分析、4个GIF动效素材、以及3个CSS、3个JS和1个HTML核心前端文件体现完整的设计-开发闭环。已有242人学习下载资源结构清晰包含.gitignore、farbox托管配置等工程化文件便于理解现代Web项目的组织逻辑与开源协作规范用户可直接复用样式代码、参考技术文档、调用设计素材或借鉴思维导图梳理项目流程显著提升原型搭建与开发效率。1. 这不是又一个“开源模板合集”而是一套可落地的 Web 设计源码仓库建设方法论当你在 Gitee 或 GitHub 搜索“Web 设计源码”时看到的往往是零散的 HTML/CSS/JS 单页、毕业设计压缩包或是缺乏文档、无持续维护的“死仓库”。但真正能支撑团队协作、支持设计系统演进、承载 UI 组件复用与设计规范落地的「Web 设计源码仓库」必须同时满足三个硬性条件结构可追溯、样式可继承、交付可验证。它不是静态资源堆砌而是以源码为载体的设计资产管理系统——设计师提交 Figma 变更后前端能自动同步原子组件视觉稿更新时CSS 变量与 Token 值能被版本化锁定甚至 QA 能基于仓库中预置的 Storybook 实例直接比对像素级差异。本文面向已掌握基础 HTML/CSS/JS 的前端工程师、UI 工程师及设计研发协同负责人不讲开源理念的抽象定义只拆解如何从零构建一个具备语义化目录、可执行构建链路、可审计变更历史、且默认启用 CI/CD 验证的 Web 设计源码仓库。所有步骤均基于当前主流工具链Vite Tailwind CSS Storybook GitHub Actions无需额外服务依赖。2. 用 Vite Tailwind 构建最小可运行设计源码仓库骨架一个真正可用的设计源码仓库其骨架必须拒绝“复制粘贴式初始化”。它需要明确区分设计意图层Design Tokens、实现层Components、验证层Stories和交付层Build Output。常见错误是把所有文件塞进src/下导致后期无法按角色设计师/前端/测试快速定位目标资产。我们采用分层目录结构每层职责清晰、边界可控。2.1 初始化带类型约束的 Vite 项目并固化设计层入口首先创建项目并安装核心依赖npm create vitelatest web-design-repo -- --template vanilla-ts cd web-design-repo npm install接着在src/下建立严格分层目录src/ ├── design/ # 设计系统源码层Token、Typography、Spacing 等 │ ├── tokens/ # CSS Custom Properties 定义JSON CSS 输出 │ │ ├── colors.json │ │ └── spacing.json │ └── themes/ # 主题配置light/dark/default │ └── default.css ├── components/ # 原子组件实现Button、Card、Input 等 │ ├── atoms/ │ └── molecules/ ├── stories/ # Storybook 实例每个组件对应 .stories.tsx └── index.html # 入口页仅用于本地开发预览非生产交付提示design/tokens/中的 JSON 文件不是装饰性配置而是设计系统的真实数据源。例如colors.json必须包含semantic和functional两类键如primary: { 50: #f0f9ff, 100: #e0f2fe, ..., 900: #0c4a6e }后续将通过脚本自动生成 CSS 变量与 TypeScript 类型声明。2.2 用csstools/postcss-color-function和postcss-preset-env支持现代 CSS 特性Tailwind 默认不启用 CSS Color Level 4 函数如color-mix()、hwb()但设计系统常需动态生成渐变色阶或主题混合色。我们在vite.config.ts中注入 PostCSS 插件// vite.config.ts import { defineConfig } from vite import react from vitejs/plugin-react import postcssPresetEnv from postcss-preset-env import postcssColorFunction from csstools/postcss-color-function export default defineConfig({ plugins: [react()], css: { postcss: { plugins: [ postcssPresetEnv({ stage: 3 }), postcssColorFunction() ] } } })该配置使你在design/themes/default.css中可直接使用:root { --color-primary-500: color(display-p3 0.047 0.286 0.431); --color-primary-mix: color-mix(in srgb, var(--color-primary-500) 70%, white); }注意color-mix()在 Chrome 111、Firefox 112 原生支持无需 Polyfill。若需兼容旧版浏览器应由设计系统团队明确标注“仅限现代浏览器预览”避免前端强行降级破坏色彩精度。2.3 生成可导入的 TypeScript 类型与 CSS 变量映射表设计 Token 必须双向同步CSS 中可用var(--spacing-md)TS 中可import { spacing } from /design/tokens并获得完整类型推导。我们编写scripts/generate-tokens.ts// scripts/generate-tokens.ts import fs from fs import path from path import { fileURLToPath } from url const __dirname path.dirname(fileURLToPath(import.meta.url)) const tokensDir path.join(__dirname, ../src/design/tokens) // 读取 colors.json 并生成 TS 类型 const colors JSON.parse(fs.readFileSync(path.join(tokensDir, colors.json), utf8)) const tsContent // Auto-generated from colors.json\nexport const colors ${JSON.stringify(colors, null, 2)} as const;\nexport type Colors typeof colors;\n fs.writeFileSync(path.join(__dirname, ../src/design/tokens/colors.ts), tsContent)并在package.json中添加脚本scripts: { tokens:generate: ts-node scripts/generate-tokens.ts, dev: npm run tokens:generate vite }每次修改colors.json后运行npm run tokens:generate即可获得强类型保障。这解决了“设计改色值 → 前端手动改 CSS → 忘记同步 TS 接口”的典型协作断点。3. 用 Storybook 为每个组件建立可交互、可归档的设计验证层Storybook 不是“给设计师看的演示站”而是设计资产的可执行说明书。它必须能回答三个问题这个组件支持哪些状态它响应哪些设计 Token它的 DOM 结构是否符合无障碍标准因此Story 的编写必须绑定设计系统约束而非自由发挥。3.1 配置 Storybook 7.6 并启用 Design Token 参数面板安装 Storybook 并初始化npx storybooklatest init关键配置在.storybook/main.ts// .storybook/main.ts import type { StorybookConfig } from storybook/react-vite const config: StorybookConfig { stories: [../src/stories/**/*.stories.(js|jsx|ts|tsx)], addons: [ storybook/addon-essentials, storybook/addon-interactions, storybook/addon-a11y, // 强制检查 aria-* 属性 storybook/addon-design-assets, // 支持上传 Figma 链接 ], framework: { name: storybook/react-vite, options: {} }, docs: { autodocs: true } } export default config注意storybook/addon-a11y会在每个 Story 渲染后自动运行 axe-core 扫描失败时直接报错。这确保“可访问性”不是验收项而是构建门槛。3.2 编写带 Token 控制器的 Button Story以Button组件为例其 Story 不仅展示默认态还必须暴露设计 Token 控制器// src/stories/Button.stories.tsx import type { Meta, StoryObj } from storybook/react import { Button } from /components/atoms/Button import { colors } from /design/tokens/colors const meta: Metatypeof Button { title: Atoms/Button, component: Button, tags: [autodocs], argTypes: { variant: { control: { type: select }, options: [primary, secondary, outline] }, size: { control: { type: radio }, options: [sm, md, lg] }, // 将设计 Token 显式暴露为参数 colorPrimary: { control: { type: color }, description: 覆盖 primary 主色对应 colors.primary[500], table: { category: Design Tokens } } } } export default meta type Story StoryObjtypeof Button export const Primary: Story { args: { children: Primary Button, variant: primary, size: md } } export const WithCustomColor: Story { args: { ...Primary.args, colorPrimary: colors.primary[500] // 默认取自 Token } }运行npm run storybook后在 Canvas 标签页下右侧 Controls 面板会显示colorPrimary颜色选择器。设计师拖动色块实时调整按钮主色前端可立即验证该色值是否在colors.json定义范围内——这实现了设计决策的即时闭环验证。3.3 导出静态 Storybook 并集成到仓库 READMEStorybook 静态站点是设计仓库的“对外 API 文档”。我们通过build-storybook生成可部署产物并在README.md中嵌入导航链接npx build-storybook -o ./storybook-static然后在README.md顶部添加## 设计资产文档 - [在线 Storybook最新版](https://your-org.github.io/web-design-repo/storybook-static/) - [Figma 设计系统文件](https://figma.com/file/xxx) - [Token 变更历史Git Blame](https://github.com/your-org/web-design-repo/tree/main/src/design/tokens) **说明**所有 Storybook 页面均通过 GitHub Pages 自动部署每次 main 分支 Push 后 3 分钟内更新。该链接指向的是纯静态 HTML不依赖任何后端服务完全符合“开源即交付”的原则——任何人克隆仓库后npm run storybook本地启动或直接打开storybook-static/index.html即可获得与线上一致的体验。4. 用 GitHub Actions 实现设计变更的自动化校验与发布流水线一个“开源理念”的仓库其价值不仅在于代码可见更在于流程可信。每次提交都应触发可审计的验证Token 是否语法合法组件是否通过无障碍扫描Storybook 是否能成功构建这些不能靠人工 checklist而必须固化为 CI 流水线。4.1 定义ci-validate.yml三阶段校验设计资产完整性在.github/workflows/ci-validate.yml中编写name: Validate Design Assets on: push: branches: [main] paths: - src/design/** - src/components/** - src/stories/** pull_request: branches: [main] paths: - src/design/** - src/components/** - src/stories/** jobs: validate-tokens: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Validate JSON Token files run: | jq empty src/design/tokens/*.json echo ✅ All token JSON files are valid validate-components: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Run Storybook accessibility audit run: npx storybook-test --test-runner playwright --test-runner-options {headless:true} --output-dir ./test-results - name: Check for a11y violations run: | if [ -f ./test-results/a11y-report.json ]; then violations$(jq .violations | length ./test-results/a11y-report.json) if [ $violations ! 0 ]; then echo ❌ Found $violations accessibility violations exit 1 fi fi echo ✅ All components pass accessibility audit build-storybook: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Build Storybook run: npm run build-storybook - name: Upload artifact uses: actions/upload-artifactv4 with: name: storybook-static path: storybook-static/该流水线有三个独立 Job分别校验 Token 合法性、组件无障碍合规性、Storybook 构建成功率。任意一环失败PR 将被阻止合并。特别地validate-components使用storybook-test运行 Playwright 驱动的 axe 扫描结果输出为 JSON便于后续集成到内部质量看板。4.2 发布设计 Token 包到 GitHub Packages Registry设计系统最终要被其他项目消费。我们将其发布为私有 npm 包免费无需付费私有 registry// package.json根目录 { name: your-org/web-design-tokens, version: 1.2.0, private: false, publishConfig: { registry: https://npm.pkg.github.com } }在.github/workflows/publish-tokens.yml中name: Publish Design Tokens on: release: types: [created] jobs: publish: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 registry-url: https://npm.pkg.github.com - name: Install dependencies run: npm ci - name: Publish to GitHub Packages run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}发布后其他项目只需npm install your-org/web-design-tokens即可在代码中导入import { colors } from your-org/web-design-tokens document.documentElement.style.setProperty(--color-primary, colors.primary[500])这完成了“设计决策 → 源码定义 → 自动验证 → 版本发布 → 跨项目复用”的全链路闭环。5. 用 Git Hooks Pre-commit 防止设计资产污染与低质提交CI 是事后拦截而 Git Hooks 是事前防御。90% 的设计仓库质量问题源于开发者本地未校验就提交JSON 多了个逗号、Story 缺少args、组件未导出默认函数。我们用simple-git-hooks在 commit 前强制运行轻量级检查。5.1 安装并配置 pre-commit 钩子npm install simple-git-hooks --save-dev在package.json中添加simple-git-hooks: { pre-commit: npm run lint:tokens npm run test:stories }, scripts: { lint:tokens: jq -S . src/design/tokens/*.json /dev/null, test:stories: npx storybook-test --test-runner jest --no-watch }然后执行npx simple-git-hooks该命令会在.git/hooks/pre-commit中生成脚本每次git commit前自动运行jq -S .校验所有 Token JSON 文件格式自动重排并检测语法错误storybook-test运行 Jest 测试需提前为每个 Story 编写快照测试。提示jq是 Linux/macOS 自带工具Windows 用户需安装 jq for Windows 并加入 PATH。若团队 Windows 占比高可替换为npm install jsonlint -g并改用jsonlint -q src/design/tokens/*.json。5.2 为设计师提供零配置的 Figma 插件同步 Token设计师不应接触 JSON 或 Git。我们集成 Figma Tokens Plugin 开源插件其导出格式与src/design/tokens/完全兼容设计师在 Figma 中编辑颜色、间距等 Token点击插件「Export → JSON (Design Tokens Spec)」将生成的colors.json、spacing.json直接拖入src/design/tokens/目录运行npm run tokens:generateTS 类型与 CSS 变量自动更新。该流程绕过 PR 评审但受 Git Hooks 保护若设计师导出的 JSON 有语法错误pre-commit会直接中断提交并提示“Token JSON invalid — please fix and retry”。5.3 建立设计变更的语义化提交规范为让git log成为可读的设计决策日志我们采用 Conventional Commits 规范并定制设计专属类型类型用途示例design:修改设计 Token 或主题design: update primary color palette to WCAG AA compliantcomponent:新增/重构原子组件component: add responsive Card with hover statesstory:更新 Storybook 实例或参数story: add disabled state for Button with aria-disabled安装commitizen并配置npm install commitizen cz-conventional-changelog --save-dev// package.json config: { commitizen: { path: ./node_modules/cz-conventional-changelog } }, scripts: { commit: cz }运行npm run commit后交互式 CLI 引导输入类型、范围、描述最终生成标准化提交信息。这使得git log --oneline --grepdesign:可一键提取所有设计变更记录为季度设计复盘提供原始数据支撑。注意不要将cz-conventional-changelog作为唯一提交方式。允许git commit -m临时使用但 CI 流水线中增加conventional-commits检查对不符合规范的提交给出明确修复指引如“Please use npm run commit or prefix message with design:”而非直接拒绝。本文还有配套的精品资源点击获取 Web设计源码仓库建设方法论：结构可追溯、样式可继承、交付可验证
简介这是一份面向Web前端开发者、UI/UX设计师及开源项目贡献者的综合性设计资源库聚焦于开放协作式Web开发实践解决设计素材复用、代码参考与项目结构学习等实际需求。压缩包共187个文件总计98.27MB涵盖56个文本文件含配置说明、技术文档与README、50个JPG/PNG/JPEG图片网页视觉素材、26个XMind思维导图网站架构与功能规划、17个DOCX文档如《2016最受欢迎的开源项目》《高并发下的HashMap》等技术分析、4个GIF动效素材、以及3个CSS、3个JS和1个HTML核心前端文件体现完整的设计-开发闭环。已有242人学习下载资源结构清晰包含.gitignore、farbox托管配置等工程化文件便于理解现代Web项目的组织逻辑与开源协作规范用户可直接复用样式代码、参考技术文档、调用设计素材或借鉴思维导图梳理项目流程显著提升原型搭建与开发效率。1. 这不是又一个“开源模板合集”而是一套可落地的 Web 设计源码仓库建设方法论当你在 Gitee 或 GitHub 搜索“Web 设计源码”时看到的往往是零散的 HTML/CSS/JS 单页、毕业设计压缩包或是缺乏文档、无持续维护的“死仓库”。但真正能支撑团队协作、支持设计系统演进、承载 UI 组件复用与设计规范落地的「Web 设计源码仓库」必须同时满足三个硬性条件结构可追溯、样式可继承、交付可验证。它不是静态资源堆砌而是以源码为载体的设计资产管理系统——设计师提交 Figma 变更后前端能自动同步原子组件视觉稿更新时CSS 变量与 Token 值能被版本化锁定甚至 QA 能基于仓库中预置的 Storybook 实例直接比对像素级差异。本文面向已掌握基础 HTML/CSS/JS 的前端工程师、UI 工程师及设计研发协同负责人不讲开源理念的抽象定义只拆解如何从零构建一个具备语义化目录、可执行构建链路、可审计变更历史、且默认启用 CI/CD 验证的 Web 设计源码仓库。所有步骤均基于当前主流工具链Vite Tailwind CSS Storybook GitHub Actions无需额外服务依赖。2. 用 Vite Tailwind 构建最小可运行设计源码仓库骨架一个真正可用的设计源码仓库其骨架必须拒绝“复制粘贴式初始化”。它需要明确区分设计意图层Design Tokens、实现层Components、验证层Stories和交付层Build Output。常见错误是把所有文件塞进src/下导致后期无法按角色设计师/前端/测试快速定位目标资产。我们采用分层目录结构每层职责清晰、边界可控。2.1 初始化带类型约束的 Vite 项目并固化设计层入口首先创建项目并安装核心依赖npm create vitelatest web-design-repo -- --template vanilla-ts cd web-design-repo npm install接着在src/下建立严格分层目录src/ ├── design/ # 设计系统源码层Token、Typography、Spacing 等 │ ├── tokens/ # CSS Custom Properties 定义JSON CSS 输出 │ │ ├── colors.json │ │ └── spacing.json │ └── themes/ # 主题配置light/dark/default │ └── default.css ├── components/ # 原子组件实现Button、Card、Input 等 │ ├── atoms/ │ └── molecules/ ├── stories/ # Storybook 实例每个组件对应 .stories.tsx └── index.html # 入口页仅用于本地开发预览非生产交付提示design/tokens/中的 JSON 文件不是装饰性配置而是设计系统的真实数据源。例如colors.json必须包含semantic和functional两类键如primary: { 50: #f0f9ff, 100: #e0f2fe, ..., 900: #0c4a6e }后续将通过脚本自动生成 CSS 变量与 TypeScript 类型声明。2.2 用csstools/postcss-color-function和postcss-preset-env支持现代 CSS 特性Tailwind 默认不启用 CSS Color Level 4 函数如color-mix()、hwb()但设计系统常需动态生成渐变色阶或主题混合色。我们在vite.config.ts中注入 PostCSS 插件// vite.config.ts import { defineConfig } from vite import react from vitejs/plugin-react import postcssPresetEnv from postcss-preset-env import postcssColorFunction from csstools/postcss-color-function export default defineConfig({ plugins: [react()], css: { postcss: { plugins: [ postcssPresetEnv({ stage: 3 }), postcssColorFunction() ] } } })该配置使你在design/themes/default.css中可直接使用:root { --color-primary-500: color(display-p3 0.047 0.286 0.431); --color-primary-mix: color-mix(in srgb, var(--color-primary-500) 70%, white); }注意color-mix()在 Chrome 111、Firefox 112 原生支持无需 Polyfill。若需兼容旧版浏览器应由设计系统团队明确标注“仅限现代浏览器预览”避免前端强行降级破坏色彩精度。2.3 生成可导入的 TypeScript 类型与 CSS 变量映射表设计 Token 必须双向同步CSS 中可用var(--spacing-md)TS 中可import { spacing } from /design/tokens并获得完整类型推导。我们编写scripts/generate-tokens.ts// scripts/generate-tokens.ts import fs from fs import path from path import { fileURLToPath } from url const __dirname path.dirname(fileURLToPath(import.meta.url)) const tokensDir path.join(__dirname, ../src/design/tokens) // 读取 colors.json 并生成 TS 类型 const colors JSON.parse(fs.readFileSync(path.join(tokensDir, colors.json), utf8)) const tsContent // Auto-generated from colors.json\nexport const colors ${JSON.stringify(colors, null, 2)} as const;\nexport type Colors typeof colors;\n fs.writeFileSync(path.join(__dirname, ../src/design/tokens/colors.ts), tsContent)并在package.json中添加脚本scripts: { tokens:generate: ts-node scripts/generate-tokens.ts, dev: npm run tokens:generate vite }每次修改colors.json后运行npm run tokens:generate即可获得强类型保障。这解决了“设计改色值 → 前端手动改 CSS → 忘记同步 TS 接口”的典型协作断点。3. 用 Storybook 为每个组件建立可交互、可归档的设计验证层Storybook 不是“给设计师看的演示站”而是设计资产的可执行说明书。它必须能回答三个问题这个组件支持哪些状态它响应哪些设计 Token它的 DOM 结构是否符合无障碍标准因此Story 的编写必须绑定设计系统约束而非自由发挥。3.1 配置 Storybook 7.6 并启用 Design Token 参数面板安装 Storybook 并初始化npx storybooklatest init关键配置在.storybook/main.ts// .storybook/main.ts import type { StorybookConfig } from storybook/react-vite const config: StorybookConfig { stories: [../src/stories/**/*.stories.(js|jsx|ts|tsx)], addons: [ storybook/addon-essentials, storybook/addon-interactions, storybook/addon-a11y, // 强制检查 aria-* 属性 storybook/addon-design-assets, // 支持上传 Figma 链接 ], framework: { name: storybook/react-vite, options: {} }, docs: { autodocs: true } } export default config注意storybook/addon-a11y会在每个 Story 渲染后自动运行 axe-core 扫描失败时直接报错。这确保“可访问性”不是验收项而是构建门槛。3.2 编写带 Token 控制器的 Button Story以Button组件为例其 Story 不仅展示默认态还必须暴露设计 Token 控制器// src/stories/Button.stories.tsx import type { Meta, StoryObj } from storybook/react import { Button } from /components/atoms/Button import { colors } from /design/tokens/colors const meta: Metatypeof Button { title: Atoms/Button, component: Button, tags: [autodocs], argTypes: { variant: { control: { type: select }, options: [primary, secondary, outline] }, size: { control: { type: radio }, options: [sm, md, lg] }, // 将设计 Token 显式暴露为参数 colorPrimary: { control: { type: color }, description: 覆盖 primary 主色对应 colors.primary[500], table: { category: Design Tokens } } } } export default meta type Story StoryObjtypeof Button export const Primary: Story { args: { children: Primary Button, variant: primary, size: md } } export const WithCustomColor: Story { args: { ...Primary.args, colorPrimary: colors.primary[500] // 默认取自 Token } }运行npm run storybook后在 Canvas 标签页下右侧 Controls 面板会显示colorPrimary颜色选择器。设计师拖动色块实时调整按钮主色前端可立即验证该色值是否在colors.json定义范围内——这实现了设计决策的即时闭环验证。3.3 导出静态 Storybook 并集成到仓库 READMEStorybook 静态站点是设计仓库的“对外 API 文档”。我们通过build-storybook生成可部署产物并在README.md中嵌入导航链接npx build-storybook -o ./storybook-static然后在README.md顶部添加## 设计资产文档 - [在线 Storybook最新版](https://your-org.github.io/web-design-repo/storybook-static/) - [Figma 设计系统文件](https://figma.com/file/xxx) - [Token 变更历史Git Blame](https://github.com/your-org/web-design-repo/tree/main/src/design/tokens) **说明**所有 Storybook 页面均通过 GitHub Pages 自动部署每次 main 分支 Push 后 3 分钟内更新。该链接指向的是纯静态 HTML不依赖任何后端服务完全符合“开源即交付”的原则——任何人克隆仓库后npm run storybook本地启动或直接打开storybook-static/index.html即可获得与线上一致的体验。4. 用 GitHub Actions 实现设计变更的自动化校验与发布流水线一个“开源理念”的仓库其价值不仅在于代码可见更在于流程可信。每次提交都应触发可审计的验证Token 是否语法合法组件是否通过无障碍扫描Storybook 是否能成功构建这些不能靠人工 checklist而必须固化为 CI 流水线。4.1 定义ci-validate.yml三阶段校验设计资产完整性在.github/workflows/ci-validate.yml中编写name: Validate Design Assets on: push: branches: [main] paths: - src/design/** - src/components/** - src/stories/** pull_request: branches: [main] paths: - src/design/** - src/components/** - src/stories/** jobs: validate-tokens: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Validate JSON Token files run: | jq empty src/design/tokens/*.json echo ✅ All token JSON files are valid validate-components: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Run Storybook accessibility audit run: npx storybook-test --test-runner playwright --test-runner-options {headless:true} --output-dir ./test-results - name: Check for a11y violations run: | if [ -f ./test-results/a11y-report.json ]; then violations$(jq .violations | length ./test-results/a11y-report.json) if [ $violations ! 0 ]; then echo ❌ Found $violations accessibility violations exit 1 fi fi echo ✅ All components pass accessibility audit build-storybook: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Build Storybook run: npm run build-storybook - name: Upload artifact uses: actions/upload-artifactv4 with: name: storybook-static path: storybook-static/该流水线有三个独立 Job分别校验 Token 合法性、组件无障碍合规性、Storybook 构建成功率。任意一环失败PR 将被阻止合并。特别地validate-components使用storybook-test运行 Playwright 驱动的 axe 扫描结果输出为 JSON便于后续集成到内部质量看板。4.2 发布设计 Token 包到 GitHub Packages Registry设计系统最终要被其他项目消费。我们将其发布为私有 npm 包免费无需付费私有 registry// package.json根目录 { name: your-org/web-design-tokens, version: 1.2.0, private: false, publishConfig: { registry: https://npm.pkg.github.com } }在.github/workflows/publish-tokens.yml中name: Publish Design Tokens on: release: types: [created] jobs: publish: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 registry-url: https://npm.pkg.github.com - name: Install dependencies run: npm ci - name: Publish to GitHub Packages run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}发布后其他项目只需npm install your-org/web-design-tokens即可在代码中导入import { colors } from your-org/web-design-tokens document.documentElement.style.setProperty(--color-primary, colors.primary[500])这完成了“设计决策 → 源码定义 → 自动验证 → 版本发布 → 跨项目复用”的全链路闭环。5. 用 Git Hooks Pre-commit 防止设计资产污染与低质提交CI 是事后拦截而 Git Hooks 是事前防御。90% 的设计仓库质量问题源于开发者本地未校验就提交JSON 多了个逗号、Story 缺少args、组件未导出默认函数。我们用simple-git-hooks在 commit 前强制运行轻量级检查。5.1 安装并配置 pre-commit 钩子npm install simple-git-hooks --save-dev在package.json中添加simple-git-hooks: { pre-commit: npm run lint:tokens npm run test:stories }, scripts: { lint:tokens: jq -S . src/design/tokens/*.json /dev/null, test:stories: npx storybook-test --test-runner jest --no-watch }然后执行npx simple-git-hooks该命令会在.git/hooks/pre-commit中生成脚本每次git commit前自动运行jq -S .校验所有 Token JSON 文件格式自动重排并检测语法错误storybook-test运行 Jest 测试需提前为每个 Story 编写快照测试。提示jq是 Linux/macOS 自带工具Windows 用户需安装 jq for Windows 并加入 PATH。若团队 Windows 占比高可替换为npm install jsonlint -g并改用jsonlint -q src/design/tokens/*.json。5.2 为设计师提供零配置的 Figma 插件同步 Token设计师不应接触 JSON 或 Git。我们集成 Figma Tokens Plugin 开源插件其导出格式与src/design/tokens/完全兼容设计师在 Figma 中编辑颜色、间距等 Token点击插件「Export → JSON (Design Tokens Spec)」将生成的colors.json、spacing.json直接拖入src/design/tokens/目录运行npm run tokens:generateTS 类型与 CSS 变量自动更新。该流程绕过 PR 评审但受 Git Hooks 保护若设计师导出的 JSON 有语法错误pre-commit会直接中断提交并提示“Token JSON invalid — please fix and retry”。5.3 建立设计变更的语义化提交规范为让git log成为可读的设计决策日志我们采用 Conventional Commits 规范并定制设计专属类型类型用途示例design:修改设计 Token 或主题design: update primary color palette to WCAG AA compliantcomponent:新增/重构原子组件component: add responsive Card with hover statesstory:更新 Storybook 实例或参数story: add disabled state for Button with aria-disabled安装commitizen并配置npm install commitizen cz-conventional-changelog --save-dev// package.json config: { commitizen: { path: ./node_modules/cz-conventional-changelog } }, scripts: { commit: cz }运行npm run commit后交互式 CLI 引导输入类型、范围、描述最终生成标准化提交信息。这使得git log --oneline --grepdesign:可一键提取所有设计变更记录为季度设计复盘提供原始数据支撑。注意不要将cz-conventional-changelog作为唯一提交方式。允许git commit -m临时使用但 CI 流水线中增加conventional-commits检查对不符合规范的提交给出明确修复指引如“Please use npm run commit or prefix message with design:”而非直接拒绝。本文还有配套的精品资源点击获取