Token-based design system: colors, type, and utility classes

Every visual value in Borrissol — color, font size, spacing, border radius, shadow — lives in src/styles/theme.css as a CSS custom property. Components never hardcode a color hex, a pixel value, or a font size directly. Instead they reference a token: var(--color-black), var(--space-md), var(--radius-pill). This single-source-of-truth approach means restyling a value like the primary border radius updates every component at once, with zero drift between copies.

Rule #1 — The DS is the single source of truth. Never hardcode any color, spacing, font size, or border value. Always reference a token from theme.css. If a value isn’t tokenized yet, add it to theme.css first, then use it.

Color tokens

The palette is monochromatic — five steps from white to black with one muted gray for secondary text:

Token	Value	Role
`--color-white`	`#FFFFFF`	Primary background
`--color-light`	`#F5F5F5`	Section fills, button preview backgrounds
`--color-mid`	`#D9D9D9`	Borders, dividers, separators
`--color-muted`	`#797979`	Secondary text, labels, metadata
`--color-black`	`#000000`	Primary text, CTAs, active borders

Four semantic aliases map the raw tokens to their intended roles:

Token	Maps to	Usage
`--bg`	`var(--color-white)`	Page background
`--bg-section`	`var(--color-light)`	Section backgrounds
`--fg`	`var(--color-black)`	Primary text
`--fg-muted`	`var(--color-muted)`	Secondary / supporting text

Typography scale

Roboto is self-hosted as a single WOFF2 file (Roboto-latin.woff2) that covers both weight 400 and weight 500 — only these two weights are used across the entire site. font-display: swap is set to avoid invisible text during load. The display font Coiny is specified for the .logo-wordmark element exclusively and must never appear on headings, hero text, or body copy.

Headings (H1–H4)

Token	Value
`--font-size-h1`	`4rem`
`--font-size-h2`	`2.5rem`
`--font-size-h3`	`2.1rem`
`--font-size-h4`	`1.4rem`
`--font-weight-heading`	`400`
`--line-height-heading`	`1.1`
`--letter-spacing-heading`	`-0.02em`

Body paragraphs (P1–P3)

Token	Value	Use case
`--font-size-p1`	`1.4rem`	Lead / intro copy
`--font-size-p2`	`1.1rem`	Service descriptions, main body
`--font-size-p3`	`0.9rem`	Footnotes, captions, supporting text
`--font-weight-body`	`400`
`--line-height-body`	`1.3`
`--letter-spacing-body`	`-0.02em`

UI / Utility

Token	Value	Use case
`--font-size-ui`	`0.8rem`	Labels, prices, metadata, dates
`--line-height-ui`	`1.1`

Button typography (shared)

Token	Value
`--font-weight-btn`	`500`
`--text-transform-btn`	`uppercase`
`--letter-spacing-btn`	`0.05em`

Spacing scale

Token	Value	Typical usage
`--space-xs`	`8px`	Internal component gap
`--space-sm`	`16px`	Card padding, grid gap
`--space-md`	`24px`	Nav padding, column gap
`--space-lg`	`40px`	Section separation
`--space-xl`	`80px`	Hero padding, large sections

Border radius

Token	Value	Usage
`--radius-pill`	`9999px`	Inputs, primary and secondary buttons
`--radius-md`	`8px`	Media frames (`.media`), nav, containers
`--radius-sm`	`4px`	Small UI elements
`--radius-xs`	`2px`	Cards (`.card`)

Border tokens

Token	Value	Usage
`--border-default`	`0.5px solid var(--color-mid)`	Dividers, containers
`--border-strong`	`1px solid var(--color-black)`	Inputs, secondary button, active states
`--border-hairline`	`0.5px solid var(--color-mid)`	Hairline divider

Button styles

All buttons share uppercase text, font-weight: 500, and letter-spacing: 0.05em — these are never overridden.

Property	Primary	Secondary	Tertiary
font-size	`0.8rem`	`0.9rem`	`0.8rem`
background	`--color-black`	`transparent`	`transparent`
color	`--color-white`	`--color-black`	`--color-black`
border	none	`1px solid black`	none
border-radius	`--radius-pill`	`--radius-pill`	`0`
padding	`1.2em 2em`	`1.2em 2.004em`	`1.2em 0`
hover	`opacity: 0.85`	`bg: --color-light`	—

An optional .btn-sm modifier reduces the size for compact contexts.

Utility classes

Utility classes are defined in theme.css and carry the type system site-wide. Scoped component CSS carries layout only.

Typography utilities

