Aiven水族馆设计系统
实施Aiven Aquarium设计系统,作为npm包发布. 快速巡演:
- 我们用法格玛来设计系统. 设计符号在 Figma 页面中控制 (见 实例页(中文(简体) ),并同步 自动 改为 符号. json
- 构成部分执行用途 设计符号 以定义他们的视觉。 这将使未来通过改变道具来更方便地更新视觉.
- 水族馆设计系统通过npm作为反应组件被曝光
- 尾风 用于样式
安装
要安装水族馆到您的应用程序 :
-
npm install --save @aivenio/aquarium -
确保您在应用程序中添加正确的字体 . 间 aiven主题.
-
将 CSS 导入您的应用程序
- Aiven 主题为
import '@aivenio/aquarium/dist/styles.css' - 如果你用过
THEME=X npm run build用于建造、使用import '@aivenio/aquarium/dist/styles_X.css'
- Aiven 主题为
-
将 React 上下文组件添加到您的 React app 的根
import MyApp from './MyApp'; + import { Context } from '@aivenio/aquarium'; const Root = () => ( return ( + <Context> <MyApp /> + </Context> ) ) -
如果您遇到解决 EcmaScript 模块的问题, 请使用此 Webpack 配置功能禁用“ 完全指定” 模式 :
webpack: { configure: { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ] }, } }, };
发展
使用npm 7! 使用npm 7! 使用更旧的 npm 版本,手动安装端点依赖性 。 如果您遇到“ 找不到模块... ” 错误, 请尝试 rm -rf node_modules && npm i。这似乎是 npm@7 引入的错误 .
先决条件
此工程需要在命令前设定某些环境变量, 如 : npm run build 将工作。 大多数都可以在队友的帮助下复制/粘贴,但你需要自己制作一个国家预防机制标志.
-
创建 npm 账户 这里 如果你还没有一个.
-
为您的账户创建一个符号 。 你可以读到如何做到这一点 这里。为了建设该项目,只读访问即可.
-
复制样本环境文件 :
cp .env.sample .env -
在新创建中添加必要的数据
.env文档. -
来源
.env要设置的环境变量文件 :source .env注意, 每当创建新 shell 实例时( 例如, 当您重新启动您的计算机时), 您需要运行
source .env,否则变量将不会被设定。 考虑使用如下解决方案:autoenv自动应用.env文档.
可选 DX 改进
- 用于 VSCode
- 安装 Tailwind CSS IntelliSense 扩展名. 见 https://github.com/tailwindlabs/tailwindcs-intellisense#推荐-vs-代码设置
- 在保存时安装 ESLint 扩展并选择启用自动格式 。 见 “步骤4——保存上的格式” 从 https://www.digitalocean.com/community/tourics/linting-and-formating- with-eslint-in-vs-code (中文(中国大陆) )
常见命令
npm ci以安装依赖关系npm run build建造图书馆生产大楼npm start开始故事书
在您的应用程序中开发
要在应用程序中开发水族馆组件,在您的应用程序中运行本地修改版的水族馆就比较容易了. 这样做有两种方法: npm 链接,或者将模块复制到您的应用程序中。 这使得您可以修改组件,并立即看到应用程序上下文中的变化.
npm link
QQ TODO:目前这个盒子没有用. 修改指令
- 在设计系统目录中,运行
npm link - 在设计系统目录中,运行
npm link <path to your app>/node_modules/react避免遇到两次反应的冲突。 否则会打破钩子规则并崩溃应用程序. 关于这一问题的更多信息 这里。如果命令在端点依赖性上出现出错,则重新运行命令,添加--force在结尾. - 在应用程序目录中运行
npm link @aivenio/aquarium - 现在
<path to your app>/node_modules/@aivenio/aquarium是一个与您的本地水族馆目录的符号链接 . - 在设计系统目录中,运行
npm run watch - 没问题! 现在,您应该能够在当地开发DS, 更改会反映到依赖于
@aivenio/aquarium - 如果您想要停止使用 npm 链接, 请返回普通导入的版本, 在您的应用目录中运行
npm unlink --no-save @aivenio/aquarium,则npm i重新建立依赖.
复制模块
如果你在DS一侧安装了新的依赖,这行不通. 见 npm 包的指令 换句话说.
npm链接可能很棘手才能工作. 一个更简单的方法是建造一个DS的制作楼,并把它复制到您的应用程序中 node-modules 目录。 记得一旦DS建成并复制完毕, 请重新启动您的应用程序的构建进程 。 这里有一个片段可以做这一切:
cd <path to ds> \
&& npm run build \
&& cd <path to your app> \
&& rm -rf ./node_modules/@aivenio/aquarium/dist \
&& cp -R <path to ds>/dist ./node_modules/@aivenio/aquarium # && <the dev/build command of your app>
npm pack
复制模块是一个黑客,当依赖性自您的应用端最后一次安装以来在DS端发生了变化时,它就失效了.
你用得着 pack-and-install.sh 创建本地发布软件包并安装到本地应用程序的实用脚本.
APP_PATH=<path to your app> ./pack-and-install.sh && <run dev/build command for your app>
每次更改后再次运行, 并重新启动您的应用程序的 Dev 服务器 。 剧本留下了应用软件
package.json 财务报告和审定财务报表 package-lock.json 没有动 就跑吧 npm ci 在应用程序中返回发布版本.
或者你想的话,你也可以跑 npm pack 命令,然后安装到您的应用程序.
cd <path to ds> \
&& npm run build \
&& jq --arg file_name $(npm pack 2>&1 | tail -1) '.dependencies["@aivenio/aquarium"] = "file:<path to ds>/\($file_name)"' <path to your app>/package.json > <path to your app>/package-json-new.tmp \
&& cd <path to your app> \
&& mv package-json-new.tmp package.json \
&& npm install # && <the dev/build command of your app>
确保您全部替换 <path to ds> 财务报告和审定财务报表 <path to your app> 用精确的绝对路径串起.
正在测试
记住 source .env 在国家防范机制下达命令之前,需要这样做.
npm test运行所有测试一次npm test -- Button只运行匹配的测试Buttonnpm run test:watch以监视模式运行测试npm run test:coverage运行所有测试并查看覆盖范围
记着! 开发时在表模式下运行测试是好主意. 例如,如果快照测试由于一些代码更改而失败,那么就很容易更新那些带有快克命令行工具的. 如果你想只是更新可以完成的快照 jest --updateSnapshot更多信息 这里
其他有用的命令
THEME=<brand> npm start以主题开始本地故事书THEME=<brand> npm run build以主题构建 DS 模块npm run figma -- sync -i .figma-file.json生成./tokens.json而不是从 API 获取巨大的 Figma 文件 .npm run figma -- sync --debug以启用更多动词输出npm run figma -- sync --foundation-page-name 'my foundations'以覆盖选项.jq '.document.children[] | select(.id == "8916:120229")' .cache/figma-file.json从整个 Figma 文件 JSON 中切入基础页面.
有一个 更多文档 用于图像同步工具.
构建和发布进程
故事书
在当地建立故事书
运行 npm run build:storybook。 。 。 .
故事书部署
故事书被部署到Cloudflare Pages中,每次新代码被合并到主.
Aiven Runtime应用程序服务也部署同样的任务 部署-故事手册. yml,这引发了该 服务以重建根 粘贴文件 并和UI一起为MCP服务器服务.
工作流程需要这些 Repo 设置 :
| 仁爱 | 名称 | 数值 |
|---|---|---|
| 秘诀 | AIVEN_TOKEN | Aiven API 令牌, 并带有服务上的调用权限 |
| 变量 | AIVEN_PROJECT | 目标 Aiven 项目名称 |
| 变量 | AIVEN_APP_NAME | aiven 应用程序服务名称 |
故事本 MCP 服务器
故事书揭露 MCP 服务器 如此的探员 可以查询真实的组件文档和道具,而不是猜测。 它来自这个repo的MDX 文件页和类型Script道具类型——见 一般事务人员(其他职等) 这里面的规则代理人 repo在使用时会跟随.
-
本地 dev : 运行
npm start,然后MCP服务器在http://localhost:6006/mcp已经 有窃听器通过 . mcp.json (英语)。 。 。 . -
从另一个项目 (例如,一个指向这个设计系统的控制台):一旦故事本是 在此运行, 添加为远程 MCP 服务器
claude mcp add --transport http aquarium-storybook http://localhost:6006/mcp。 。 。 . -
主机 : 每次合并到主机都会在Aiven Runtime上重新部署容器,所以没有必要 在本地运行故事本, 以查询 docs - 点
<service-url>/mcp换句话说 找到服务 Aiven 控制台中的 URL 。 它住在VPC里,所以检查它能从你运行的地方到达 探员. -
集装箱: 构建和运行 粘贴文件 获取静态故事书和 自托管的仅多克的 MCP 服务器 (
mcp-server/在同一端口:docker build -t aquarium-storybook-mcp . docker run --rm -p 6006:6006 aquarium-storybook-mcp两人从
http://localhost:6006。只有文档工具集在这里工作,它没有 运行 dev 服务器,以预览或测试针对的故事 .只向代理人提供交叉文件页(概念、设计标志、如何向导)。 这个 每个组件的MDX页被删除,因为每个组件的指向都生活在元中a JSDoc 并通过其组件条目联系代理商。 内容故事、片段和 道具表不受影响。 见 mcp 服务器/服务器 为什么这不是 完成的故事书
!manifest标签.
水族馆套装
如何在当地建立水族馆软件包
- 运行
npm run build - 见
dist用于构建代码
如何创建释放
-
运行
npm run release -- --bump <bump>(所有破折号都需要) 撞伤是其中之一major, (中文(简体) ),minor或者说patch。 。 。 .此命令将自动检查一个发布分支, 输入版本突起, 并打开您的浏览器提交 PR .
-
审查创建的公关,并合并到主机上. GH动作会处理其余的.
任何API的突破更改都应该是主要的版本起伏并应该在发行注释中提及!
中断更改
中断更改示例 :
- 在按钮组件中重命名道具
- 将卡片组件重命名为 Box
- 删除道具
- 删除组件
这些不是打破更改 :
- 为按钮添加新道具
- 添加新组件
- 更改故事书
- 更改测试
背景情况
对现有的设计系统做了大量研究,如果我们能再利用 部分内容。 得出的结论是,我们主要从好的 并使用单个组件 通过复制粘贴代码到我们的系统.
对现有反应图书馆的评价
一些工程是巨大的,最常用的链接直接指向定义组件的代码基础部分. 对于测试,我检查了一些组件的测试 看上去不错,没有做覆盖或更深入的分析.
接下来要考虑的事项:
- 使用图书馆的一部分时 树能摇动吗? 地盘的大小也是一个重要因素,但树木摇晃后,各图书馆的脚印应该相当相近
- 成熟性和活性(承诺、最近的活动、贡献者分布、结束的与未解决的问题、公关合并活动)
- 他们是否迁移到另一个技术领域? TS, Sass - > 有型组件等
- 老板,是社区驱动还是公司驱动? 有13颗恒星的项目如果是公司内部开发的,N年投入20克就可以超成熟了
- 无障碍
- 自定义性, 您需要叉子还是可以在获取上游更新时自定义 ?
| 链接 | 提交* | 联合来文/TS | 样式 | 许可证 | 测试 | 其它 |
|---|---|---|---|---|---|---|
| 蚂蚁设计 | 18.6k (韩语) | TS 翻译 | 减. 实例 | 麻省理工学院 | ☑️ | |
| 阿拉贡大学 | 0.8k (中文(简体) ) | 联合来文 | 样式组件 | 麻省理工学院 | 没什么 | |
| Uber 的 Baseweb 网络 | 2.3k (单位:千美元) | 联合来文(Flow) | 样式 | 麻省理工学院 | ☑️ | |
| 依据 | 0.3k (简体中文) | 联合来文 | 情绪 | 麻省理工学院 | ☑️ | |
| 蓝图 | 1.8k (中文(简体) ) | TS 翻译 | 萨斯 | Apache 2.0 (英语) | ☑️ | |
| 碳矿 | 6.8k (简体中文) | 联合来文 | CSS 类名链接到 萨斯 | Apache 2.0 (英语) | ☑️ | · 故事本 |
| 微软的流利UI | 8.6k (单位:千美元) | TS 翻译 | 联署材料中的CSS似乎是一个 自定义一 | 麻省理工学院 | ☑️ | |
| 格罗姆特 | 5.2k (韩语) | 联合来文 | 样式组件 | Apache 2.0 (英语) | ☑️ | · 故事本 |
| 材料界面 | 11.9k (韩语) | 联合来文 | CLSX,JS中的CSS. 示例 | 麻省理工学院 | ☑️ | |
| MongoDB 设计 | 0.4k (简体中文) | 联合来文 | 支助科 | package.json说麻省理工学院没有LICENSE文件 | 没有 | |
| 关键UI | 4.0k (中文(简体) ) | 联合来文 | 萨斯 | 麻省理工学院 | ☑️ | |
| 由 Shopify 创建的极地 | 6.1k (韩语) | TS 翻译 | 萨斯 | 修改后的麻省理工学院, 看见更多 | ☑️ | |
| GitHub 的首页 | 4.5克级 | 联合来文 | 样式组件 | 麻省理工学院 | ☑️ | |
| 反射启动陷阱 | 3.8k (单位:千克) | 联合来文 | 靴子CSS类 | 麻省理工学院(Bootstrap也是麻省理工学院) | ☑️ | |
| 反应陷阱 | 0.8k (中文(简体) ) | 联合来文 | 靴子CSS类 | 麻省理工学院 | ☑️ | |
| 罗姆妇女理事会 | 1.9k (单位:千美元) | 联合来文 | 使用 CSS 类名 材料组件-网络 由 Google (来源为 Sass) | 麻省理工学院(材料组件网络也是麻省理工学院) | ☑️ | |
| 销售力设计系统 | 9.5克级 | 联合来文 | 萨斯 | 代码 BSD 3- Clause,参见: https://github.com/salesforce-ux/design-system#licenses (英语) | ☑️ | |
| 缩略图 | 0.7k (简体中文) | TS 翻译 | 萨斯 | Apache 2.0 (英语) | ☑️ | |
| VTEX 样式指南 | 4.3克级 | 联合来文 | 自定义 塔克扬 + CSS 类。 示例 执行 财务报告和审定财务报表 支助科 | 无执照 | 没什么 | |
| 禅桌花园 | 0.8k (中文(简体) ) | TS 翻译 | 样式组件 | Apache 2.0 (英语) | ☑️ | · 故事本 |
- 这些再现者大多是同Lerna一起管理的单发. 承诺数只是粗略估计代码被重复了多少 .
为了进一步调查,您可以在 GitHub 中找到许多组件: https://github.com/search?l=&p=99&q=创建了%3A%3E2015-01-01+extension%3Ajs+extension%3Ajsx+extension%3Ats+extension%3Atsx+signal%3Abutton.js+filename%3Abutton.jsx+filename%3Abutton.jsxssearch&type=Code
您可以在此找到更多设计系统 : https://github.com/alexpate/awesome-design-systems (中文(简体) )。并不是所有人都有开源代码.