Astryx Butter 主题深度指南暖金色设计系统主题的安装、配置与调色板再生成【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx导读astryxdesign/theme-butter是开源设计系统 Astryx 官方发布的主题包之一以温暖的金黄色 清爽的蓝色点缀为核心视觉语言专为消费级界面场景设计足够俏皮、又能保持可读性。本文将完整讲解该主题的安装接入、运行时挂载方式、21 步色调色板与语义色角色、字体排版体系并深入其源码与生成脚本带你理解调色板如何由 CIELab → HCT 算法平滑生成、组件级覆盖如何落地从而具备自定义与再生成该主题的实战能力。主题概览Butter 主题的定位在 package.json 中有明确描述Warm, creamy yellows with a friendly blue accent. Playful enough for consumer surfaces, soft enough to stay readable.温暖奶油黄 友好蓝色点缀对消费者界面足够俏皮对可读性足够柔和。展示字体DisplaySarina手写体仅用于页级大标题标题与正文Heading BodyOutfit基准 14px、比例 1.25代码字体CodeJetBrains Mono强调色Accent品牌蓝#225BFF暗色模式下切换为黄油黄#FDEE8C该主题基于 Astryx Core 的defineThemeAPI 定义产物包含编译后的theme.css、运行时主题对象与图标注册表可通过XDSTheme组件挂载到任意 React 应用中。安装使用 npm或 pnpm / yarn安装主题包同时需要安装其 peer 依赖astryxdesign/core与reactnpm install astryxdesign/theme-butter从 package.json 可以看到版本约束peerDependenciesastryxdesign/core0.6.0、react19dependencieslucide-react^1.18.0图标组件来源devDependenciesastryxdesign/cli0.6.0用于astryx theme build编译 CSS包的exports字段提供了三个子路径入口导入路径内容astryxdesign/theme-butter源码入口dist/source.js/dist/source.mjs同时导出butterTheme、butterPalettes与butterIconRegistryastryxdesign/theme-butter/built编译后的主题对象dist/butter.js供XDSTheme直接消费astryxdesign/theme-butter/theme.css编译生成的静态 CSSdist/theme.css快速接入在 React 应用中挂载 Butter 主题主题通过 Astryx 的运行时组件XDSTheme挂载。官方推荐的用法是导入built子路径下的butterTheme并同时引入theme.css保证在 JavaScript 运行前样式就已就位import {butterTheme} from astryxdesign/theme-butter/built; import {XDSTheme} from astryxdesign/core/theme; import astryxdesign/theme-butter/theme.css; function App() { return XDSTheme theme{butterTheme}{/* Your app content */}/XDSTheme; }要点说明为什么用/built而非根入口根入口导出的是 TS 源码打包产物含调色板数据等/built则是为运行时优化后的主题对象避免把不必要的元数据带进最终包体theme.css必须在文档头加载它由 CLI 编译生成包含全部 CSS 变量与组件样式提前引入可避免主题样式闪烁FOUCSarina 与 Outfit 依赖 Google FontsREADME 明确建议在文档head中手动添加对应的link relstylesheet预加载字体避免运行时按需拉取字体造成布局抖动。色彩体系源调色板与 21 步色调色板源色Source PaletteButter 的设计源头是以下六个品牌色其中 Accent 即品牌蓝暗色模式的主题强调色则切换为黄油黄RoleHexAccent#225BFFYellow#FDEE8CError#FC473BWarning#FFC502Success#91D143Info#4883FD21 步色调色板butterPalettes从 butterTheme.ts 可以看到Blue、Cyan、Green、Orange、Pink、Purple、Red、Teal、Yellow 九个分类色加上 Error / Warning / Success 三个语义色每一个都被发布为一套平滑的 21 步色调色板tone 从 0 到 100步长 5统一挂在butterPalettes导出下。例如 Blue 色板的提取片段blue: { 0: #000000, 5: #001041, 10: #001b4c, 15: #002558, 20: #062f63, 25: #203a6c, 30: #324575, ... 85: #cbd3f9, 90: #dbe1ff, 95: #edf0ff, 100: #ffffff, }语义色角色T90 / T80 / T25 三分法分类徽章Categorical badges、卡片cards与横幅文本banner text角色统一从这些色板中读取遵循固定的明暗两套取值约定T90浅色模式/T15暗色模式背景表面background surfacesT80浅色模式/T25暗色模式边框、暗色模式文本borders, dark-mode textT25浅色模式/T80暗色模式浅色模式文本、图标light-mode text, icons这一点在butterTheme.ts的 categorical 区域得到印证每个分类色的--color-background-*、--color-border-*、--color-text-*/--color-icon-*都取自同一色板的不同音阶。例如 Blue 分类--color-background-blue: [#dbe1ff, #dbe1ff], // T90 --color-border-blue: [#bdc5eb, #bdc5eb], // T80 --color-icon-blue: [#203a6c, #203a6c], // T25 --color-text-blue: [#203a6c, #203a6c], // T25值得注意的设计决策分类色在明暗两种模式下使用完全相同的值浅色模式的柔和粉彩背景 深色文字同样适用于暗色模式这与中性色/强调色在明暗模式下互换音阶的做法不同属于刻意保留的curated dark mode。语义状态色与徽章状态语义在 light / dark 两侧同样遵循 T25 / T80 约定例如--color-error: [#771210, #ffb4a6], --color-warning: [#543700, #f7be00], --color-success: [#004700, #99d94b],而徽章badge的语义变体则直接钉死品牌色以获得高辨识度的 vivid 填充例如variant:info使用#4883fd而非品牌蓝#225BFF、variant:error使用#fc473b、variant:success使用#91D143、variant:warning使用#ffc502variant:neutral则用黄油黄背景 品牌蓝文字。排版体系Sarina × Outfit × JetBrains Mono从 butterTheme.ts 的typography配置可以看到完整定义typography: { scale: {base: 14, ratio: 1.25}, body: { family: Outfit, fallbacks: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica, Arial, sans-serif, }, heading: { family: Outfit, fallbacks: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica, Arial, sans-serif, weights: {3: bold, 4: bold}, }, code: { family: JetBrains Mono, fallbacks: SF Mono, Monaco, Consolas, monospace, }, },Outfit承担标题与正文基准字号 14px、比例 1.25即 h 系列按 1.25 的等比缩放向上递增并为用户系统字体预留了完整 fallback 链Sarina手写体只用于text组件的type:display-1 / display-2 / display-3三个展示级尺寸通过组件覆盖的fontFamily引入含Brush Script MT, Snell Roundhand, cursive回退README 说明其通过页级内联样式应用专门留给 hero / 营销级大标题正文与标题不使用它JetBrains Mono用于代码fallback 到SF Mono, Monaco, Consolas。源码级原理调色板如何再生成单锚点平滑渐变算法generate-palettes.mjs 是调色板的生成器。它的核心思路是单锚点single-anchor每个色板只有一个源色source hex整套 21 步渐变通过CIELab → HCT色彩空间算法推导得到——这与主题预览条ThemePalettePreview使用的算法一致从而保证渲染的色带与消费的 token 值严格 1:1。关键实现细节hexToHct把 hex 依次转换为 sRGB → linear RGB → XYZD65 白点→ Lab再从 Lab 中分离出 hue色相角、chroma彩度与 tone明度 0–100hctToHex反向迭代求解通过二分逼近保证颜色落在 sRGB 色域内chroma 0.5时直接退化为灰度从而得到给定 tone 下的最纯色tonalPalette(hue, chroma)对STEPS [0,5,10,...,95,100]逐个 tone 生成颜色并带有彩度增强逻辑——t 50时按1 (50 - t) / 40提高 chroma低 tone 端需要更高彩度才能保持色相可见上限为源色彩度的 1.8 倍。SOURCES 选择策略与再生成流程生成器把SOURCES映射表generate-palettes.mjs作为唯一输入const SOURCES { blue: #bdc5eb, cyan: #8dd2d3, green: #a5d29d, orange: #f2bd81, pink: #f0b3e8, purple: #ddb9f6, red: #f4b8ae, teal: #94d3bb, yellow: #e5d765, neutral: #c1c6d5, accent: #225BFF, error: #ffb3a5, warning: #f7be00, success: #91D143, };选择源色时有一个精妙的约定分类色以T80浅色边框色作为锚点让中浅色音阶保持诚实mid-light tone honest使渐变向两端平滑展开对于 T80 本身彩度过高、难以向两端展开的色相如黄色则改用略高的 tone 作为源。而语义色error / warning / success直接用 vivid 品牌色作锚让色板在徽章填充色附近扎根。再生成步骤README 明确给出编辑SOURCES映射中的源色 hex运行生成脚本仓库根目录下执行node packages/themes/butter/scripts/generate-palettes.mjs脚本会向 stdout 打印完整的export const butterPalettes {...}代码将其粘贴回 butterTheme.ts 中替换原有butterPalettes定义即可。脚本注释还提醒T15 / T25 / T80 / T90 这四个在用音阶会与当前 token 值接近但不一定完全相等脚本打印新 T 值与旧 token 的差值delta方便确认色板漂移程度。组件级定制与图标注册表组件覆盖components 配置defineTheme的components段允许主题在不改组件源码的前提下按组件与变体精确覆盖样式。Butter 的覆盖策略可以从源码中归纳为几个清晰的模式TopNav 强调品牌蓝top-nav-heading 与 top-nav-item 覆盖 将标题与选中项设为完整品牌蓝#225BFF暗色模式为黄油黄#FDEE8C未选中项用更浅的蓝#6E92FF选中项刻意不设背景药丸依靠字重与颜色制造强调按钮Button不钉死圆角保留 core 的--_button-radius回退保证独立按钮 8px、聊天输入框内可被覆盖成全圆角variant:secondary用蓝色描边 蓝色文字暗色模式切黄油黄hover 添加#225BFF14半透明蓝底variant:destructive使用粉彩红底#ffdad3 深红文字#550000横幅Banner与字段状态FieldStatus在局部作用域内覆写--color-*-muted等语义 token使横幅头部渲染出与徽章一致的 vivid 填充色且不会泄漏到全局输入类组件text-input、text-area、number-input、date-input、time-input、selector、multi-selector、typeahead、tokenizer统一使用--spacing-2的垂直内边距与更柔和的边框并把status:success / warning / error的语义色局部重映射为徽章同款 vivid 色让状态图标与边框与横幅读感一致圆角与阴影--radius-element: 8px按钮、徽章、输入框、--radius-container: 12px卡片、横幅、弹层--radius-none与--radius-full恒定为 0 与 9999px 不可被主题缩放阴影统一使用暖中性色#1d1c11的透明色阶。图标注册表Butter 自带的butterIconRegistry见 icons.tsx把语义图标名映射到lucide-react的图标组件close、check、success、error、warning、info、search、calendar、menu等 30 个所有图标统一size: 1em、aria-hidden随主题打包而非随 Core 打包——这也是lucide-react出现在依赖而非 peer 依赖的原因。构建产物与发布形态package.json的build脚本展示了完整的产物流水线node ../../../scripts/clean-dist.mjs \ astryx theme build src/butterTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs \ tsup \ tsc --project tsconfig.build.json \ node ../../../scripts/check-fully-specified.mjs即先清理dist再由 Astryx CLI 将src/butterTheme.ts编译为dist/theme.css对应theme.css导出随后tsup配置见 tsup.config.ts对source.ts与icons.tsx分别产出 CJS / ESM与tsc生成类型声明最后用check-fully-specified校验所有导出路径均已声明确保发布包的导入路径完备。最终files字段发布dist与src两目录。小结astryxdesign/theme-butter是一个完整的、可独立发布与消费的 Astryx 主题包XDSThemetheme.css一行挂载即可应用21 步色调色板由 CIELab → HCT 算法从单一锚点平滑生成T90 / T80 / T25 音阶约定统一了徽章、卡片、横幅的明暗角色映射Sarina × Outfit × JetBrains Mono 组合定义了从展示级大标题到代码的完整字体阶梯组件级覆盖与图标注册表则让主题能在不触碰组件源码的前提下精准定制品牌感知。若想进一步了解 Astryx 主题规范与架构约定可继续阅读 主题规范索引 与 主题编译、主题令牌 等架构文档。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考