2321 字
12 分钟
Fuwari 博客模板 Design Tokens 完整指南
2025-11-07
环境搭建
环境搭建

概述#

Fuwari 是一个基于 Astro 的现代化静态博客模板，采用了一套完整的设计令牌（Design Tokens）系统来管理颜色、间距、排版和其他设计元素。该系统结合了 CSS 变量、Tailwind CSS 和动态色相调整，提供了高度可定制的主题体验。

核心 CSS 变量列表#

颜色相关 (Colors)#

主要色彩变量#

变量名描述定义方式使用场景
--hue主题色相值 (0-360)JavaScript 动态设置所有使用 OKLCH 颜色的元素
--primary主要品牌色基于 --hue 的 OKLCH 颜色链接、按钮强调色、图标

背景色#

变量名描述浅色模式深色模式
--page-bg页面背景色oklch(0.95 0.01 var(—hue))oklch(0.16 0.014 var(—hue))
--card-bg卡片/面板背景色whiteoklch(0.23 0.015 var(—hue))
--float-panel-bg浮动面板背景色whiteoklch(0.23 0.015 var(—hue))
--codeblock-bg代码块背景色oklch(0.17 0.015 var(—hue))oklch(0.17 0.015 var(—hue))
--codeblock-topbar-bg代码块顶部条背景色oklch(0.3 0.02 var(—hue))oklch(0.12 0.015 var(—hue))
--inline-code-bg内联代码背景色引用 —btn-regular-bg引用 —btn-regular-bg
--license-block-bg许可证块背景色rgba(0,0,0,0.03)引用 —codeblock-bg

按钮状态色#

变量名亮色值深色值说明
--btn-contentoklch(0.55 0.12 var(—hue))oklch(0.75 0.1 var(—hue))按钮内容（文字）颜色
--btn-regular-bgoklch(0.95 0.025 var(—hue))oklch(0.33 0.035 var(—hue))普通按钮背景色
--btn-regular-bg-hoveroklch(0.9 0.05 var(—hue))oklch(0.38 0.04 var(—hue))普通按钮悬停色
--btn-regular-bg-activeoklch(0.85 0.08 var(—hue))oklch(0.43 0.045 var(—hue))普通按钮激活色
--btn-plain-bg-hoveroklch(0.95 0.025 var(—hue))oklch(0.30 0.035 var(—hue))文字按钮悬停背景
--btn-plain-bg-activeoklch(0.98 0.01 var(—hue))oklch(0.27 0.025 var(—hue))文字按钮激活背景
--btn-card-bg-hoveroklch(0.98 0.005 var(—hue))oklch(0.3 0.03 var(—hue))卡片按钮悬停背景色
--btn-card-bg-activeoklch(0.9 0.03 var(—hue))oklch(0.35 0.035 var(—hue))卡片按钮激活背景色

文本相关色#

变量名亮色值深色值说明
—deep-textoklch(0.25 0.02 var(—hue))-深色文本（暗色主题用）
—title-activeoklch(0.6 0.1 var(—hue))-活跃标题颜色
—inline-code-color引用 —btn-content引用 —btn-content内联代码文字颜色

链接相关色#

变量名描述用途
--link-underline链接下划线色默认链接样式
--link-hover链接悬停色链接悬停下划线
--link-active链接激活色链接点击色

其他元素色#

变量名描述用途
--line-color线条颜色虚线分割线等
--selection-bg文本选中背景文本被选中时的背景
--codeblock-selection代码块选中背景代码块中选中文本

目录 (TOC) 相关色#

变量名描述用途
--toc-btn-hover目录项悬停色TOC 链接悬停状态
--toc-btn-active目录项激活色当前页面对应 TOC 项
--toc-badge-bg目录徽章背景标记当前深度的徽章
--title-active标题激活色当前目录标题
--enter-btn-bg进入按钮背景TOC 进入按钮
--enter-btn-bg-active进入按钮激活色TOC 进入按钮激活

滚动条相关色#

