DESIGN.md

The starter's design system, theme colors, and implementation rules.

Theme system

Choose a color direction without changing the whole system

The starter ships with color theme packs. They switch semantic color tokens while preserving the template's typography, spacing, layout, radius, and component behavior.

View Elements

Open raw file

Source files

src/config/themes.js

src/styles/global.css

src/styles/themes.css

src/layouts/Layout.astro

src/components/sections/Header.astro

docs/DESIGN.md

docs/DESIGN/{theme-id}.md

Details

Theme details

Each theme keeps the starter structure intact. Expand a theme to see the source mood, color roles, and implementation guidance.

Retro BlueDefault paletteDetails

Warm editorial canvas with confident blue headings, gold highlights, and calm slate neutrals.

Best for

Starter sitesEditorial product pagesDocumentation

Color roles

Editorial Blue

#2d6dc3

Headings, links, and primary actions

Gold Highlight

#fad13b

Badges and secondary emphasis

Warm Canvas

#fdfaf5

Light page background

Guidance

docs/DESIGN/retro-blue.md

Keep blue as the main signal for navigation, headings, and calls to action.
Use gold as a small highlight rather than a large surface color.
Preserve the warm canvas so the theme feels editorial instead of corporate.

Minimal MonoMonochrome paletteDetails

Restrained monochrome with warm grays, crisp type contrast, and almost no saturated color.

Best for

Editorial sitesPortfoliosDocumentation

Color roles

Ink

#1a1a1a

Text, headings, and primary controls

Warm Gray

#f5f3f1

Soft surfaces and quiet accents

Paper

#fdfcfc

Light page canvas

Guidance

docs/DESIGN/minimal-mono.md

Do not introduce new saturated accents; the restraint is the feature.
Use gray hierarchy for emphasis instead of colored labels.
Keep the theme quiet enough for long-form reading.

Forest GreenBotanical paletteDetails

Grounded botanical palette with paper surfaces, natural greens, and low-glare reading contrast.

Best for

Knowledge basesWellness productsCalm product sites

Color roles

Forest Green

#4a7c59

Brand color, links, and filled actions

Leaf Tint

#dce9d8

Badges and soft highlights

Paper

#f7f5f0

Light page canvas

Guidance

docs/DESIGN/forest-green.md

Keep green as the only meaningful chromatic direction.
Use the lighter green tint for supporting surfaces, not primary text.
Make both light and dark variants feel natural and low glare.

Vellum InkWarm vellum paletteDetails

Academic journal on vellum: warm off-white surfaces, precise dark text, and a quiet terra cotta accent.

Best for

AI productsResearch toolsWriting appsKnowledge products

Color roles

Ink Black

#141413

Primary text, headings, and dark filled actions

Vellum White

#faf9f5

Page canvas and card surfaces

Terra Cotta

#d97757

Small accent moments and icon details

Guidance

docs/DESIGN/vellum-ink.md

Use warm neutral surfaces generously; avoid harsh pure-white layouts.
Keep terra cotta small and intentional so the theme stays understated.
Use dark filled buttons for the clearest primary action.

Creator YellowCreator economy paletteDetails

Buoyant community canvas with tactile white cards, soft shadows, bright yellow action, and approachable dark text.

Best for

Creator toolsCommunity sitesSupport pagesCommerce landing pages

Color roles

Goldenrod

#ffdd00

Primary action and brand highlight

Deep Graphite

#222222

Headings and strong body text

Canvas Gray

#e5e7eb

Soft page background

Guidance

docs/DESIGN/creator-yellow.md

Let yellow own the main action; avoid adding competing saturated accents.
Use white cards over the gray canvas to preserve the creator-card feeling.
Pair yellow with black text for crisp, friendly contrast.

Precision OrangeTechnical neutral paletteDetails

Technical brutalism with monochrome structure, compressed engineering clarity, and a single orange indicator.

Best for

Developer toolsCLI productsAI engineering platformsTechnical docs

Color roles

Factory Black

#020202

Primary text and stark interactive contrast

Factory Light Gray

#eeeeee

Page canvas and quiet surfaces

Code Orange

#ef6f2e

Status labels and small high-attention signals

Guidance

docs/DESIGN/precision-orange.md

Use orange sparingly for new, active, or technical signal states.
Lean on black, gray, and spacing for hierarchy rather than decoration.
Keep the palette crisp and utilitarian.

Comic PulpSoft comic paletteDetails

Soft pulp comic energy: pale paper canvas first, grape-lavender structure second, lemon-yellow action, and graphic ink contrast.

Best for

Playful brandsCampaign pagesGamesCreative launches

Color roles

Grape Ink

#6b5fb5

Headings, links, and brand structure

Lemon Drop

#f2dc4d

Primary action and cheerful emphasis

Pulp Paper

#fbf7ea

Soft page background

Guidance

docs/DESIGN/comic-pulp.md

Keep the page background pale so the comic accents have room to breathe.
Use yellow for action and emphasis, balanced by grape text instead of pure black everywhere.
Let the theme feel graphic through color contrast without turning the whole page saturated.

Midnight PastelDark pastel paletteDetails

Matte pastel blocks on midnight: a dark workspace softened by violet, ochre, rose, and clay accents.

