尧图网页设计 
astryx Stone 主题演进指南从版本变更记录到设计令牌源码实践【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxStone 是 astryx 设计系统中一套以暖灰石色warm stone slate为主基调的开源主题官方定位为earthy and understated, with just enough character to feel handcrafted。本篇指南以 packages/themes/stone/CHANGELOG.md 为骨架逐条还原 Stone 主题从 0.0.15 到 0.6.0 的关键变更——包括暗色模式透明度修复、WCAG AA 对比度修正、--radius-none固定语义回归、/built入口的 ESM/SSR 兼容以及icons.mjs产物瘦身——并深入到 packages/themes/stone/src/stoneTheme.ts 的令牌与组件覆盖实现。读完你将掌握如何安装使用 Stone 主题、三个导入路径的取舍、其设计令牌体系色调/圆角/阴影/分类色板的底层约定以及为什么每一次版本修复都指向可复现的无障碍与构建问题。一、主题概况与安装使用Stone 主题包名为astryxdesign/theme-stone与astryxdesign/core配合使用。当前仓库内版本为 0.6.0见 packages/themes/stone/package.json其 peerDependencies 要求astryxdesign/core0.6.0与react 19运行时依赖lucide-react提供图标。1.1 安装npm install astryxdesign/theme-stone注意0.6.0 属于协调稳定版coordinated stable releaseCHANGELOG 明确要求同时升级 Core 与主题包Upgrade Core and this theme together混用不同大版本会导致令牌或组件接口不匹配。1.2 通过 React 组件使用在应用根节点用XDSTheme包裹传入stoneThemeimport {XDSTheme} from astryxdesign/core/theme; import {stoneTheme} from astryxdesign/theme-stone/built; function App() { return XDSTheme theme{stoneTheme}{/* your app */}/XDSTheme; }1.3 三个导入路径的取舍路径适用场景astryxdesign/theme-stone源码构建经由astryxdesign/build的 StyleX 编译astryxdesign/theme-stone/built预构建 distTailwind、纯 CSS、或无构建步骤astryxdesign/theme-stone/theme.css预构建 CSS 文件在样式表中直接引入从 package.json 的exports字段可以看到三种产物的实际落点.指向dist/source.mjsESM与dist/source.jsCJS./built指向dist/stone.js是经过编译、无需 StyleX 预处理即可直接运行的构建产物./theme.css指向dist/theme.css。若使用astryxdesign/build做 StyleX 源码编译请从裸路径导入否则一律使用/built。纯 CSS 场景还可以在样式表中这样引入import astryxdesign/theme-stone/theme.css;1.4 字体加载必须单独引入Stone 主题引用三类自定义字体但不打包字体文件需要自行加载否则回退到系统字体角色字体正文 BodyFigtree标题 HeadingMontserrat代码 CodeJetBrains Mono在 HTMLhead中加入link relpreconnect hrefhttps://fonts.googleapis.com / link relpreconnect hrefhttps://fonts.gstatic.com crossorigin / link relstylesheet hrefhttps://fonts.googleapis.com/css2?familyFigtree:wght400;500;600;700familyJetBrainsMono:wght400;500;600;700familyMontserrat:wght400;500;600;700displayswap /二、版本演进主线CHANGELOG 逐版解读Stone 的 CHANGELOG 呈现出空版本多、关键修复密集的特征——多数小版本无实质变更0.5.4、0.5.2、0.5.0、0.4.7……而带 Fixes 的版本往往解决了暗色模式对比度或构建兼容性问题。以下按时间倒序梳理关键版本。2.1 0.6.0 —— 协调稳定版BreakingBreaking Changes要求astryxdesign/core0.6.0作为协调稳定发布的一部分。升级时必须 Core 与主题同步升级。2.2 0.5.3 —— 语法主题标识符重命名#5847重命名内置语法主题built-in syntax theme标识符。该变更与 Core 侧的语法主题命名约定对齐贡献者 rubyycheung。在 Stone 源码中语法主题通过defineSyntaxTheme({name: astryx-stone, ...})定义见 stoneTheme.ts标识符astryx-stone是CodeBlock等组件按名称查找语法高亮方案的键。2.3 0.5.1 —— 次级文本对比度与产物瘦身#5505/#5509/#5512对比度修复将--color-text-secondary迁移到规范的 T40/T70 色阶对使普通次级文本在主题的明/暗消费表面上达到 WCAG AA 标准。在源码中对应--color-text-secondary: [#5e5e63, #ababb0]浅色 T40 / 深色 T70见 stoneTheme.ts注释明确写到T40/T70 keeps normal secondary text above AA on every stone surface。产物瘦身主题包不再发布未使用的 CommonJSicons.js工件。根入口保留 CJS 与 ESM 两种输出而/built使用的独立图标伴生文件只以icons.mjs形式输出。这与 tsup.config.ts 中icons.tsx仅以 ESM 格式构建、source.ts同时构建 cjs/esm 的配置一致。2.4 0.4.3 —— Node ESM 与 SSR 兼容#AKnassa/built入口现在能在 Node ESM 与外部化 SSRVite--ssr、Remix / React Router v7下正常加载它改为导入./icons.mjs而非无扩展名的./iconsNode 无法解析无扩展名模块。这解释了 0.5.1 中图标仅输出icons.mjs的决策脉络——它们是一对连续的构建兼容修复。2.5 0.4.2 —— 圆角令牌回归修复#is-jain--radius-none不再被错误覆盖为0.125rem。--radius-none与--radius-full被文档约定为永远固定、不被主题缩放分别恒为0px与9999px与 Core 自身默认一致。此前 Stone 等主题的圆角组误将--radius-none一并缩放导致任何通过--radius-none取消圆角的组件静默得到 2px 圆角。修复后stoneTheme.ts 中可以看到完整的圆角阶梯--radius-none: 0px、--radius-inner: 0.25rem、--radius-element: 0.5rem、--radius-container: 0.75rem、--radius-page: 1.5rem、--radius-full: 9999px其中--radius-none与--radius-full明确带注释always fixed and must never be scaled by a theme。2.6 0.1.4 —— 暗色模式 overlay/accent-muted 透明度修复#3622/#3625这是 CHANGELOG 中最具技术深度的两次修复全部围绕半透明覆盖令牌在暗色模式下丢失 alpha问题 1#3622暗色模式下--color-accent-muted、--color-overlay-hover、--color-overlay-pressed曾是完全不透明的#f3f3f5而浅色模式对应值是半透明色。由于这些令牌负责绘制绝对定位的 hover/press 覆盖层与 muted-accent 填充不透明暗值会遮挡下层内容而非着色。修复后覆盖层与浅色对称hover#f3f3f50d/ pressed#f3f3f51a与 butter/chocolate/matcha/neutral/y2k 一致accent-muted 在暗色下强化一档#f3f3f520沿用 chocolate/matcha/y2k 的浅 14 / 暗 20模式。问题 2#3625暗色模式下--color-overlay、--color-border、--color-shadow曾完全不透明#28282a、#f3f3f5、#000000。不透明 overlay 会把整页盖成实心块而非半透明遮罩不透明 border 画出实心近白细线而非微妙的发丝线不透明 shadow 没有衰减。修复恢复了 Stone 引入时的原始值--color-overlay: #28282acc80%、--color-border: #f3f3f51aT96 · 10%、--color-shadow: #0000004d30%。这些数值在当前源码中都能一一对应验证见 stoneTheme.ts 中--color-overlay、--color-border、--color-shadow、--color-accent-muted、--color-overlay-hover、--color-overlay-pressed的明暗双值定义。2.7 0.1.2 —— 暗色模式--color-neutral透明度修复#3119暗色模式下--color-neutral曾是不透明#f3f3f5而其他主题均使用约 10% alpha 的半透明中性色调。由于--color-neutral填充 secondary 按钮变体暗色模式下会渲染出实心近白表面 近白文字的不可读组合。修复为#f3f3f51a与所有其他主题的约定一致。源码当前值为--color-neutral: [#25252a0f, #f3f3f51a]浅色 T15 · 6% / 暗色 T96 · 10%。2.8 0.0.15 —— 迁移基准Changes跟踪xds/core0.0.15裸名迁移 contenteditable="false">【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 astryx Stone 主题演进指南：从版本变更记录到设计令牌源码实践
astryx Stone 主题演进指南从版本变更记录到设计令牌源码实践【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxStone 是 astryx 设计系统中一套以暖灰石色warm stone slate为主基调的开源主题官方定位为earthy and understated, with just enough character to feel handcrafted。本篇指南以 packages/themes/stone/CHANGELOG.md 为骨架逐条还原 Stone 主题从 0.0.15 到 0.6.0 的关键变更——包括暗色模式透明度修复、WCAG AA 对比度修正、--radius-none固定语义回归、/built入口的 ESM/SSR 兼容以及icons.mjs产物瘦身——并深入到 packages/themes/stone/src/stoneTheme.ts 的令牌与组件覆盖实现。读完你将掌握如何安装使用 Stone 主题、三个导入路径的取舍、其设计令牌体系色调/圆角/阴影/分类色板的底层约定以及为什么每一次版本修复都指向可复现的无障碍与构建问题。一、主题概况与安装使用Stone 主题包名为astryxdesign/theme-stone与astryxdesign/core配合使用。当前仓库内版本为 0.6.0见 packages/themes/stone/package.json其 peerDependencies 要求astryxdesign/core0.6.0与react 19运行时依赖lucide-react提供图标。1.1 安装npm install astryxdesign/theme-stone注意0.6.0 属于协调稳定版coordinated stable releaseCHANGELOG 明确要求同时升级 Core 与主题包Upgrade Core and this theme together混用不同大版本会导致令牌或组件接口不匹配。1.2 通过 React 组件使用在应用根节点用XDSTheme包裹传入stoneThemeimport {XDSTheme} from astryxdesign/core/theme; import {stoneTheme} from astryxdesign/theme-stone/built; function App() { return XDSTheme theme{stoneTheme}{/* your app */}/XDSTheme; }1.3 三个导入路径的取舍路径适用场景astryxdesign/theme-stone源码构建经由astryxdesign/build的 StyleX 编译astryxdesign/theme-stone/built预构建 distTailwind、纯 CSS、或无构建步骤astryxdesign/theme-stone/theme.css预构建 CSS 文件在样式表中直接引入从 package.json 的exports字段可以看到三种产物的实际落点.指向dist/source.mjsESM与dist/source.jsCJS./built指向dist/stone.js是经过编译、无需 StyleX 预处理即可直接运行的构建产物./theme.css指向dist/theme.css。若使用astryxdesign/build做 StyleX 源码编译请从裸路径导入否则一律使用/built。纯 CSS 场景还可以在样式表中这样引入import astryxdesign/theme-stone/theme.css;1.4 字体加载必须单独引入Stone 主题引用三类自定义字体但不打包字体文件需要自行加载否则回退到系统字体角色字体正文 BodyFigtree标题 HeadingMontserrat代码 CodeJetBrains Mono在 HTMLhead中加入link relpreconnect hrefhttps://fonts.googleapis.com / link relpreconnect hrefhttps://fonts.gstatic.com crossorigin / link relstylesheet hrefhttps://fonts.googleapis.com/css2?familyFigtree:wght400;500;600;700familyJetBrainsMono:wght400;500;600;700familyMontserrat:wght400;500;600;700displayswap /二、版本演进主线CHANGELOG 逐版解读Stone 的 CHANGELOG 呈现出空版本多、关键修复密集的特征——多数小版本无实质变更0.5.4、0.5.2、0.5.0、0.4.7……而带 Fixes 的版本往往解决了暗色模式对比度或构建兼容性问题。以下按时间倒序梳理关键版本。2.1 0.6.0 —— 协调稳定版BreakingBreaking Changes要求astryxdesign/core0.6.0作为协调稳定发布的一部分。升级时必须 Core 与主题同步升级。2.2 0.5.3 —— 语法主题标识符重命名#5847重命名内置语法主题built-in syntax theme标识符。该变更与 Core 侧的语法主题命名约定对齐贡献者 rubyycheung。在 Stone 源码中语法主题通过defineSyntaxTheme({name: astryx-stone, ...})定义见 stoneTheme.ts标识符astryx-stone是CodeBlock等组件按名称查找语法高亮方案的键。2.3 0.5.1 —— 次级文本对比度与产物瘦身#5505/#5509/#5512对比度修复将--color-text-secondary迁移到规范的 T40/T70 色阶对使普通次级文本在主题的明/暗消费表面上达到 WCAG AA 标准。在源码中对应--color-text-secondary: [#5e5e63, #ababb0]浅色 T40 / 深色 T70见 stoneTheme.ts注释明确写到T40/T70 keeps normal secondary text above AA on every stone surface。产物瘦身主题包不再发布未使用的 CommonJSicons.js工件。根入口保留 CJS 与 ESM 两种输出而/built使用的独立图标伴生文件只以icons.mjs形式输出。这与 tsup.config.ts 中icons.tsx仅以 ESM 格式构建、source.ts同时构建 cjs/esm 的配置一致。2.4 0.4.3 —— Node ESM 与 SSR 兼容#AKnassa/built入口现在能在 Node ESM 与外部化 SSRVite--ssr、Remix / React Router v7下正常加载它改为导入./icons.mjs而非无扩展名的./iconsNode 无法解析无扩展名模块。这解释了 0.5.1 中图标仅输出icons.mjs的决策脉络——它们是一对连续的构建兼容修复。2.5 0.4.2 —— 圆角令牌回归修复#is-jain--radius-none不再被错误覆盖为0.125rem。--radius-none与--radius-full被文档约定为永远固定、不被主题缩放分别恒为0px与9999px与 Core 自身默认一致。此前 Stone 等主题的圆角组误将--radius-none一并缩放导致任何通过--radius-none取消圆角的组件静默得到 2px 圆角。修复后stoneTheme.ts 中可以看到完整的圆角阶梯--radius-none: 0px、--radius-inner: 0.25rem、--radius-element: 0.5rem、--radius-container: 0.75rem、--radius-page: 1.5rem、--radius-full: 9999px其中--radius-none与--radius-full明确带注释always fixed and must never be scaled by a theme。2.6 0.1.4 —— 暗色模式 overlay/accent-muted 透明度修复#3622/#3625这是 CHANGELOG 中最具技术深度的两次修复全部围绕半透明覆盖令牌在暗色模式下丢失 alpha问题 1#3622暗色模式下--color-accent-muted、--color-overlay-hover、--color-overlay-pressed曾是完全不透明的#f3f3f5而浅色模式对应值是半透明色。由于这些令牌负责绘制绝对定位的 hover/press 覆盖层与 muted-accent 填充不透明暗值会遮挡下层内容而非着色。修复后覆盖层与浅色对称hover#f3f3f50d/ pressed#f3f3f51a与 butter/chocolate/matcha/neutral/y2k 一致accent-muted 在暗色下强化一档#f3f3f520沿用 chocolate/matcha/y2k 的浅 14 / 暗 20模式。问题 2#3625暗色模式下--color-overlay、--color-border、--color-shadow曾完全不透明#28282a、#f3f3f5、#000000。不透明 overlay 会把整页盖成实心块而非半透明遮罩不透明 border 画出实心近白细线而非微妙的发丝线不透明 shadow 没有衰减。修复恢复了 Stone 引入时的原始值--color-overlay: #28282acc80%、--color-border: #f3f3f51aT96 · 10%、--color-shadow: #0000004d30%。这些数值在当前源码中都能一一对应验证见 stoneTheme.ts 中--color-overlay、--color-border、--color-shadow、--color-accent-muted、--color-overlay-hover、--color-overlay-pressed的明暗双值定义。2.7 0.1.2 —— 暗色模式--color-neutral透明度修复#3119暗色模式下--color-neutral曾是不透明#f3f3f5而其他主题均使用约 10% alpha 的半透明中性色调。由于--color-neutral填充 secondary 按钮变体暗色模式下会渲染出实心近白表面 近白文字的不可读组合。修复为#f3f3f51a与所有其他主题的约定一致。源码当前值为--color-neutral: [#25252a0f, #f3f3f51a]浅色 T15 · 6% / 暗色 T96 · 10%。2.8 0.0.15 —— 迁移基准Changes跟踪xds/core0.0.15裸名迁移 contenteditable="false">【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考