Fluid Design System

The core design philosophy is hybrid responsive design:

1. Continuous Fluid Scaling: All design tokens (typography, spacing) scale continuously based on viewport size.
2. Breakpoint Constraints: Major structural changes or legibility limits are enforced using media queries (breakpoints).

1. Core Implementation & Units

A. Units of Measure

• Base Font Size: 100% on the <html> element, so 1rem = 16px — the browser default is left alone, which is the accessibility-correct choice. (Corrected 2026-08-29: this spec previously said 62.5% / 1rem = 10px, contradicting what the monorepo actually ships. Resolved in favour of the shipped 100% — Talbot.)
• Sizing/Spacing: Primarily use rem and clamp() for fluid scaling. Use px only for 1px borders or other fixed visual details.
• Fluid Values: Use clamp(min-size, fluid-rate, max-size) for all fluid parameters (typography, margin, padding, line height, line spacing, etc.).
  • The fluid rate should be based on vw (viewport width) within a controlled range (e.g., calc(1rem + 1vw)).

B. CSS Variables (Design Tokens)

All design parameters must be exposed as CSS Variables (Custom Properties) to ensure themeability and maintainability.

• Naming Convention: See Naming Systems: CSS
• Theming: All colors and key component-level sizes must support a light/dark mode switch via CSS variables, following the structure established by Shadcn-Svelte’s theming system.

2. Fluid Scaling (Utopia.fyi)

The fluid scales for typography and spacing will be generated using principles derived from Utopia.fyi.

A. Fluid Typography Scale

• Tooling: Use the clamp() generator from Utopia or a similar calculator.

• Implementation:

  • Define four fluid steps (e.g., 320px to 1500px).
  • Define a minimum and maximum font size for the base body text.
  • Define a typographic ratio (e.g., 1.25 for H2 from H3).

• CSS Variable Example:

  :root {
    /* Base body text: 16px -> 20px */
    --font-size-body: clamp(1rem, 1rem + 0.34vw, 1.25rem);
    /* Heading 1: 40px -> 72px */
    --font-size-h1: clamp(2.5rem, 2.5rem + 2.71vw, 4.5rem);
  }

  These are the values the monorepo actually ships, read from sites/template/src/styles/design-tokens.conservative.css — not illustrative numbers.

---

3. Where this is authoritative

Under the design boundary rule (see Design), a build-read fact lives repo-side. The generated type and spacing scales are build-read, so ~/projects/monorepo/docs/design/typography.md is the SSOT; this file is the philosophy note behind it. If the two ever disagree again, the repo wins and this file is the one to correct.