Astryx 应用工作区解析/apps 下文档站、示例工程、Sandbox 与 Storybook 的定位与协作【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx导读Astryx 是一个完全可定制、面向 Agent的开源设计系统其仓库采用 pnpm monorepo 结构而apps/目录承担着开发、文档与视觉测试三类上层应用职能。本文以 apps/README.md 为主线逐一拆解文档站docsite、示例工程example-*、开发沙盒sandbox与视觉测试storybook这四类工作区的定位、运行方式与内部实现并结合各子目录的 README、package.json与配置源码说明它们如何围绕packages/下的核心包core、cli、charts、themes 等协同工作。读完本文你将掌握 Astryx 仓库中每个应用工作区的启动命令、消费方式dist 预编译 vs 源码编译与扩展入口新增主题、新增包、新增博客等。一、/apps 目录总览四类角色的定位表apps/README.md的开篇以一张表概括了该目录下各子目录的职责DirectoryRolePurposedocs/DocumentationDesign system 的文档网站example-nextjs/Example面向 source 分发消费者的参考 Next.js 应用Babel PostCSS 路径example-vite/Example面向 source 分发消费者的参考 Vite React 应用unplugin 路径sandbox/Development本地开发与测试环境storybook/Visual Testing用于组件开发与视觉文档的 Storybook这张表定义了apps/目录的宪法所有应用只承担文档、示例、开发、视觉测试四件事真正的组件实现一律沉淀在packages/中。表格旁还标注了!-- SYNC: When files in this directory change, update this document. --同步注释说明该表需要随目录变更保持更新。需要补充的是表格中列出的五个目录是最小编制而当前仓库实际还包含了example-nextjs-source、example-nextjs-stylex、example-nextjs-tailwind、example-vite-tailwind等衍生示例它们分别演示了源码编译路径产品代码使用 StyleX搭配 Tailwind v4等不同消费场景共同构成完整的示例矩阵。二、docsite由数据管线驱动的文档站apps/docsite/是 Astryx 的开源文档网站基于 Next.js StyleX 构建见 apps/docsite/README.md。它的核心设计哲学是页面代码永不硬编码包列表、组件目录或主题映射所有内容都通过构建期数据管线从 monorepo 中提取并写入src/generated/下的类型化 TypeScript 注册表。2.1 快速启动pnpm install # 在仓库根目录执行 pnpm build # 构建所有包主题需要已构建的产物 cd apps/docsite pnpm generate # 从 monorepo 提取数据到 src/generated/ pnpm dev # 启动开发服务器从 apps/docsite/package.json 可以看到pnpm dev与pnpm build都会先自动执行pnpm generategenerate脚本依次执行主题构建astryx theme build、数据提取generate-data.mjs、作用域生成generate-scope.mjs、Playground 类型生成generate-playground-types.mjs与 vendor 拷贝copy-vendor.mjs。2.2 数据管线十大注册表scripts/generate-data.mjs扫描 monorepo 并产出以下注册表均落在被 gitignore 的src/generated/目录RegistrySourceWhat it containspackageRegistry.tspackages/*/package.json每个已发布包的名称、版本、描述、READMEcomponentRegistry.tsCore CLI 配置的集成.doc.mjs文件每个包的 Props、用法文档、hooks、分组componentPreviewRegistry.ts上述包中的组件共享 Properties 预览的运行时导出blockRegistry.tsCLI 集成模板块带元数据的展示与示例块templateRegistry.tsCLItemplates/pages/页面级模板如 dashboard、settingsdocsRegistry.tsCLIdocs/长文指南与基础主题blogRegistry.tssrc/content/blog/posts/人工撰写的博客文章frontmatter 校验themeRegistry.ts已安装的astryxdesign/theme-*包按包名索引的内置主题对象showcaseRegistry.ts带isShowcase标记的块拷贝的展示源码文件exampleRegistry.ts带exampleFor标记的块每个组件的示例块规则所有数据必须来自管线。页面代码不得直接import {fooTheme} from astryxdesign/theme-foo/built而应使用themeRegistry中的themeObjects不得手写组件名数组而应使用componentRegistry不得写if (pkg astryxdesign/core)之类的分支让管线去分类包。这一约定保证了文档站始终与仓库真实状态同步无需手工接线。2.3 版本化内容latest vs canary文档站同一套代码部署自main分支但数据管线可按构建目标从两个不同来源读取包文档恰好对应 npm 的两个 dist-tagTargetnpm dist-tag读取包文档来源部署位置latestlatest最近一次已发布的 npm 版本生产站canarycanary实时 monorepomainWIPcanary 站 每个 PR 预览目标由 Vercel 的VERCEL_ENV派生生产部署为latest预览部署main canary 站与所有 PR 预览以及本地开发为canary。scripts/resolve-content-root.mjs负责把目标映射为管线读取的文件系统根目录——latest会从 npm 下载已发布包的 tarball其src/中携带管线所需的.doc.mjscanary则读取实时工作区并加载astryx.config.mjs中的组件集成。标记为astryx.canaryOnly的包会被排除出latest快照。贡献者须知库的变更在发布之前不会出现在生产站上。往main合入新组件、修改 prop 或更新文档后想看线上效果请使用 canary 站或任意 PR 预览两者都读main。本地开发不受影响pnpm dev没有VERCEL_ENV默认走canary读实时工作区如需本地预览latest视图可运行DOCSITE_TARGETlatest需要联网拉取已发布 tarball。2.4 扩展入口新增主题、新增包、新增博客新增主题步骤见 apps/docsite/README.md在packages/themes/name/下创建主题包在apps/docsite/package.json依赖中加入astryxdesign/theme-name: *在src/app/globals.css中添加import astryxdesign/theme-name/theme.css加载主题字体主题只按名称引用字体而不打包字体文件字体缺失时会静默回退到系统字体因此需要在src/app/layout.tsx的 Google Fontslink中补齐缺失字族各主题 README 的## Fonts一节会说明具体 URL运行pnpm generate主题会自动出现在themeRegistry.ts、packageRegistry.ts、侧边栏、craft 页面与包详情页中。注意只应把公开非 private主题包加入文档站。新增包在packages/name/下创建包在apps/docsite/package.json加入astryxdesign/name: *若为 canary-only 组件包需在其package.json设置astryx.canaryOnly: true、添加带components: ./src的astryx.integration.mjs、将该文件纳入files并在apps/docsite/astryx.config.mjs中登记可选 showcase 块保留在包内并通过集成templates字段暴露目录文档站通过 CLI 模板 API 获取运行pnpm generate。新包会自动出现在侧边栏、libraries 区块并获得独立的/docs/name详情页canary-only 包与组件只出现在 canary 构建中并携带 flask 图标。新增博客博客位于/blog与/blog/slug文章是带 YAML frontmatter 的 Markdown位于src/content/blog/posts/具体规范见src/content/blog/README.md。要点是创建posts/slug.md必填 frontmatter 为title、description、date、type、authors、tags新作者需在src/content/blog/authors.ts登记然后运行pnpm generate pnpm test pnpm typecheck最后pnpm dev预览。构建期会校验必填 frontmatterdraft: true的草稿不会出现在生产输出中。三、example-nextjs最简的 dist 预编译消费路径apps/example-nextjs/README.md 展示了以预构建 dist 包方式在 Next.js 中消费astryxdesign/core的最简流程——无需任何 StyleX 构建插件Astryx 已随包发布编译好的 CSS 与 JS。步骤一安装依赖npm install astryxdesign/core astryxdesign/theme-neutral next react react-dom npm install --save-dev types/react types/react-dom typescript步骤二CSS 导入顺序关键在src/app/globals.css中import astryxdesign/core/reset.css; /* 1. 基线 resetlayer reset */ import astryxdesign/core/astryx.css; /* 2. 全部组件样式layer astryx-base */ import astryxdesign/theme-neutral/theme.css; /* 3. 主题 token 覆盖layer astryx-theme */顺序错了会导致主题 token 缺失或图层错乱。步骤三Theme LinkProvider客户端边界// src/app/providers.tsx use client; import Link from next/link; import {Theme} from astryxdesign/core/theme; import {LinkProvider} from astryxdesign/core/Link; import {neutralTheme} from astryxdesign/theme-neutral/built; export function Providers({children}) { return ( Theme theme{neutralTheme} LinkProvider component{Link}{children}/LinkProvider /Theme ); }LinkProvider为所有基于链接的 Astryx 组件Link、带 href 的 Button、TopNav、SideNav、Breadcrumbs、TabList接通 Next.js 客户端导航。两个易错点provider 文件必须加use client否则createContext在服务端组件中报错。四、example-vite源码分发的 unplugin 路径与 dist 路径相反apps/example-vite/README.md 演示的是源码分发Astryx 以原始 TypeScript StyleX 源码发布由应用层在构建时编译没有预构建的 CSS/JS 产物。该示例使用stylexjs/unplugin用单个 Vite 插件同时完成 StyleX 编译与 CSS 提取。4.1 与 Next.js 的差异ConcernNext.jsViteStyleX 集成Babel 插件 PostCSS 插件stylexjs/unplugin单插件CSS 提取PostCSS 替换stylex;at-rule由 unplugin 自动处理所需配置文件babel.config.jspostcss.config.jsnext.config.mjs仅vite.config.ts主题 provider需要use client边界无客户端/服务端边界4.2 三个必须的配置要点第一package.json中必须声明browserslistAstryx token 使用原生light-dark()属于 2024 基线特性若无现代浏览器目标lightningcss 会将其降级成破坏主题的 polyfill 变量{ browserslist: [last 1 Chrome version] }第二vite.config.ts中必须显式传入lightningcssOptions.targets因为 unplugin 内部的 lightningcss 默认使用browserslist( 1%)其中包含不支持light-dark()的 Chrome 112会导致所有主题色静默失效同时要通过resolve.alias把astryxdesign/core指向源码、在optimizeDeps.exclude中排除 Astryx否则 esbuild 预打包会剥离stylex.create/defineVars调用导致运行时错误且stylex.vite()必须位于react()之前。完整配置见 apps/example-vite/vite.config.ts。第三src/index.css需要一个最小占位--stylex-injection: 0让 Vite 有 CSS 资源可供 StyleX 追加在main.tsx中按 reset → theme → index.css 顺序导入。4.3 常用命令npm run dev # 启动带 HMR 的开发服务器 npm run build # 生产构建 npm run preview # 预览生产构建该 README 还列出六条 Gotchas缺 lightningcssOptions、Vite 预打包、缺 alias、缺 CSS 入口、插件顺序、monorepo 中重复的 React 类型其中前五项均可直接对照 apps/example-vite/vite.config.ts 与 apps/example-vite/package.json 验证。五、sandbox设计探索与 vibe 测试沙盒apps/sandbox/是 Astryx 的组件沙盒用于设计者探索与 vibe 测试每个 PR 都会与 Storybook 一起部署。根据 apps/sandbox/README.md它是配置为静态导出output: export的 Next.js 应用PR 时由 CI 构建并部署到带版本号的 URL。安装执行npm install会自动通过postinstall钩子运行astryx init --features agents生成带 Astryx 组件索引的AGENTS.md——这是阅读全部组件文档的入口内含浏览组件、token、主题与设计规则的 CLI 命令若文件缺失可运行npx astryxdesign/cli init --features agents重新生成。新增页面创建src/app/pages/name/page.tsx并在src/app/Sidebar.tsx的pages数组中登记即可页面会自动出现在侧边栏并拥有 PR 部署 URL。三种本地运行模式由 apps/sandbox/package.json 中的脚本支撑模式命令适用场景快速启动pnpm dev:sandbox只构建一次 core 后启动适合只改沙盒页面源码模式pnpm dev:sandbox:source通过sourceexports 条件直接解析 TS 源码热更新约 200ms但 CSSlayer包装只存在于 dist 产物中因此主题与 CSS 图层不可用只适合布局/行为迭代Watch 模式终端 1pnpm -F astryxdesign/core dev终端 2pnpm -F astryxdesign/sandbox devBabel CLI 增量重建 dist数秒CSS 图层顺序正确主题正常工作沙盒的文件清单package.json、babel.config.js、postcss.config.js、next.config.mjs、src/app/globals.css的stylex;注入点、providers/layout/Sidebar 等在 README 中有完整表格其中next.config.mjs负责静态导出、GitHub Pages 的 basePath 与主题 token 的 webpack alias。六、storybook组件开发与视觉文档的单一事实来源apps/storybook/是面向组件开发与视觉文档的 Storybook 应用Vite 集成见 apps/storybook/package.json 中的storybook/react-vite与astryxdesign/build依赖本地端口 6006构建产物输出到dist/并附带一个 RTL 审计脚本rtl-audit/rtl-audit.mjs用于对构建产物做从右到左布局审计。6.1 故事组织规则一个形状apps/storybook/README.md 规定故事统一按一个形状组织让读者能猜到任何东西的位置、视觉门禁能找到它Package/Component/(Default | Theme Sheet | …) Package/Hooks/hook Package/Themes/theme featurePackage只取Core、Lab、Charts、Vega或RichText——组件所属的实际包名绝不用 Components 这类分类词Default排第一它是最简单诚实的用法也是构建者第一眼看到的东西Theme Sheet排第二该组件每个可主题化目标.doc.mjs 声明的每个变体与状态集中在一页。它是主题作者的参考也是视觉门禁在 probe 主题下拍照的表面——只有通过 Theme Sheet 才能证明某个 theming 目标确实到达了像素Hooks 与主题级特性不是组件不与组件并列Icon/Indicator 注册表、MediaTheme、CodeTheme等放在Themes/下。6.2 Theme Sheet 不得自锁主题一个常见的反模式story 内部用Theme theme{…}包裹自己这会覆盖全局主题导致工具栏无法切换、视觉门禁永远探测不到它故事恰恰对它最需要帮助的测试隐形。正确做法是渲染组件本身让工具栏驱动主题。// 好——工具栏和门禁控制主题 export const ThemeSheet: Story { name: Theme Sheet, render: () ( {VARIANTS.map(v ( Badge key{v} variant{v} {v} /Badge ))} / ), };这一约束与 docs/architecture/、internal/a11y-spec/ 中的可访问性与主题验证思路一脉相承storybook 不仅是演示工具更是被自动化门禁rtl-audit、vibe 测试直接消费的验证表面。七、示例矩阵中的其他成员除apps/README.md表格列出的五个目录外仓库还维护了四个衍生示例分别覆盖不同的消费组合apps/example-nextjs-source源码编译路径webpack 上的 Babel PostCSS 双插件astryxdesign/build提供astryx/x双类前缀与独立 CSS 图层README 中明示其依赖 webpack在 Next 16默认 Turbopack下需显式next dev --webpack/next build --webpack且withAstryx()在 Turbopack 下会直接抛错而非产出无样式构建。apps/example-nextjs-stylexdist 预编译 产品代码使用 StyleX 的组合。apps/example-nextjs-tailwinddist 预编译 Tailwind v4。关键点是必须在globals.css中预先声明全部图层顺序reset, theme, base, astryx-base, astryx-theme, components, utilities否则 Astryx 图层在 Tailwind 声明之后创建、会让组件样式压过utilitiesREADME 还介绍了astryxdesign/core/tailwind-theme.css桥接通过 Tailwind v4 的theme inline把 Astryx token 映射为 80 原生工具类如text-primary、bg-surface、rounded-lg无需var()。apps/example-vite-tailwindVite Tailwind 组合。从 apps/example-nextjs/package.json 与 apps/example-vite/package.json 可以看到所有示例均通过astryxdesign/core: *、astryxdesign/theme-neutral: *这类工作区通配版本消费包与pnpm-workspace.yaml的 monorepo 解析保持一致。八、应用层与包层的协作闭环把整条链路串起来看apps/的五个外加四个衍生应用构成了围绕packages/的完整闭环生产源头组件、token、主题、CLI 全部实现于packages/core、cli、charts、lab、richtext、vega、themes 等文档外化docsite通过构建期管线把这些包的内容提取成类型化注册表输出文档站与博客消费验证example-*系列从外部消费者视角验证 dist 与 source 两条分发路径在 Next.js/Vite/Tailwind 等生态中的可用性设计迭代sandbox提供快速试玩与 vibe 测试的静态导出环境视觉门禁storybook以统一的Default → Theme Sheet结构承载视觉文档并被rtl-audit等自动化脚本消费。这种应用层只做消费与验证、实现全部下沉到包层的划分正是apps/README.md那张角色表的深层含义任何一个应用目录都可以随仓库演进被替换或新增而不会污染包层的公共 API。若需深入了解各应用的配置细节可直接阅读对应目录的 README 与配置文件如 apps/docsite/astryx.config.mjs、apps/docsite/next.config.mjs、apps/example-vite/vite.config.ts、apps/sandbox/next.config.mjs。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考