CSS architecture and design token system

Pikanté’s visual language is defined by a single file — src/styles/global.css — that combines two complementary systems: a hand-authored set of OKLCH CSS custom properties that encode every design decision, and Tailwind CSS v4 for utility classes where they accelerate layout work. Neither system is a fallback for the other; they run side-by-side throughout the project.

Tailwind CSS v4 utility classes (e.g. flex, gap-4, text-sm) are available everywhere in .astro templates at the same time as the custom CSS classes and design-token variables defined in global.css. Both systems are active simultaneously — you do not have to choose one or the other within a component.

Two styling systems, one file

/* src/styles/global.css — line 1 */
@import "tailwindcss";

The @import "tailwindcss" directive at the top of global.css activates the full Tailwind utility layer. Tailwind v4 requires no tailwind.config.js — configuration happens entirely through the Vite plugin registered in astro.config.mjs:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  integrations: [react()],
  vite: {
    plugins: [tailwindcss()]
  }
});

Every custom rule and design token written below the @import line is authored in plain CSS — no preprocessor, no @apply abuse, no build-time configuration beyond the Vite plugin.

OKLCH color system

All color values in global.css use the oklch() functional notation rather than hsl() or hex. OKLCH (Oklab Lightness-Chroma-Hue) offers two concrete advantages for this design system:

Perceptual uniformity. Two colors at the same L value in OKLCH will appear equally bright to the human eye, regardless of hue. This makes it safe to derive tints and shades by adjusting only L without shifting perceived contrast.
Consistent chroma. The C (chroma) axis is device-independent, so a C: 0.21 fire orange and a C: 0.21 lime green will appear equally saturated. This is not true in HSL, where the same S value produces wildly different visual saturation across hues.

color-mix(in oklab, ...) is used throughout to derive --accent-soft, --accent-glow, and per-hover states without hardcoding additional color stops.

CSS custom properties (design tokens)

All tokens are declared on :root. The complete set from global.css:

:root {
  /* ── Background scale (cool charcoal, hue 260°) ── */
  --bg:     oklch(5%  0.008 260deg);   /* deepest background */
  --carbon: oklch(8%  0.010 260deg);   /* section alternates */
  --char:   oklch(11% 0.010 260deg);   /* card surfaces */
  --line:   oklch(16% 0.008 260deg);   /* dividers */
  --line-2: oklch(22% 0.008 260deg);   /* subtle borders */

  /* ── Ink scale (component fill layers) ── */
  --ink-1:  oklch(5%  0.008 260deg);   /* deepest fill — same as --bg */
  --ink-2:  oklch(8%  0.010 260deg);   /* card base */
  --ink-3:  oklch(11% 0.010 260deg);   /* card gradient top */
  --ink-4:  oklch(14% 0.010 260deg);   /* slightly lifted surface */

  /* ── Fire / chile accent palette ── */
  --fire:       oklch(65% 0.21  35deg);  /* primary accent — orange-red */
  --chile:      oklch(56% 0.23  22deg);  /* deeper chile red */
  --dark-red:   oklch(38% 0.14  22deg);  /* shadow / dark red */
  --lime:       oklch(76% 0.17 130deg);  /* prep-step label green */
  --amber:      oklch(50% 0.12  50deg);  /* warm amber */
  --chile-dust: oklch(34% 0.10  22deg);  /* darkest red-brown */

  /* ── Semantic accent aliases ── */
  --accent:      var(--fire);
  --accent-soft: color-mix(in oklab, var(--accent) 38%, transparent);
  --accent-glow: color-mix(in oklab, var(--accent) 72%, transparent);
  --lime-soft:   color-mix(in oklab, var(--lime)   35%, transparent);

  /* ── Text hierarchy ── */
  --text-1: oklch(92% 0.006 260deg);   /* primary text */
  --text-2: oklch(75% 0.006 260deg);   /* secondary text */
  --text-3: oklch(57% 0.006 260deg);   /* tertiary / muted */
  --text-4: oklch(40% 0.006 260deg);   /* disabled / labels */
  --smoke:  oklch(55% 0.006 260deg);   /* eyebrow / meta labels */
  --paper:  oklch(94% 0.010  60deg);   /* warm near-white body text */
  --white:  oklch(99% 0.004 260deg);   /* pure white */

  /* ── Layout ── */
  --max:    1440px;
  --gutter: clamp(20px, 4vw, 64px);   /* responsive horizontal padding */

  /* ── Radii ── */
  --rad-sm: 10px;
  --rad:    16px;
  --rad-lg: 28px;

  /* ── Transitions ── */
  --t-fast: .18s cubic-bezier(.2,.7,.2,1);
  --t:      .36s cubic-bezier(.2,.7,.2,1);
}

Token groups at a glance

Background scale

Five steps from near-black --bg to dark charcoal --line-2. All use hue 260° (cool blue-violet) to create a thermal contrast against the warm fire accent. Sections alternate between --bg, --carbon, and --char to create depth without color.

Fire / chile palette

Six named colors spanning orange-red (--fire) through deep chile crimson (--dark-red) and lime green (--lime). Every color in this group uses a different hue but sits at a carefully chosen chroma so they feel cohesive when used together.

