Astryx + Tailwind完整指南：一个桥接文件让你直接用rounded-lg和bg-surface

Astryx Tailwind完整指南一个桥接文件让你直接用rounded-lg和bg-surface【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx 是 Meta 开源的 React 设计系统150 无障碍组件 7 套主题 CLI它和 Tailwind 天生互补组件交给 Astryx布局和微调交给 Tailwind。更妙的是官方提供了一个桥接文件tailwind-theme.css导入一行后你就可以直接写rounded-lg、bg-surface、text-primary这样的原生 Tailwind 类名——它们背后全部指向 Astryx 的设计令牌design tokens换主题、切深色模式完全不用改代码。本指南带你从零到跑通。一、先装好这两个搭档 Astryx 要求React 19Tailwind 侧需要Tailwind CSS v4v4 的theme机制是桥接的前提。npm install astryxdesign/core astryxdesign/theme-neutral stylexjs/stylex npm install -D tailwindcss tailwindcss/viteVite 项目只需在构建配置里加上tailwindcss/vite插件参考示例工程 vite.config.tsNext.js 项目则连构建插件都不需要Astryx 附带预编译好的 CSS直接import即可。 所有 Astryx 组件都接受className这意味着两套系统不会打架而是分层协作。二、桥接文件的魔法一个文件换 80 语义化类名 桥接文件位于 tailwind-theme.css它用 Tailwind v4 的theme inline把 Astryx 的 CSS 变量注册成 Tailwind 主题变量theme inline { --color-surface: var(--color-background-surface); --color-primary: var(--color-text-primary); --radius-lg: var(--radius-container); /* ……颜色、间距、圆角、阴影、字体全部映射 */ }注意inline关键字它不输出重复的 CSS 声明只告诉 Tailwind “这些变量从 Astryx 的 CSS 自定义属性取值”。好处是——当 Astryx 切换主题或深浅色模式时var()引用的值变了你的bg-surface自动跟着变无需任何同步逻辑。常用映射一览Tailwind 类名对应 Astryx 令牌text-primary/text-secondary主文本 / 次级文本bg-surface/bg-card/bg-body卡片面 / 卡片底 / 页面底border-border/border-strong默认边框 / 强调边框bg-success/text-error/text-warning状态色令牌bg-blue-subtle/border-blue-ring/text-blue-vivid10 色调色板subtle / ring / vivid 三档强度rounded-sm/rounded-md/rounded-lg4px / 8px / 12px 圆角令牌shadow-sm/shadow-md/shadow-lg低 / 中 / 高投影间距也同步了桥接把--spacing基准指向 Astryx 的--spacing-14px所以p-4正好等于 Astryx 的--spacing-4 16px两边像素级一致。三、最快配置方法声明 CSS 层序 按顺序导入这是最容易踩坑的一步。在入口 CSS如globals.css或index.css里先把所有层一次性声明好再按顺序导入layer reset, theme, base, astryx-base, astryx-theme, components, utilities; import tailwindcss/theme.css layer(theme); import tailwindcss/preflight.css layer(base); import astryxdesign/core/reset.css; import astryxdesign/core/astryx.css; import astryxdesign/theme-neutral/theme.css; import astryxdesign/core/tailwind-theme.css; import tailwindcss/utilities.css layer(utilities);层序的意义是utilities 层优先级最高你随时可以用 Tailwind 工具类精准覆盖 Astryx 组件样式。如果漏掉了开头的layer声明Astryx 的层会在 Tailwind 之后创建导致classNamebg-red-500这类覆盖失效——完整原理见示例工程说明 README.md。别忘了在组件外包裹主题提供者Next.js 中放providers.tsxTheme theme{neutralTheme} LinkProvider component{Link}{children}/LinkProvider /Theme四、动手体验30 秒写出令牌驱动的卡片桥接就位后对比一下前后写法差距一目了然// 桥接前冗长的任意值 div classNamerounded-[var(--radius-container)] bg-[var(--color-background-surface)] p-[var(--spacing-4)] // 桥接后干净利落 div classNamerounded-lg bg-surface p-4 p classNametext-primaryStyled with Astryx tokens/p /div实际项目中的典型分工Astryx 出组件Tailwind 管布局main classNamemin-h-screen bg-body p-8 div classNamemx-auto max-w-3xl Card…Astryx 组件…/Card /div /main五、覆盖不足时两个逃生通道任意值语法桥接没覆盖到的令牌直接bg-[var(--color-background-surface)]随时可用className 覆盖所有 Astryx 组件都接受className例如Button labelCustom classNamerounded-full shadow-xl /utilities 层保证覆盖生效。六、换主题零成本深色模式免费获得这是桥接最爽的部分neutral、butter、matcha、y2k等 7 套主题只是不同的 CSS 变量取值。你写的每一个bg-surface、text-primary、rounded-lg都会自动解析到新主题的值上深色模式下同样如此——因为底层始终是同一组 CSS 自定义属性。设计师换肤开发者一行代码不动。参考资料桥接源码231 行含完整令牌映射注释tailwind-theme.css官方安装与 Tailwind 集成指南README.mdTailwind 互操作完整文档含 StyleX、CSS Modules、图表场景styling-libraries.doc.mjs可直接运行的示例工程index.css、App.tsx总结一句话导入astryxdesign/core/tailwind-theme.css声明好层序Astryx 的令牌就全部变成了你熟悉的 Tailwind 类名——组件用 Astryx 的样式用 Tailwind 的主题切换零成本。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考