变量名描述模式
--scrollbar-bg自动滚动条颜色Auto
--scrollbar-bg-hover自动滚动条悬停Auto
--scrollbar-bg-active自动滚动条激活Auto
--scrollbar-bg-dark深色模式滚动条Dark
--scrollbar-bg-hover-dark深色模式悬停Dark
--scrollbar-bg-active-dark深色模式激活Dark
--scrollbar-bg-light浅色模式滚动条Light
--scrollbar-bg-hover-light浅色模式悬停Light
--scrollbar-bg-active-light浅色模式激活Light

布局和间距相关变量#

尺寸变量 (Dimensions)#

变量名值描述文件位置
--page-width75rem页面最大宽度Layout.astro (define)
--radius-large-大圆角尺寸组件中使用
--coverWidth-封面宽度组件中使用

动画和过渡变量#

变量名值描述
--content-delay默认/0ms内容进入延迟
--banner-height35vhBanner 正常高度
--banner-height-home65vh首页 Banner 高度
--banner-height-extend30vhBanner 扩展高度
--collapsedHeight-折叠元素的高度

颜色定义方案#

OKLCH 颜色模型#

该项目广泛使用 OKLCH（Oklch）颜色模型，这是一种基于色相 (Hue) 的现代颜色空间：

/* OKLCH 语法: oklch(lightness saturation hue) */
oklch(0.75 0.14 var(--hue))  /* 明度 75%，饱和度 14%，色相变量 */

常见的 OKLCH 配置#

用途OKLCH 值说明
主要强调色oklch(0.75 0.14 var(--hue))用于成功/确认类按钮
常规按钮背景 (浅)oklch(0.45 0.01 var(--hue))浅色模式按钮
常规按钮背景 (深)oklch(0.30 0.02 var(--hue))深色模式默认
常规按钮悬停 (深)oklch(0.35 0.03 var(--hue))深色模式悬停
常规按钮激活 (深)oklch(0.40 0.03 var(--hue))深色模式激活
代码块语言标签oklch(0.75 0.1 var(--hue))文本颜色
代码块语言标签背景oklch(0.33 0.035 var(--hue))背景颜色

主题系统架构#

1. 文件组织结构#

src/
├── styles/
│   ├── main.css           # 主要 CSS 变量使用和组件定义
│   ├── markdown.css       # Markdown 内容样式
│   ├── scrollbar.css      # 滚动条样式
│   ├── transition.css     # 页面过渡动画
│   ├── expressive-code.css # 代码块样式
│   └── photoswipe.css     # 图片查看器样式
├── components/
│   ├── GlobalStyles.astro  # 全局样式容器
│   ├── ConfigCarrier.astro # 主题配置传递
│   └── widget/DisplaySettings.svelte # 主题色选择器
├── layouts/
│   └── Layout.astro       # 根布局，定义核心 CSS 变量
├── utils/
│   └── setting-utils.ts   # 主题设置工具函数
└── config.ts              # 网站配置（包含默认色相值）

2. CSS 变量定义层级#

第一层：根元素变量定义 (Layout.astro)#

// 内联脚本在页面加载时执行
document.documentElement.style.setProperty('--hue', hueValue);
document.documentElement.style.setProperty('--banner-height-extend', `${offset}px`);

第二层：Astro define 动态生成#

<style define:vars={{
    configHue,
    'page-width': `${PAGE_WIDTH}rem`,
}}>
</style>

第三层：CSS 中的 var() 引用#

.card-base {
    @apply rounded-[var(--radius-large)] overflow-hidden bg-[var(--card-bg)] transition;
}

3. 主题切换流程#

用户交互
    ↓
LightDarkSwitch/DisplaySettings 组件
    ↓
setTheme() / setHue() 函数 (setting-utils.ts)
    ↓
localStorage 存储
    ↓
修改 DOM (添加/移除 .dark 类)
    ↓
修改 CSS 变量 (--hue)
    ↓
Tailwind dark: 修饰符 + CSS 变量响应式更新
    ↓
界面即时更新

Tailwind CSS 集成#

主题配置 (tailwind.config.cjs)#

