Customisation Guide

Theme structure — the one-file promise

99% of visual customisation happens in one file: src/app/globals.css. The three-tier OKLCH token system below is the single source of truth for every colour, spacing, motion, and font binding in the kit.

Tier 1 — Primitives        Tier 2 — Semantic aliases    Tier 3 — Component tokens
( --p-*, raw OKLCH )   →   ( --brand-accent, --brand-  →   ( --bg-surface, --text-
                             glow, --chart-series-*,       primary, --border-*,
                             --severity-*, --model-* )     --glass-*, --radius-* )

Most brand-critical OKLCH values live in primitives. Semantic aliases derive from primitives where they need to rebrand together; intentionally independent semantic/component tokens (severity, chart series, glass alpha, overlays, shadows, and model comparison colours) keep their own OKLCH values so they remain meaningful across rebrands. Tailwind consumes the final layer through the @theme inline { ... } block.

Tailwind v4 note — this kit uses Tailwind v4's CSS-first configuration. All theme tokens live in src/app/globals.css inside @theme inline { … }. There is no tailwind.config.js / tailwind.config.ts to edit. If you're coming from v3, stop looking for the JS config — it's gone by design.

Where to edit

Documented exceptions (raw hex allowed)

A handful of files intentionally hold literal hex values because CSS custom properties are unavailable at that execution point. Each carries a top-of-file comment explaining why. If you retheme the accent or model colours, update these too:

Toggle-knob colour comes from the --toggle-knob CSS variable (defined in globals.css) — it's near-white in dark mode and near-black in light mode so both satisfy WCAG AA contrast against the alpha-on-ink track. Don't replace with a literal bg-white — that fails light-mode contrast and has been deliberately retired from this kit.

Colours

The brand colour system is defined as OKLCH tokens in src/app/globals.css. Editing the four --p-amber-* primitive lines alone cascades through every brand-semantic surface in the kit — buttons, links, badges, section labels, borders, pricing card auras, shadow glows, orb backgrounds, surface tints. 3 additional files require manual edits for the hex/RGBA fallback (used by WebGL), the app icon SVG, and the error fallback page. See Documented exceptions above and Rebrand workflow below.

Important: If you are shipping under a different brand, complete the full manual checklist before considering the rebrand finished.

Change the brand colour

Edit the Tier 1 primitives in :root {}:

:root {
  /* Tier 1 — Primitive palette */
  --p-amber-400: oklch(0.85 0.16 75);        /* light amber */
  --p-amber-500: oklch(0.76 0.175 75);       /* mid amber */
  --p-amber-600: oklch(0.740 0.111 74.6);    /* ← main accent (#D4A055) */
  --p-amber-700: oklch(0.52 0.145 75);       /* dark amber for light-mode text */
}

Adjust the hue value (75 = warm amber) to shift the entire brand colour:

• 75 — warm amber/gold (default)
• 145 — green
• 180 — teal
• 255 — blue
• 320 — pink/rose

The second OKLCH value controls saturation (chroma). Lightness steps are set for contrast — keep the relative differences when changing.

Accent variants

The commented Teal/Rose snippets in globals.css are reference palettes, not one-step theme switches. For a complete rebrand, re-hue the four --p-amber-* primitives in :root {} and then update the three non-CSS surfaces in the workflow below. That keeps glow, orb, surface-tint, light-mode, and hero-frame colours on the same hue instead of leaving amber-derived tokens behind.

Light mode colours

Overrides are in html.light {} in globals.css. Edit those values to customise the light theme independently.

Known exceptions

These elements use hardcoded colours that won't update from the CSS tokens:

• Hex/RGBA fallback (src/lib/tokens.ts) — source of truth for WebGL, Canvas, viewport metadata, and root error fallback contexts that cannot read CSS custom properties. light-droplets-bg.tsx imports BRAND.amber.accent; ambient-glow.tsx imports WEBGL.ambientBrand / WEBGL.darkBackground; src/app/global-error.tsx mirrors ERROR_FALLBACK locally.
• SVG icon (src/app/icon.svg) — replace #D4A055 manually or regenerate in your brand colour, and keep the glyph fill/stroke aligned with your brand-accent foreground mirror.
• Recharts chart colours — SVG <stop> elements in src/components/dashboard/UsageDailyChart.tsx reference var(--chart-series-2). To change the chart-2 hue, edit the --chart-series-2-base: oklch(0.733 0.156 297.2); token in src/app/globals.css; the exported --chart-series-2 token derives from it and light mode automatically mixes the same base for contrast — no component edit needed.
• Status/severity colours — operational (green), warning (amber), error (red), info (blue) are driven by four CSS custom properties in globals.css (--severity-success, --severity-warning, --severity-error, --severity-info) that are independent of the brand colour. These are registered in @theme as --color-severity-*, so Tailwind utilities work with the full modifier syntax: bg-severity-success, text-severity-error, border-severity-info/20, hover:bg-severity-warning/10. Edit the four OKLCH values in globals.css to shift the whole status palette.
• Shadow glows — shadow-[0_0_Xpx_var(--brand-glow)] utilities throughout the kit resolve through a color-mix(in oklch, var(--brand-accent) X%, transparent) cascade, so no manual edit is needed after a primitive hue swap.

Rebrand workflow

Follow these steps in order when changing the brand colour:

Step 1 — CSS tokens (covers most UI)

• Open src/app/globals.css
• Change the four --p-amber-400/500/600/700 primitives to your brand hue (adjust lightness, chroma, and hue)
• That's it for the cascade. --brand-accent, --brand-glow*, --brand-orb-glow, --brand-surface-tint*, .brand-glow-* utilities, and the orb backgrounds all derive from these primitives via var() or color-mix() — no further edit needed.
• Convert your OKLCH values to hex at oklch.com when you need a literal for the non-CSS surfaces in Step 2.

