Musea 组件画廊快速入门：用 Vize 搭建组件文档、Design Token 与 VRT 体系

Musea 组件画廊快速入门用 Vize 搭建组件文档、Design Token 与 VRT 体系【免费下载链接】vizeBlazing fast Vue.js Toolchain. Compiler, Linter, Type Checker, Formatter, LSP, Story System, Editor Extensions. This already passed 10k test suites, includes real world E2E.项目地址: https://gitcode.com/gh_mirrors/viz/vizeVize 是一款极速的 Vue.js 工具链编译器、Linter、Type Checker、Formatter、LSP 一体化而Musea是它内置的组件画廊与文档系统。只需几行配置你就能拥有自动生成的组件文档页、可视化的 Design Token 面板以及开箱即用的 VRT 视觉回归测试。本文带你从零开始用 Vize Musea 快速搭起一套完整的组件文档体系。️ Musea 是什么Musea插件包vizejs/vite-plugin-musea是一个挂在 Vite 开发服务器上的组件画廊中间件。它会扫描你指定的.vue组件自动构建一个独立的文档站点内置三大能力组件画廊自动列出全部组件展示变体Variant、标签、就绪状态READY支持分类导航和全局搜索组件文档页每个组件自带 Variants / Props / Docs / A11y / VRT 五个标签页还能一键切换 Light / Dark / Transparent 预览背景Design Token 面板 VRT 视觉回归把设计令牌可视化并对每个页面做截图比对防止 UI 悄悄漂移整个站点运行在本地开发服务器的/__musea__路径下团队成员打开浏览器就能查阅组件无需额外部署。 快速开始3 步拥有组件画廊第 1 步获取项目git clone https://gitcode.com/gh_mirrors/viz/vize第 2 步安装 Musea 相关依赖一次性安装vp之后执行vp install -D vizejs/vite-plugin vizejs/vite-plugin-musea vize第 3 步配置并启动在共享配置中声明 Musea 的扫描范围与站点路径即可// vize.config.ts import { defineConfig } from vize; export default defineConfig({ musea: { include: [src/**/*.vue], basePath: /__musea__, }, });然后运行vp dev浏览器打开http://localhost:5173/__musea__画廊就出现了 ✅⚠️ 小提示Musea 中间件面向本地开发服务器和可信内网不要把它直接暴露到公网。官方仓库中的完整示例见examples/vite-musea/其中的 vize.config.ts 展示了inlineArt、VRT 阈值、多视口等进阶配置。 组件文档怎么写.art.vue 艺术文件Musea 用一种名为Art 文件.art.vue的格式描述组件的展示方式。核心是一个编译器宏defineArt 一个art模板块!-- Button.art.vue -- script setup langts defineArt(./Button.vue, { title: Button, category: UI, tags: [button, form], }); /script art variant namePrimary default Button variantprimaryClick me/Button /variant variant nameDisabled Button disabledDisabled/Button /variant /art对新手来说有三个省心之处零样板代码defineArt会被编译器移除Musea 自动生成组件 import你只管写展示变体隔离根级script setup状态默认按变体隔离每个 variant 拥有独立的 refs 和 composable编辑器深度支持Musea 语言服务器提供组件路径补全、缺失文件诊断、跳转到定义、Props/Slot 推断写文档也有智能提示插件还支持previewCss全局预览样式、previewSetup预览初始化脚本、theme、tokensPath、storybookOutDir/storybookCompat导出 Storybook 兼容产物等选项详见npm/builder/vite-musea/README.md。 Design Token设计系统的单一事实来源Musea 的 Design Tokens 页面直接读取你项目里的令牌文件如 tokens.json把颜色、间距、字体、圆角、阴影、过渡等设计决策全部可视化。推荐采用示例中使用的两层结构层级说明例子Primitive原始层基础调色板与尺寸标尺按 50–950 等刻度编号color.neutral.900→#121212Semantic语义层面向用途的语义令牌通过$reference引用原始层semantic.color.text.default→{color.neutral.900}好处是换主题时只需改原始层语义层自动跟随而组件里始终只引用语义令牌设计意图一目了然。Musea 面板中每个色块都会标注其层级PRIMITIVE / SEMANTIC和取值设计评审与前端对齐效率大幅提升。 VRT 视觉回归让 UI 不再悄悄漂移组件文档最怕的是上次还是好的这次怎么不一样了。Musea 内置 VRTVisual Regression Testing能力用截图比对守护 UI 一致性配置视口与阈值在vize.config.ts的musea.vrt中声明比对阈值和多端视口vrt: { threshold: 0.1, viewports: [{ width: 1280, height: 720, name: desktop }], },生成基线快照运行musea-vrt首次生成基准图改动设计后用musea-vrt -u更新CI 中持续比对示例项目用 Playwright 对画廊首页、Token 页、测试汇总页和每个组件页逐一截图断言测试脚本见examples/vite-musea/e2e/vrt/musea-gallery.spec.ts对应package.json中的vrt/test:vrt脚本只要某次改动导致渲染差异超过阈值CI 立刻红牌报警问题被拦在合并之前。❓ 新手常见问题会影响生产构建吗不会。Musea 中间件只挂在开发服务器上产物里不含任何画廊代码。组件多了会不会慢Musea 由 Vize 原生编译器驱动扫描与文档生成走 Rust 侧高性能实现仓库整体已通过 10k 测试套件大规模组件库同样从容。改了组件想更新基线图怎么办本地musea-vrt -u或playwright test --update-snapshots即可。只想预览某个目录的组件用include/excludeglob 控制扫描范围例如只收录src/components/**/*.art.vue。 相关资源索引完整示例工程examples/vite-musea/6 个组件 Token 文件 VRT 用例Musea 插件文档npm/builder/vite-musea/README.mdMusea 核心实现crates/vize_musea/VRT 基线快照目录examples/vite-musea/e2e/vrt/__snapshots__/组件 Token 定义examples/vite-musea/src/tokens.json组件源码参考examples/vite-musea/src/components/Button、Badge、Card、Input、Alert、Avatar用 Vize 的 Musea一条命令就能让组件文档、Design Token 与 VRT 体系同时上线——少写文档、少踩视觉坑把时间留给真正的设计与开发 【免费下载链接】vizeBlazing fast Vue.js Toolchain. Compiler, Linter, Type Checker, Formatter, LSP, Story System, Editor Extensions. This already passed 10k test suites, includes real world E2E.项目地址: https://gitcode.com/gh_mirrors/viz/vize创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考