Accent aliases

--accent is always --fire. --accent-soft and --accent-glow are color-mix() derivatives used for glows, shadows, and hover fills. Swapping the single --fire value would re-theme every accent in the entire site.

Text hierarchy

Four numeric tiers (--text-1 → --text-4) plus --smoke, --paper, and --white. All share hue 260° with minimal chroma, keeping text neutral against the warm accents. --paper shifts to hue 60° for a slightly warm tone that reads softer than pure white.

Utility and component classes

Beyond design tokens, global.css defines a set of reusable classes used throughout the component templates:

Class	Purpose
`.container`	Max-width `1440px`, auto margins, responsive `--gutter` horizontal padding
`.eyebrow`	JetBrains Mono, 11 px, all-caps, tracked; prepends an `--accent` horizontal rule via `::before`
`.mono`	JetBrains Mono, 14 px, `.22em` letter-spacing, uppercase — used for labels and data tags
`.h-display`	Anton font, weight 400, `line-height: .86`, uppercase — base class for all display headings
`.btn`	Base pill button: `border-radius: 999px`, JetBrains Mono, 12 px, uppercase, tracked
`.btn-primary`	Fire gradient fill, dark text — primary CTA button skin
`.btn-ghost`	Semi-transparent fill with a `--line-2` inset border — secondary CTA skin
`.section-head`	Two-column grid (heading left, body text right) with responsive single-column breakpoint at 780 px
`.reveal`	Scroll-reveal base: `opacity: 0`, `translateY(28px)` — transitions to visible when `.in` is added

Typography

Three typefaces are loaded via Google Fonts in the <head> of index.astro:

<link href="https://fonts.googleapis.com/css2?family=Anton
  &family=Inter:wght@400;500;600;700
  &family=JetBrains+Mono:wght@400;500
  &display=swap" rel="stylesheet"/>

Typeface	Role	CSS assignment
Anton	Display headings, section titles, large numerals	`.h-display`, `.section-head h2`, `.what-n`, `.step-body h3`, etc.
Inter	Body copy, paragraph text, UI labels	`body { font-family: 'Inter', system-ui, sans-serif }`
JetBrains Mono	Eyebrows, pill labels, prices, meta tags, buttons	`.mono`, `.eyebrow`, `.btn`, `.variant-pill`, `.nav-links a`, etc.

Film grain overlay

A full-viewport SVG noise texture is layered over the entire page via a body::after pseudo-element. The texture uses an inline SVG data URI with an feTurbulence filter — no external image request needed:

body::after {
  content: "";
  position: fixed;
  inset: 0;
  pointer-events: none;
  z-index: 200;
  background-image: url("data:image/svg+xml;utf8,
    <svg xmlns='http://www.w3.org/2000/svg' width='220' height='220'>
      <filter id='n'>
        <feTurbulence type='fractalNoise' baseFrequency='0.9'
          numOctaves='2' stitchTiles='stitch'/>
        <feColorMatrix values='0 0 0 0 1  0 0 0 0 1  0 0 0 0 1  0 0 0 .35 0'/>
      </filter>
      <rect width='100%' height='100%' filter='url(#n)' opacity='.5'/>
    </svg>");
  mix-blend-mode: overlay;
  opacity: .18;
}

mix-blend-mode: overlay ensures the grain blends naturally with both the dark backgrounds and the bright accent highlights rather than simply sitting on top. At opacity: .18 the effect is subtle — it reads as cinematic texture rather than visible noise.

The grain overlay sits at z-index: 200, above most content layers. It carries pointer-events: none, so it never interferes with clicks, taps, or hover states on any element beneath it.

Responsive strategy

The design is mobile-considered but desktop-first. Most layout shifts happen at three breakpoints defined inline per component section using @media:

Breakpoint	Typical change
`max-width: 980px`	Hero grid collapses to single column
`max-width: 880px`	Products, HowTo steps, Stores city grid go single-column
`max-width: 760px`	Nav links hidden; sticky mobile CTA bar appears
`max-width: 640px`	City grid fully stacked

Fluid sizing uses clamp() extensively — --gutter, section headings, hero text, and display numerals all scale continuously between a minimum and maximum value rather than snapping at fixed breakpoints.

Get Started

Project Structure

CSS architecture and design token system

Two styling systems, one file

OKLCH color system

CSS custom properties (design tokens)

Token groups at a glance

Background scale

Fire / chile palette

Accent aliases

Text hierarchy

Utility and component classes

Typography

Film grain overlay

Responsive strategy

Build docs developers (and LLMs) love

Get Started

Project Structure

Documentation Index

​Two styling systems, one file

​OKLCH color system

​CSS custom properties (design tokens)

​Token groups at a glance

Background scale

Fire / chile palette

Accent aliases

Text hierarchy

​Utility and component classes

​Typography

​Film grain overlay

​Responsive strategy

Build docs developers (and LLMs) love

Two styling systems, one file

OKLCH color system

CSS custom properties (design tokens)

Token groups at a glance

Utility and component classes

Typography

Film grain overlay

Responsive strategy