Class	Description
`.text-h1` – `.text-h4`	Applies the corresponding heading token set (size, weight, line-height, letter-spacing)
`.text-p1` – `.text-p3`	Applies the corresponding body token set
`.text-ui`	`--font-size-ui`, `--line-height-ui`, weight 500
`.text-muted`	Sets color to `var(--color-muted)`
`.eyebrow`	Small uppercase label above section headings

Container utilities

Class	Description
`.card`	White surface + `--border-default` hairline border + `--radius-xs` corners
`.media`	Media frame: `--radius-md` + `overflow: clip`; child `img`/`iframe`/`video` fills and crops. Set `aspect-ratio` in scoped CSS.

Button utilities

Class	Description
`.btn`	Base styles (shared typography)
`.btn-primary`	Black background, white text, pill radius
`.btn-secondary`	Transparent background, black border, pill radius
`.btn-tertiary`	No border, no radius, zero horizontal padding
`.btn-sm`	Size modifier for compact contexts

Miscellaneous utilities

Class	Description
`.badge`	Dark badge / tag
`.badge-light`	Light badge variant
`.input`	Pill-bordered form input (uses `--input-*` tokens)
`.checkbox`	Styled checkbox (checked state)
`.checkbox-unchecked`	Styled checkbox (unchecked state)
`.link-arrow`	Inline link with trailing arrow indicator

The hybrid model: utility classes + scoped CSS

Utility classes carry the type system; scoped CSS carries layout. Both apply to the same element when needed:

<h2 class="text-h2 tb-h2">Team Building</h2>

/* scoped <style> in the component */
.tb-h2 { margin: 0 0 var(--space-md); }

The text-h2 class sets size, weight, line-height, and letter-spacing. The tb-h2 class adds only the margin that is specific to this layout. This prevents the type scale from drifting when tokens are updated, because every heading across the site references the same .text-h* definition.

.text-* utilities set type only — color comes from .text-muted or the inherited body default. Margins are never baked into utility classes; always add them in scoped CSS.

Icons

Borrissol uses Lucide Icons exclusively. All icons are outline-style with a stroke width of 1.5px and use var(--icon-color) (aliased to var(--color-black)) for their color.

Token	Value	Context
`--icon-stroke-width`	`1.5px`	All icons
`--icon-color`	`var(--color-black)`	Default icon color
`--icon-size-inline`	`16px`	Inline UI
`--icon-size-btn`	`20px`	Inside buttons
`--icon-size-nav`	`24px`	Navigation
`--icon-size-feature`	`32px`	Feature highlights
`--icon-size-hero`	`48px`	Hero / CTA

Icons are loaded via CDN and initialized with lucide.createIcons():

<script src="https://unpkg.com/lucide@latest"></script>
<!-- Usage: -->
<i data-lucide="arrow-right"></i>

Do not use any icon library other than Lucide. Do not change the stroke width from 1.5px. Do not use filled icon variants.

Fonts: self-hosted Roboto

Roboto is self-hosted as a single WOFF2 file (Roboto-latin.woff2) — no Google Fonts CDN request at runtime. A single @font-face block covers both weights using a range declaration. Requesting any other weight (300, 700, etc.) would introduce unused bytes and a render-blocking request.

/* Correct — only these two weights exist in the project */
font-weight: 400; /* body, headings */
font-weight: 500; /* buttons, labels, eyebrows, .text-ui */

The Coiny display font is specified for the .logo-wordmark class on the brand name element in the Navbar and must never appear anywhere else in the UI.

Getting Started

Core Concepts

Token-based design system: colors, type, and utility classes

Color tokens

Typography scale

Headings (H1–H4)

Body paragraphs (P1–P3)

UI / Utility

Button typography (shared)

Spacing scale

Border radius

Border tokens

Button styles

Utility classes

Typography utilities

Container utilities

Button utilities

Miscellaneous utilities

The hybrid model: utility classes + scoped CSS

Icons

Fonts: self-hosted Roboto

​Color tokens

​Typography scale

​Headings (H1–H4)

​Body paragraphs (P1–P3)

​UI / Utility

​Button typography (shared)

​Spacing scale

​Border radius

​Border tokens

​Button styles

​Utility classes

​Typography utilities

​Container utilities

​Button utilities

​Miscellaneous utilities

​The hybrid model: utility classes + scoped CSS

​Icons

​Fonts: self-hosted Roboto

Color tokens

Typography scale

Headings (H1–H4)

Body paragraphs (P1–P3)

UI / Utility

Button typography (shared)

Spacing scale

Border radius

Border tokens

Button styles

Utility classes

Typography utilities

Container utilities

Button utilities

Miscellaneous utilities

The hybrid model: utility classes + scoped CSS

Icons

Fonts: self-hosted Roboto