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

把 AstroWind 模板改成你的品牌，只涉及少数几个文件，而且都不在你本来不想碰的组件里面。演示站是蓝色的，用 Inter，到处都写着 “AstroWind”；这篇指南按大多数项目需要的顺序，说明要改什么。如果项目还没建好，先看入门指南。

你会改这些

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

改主题色（浅色和深色）

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 用于偶尔的高亮。深色模式的主色要在深色背景上仍然看得清：演示站沿用同一个蓝色，只在小字需要更高对比度的少数地方，退回到更浅的 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 切换。

生成网站图标和社交分享图

网站图标在 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 技能里。

页眉和页脚

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 插槽。

给你自己的组件用的令牌

任何组件或页面都可以用两套令牌：

• AstroWind 工具类，例如 text-primary、text-heading、text-muted、bg-page、btn-* 按钮类和 font-heading，在 tailwind.css 里声明。
• 兼容 shadcn/ui 的令牌，例如 bg-background、text-foreground、bg-card 和 border-border，在 src/assets/styles/shadcn.css 里由同一组变量派生。从 shadcn/ui 或基于它的社区区块复制来的组件，不用改 class 就会用上你的颜色。注意 primary、secondary、accent 和 muted 仍保持 AstroWind 的含义；use-shadcn-tokens 技能说明了这层对应关系。

你自己的工具类写成 @utility 块，放在 tailwind.css 里现有工具类旁边；这个文件用的 @theme 语法见 Tailwind CSS 主题文档。

深色模式的行为

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

上线之前

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