Colours, fonts and photos

How the colours work

Polaris’s colours come in layers, all in src/styles/tokens/:

File	What’s in it
colors.css	The colour scales, each from 50 (lightest) to 950 (darkest): pine, glacier, apricot, snow, night and red. Generated by npm run palette.
theme.css	What each colour is for: --brand, --accent, --info, surfaces, text, lines, trail grades and the season strip, each with a light-mode and a dark-mode value. Blocks only use these names. It also defines the section tones.
scale.css	Type sizes, spacing, corners, shadows and page width.

The scales are used like this:

Scale	Used for
pine	The brand colour: a deep, slightly blue forest green.
apricot	The accent: the one main action on each view.
glacier	Information, maps and the “moderate” trail grade.
snow	Light neutrals and text.
night	Dark mode and the night tone.
red	Errors and the “expert” trail grade.

Every text and background pair is chosen to meet the WCAG AA contrast standard.

Changing your brand colour

The quickest way is to change a scale’s hue and chroma, then regenerate the colours:

1. Open scripts/palette.mjs. Each family at the top has a hue (0 to 360, the colour’s position on the colour wheel) and a chroma (how vivid it is).
2. Change the hue of pine to your brand’s, and the hue of apricot if you want a different accent. Any online “hex to OKLCH” converter tells you your colour’s hue.
3. Run:

npm run palette

It writes src/styles/tokens/colors.css with the new scales.

To check the contrast of a pair, pass it after --, for example:

npm run palette -- pine-700/snow-50

It prints the ratio. 4.5 or more is right for body text.

You can also point --brand or --accent at a different scale in theme.css, for example --brand: light-dark(var(--glacier-800), var(--glacier-300));. Change the -hover, -ink and -soft lines under it the same way.

Section tones

The six tones you can give a block are default, mist, sand, dawn, pine and night. They are at the bottom of theme.css. pine and night are dark: everything inside them, including buttons and cards, switches to its dark-mode colours.

Light and dark mode

The site follows each visitor’s system setting, and the switch in the header lets them choose. Their choice is saved in their browser.

The style guide

Open /style-guide/ while npm run dev is running to see the colours, type and components on one page.

Heading font

Headings use Newsreader, an editorial serif, through Astro’s built-in Fonts API. The font files are in src/assets/fonts/, served from your own site with no requests to Google. Body text uses each device’s system font, which costs nothing to load.

To use a different heading font, put its .woff2 files in src/assets/fonts/ and change the fonts entry in astro.config.mjs: set name and point each src at your files. Keep cssVariable: '--font-display', because the theme uses that name. The font’s licence is in src/assets/fonts/OFL-Newsreader.txt: replace it with your font’s licence.

Logo

The logo is the Polaris star in the accent colour followed by your name in the heading font. It is one small component, src/components/ui/Logo.astro. Replace its contents with your own mark, for example an <img> of a file in public/.

Replace public/favicon.svg and public/apple-touch-icon.png with your own icons too. The touch icon is also used as the logo in structured data.

Photos

Photos live in src/assets/images/, and pages and content files refer to them by file name:

image: trip-foothills-teahouse-circuit.jpg
imageAlt: "Old stone steps climbing through green forest"

Polaris resizes every photo when you build, converts it to WebP, and gives each visitor only the size their screen needs, so you can add large, good-quality JPGs straight from your camera or phone. Always write an imageAlt describing the photo.

The placeholder images

The demo uses free-licence photos from Unsplash, which are not included in the download. Placeholders with the same file names are drawn by scripts/placeholders.mjs before every npm run dev and npm run build, but only for file names that are missing. Your own photos are never touched.

To replace a placeholder, put your photo in src/assets/images/ with the same file name. Or give it a new name and change the name in the page or content file.

The script draws a placeholder for every image file name it finds in your content. If you misspell a file name, you get a placeholder with that name instead of your photo, so check the name if you still see a placeholder.

Photo credits

The demo’s photo credits are in CREDITS.md. They apply to the demo photos only.