FanControl完全指南：5分钟快速配置电脑风扇温度曲线
2026/9/16 17:47:59
astryx Stone 主题演进指南：从版本变更记录到设计令牌源码实践
【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx
Stone 是 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/core@0.6.0与react >= 19，运行时依赖lucide-react提供图标。
1.1 安装
npm install @astryxdesign/theme-stone注意：0.6.0 属于协调稳定版（coordinated stable release），CHANGELOG 明确要求同时升级 Core 与主题包（"Upgrade Core and this theme together"），混用不同大版本会导致令牌或组件接口不匹配。
1.2 通过 React 组件使用
在应用根节点用XDSTheme包裹，传入stoneTheme：
import {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 | 预构建 dist（Tailwind、纯 CSS、或无构建步骤） |
@astryxdesign/theme-stone/theme.css | 预构建 CSS 文件（在样式表中直接引入） |
从 package.json 的exports字段可以看到三种产物的实际落点：
"."指向dist/source.mjs（ESM）与dist/source.js（CJS）；"./built"指向dist/stone.js，是经过编译、无需 StyleX 预处理即可直接运行的构建产物；"./theme.css"指向dist/theme.css。
若使用@astryxdesign/build做 StyleX 源码编译，请从裸路径导入；否则一律使用/built。纯 CSS 场景还可以在样式表中这样引入：
@import '@astryxdesign/theme-stone/theme.css';1.4 字体加载（必须单独引入）
Stone 主题引用三类自定义字体，但不打包字体文件，需要自行加载，否则回退到系统字体：
| 角色 | 字体 |
|---|---|
| 正文 Body | Figtree |
| 标题 Heading | Montserrat |
| 代码 Code | JetBrains Mono |
在 HTML<head>中加入：
<link rel="preconnect" href="https://fonts.googleapis.com" /> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin /> <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Montserrat:wght@400;500;600;700&display=swap" />二、版本演进主线：CHANGELOG 逐版解读
Stone 的 CHANGELOG 呈现出"空版本多、关键修复密集"的特征——多数小版本无实质变更（0.5.4、0.5.2、0.5.0、0.4.7……），而带 Fixes 的版本往往解决了暗色模式对比度或构建兼容性问题。以下按时间倒序梳理关键版本。
2.1 0.6.0 —— 协调稳定版（Breaking）
- Breaking Changes：要求
@astryxdesign/core@0.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"。 - 产物瘦身：主题包不再发布未使用的 CommonJS
icons.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 与外部化 SSR（Vite--ssr、Remix / React Router v7）下正常加载：它改为导入./icons.mjs而非无扩展名的./icons（Node 无法解析无扩展名模块）。这解释了 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"模式）。
- 覆盖层与浅色对称：hover
- 问题 2（#3625）：暗色模式下
--color-overlay、--color-border、--color-shadow曾完全不透明（#28282a、#f3f3f5、#000000）。不透明 overlay 会把整页盖成实心块而非半透明遮罩；不透明 border 画出实心近白细线而非微妙的发丝线；不透明 shadow 没有衰减。修复恢复了 Stone 引入时的原始值：--color-overlay: #28282acc（80%）、--color-border: #f3f3f51a（T96 · 10%）、--color-shadow: #0000004d（30%）。
这些数值在当前源码中都能一一对应验证：见 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/core@0.0.15（裸名迁移 + contenteditable="false">【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考