Everything Komono ships with.

A tour of the theme — and, behind each feature, exactly how to configure it. This page lives in your copy of the theme too, so the docs are always where your code is.

Every setting in one file

Colors, fonts, logo, meta tags, social links and navigation all live in theme.config.ts — typed, validated, and impossible to typo silently. Change a value, save, and the whole site follows.

Setup & config

Open theme.config.ts in the project root. The grey ramp drives text, backgrounds and borders; the three accents are yours to brand. Utilities like bg-accent-1 andtext-grey-700 update automatically.

theme.config.ts

colors: { grey: { '50': '#fafaf9', /* … */ '950': '#0d0c0a' }, accent1: '#ff5c1f', accent2: '#2424d6', accent3: '#ffd23f', }

Invalid values fail the build with a readable error pointing at the exact field.

Light, dark and system color schemes are built in: the grey ramp inverts automatically in dark mode, colors.dark overrides any accent, and the toggle in the nav cycles auto → light → dark (persisted, no flash on load). Set dark: false to ship light-only.

Fast — measured, not promised

Every Komono release is audited with Lighthouse before it ships, on a throttled mobile connection and on desktop. These are the real numbers from v1.0.0, and they ship with the theme so you can re-run them yourself.

Mobile

Performance

Accessibility

100

Best practices

100

SEO

Desktop

100

Performance

Accessibility

100

Best practices

100

SEO

mobile: FCP 1.5 s · LCP 2.3 s · TBT 0 ms · CLS 0 — Lighthouse 13.4.0, median of 3 runs, 2026-06-10

Setup & config

Why it's fast: static HTML (no client framework), build-time image optimization to responsive WebP, self-hosted fonts with preloading and generated fallbacks (zero layout shift), and one small JS bundle for the animations. Verify it on your own machine:

terminal

npm run build && npm run preview npx lighthouse http://localhost:4321 --view

The scores above are stored insrc/data/lighthouse.json and refreshed with every theme release.

Google Fonts, Adobe Fonts, local files, or system stacks

Fonts are declared in the same config file and self-hosted at build time by Astro's Fonts API — no third-party requests in production, no layout shift thanks to auto-generated fallbacks.

Setup & config

theme.config.ts — Google

fonts: { heading: { provider: 'google', family: 'Bricolage Grotesque', weights: [400, 600, 800] }, body: { provider: 'google', family: 'Inter', weights: [400, 500] }, }

Adobe Fonts

heading: { provider: 'adobe', family: 'Futura PT' }

For Adobe, copy .env.example to.env and setADOBE_FONTS_KIT_ID (from fonts.adobe.com → Web Projects). Add the same variable in your deploy platform's settings. Local files useprovider: 'local' withvariants; system stacks need no files at all.

Typography that scales itself

A fluid type and spacing scale, tuned for two sizes per device class. Text grows smoothly between 360px and 1440px viewports — no breakpoint jumps, and user font-size zoom keeps working.

step −1 · The quick brown fox

step 0 · The quick brown fox

step 1 · The quick brown fox

step 2 · The quick brown fox

step 3 · Quick brown

step 4 · Quick

Setup & config

Use text-step--1 throughtext-step-5 for font sizes andp-space-xs …m-space-3xl for fluid spacing — they're regular Tailwind utilities. The scale lives insrc/_core/styles/tokens.css; override any step insrc/styles/custom.css by redefining its variable.

The image-trail hero

Komono's signature moment: on the home page, images from your featured projects trail the visitor's pointer. Touch devices and reduced-motion users get a clean typographic hero instead — automatically.

Try it on the home page — move your cursor across the hero.

Setup & config

The hero pulls images from projects markedfeatured: true that definetrailImages:

src/content/work/your-project.md

featured: true trailImages: - ../../assets/your-project/trail-1.jpg - ../../assets/your-project/trail-2.jpg

Two to four images per featured project works best. The headline and subline are props on the <ImageTrailHero> component insrc/pages/index.astro.

Scroll reveals — you're watching them now

Headings and cards ease in as they enter the viewport, powered by GSAP. Honors prefers-reduced-motion, cleans up after itself on every page transition.

Setup & config

Add the attribute to any element:

any component

<h2 data-reveal>Eases up</h2> <div data-reveal="left" data-reveal-delay="0.15">From the left, delayed</div>

Directions: up (default),down, left,right, fade.

One rule keeps the Lighthouse scores intact: for above-the-fold content (hero headlines, page titles) use the CSS-onlyclass="ko-rise" (stagger withstyle="--ko-rise-delay: 0.1s") — it animates without waiting for JavaScript, so it never delays LCP.data-reveal is for everything below the fold.

Projects as plain markdown

Each project is one markdown file with typed frontmatter — title, year, category, images, credits. Astro validates every field and optimizes every image at build time.

Setup & config

src/content/work/example.md

--- title: Aurora tagline: Identity for a Nordic lighting house description: Used for meta tags and social cards. client: Aurora Lys AS        # optional year: 2024 category: branding           # branding | web | motion | print | photography tags: [Identity, Packaging] cover: ../../assets/aurora/cover.jpg hero: ../../assets/aurora/hero.jpg   # optional, falls back to cover order: 1                     # sort position on /work featured: true               # show on home + feed the hero draft: false                 # true = hidden everywhere --- Your case study text, with ## headings.

Drop images next to your content in src/assets/; they're converted to responsive WebP automatically.

SEO without a plugin

Canonical URLs, Open Graph and Twitter cards, per-page titles and descriptions, sitemap and robots.txt — wired in, fed by your config and your content.

Setup & config

Site-wide defaults come from meta in theme.config.ts. Any page can override them:

any page

<PageLayout title="Page title" description="Page description" ogImage="/og-custom.png" >

The sitemap is generated at /sitemap-index.xml; update the domain in public/robots.txt when you deploy.

Demo content — keep it or strip it

The theme arrives with twelve example projects so every page has something to show. One command removes all of it, cleanly, the moment you're ready for your own work.

Setup & config

terminal

npm run fresh

Removes the demo projects, demo images, and placeholder copy on the about/contact pages. Keeps all structure, your config, and your styles — the site builds immediately after.

Updates that respect your changes

Theme updates arrive as git pulls. Your config, content, styles and overrides live in designated safe zones the updates never touch — customize freely and stay current.

Setup & config

Safe zones — yours forever:

update-safe

theme.config.ts                 # settings src/styles/custom.css           # your CSS, loads last src/content/                    # your projects & pages src/components/overrides/       # your component versions public/                         # favicons, OG images, files

Don't edit src/_core/ — to change a core component, copy it intosrc/components/overrides/ and update its import where it's used. npm run build warns if _core has local edits. Updating:

terminal

git remote add upstream <theme-repo-url>   # once git fetch upstream git merge upstream/main npm install