Project AIRI 设计工具链实战：UnoCSS 配色体系、Radix Colors 与背景纹理资源指南-育师

Project AIRI 设计工具链实战：UnoCSS 配色体系、Radix Colors 与背景纹理资源指南

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

AIRI 是一个自托管、you-owned 的 AI 陪伴项目，其 UI/UX 设计团队维护了一套完整的设计指南。本文以仓库中设计指南 · 工具篇为核心骨架，结合仓库内真实的 UnoCSS 配置与组件实现，系统讲解 AIRI 的配色工具链（UnoCSS、Tailwind 色板、Radix Colors、互补色选择工具）与背景纹理资源工具，以及这些原则如何落实到代码中。读完本文，你将掌握为 AIRI 各端（Web / Desktop / 组件库）贡献样式代码时的选色规范、透明度使用边界，以及背景装饰的可复用方案。

一、配色工具链（Colors）

AIRI 的样式体系以「原子化 CSS + 预设色板 + 色彩理论工具」三层结构展开，每一层都有明确的分工。

1.1 UnoCSS：样式生成的默认引擎

开发期间，AIRI 使用 UnoCSS 生成全部样式相关代码。文档明确指出：这是一个与 Tailwind 工作方式几乎一致的工具，因此 Tailwind 的经典工具类心智模型（如bg-neutral-500、text-pink-400）可以无缝迁移。

在仓库根目录的 uno.config.ts 中可以看到 AIRI 实际使用的完整预设组合：

