定制 Astro 模板：颜色、字体和 Logo

把 AstroWind 改成你的品牌，只涉及少数几个文件，没有一个藏在你不想碰的组件里面。演示站是蓝色的，用 Inter，到处写着 AstroWind。这篇按大多数项目需要的顺序，讲该改什么。如果项目还没创建，先看入门指南。

你会改什么

• 色板，浅色和深色都在同一个文件里。
• 字体，通过 Astro 的 Fonts API 自行托管。
• logo、favicon，以及默认的社交分享图。
• 页眉菜单、页眉按钮和页脚。
• 你自己的组件，以及任何 shadcn/ui 区块会用到的 token。

改主题色（浅色和深色）

src/components/CustomStyles.astro 用 CSS 变量声明色板。浅色写在 :root 下面，深色写在 .dark 下面：

:root {
  --aw-color-primary: rgb(1 97 239);
  --aw-color-secondary: rgb(1 84 207);
  --aw-color-accent: rgb(109 40 217);

  --aw-color-text-heading: rgb(0 0 0);
  --aw-color-text-default: rgb(16 16 16);
  --aw-color-text-muted: rgb(16 16 16 / 66%);
  --aw-color-bg-page: rgb(255 255 255);
}

.dark {
  --aw-color-primary: rgb(1 97 239);
  /* … */
  --aw-color-bg-page: rgb(8 9 10);
}

品牌色

primary 是品牌色：按钮、链接、图标、当前菜单项。secondary 用于短标语和次一级的强调；accent 用于偶尔的高亮。深色模式下的 primary 要在深色背景上仍然看得清。演示站保持同一支蓝，只在少数小字需要更高对比度的地方，退回到更浅的 Tailwind 蓝。

文字和表面

三种文字色和页面背景，是每个小组件用来画标题、正文、弱化说明和表面的。两种模式下，text-default 和 bg-page 的对比度都要高于 4.5:1。弱化色是从默认文字色加上透明度来的，所以会自动跟着走。

哪些东西会跟着色板走

改这些值，整个站点会跟着变，因为组件用的是 text-primary、text-heading、text-muted、bg-page 这类 Tailwind 工具类，它们在 src/assets/styles/tailwind.css 里映射到这些变量。有一个例外：少数组件在深色模式的小字上用了写死的 dark:text-blue-*。色板改动比较大之后，在 src/components 里 grep blue-，把那几处对一下。

页眉如果想用自己的链接色，可以设置 --aw-color-link，当前菜单项就会用它，而不用 primary。

改字体

字体用 Astro 的 Fonts API 加载，在 astro.config.ts 里声明：

fonts: [
  {
    provider: fontProviders.fontsource(),
    name: 'Inter',
    cssVariable: '--font-inter',
    weights: ['100 900'],
    styles: ['normal'],
    subsets: ['latin'],
    fallbacks: ['sans-serif'],
  },
],

第二种字（比如标题用的衬线体）就再加一条，然后把 CustomStyles.astro 里的 --aw-font-sans、--aw-font-serif 和 --aw-font-heading 指到新的 cssVariable。Astro 在构建时下载这些文件，自行托管，并生成带度量调整的回退 @font-face，所以运行时不会向第三方发请求，字体到达时也不会把版面挤一下。src/layouts/Layout.astro 里的 Font 组件负责把它们放进去。有哪些提供方，见 Astro 的字体文档。

换掉 logo 和站点名称

名称来自 src/config.yaml 里的 site.name。src/components/Logo.astro 用一个火箭表情把它画出来。把组件的内容换成你的标志：

---
import { Image } from 'astro:assets';
import logo from '~/assets/images/logo.svg';
---

<Image src={logo} alt="Acme" width={120} height={32} class="self-center ml-2 rtl:ml-0 rtl:mr-2" />

对齐用的 class 留着，logo 才会在页眉里坐正。如果浅色和深色各需要一版 logo，两版都渲染，用 dark:hidden 和 hidden dark:block 切换。

生成 favicon 和社交分享图

favicon 放在 src/assets/favicons/：favicon.ico、favicon.svg 和 apple-touch-icon.png。换文件时保持这些名字。页面自己没有指定分享图时，默认的 Open Graph 图是 src/assets/images/default.png（1200 × 628），也换掉，或者把 config.yaml 里的 metadata.openGraph.images 指到别的文件。细节在 .agents/skills/ 的 set-open-graph-image skill 里。

页眉和页脚

src/navigation.ts 导出 headerData（菜单项，可以带下拉的 links，以及 actions 按钮）和 footerData（分栏链接、次级链接、社交链接和页脚那句说明）。站内链接走 getPermalink()，这样部署到子路径时会尊重 base。

页眉本身是 src/components/widgets/Header.astro。常见需求用 props 就够，不用改组件：isSticky、isDark、isFullWidth、showToggleTheme、showRssFeed、position（left、center、right）。页面也可以自带页眉，好几张演示页就是这样做的，通过 PageLayout 的 header 插槽传进去。

给你自己的组件用的 token

任何组件或页面里都可以用两套 token：

• AstroWind 的工具类，例如 text-primary、text-heading、text-muted、bg-page、btn-* 按钮类和 font-heading，声明在 tailwind.css 里。
• 兼容 shadcn/ui 的 token，例如 bg-background、text-foreground、bg-card 和 border-border，在 src/assets/styles/shadcn.css 里从同一组变量推导出来。从 shadcn/ui 或基于它的社区区块拷来的组件，不用改 class 就会用上你的颜色。注意 primary、secondary、accent 和 muted 仍然是 AstroWind 的含义；use-shadcn-tokens 这份 skill 解释了两边怎么对应。

你自己的工具类写在 tailwind.css 里，用 @utility 块，挨着现有的那些。Tailwind CSS 的主题文档讲了这个文件用的 @theme 写法。

深色模式怎么表现

config.yaml 里的 ui.theme 决定默认值。system 跟随操作系统，并显示切换按钮。light 或 dark 设定默认，但保留切换。light:only 和 dark:only 拿掉切换。选择存在 localStorage 里，并在首次绘制之前生效，所以不会闪一下。

上线之前

跑一遍 npm run check，然后把每一页在浅色和深色、手机和桌面上看一遍。首页上没问题的颜色，可能在带色带的落地页上，或在深色代码块里失败。上面大多数任务的逐步版本在 .agents/skills/ 里，写得既让 AI 编程助手能照着做，也短到你可以自己跟着走。如果想知道这些文件为什么这样接在一起，读模板内部是怎么工作的。