module.exports = {
    darkMode: "class",  // 使用 class 模式实现 dark 主题
    theme: {
    extend: {
        fontFamily: {
        sans: ["Roboto", "sans-serif", ...defaultTheme.fontFamily.sans],
        },
    },
    },
    plugins: [require("@tailwindcss/typography")],
}

关键特性#

  1. Dark Mode 实现

    • 通过 html.dark class 控制
    • Tailwind dark: 前缀修饰符
    • 自动响应 prefers-color-scheme 系统偏好

  2. 动态颜色生成

    • 使用 CSS 变量 + OKLCH 颜色模型
    • 用户可通过滑块调整 0-360° 的色相值
    • 保持饱和度和明度不变，只改变色相

  3. Typography 插件

    • 增强 Markdown 排版样式
    • 自动适配 dark/light 模式

详细的颜色定义和变量用途#

光明模式 (Light Mode) 默认值#

浅色模式通过移除 html.dark class 实现，使用较浅的背景和较深的文字。

/* 代表性颜色值 (概念性，实际通过变量) */
--page-bg: 白色 (#ffffff)
--card-bg: 浅灰色 (#f5f5f5)
--primary: 基于 hue 的 OKLCH 颜色
--text: 深灰色 (#333333)

深色模式 (Dark Mode) 默认值#

深色模式通过添加 html.dark class 实现，使用较深的背景和较浅的文字。

/* 深色模式特定变量 */
--page-bg: 黑色 (#000000)
--card-bg: 深灰色 (#1a1a1a)
--primary: 基于 hue 的 OKLCH 颜色 (更亮)
--text: 白色/浅灰色

交互状态颜色#

状态按钮类型变量颜色值
NormalRegular--btn-regular-bgoklch(0.45 0.01 var(—hue))
HoverRegular--btn-regular-bg-hoveroklch(0.50 0.01 var(—hue))
ActiveRegular--btn-regular-bg-activeoklch(0.55 0.01 var(—hue))
Normal (Dark)Regular--btn-regular-bgoklch(0.30 0.02 var(—hue))
Hover (Dark)Regular--btn-regular-bg-hoveroklch(0.35 0.03 var(—hue))
Active (Dark)Regular--btn-regular-bg-activeoklch(0.40 0.03 var(—hue))

实际使用示例#

示例 1: 使用 CSS 变量的卡片组件#

src/components/PostCard.astro
<div class="card-base">
    <!-- 使用 --card-bg 变量设置背景色 -->
    <!-- 自动适应 light/dark 模式 -->
</div>

对应的 CSS：

.card-base {
    @apply rounded-[var(--radius-large)] overflow-hidden bg-[var(--card-bg)] transition;
}

示例 2: 链接样式#

a:not(.no-styling) {
    @apply relative bg-none link font-medium text-[var(--primary)]
    underline decoration-[var(--link-underline)] decoration-1 decoration-dashed underline-offset-4;


    &:hover, &:active {
        @apply decoration-transparent;
        background: var(--btn-plain-bg-hover);
        border-bottom: 1px dashed var(--link-hover);
        text-decoration: none;
    }
}

示例 3: 按钮状态#

.btn-plain {
    @apply transition relative flex items-center justify-center bg-none
    text-black/75 hover:text-[var(--primary)] dark:text-white/75 dark:hover:text-[var(--primary)];


    &:not(.scale-animation) {
        @apply hover:bg-[var(--btn-plain-bg-hover)] active:bg-[var(--btn-plain-bg-active)]
    }
}

代码块 (Expressive Code) 样式#

CSS 变量覆盖#

在 astro.config.mjs 中定义：

styleOverrides: {
    codeBackground: "var(--codeblock-bg)",
    borderRadius: "0.75rem",
    codeFontSize: "0.875rem",
    frames: {
        editorBackground: "var(--codeblock-bg)",
        terminalBackground: "var(--codeblock-bg)",
        terminalTitlebarBackground: "var(--codeblock-topbar-bg)",
        editorTabBarBackground: "var(--codeblock-topbar-bg)",
        editorActiveTabIndicatorBottomColor: "var(--primary)",
    },
    textMarkers: {
        delHue: 0,      // 删除标记色相 (红色)
        insHue: 180,    // 插入标记色相 (青色)
        markHue: 250    // 高亮标记色相 (紫色)
    }
}

代码块语言标签#

使用 OKLCH 颜色和 --hue 变量动态着色：

[data-language]::before {
    color: oklch(0.75 0.1 var(--hue));
    background: oklch(0.33 0.035 var(--hue));
}

数据持久化#

localStorage 键值对#

键名类型范围示例
themeString”light” | “dark” | “auto""dark”
hueString”0” - “360""250”

初始化流程#

  1. 页面加载时的内联脚本读取 localStorage
  2. 如果无记录，使用默认值 (auto + config.hue)
  3. 立即应用到 DOM，防止页面闪烁
const theme = localStorage.getItem('theme') || DEFAULT_THEME;
const hue = localStorage.getItem('hue') || configHue;
document.documentElement.style.setProperty('--hue', hue);

响应式设计#

Breakpoints (Tailwind 默认)#

  • sm: 640px
  • md: 768px
  • lg: 1024px
  • xl: 1280px

布局相关变量#

变量名值用途
--page-width75rem (1200px)内容最大宽度
--banner-height35vh非首页 Banner 高度
--banner-height-home65vh首页 Banner 高度
--banner-height-extend30vhBanner 扩展空间

字体和排版#

字体定义#

用途字体来源
正文Roboto 400/500/700@fontsource/roboto
代码块JetBrains Mono VariableTailwind 配置
数学公式KaTeX FontsKaTeX CSS

字号设置#

<html class="text-[14px] md:text-[16px]">
  • 移动端: 14px
  • 桌面端: 16px

动画和过渡#

CSS 变量控制#

变量名值用途
--content-delay150ms内容加载延迟

关键动画#

Fade-in-up 动画#

@keyframes fade-in-up {
    0% {
        transform: translateY(2rem);
        opacity: 0;
    }
    100% {
        transform: translateY(0);
        opacity: 1;
    }
}

Swup 页面过渡#

html.is-changing .transition-swup-fade {
    @apply transition-all duration-200
}
html.is-animating .transition-swup-fade {
    @apply opacity-0 translate-y-4
}

最佳实践#

1. 变量命名规范#

--[category]-[element]-[state]
--btn-regular-bg-hover
--card-bg
--primary

2. 颜色系统架构#

  • 基础色: --primary (通过 hue 变量动态)
  • 背景色: --*-bg 系列
  • 文字色: 通过 dark: 修饰符
  • 交互态: -hover, -active 后缀

3. 响应式应用#

<!-- Tailwind 提供响应式前缀 -->
<div class="text-sm md:text-base lg:text-lg">
    Dynamic sizing
</div>

4. 动态颜色计算#

// 在 JavaScript 中设置 hue
const hue = 250; // 用户选择的值
document.documentElement.style.setProperty('--hue', hue);


// 在 CSS 中引用生成颜色
background: oklch(0.45 0.01 var(--hue));

总结#

Fuwari 博客模板的 Design Tokens 系统是一个完整的、现代化的设计系统，具有以下特点：

  1. 灵活性: CSS 变量 + JavaScript 动态设置，支持实时主题切换
  2. 一致性: 统一的变量命名规范和颜色系统
  3. 可访问性: 支持系统偏好检测和用户自定义
  4. 性能: 高效的 CSS 变量和 Tailwind CSS 编译
  5. 可维护性: 清晰的文件组织和模块化设计

所有 CSS 变量都遵循同一套规范，确保整个项目的视觉一致性和易维护性。

Fuwari 博客模板 Design Tokens 完整指南
https://martinlevine.vercel.app/posts/daisy/
作者
404 Not Found.
发布于
2025-11-07
许可协议
CC BY-NC-SA 4.0
ClaudeCode项目规范
© 2025 404 Not Found. All Rights Reserved. /
Powered by Astro & Fuwari