Step 2 — Non-CSS surfaces (3 files)

Informational — token-driven, no edit needed

Step 3 — Verify

• Run pnpm dev and check the landing page in both dark and light mode
• Toggle the theme — all branded elements should match your new colour
• Check the dashboard, pricing, and error pages

Step 4 — Catch leftover brand strings The kit ships with pnpm rebrand-check (see scripts/rebrand-check.mjs). It greps the source for hardcoded occurrences of the kit's original brand name (Aria) outside SITE_CONFIG. Run it after Step 3 — any hits are strings the cascade can't reach (model labels, status copy, demo data seeded with the brand name). Replace each with SITE_CONFIG.name or your new brand string.

pnpm rebrand-check

The script exits 0 if every match is in an allowlisted file (e.g. src/lib/site-config.ts, where the brand name is the source of truth).

Typography

Fonts are bundled as .woff2 variable font files in src/app/fonts/ and loaded via next/font/local — no network access is required at build time (deliberate choice for air-gapped CI / offline-build support). Three files ship with the kit:

The @theme inline { … } block in globals.css maps these variables to the role-neutral names Tailwind consumes. Consumers use font-sans, font-mono, .font-display (or style={{ fontFamily: 'var(--font-display)' }}) — never reference --font-space-grotesk directly outside the binding.

The display font is preloaded because the homepage H1 uses it as an LCP-critical headline font. Keeping it preloaded avoids layout shift from a late headline font swap on wide viewports.

Change the display font

Replace src/app/fonts/space-grotesk.woff2 with any variable .woff2 and update the localFont config in src/app/layout.tsx:

// src/app/layout.tsx
const spaceGrotesk = localFont({
  src: [{ path: './fonts/your-font.woff2', weight: '300 700', style: 'normal' }],
  variable: '--font-space-grotesk',
  display: 'swap',
  preload: true,
})

The --font-space-grotesk CSS variable is referenced throughout the template via the .font-display class.

Change the body font

The body font is Geist Sans. Replace src/app/fonts/geist-sans.woff2 and update the localFont config:

const geistSans = localFont({
  src: './fonts/your-body-font.woff2',
  variable: '--font-geist-sans',
  weight: '100 900',
  display: 'swap',
})

Fluid type scale

Font sizes use clamp() in @theme inline {}:

--text-step-3: clamp(1.5rem, 1.2rem + 1.5vi, 2.25rem);

Adjust the min, preferred, and max values to taste. The vi unit scales relative to the viewport inline size.

Content

Site copy

All section content lives in the component files under src/components/sections/. Each section exports a single component; edit the constant arrays and strings directly.

Navigation links

Edit src/components/layout/navbar.tsx — the NAV_LINKS constant.

Brand identity (name, emails, social links, metadata, API URLs)

Shell-level brand identity (name, metadata, contact emails, social links, API URLs) is centralised in src/lib/site-config.ts. Change the SITE_CONFIG object to update these across the site in one place. Demo marketing, legal, blog, and testimonial content is separate and must be replaced manually — see the "Demo content" section below.

The wordmark text comes from SITE_CONFIG.name, but the mark itself is an icon. Replace the default Zap icon imports/rendering in src/components/layout/navbar.tsx and src/components/layout/footer.tsx, then keep src/app/icon.svg in sync so the browser favicon matches the visible logo.

The config object has the following sections:

Demo content (replace before production)

site-config.ts covers your brand shell — name, metadata, contact details, and social links. The following pages contain demo content (marketing copy, blog posts, testimonials, legal text) that you should replace with your own before publishing:

These pages contain realistic placeholder content to demonstrate the design. Do not publish them as-is — replace with your own copy. See DEMO_CONTENT.md for the full checklist.

Footer links

Edit src/components/layout/footer.tsx — the FOOTER_LINKS object. Social links and the brand name are imported from src/lib/site-config.ts.

Pricing plans

Edit both pricing data sources:

• src/components/sections/pricing.tsx — homepage pricing cards and landing-page billing toggle.
• src/components/dashboard/pricing-data.ts — dedicated /pricing route cards and comparison table.

Keep plan names, prices, limits, and feature wording aligned across both files unless you intentionally want the homepage to use shorter marketing copy.

FAQ

Edit src/components/sections/faq.tsx — the FAQ_ITEMS constant array.

Testimonials

Edit src/components/sections/testimonials.tsx — the TESTIMONIALS constant array.

Adding a new page

1. Create src/app/my-page/page.tsx
2. Export a default React component
3. Add a link in src/components/layout/navbar.tsx

Pages use the shared layout from src/app/layout.tsx automatically.

Animations

Disable all animations

Motion is controlled by src/hooks/use-motion-preference.ts. The system respects four signals:

1. System preference: prefers-reduced-motion: reduce — detected automatically
2. Viewport: animations are disabled on mobile (< 768px) — static layouts shown instead
3. Manual toggle: if you add a MotionToggle button (see use-motion-preference.ts for the API)
4. Global override: CSS variable or HTML data attribute, useful for buyer QA

To disable animations globally regardless of system settings, add this to src/app/globals.css:

:root { --force-reduce-motion: true; }

Or set data-reduce-motion="true" on the <html> element.

Adjust animation speed

The GSAP animation easings and durations are configured in src/lib/gsap.ts and individual section components. Lenis smooth scroll speed is in src/components/providers/lenis-provider.tsx:

new Lenis({
  duration: 1.2,      // scroll animation duration in seconds
  touchMultiplier: 2, // mobile scroll speed multiplier
})