Customizing Your Astro Theme — Colors, Fonts, and Layout

A good theme gives you a solid foundation. Customization makes it yours. Here’s how to tweak Hermes Prime—or any Astro theme—without fighting the framework.

Where Styles Live

Hermes Prime uses Tailwind v4 with a single global stylesheet: src/styles/global.css. Theme variables live in @theme:

Copy@theme {
  --font-sans: 'Geist', ui-sans-serif, system-ui, sans-serif;
  --font-serif: 'Source Serif 4', ui-serif, Georgia, serif;
  --color-neutral-50: oklch(0.985 0.002 264);
  --color-neutral-900: oklch(0.2 0.004 264);
  /* ... */
}

Change these and the whole site updates. No hunting through components.

Changing Colors

Light Mode

Edit the --color-* variables. For a warmer palette, shift the hue (the last number in oklch):

Copy--color-neutral-900: oklch(0.2 0.004 30);  /* Warmer (30 vs 264) */

Dark Mode

Dark mode uses [data-theme=dark]. Override prose and component colors there:

Copy[data-theme=dark] .prose {
  --tw-prose-body: oklch(0.88 0.01 264);
  --tw-prose-headings: #fff;
}

Accent Color

Add or override an accent for links and buttons:

Copy--color-accent-500: oklch(0.55 0.15 250);  /* Blue accent */

Then use text-accent-500 or bg-accent-500 in your components.

Changing Fonts

1. Add the font (Google Fonts, local, or self-hosted)
2. Update the variables:

Copy@theme {
  --font-sans: 'Your Sans', ui-sans-serif, system-ui, sans-serif;
  --font-serif: 'Your Serif', ui-serif, Georgia, serif;
}

3. Ensure the font is loaded in your layout. Hermes Prime uses a <link> in BaseLayout.astro for Google Fonts.

Content Width

The theme defines content widths:

Copy--content-narrow: 42rem;   /* ~672px, optimal for reading */
--content-wide: 48rem;
--content-max: 64rem;

Articles use max-w-[680px] or var(--content-narrow). Adjust these for wider or narrower reading columns.

Prose Overrides

Blog content uses Tailwind Typography. Override in global.css:

Copy.prose {
  --tw-prose-headings: #000;
  --tw-prose-links: var(--color-accent-600);
}
.prose h1 { font-size: 2.5rem; }

Be specific enough to override the plugin’s defaults. Use !important sparingly—only when the cascade fights you.

Component-Level Changes

For one-off tweaks, edit the component. Header, footer, and card styles are in src/components/. Use Tailwind classes or add scoped CSS.

Keeping Upgrades Easy

• Prefer CSS variables over hardcoded values
• Put overrides in global.css rather than scattering them
• Document your changes in a CUSTOMIZATION.md file
• Avoid modifying node_modules or plugin configs when possible

Quick Wins

1. Logo — Swap the text in Header.astro for an <img> or SVG
2. Favicon — Replace public/favicon.svg and favicon.ico
3. Meta — Update src/lib/site.ts for title, description, social URLs
4. Footer — Edit Footer.astro for links and copyright

---

A theme should adapt to you, not the other way around. Start with small tweaks, then go deeper as you learn the structure.