Best for

Creative workspacesCollaboration toolsProject dashboardsStudios

Color roles

Midnight Canvas

#000000

Dark page foundation

Warm Violet

#bbb2ce

Prominent accent and project-card energy

Earth Clay

#65451d

Grounded primary action color

Guidance

docs/DESIGN/midnight-pastel.md

Let the dark base carry the interface, then use pastels as controlled highlights.
Use clay and ochre for warm actions rather than generic bright colors.
Avoid sharp neon colors; keep the palette muted and tactile.

Sky BluePale product paletteDetails

Blueprint on frosted linen with a near-white base, soft sky-blue wash, and vivid blue used like a highlighter.

Best for

CRM productsSaaS dashboardsPipeline toolsProductivity apps

Color roles

Signal Blue

#145aff

Links, focus rings, and high-emphasis action

Linen Canvas

#fcfcfc

Primary page surface

Midnight Ink

#020520

Dense display text and strong controls

Guidance

docs/DESIGN/sky-blue.md

Use blue as a precise signal, not as an all-over paint color.
Let near-white and pale sky surfaces provide most of the depth.
Keep secondary text in blue-gray neutrals for a calm product feel.

Signal RedRed action paletteDetails

Cloud control panel on pristine paper: enterprise clarity, warm grays, strong typography, and one confident red action color.

Best for

B2B SaaSInfrastructure toolsSecurity productsEnterprise docs

Color roles

Action Red

#d04841

Primary calls to action and active states

Graphite Black

#181717

Headings and strong text

Canvas Pale

#eeebea

Warm page background

Guidance

docs/DESIGN/signal-red.md

Reserve red for primary action or unambiguous active state.
Use warm gray surfaces to soften the enterprise palette.
Prefer strong text contrast and simple card surfaces over decoration.

Brand color, links, CTAs, headings

#2d6dc3

#1a1a1a

#4a7c59

#141413

#222222

#020202

#6b5fb5

#453b60

#145aff

#d04841

--color-primary-strong

Hover and emphasis

#0066ff

#333333

#356644

#1f1e1d

#000000

#3d3a39

#3f357d

#65451d

#0f1f3d

#a83b35

--color-primary-light

Soft accents and focus surfaces

#8fb9ff

#b1b0b0

#8fba98

#9c9a92

#717171

#b8b3b0

#c8c1f0

#bbb2ce

#b6cbfd

#f2aaa5

--color-accent

Badges and secondary highlights

#fad13b

#f5f3f1

#dce9d8

#d97757

#ffdd00

#ef6f2e

#f2dc4d

#e4b976

#f0f4fe

#eeebea

--color-bg-primary

Light page canvas

#fdfaf5

#fdfcfc

#f7f5f0

#faf9f5

#e5e7eb

#eeeeee

#fbf7ea

#f3f1ec

#fcfcfc

#eeebea

--color-bg-secondary

Cards and panels

#ffffff

#fafafa

#fffdf5

#ffffff

--color-text-primary

Headings and emphasized text

#2d6dc3

#1a1a1a

#2f6840

#141413

#222222

#020202

#241c3d

#453b60

#020520

#181717

--color-text-secondary

Body text

#3f4a5a

#57534f

#33443a

#3d3d3a

#414141

#3d3a39

#473f67

#333333

#374151

#2e2d2d

--color-text-tertiary

Muted metadata

#7a6550

#777169

#66736a

#73726c

#717171

#756f6b

#806f4b

#65451d

#696a72

#706e6d

--color-btn-primary

Filled button background

#2d6dc3

#1a1a1a

#4a7c59

#141413

#ffdd00

#020202

#f2dc4d

#65451d

#145aff

#d04841

--color-btn-primary-hover

Filled button hover background

#0066ff

#333333

#356644

#1f1e1d

#f7d046

#3d3a39

#f6cc5f

#453b60

#0f1f3d

#a83b35

--color-btn-primary-text

Filled button foreground

#ffffff

#000000

#ffffff

#241c3d

#ffffff

Typography

Type stays consistent

The theme switcher is intentionally color-only. Fonts and spacing remain stable so developers can compare palettes without rebuilding the interface.

--font-brand

Instrument Serif

Display headings and large section titles

--font-sans

Inter

Body text, navigation, buttons, UI labels

--font-body

Inter

Long-form content

Theme rules

Theme switching changes semantic color tokens only.

Typography, spacing, radii, layout, and component structure stay stable.

Use src/config/themes.js as the source of truth for theme options.

Use localStorage.theme_id, a theme_id cookie fallback, and html[data-theme] for runtime selection.

Keep light and dark mode styles paired for every theme.

Keep one DESIGN.md file per theme, with separate Light and Dark token sections inside that file.

Treat each theme as a color system, not a full component replacement.

Page patterns

Marketing sections

Use .site-container, SectionHeader, responsive grids, and dashed separators.

Article pages

Use the PostLayout, article styles, TOC, reading progress, and MDX content entries.

Theme reference

Use /elements to inspect how the active theme affects real components.

A generic Astro 7 starter with Blog, DESIGN.md, Elements, Tailwind CSS v4, MDX, and a reusable theme system.

Starter

Resources

v1.0.0Astro 7 starterView source