export function sharedUnoConfig() { return defineConfig({ presets: [ presetWind3(), // Tailwind Wind3 兼容的原子类 presetAttributify(), // 属性化写法，如 <div bg="pink-500" /> presetTypography(), // 排版（prose 系列） presetIcons({ scale: 1.2 }), // 图标（lobe-icons / meteocons 集合） presetScrollbar(), // 滚动条样式 presetChromatic({ // 色相驱动的主题色生成 baseHue: 220.44, colors: { primary: 0, complementary: 180 }, }), ], // ... }) }

其中presetChromatic来自仓库内部的@proj-airi/unocss-preset-chromatic包（见 pnpm-workspace.yaml），它把下文要讲的「互补色」理念直接编码进了构建流程。该配置不仅用于根目录，也被 apps/component-calling/uno.config.ts 和 docs/uno.config.ts 等子应用复用，说明这是一套跨端统一的样式基线。

1.2 基础色板：沿用 Tailwind 色彩体系

由于 UnoCSS 与 Tailwind 高度同构，AIRI 的基础色板直接引用 Tailwind CSS 官方 Colors 文档中的色阶定义。这意味着任何熟悉 Tailwind 色板的开发者都能立即上手，无需重新学习一套新的十六进制色值表。

AIRI 默认主题约定使用四类色：

色系	用途倾向
`neutral`	中性灰阶，用于文字、边框、背景分层
`pink`	主色调之一，用于强调与品牌点缀
`violet`	辅助强调色，常用于渐变与高亮
`cyan`	冷色点缀，用于状态与信息提示

这四个色系在组件代码中的典型用法例如：bg-pink-500/10、text-violet-400、border-neutral-800。为了确保动态生成的primary色系类名不会被 UnoCSS 的按需扫描机制遗漏，仓库在 uno.config.ts 提供了safelistAllPrimaryBackgrounds()：

export function safelistAllPrimaryBackgrounds(): string[] { return [undefined, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950].map((shade) => { const prefix = shade ? `bg-primary-${shade}` : `bg-primary` return [ prefix, ...[5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100].map(opacity => `${prefix}/${opacity}`), ] }).flat() }

它预先生成了bg-primary的 50～950 全色阶，以及 5%～100% 共 11 档透明度变体，可见主色体系在整个 UI 中被大量动态使用。

1.3 调色第一原则：改变色度优先选择纯色，而非透明度

这是 AIRI 设计指南中一条硬性规范，引述自 Refactoring UI：

当我们需要改变颜色的色度（chroma）时，应尽量避免使用透明度（opacity），而应手工挑选对比度最佳的、不含 alpha 通道的纯色。

原因在于：opacity会让底色透出，导致前景与背景的对比度不可控；而手工挑选的纯色可以精确计算对比度，保证可读性。文档的结论是：

除非透明度本身就是排版设计的一部分，否则请尽量挑选最好的纯色以获得更好的可读性。

这条原则在仓库中有镜像实现：presetChromatic以baseHue: 220.44为基准，自动推导出完整的primary纯色色阶（50～950），让开发者始终有「一整条纯色梯」可用，而不是靠opacity凑色。safelistAllPrimaryBackgrounds()中同时保留了透明度变体，正说明透明度仅用于特殊场景（如悬浮态遮罩），常规正文与组件底色应使用纯色。

1.4 Radix Colors：交互组件的色彩基石

AIRI 文档将 Radix Colors 定位为「交互式 UI 元素的构建块」——它提供了经过色彩理论推敲的完整色板，支持从调色板中直接挑选合适颜色。

在仓库的实际依赖中，这一理念的落地载体是reka-ui（Radix UI 的 Vue 移植版）：packages/stage-ui/package.json 与 packages/ui/package.json 等核心 UI 包均声明了reka-ui依赖。Radix 生态的交互原语（对话框、弹层、下拉菜单等）自带经过对比度验证的语义配色方案，AIRI 将其作为组件库的配色底层，与 UnoCSS 的原子类体系互补：Radix 管「交互组件的色彩语义」，UnoCSS 管「页面布局与主题色」。

Radix 风格的动效也在 uno.config.ts 中预置了对应的 keyframes 与缓动函数，例如弹层出现的contentShow（150ms，cubic-bezier(0.16, 1, 0.3, 1)缓动 + 缩放位移）、滑入类slideUpAndFade（400ms）等，说明交互组件的"入场/离场"动画节奏已被统一收口到主题层。

1.5 互补色（Complementary Color）与配色工具

互补色对提升对比度非常有效。AIRI 设计指南推荐了三个可交互的互补色选择工具：

Figma Color Wheel —— 设计工具内的取色轮
Canva Colors - Color Wheel —— 在线快速配互补色
Paletton —— 支持单色、邻近色、三色、四色等多种配色方案的调色板

有趣的是，互补色不仅是设计工具中的概念，在 AIRI 代码中也被参数化了。uno.config.ts 的presetChromatic配置里：

presetChromatic({ baseHue: 220.44, colors: { primary: 0, // 主色 = 基准色相偏移 0° complementary: 180, // 互补色 = 在色环上偏移 180°，即主色的正对角色 }, })

complementary: 180正是在色环上取主色的对角色相——与设计指南中"利用互补色增强对比"的建议完全对应。开发者无需手动计算色相，主题系统会自动生成与主色严格互补的complementary色阶。这种「文档给方法论、代码给自动化实现」的组合，是 AIRI 设计体系的一大特色。

二、背景与纹理（Backgrounds & Patterns）

设计指南提供了两个背景资源工具，用于为页面、弹层、Hero 区域快速生成视觉装饰：

2.1 SVG Backgrounds

SVG Backgrounds 提供免费可用的 SVG 背景与图案集合，适合生成点阵、网格、波形、几何图形等轻量背景，可直接内联或作为 CSSbackground-image使用，无需引入图片资源。

在 AIRI 的 UnoCSS 配置中，可以找到与点阵背景对应的自定义规则（uno.config.ts）：

[/^bg-dotted-\[(.*)\]$/, ([, color], { theme }) => { const parsedColor = parseColor(color, theme) return { 'background-image': `radial-gradient(circle at 1px 1px, ${...} 1px, transparent 0)`, '--un-background-opacity': ..., } }],

用法示例：bg-dotted-[#c084fc]即可生成以指定颜色绘制的径向渐变点阵背景——这正是把「SVG 背景图案」这一资源工具内化成原子类能力的做法，让组件开发者可以在模板里一行代码产出装饰性纹理。

2.2 Finisher 动画背景头部

Finisher 用于为任意网站生成带动画效果的背景头部（Animated Background Headers），适合 Landing 页、舞台页首屏等需要流动感的场景。它输出一段可嵌入的脚本与样式，与前端框架无关，接入成本低。

2.3 更多背景资源入口

设计指南还指向了与 Resources 篇同源的两类补充资料：创意背景聚合站（如 wweb.dev 的 Creative Backgrounds 合集）与 CSS Loaders 加载动画合集，可作为背景与微交互素材的备选池。

三、如何在 AIRI 仓库中应用这套规范

结合以上工具链，在 AIRI 仓库中贡献设计代码时的推荐路径如下：

起手式：在任一子应用（如 apps/component-calling/uno.config.ts、packages/stage-ui/uno.config.ts）继承sharedUnoConfig()，获得统一的presetChromatic主题色、动效 keyframes 与自定义背景规则。
选色：基础灰阶与强调色从 Tailwind 色板（neutral/pink/violet/cyan）中选；交互组件语义色参考 Radix Colors（仓库内由reka-ui承载）；主题主色直接使用primary-{50..950}纯色阶。
调色戒律：需要更浅/更深的色度时，改选相邻色阶（如primary-400→primary-300），不要叠加opacity，除非是排版层面的刻意设计。
互补强调：需要与主色对撞的强调元素时，使用自动生成的complementary色系，避免手工对色相。
背景装饰：点阵等纹理使用bg-dotted-[颜色]原子类；需要更复杂的背景图案时参考 SVG Backgrounds 资源，动画背景头部可参考 Finisher。
交互动效：弹层、浮层类组件的显隐动画使用主题内置的overlayShow/contentShow/slideUpAndFade等 keyframes，保证全端节奏一致。

四、总结

AIRI 的设计工具链呈现出一条清晰的「工具 → 原则 → 代码」闭环：UnoCSS 提供与 Tailwind 兼容的原子化基础，Tailwind 色板与 Radix Colors 提供经过验证的色阶语义，互补色工具与 Refactoring UI 的纯色原则提供选色方法论，而presetChromatic（baseHue: 220.44+complementary: 180）、safelistAllPrimaryBackgrounds()、bg-dotted-[...]与 Radix 风格动效 keyframes 则把这些原则固化为可复用的工程实现。无论你是为 AIRI 的 Web 端、Desktop 端还是 stage-ui 组件库提交样式代码，这套规范都能保证产出风格统一、对比度可靠、可直接并入主线的 UI。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考