Skip to content

DESIGN.md

Latest commit

 

History

History
210 lines (171 loc) · 11.5 KB

DESIGN.md

File metadata and controls

210 lines (171 loc) · 11.5 KB

Design System Specification

1. Overview & Creative North Star: "The Crystalline Zest"

This design system is a sensory exploration of refreshment. It moves beyond standard functional UI to evoke the visceral feeling of a chilled glass of lemonade—crisp, translucent, and vibrant. The "Creative North Star" for this system is Crystalline Zest.

Unlike rigid, corporate grids, this system leverages heavy glassmorphism and a tonal gradient architecture to create depth. It rejects the "flat web" in favor of an editorial layout that feels like looking through ice and liquid. We use intentional asymmetry and a strict 4-column content structure to provide a high-end, curated feel that prioritizes readability against a luminous, shifting background.

2. Colors & Tonal Architecture

The palette is a celebration of citrus. We strictly avoid dark "muddy" yellows or browns to maintain the "chilled" aesthetic.

The Background Gradient

The primary canvas is not a flat color. It is a vertical gradient:

  • Top (Ice): --surface-container-lowest (#FFFFFF)
  • Bottom (Settled Juice): Transitioning toward #FFF9C4 (pale lemon).

Key Tokens

  • Primary (Vibrant Citrus): --primary-yellow (#FCD846). The signature accent for buttons, highlights, and energy.
  • On Primary: --on-primary (#000000). Black text and icons on yellow surfaces for maximum contrast.
  • On Primary Muted: --on-primary-muted (#3a3000). For text on light-yellow tinted surfaces (e.g. chat bubbles).
  • Accent Gold: --accent-gold (#5C4B00). Used for icon tints and value-link text on white surfaces.
  • Natural Accent (Lemon Leaf): --tertiary (#3C6531). Used sparingly for success states.
  • Neutral Surface: --surface (#F6F6F6) provides the "chilled glass" base.

Text Hierarchy

From darkest to lightest:

  • --text-on-light (#000000) — Maximum contrast on light backgrounds.
  • --text-primary (#2D2F2F) — Body text and headings.
  • --text-secondary (#474747) — Descriptions and supporting text.
  • --text-nav (#52525b) — Navigation links.
  • --text-muted (#6b6b6b) — Labels and metadata.
  • --text-light (#999) — Disabled or decorative text.

Core Rules

  • The "No-Line" Rule: 1px solid borders are strictly prohibited for sectioning. Use surface-container shifts to define boundaries.
  • Surface Nesting: Hierarchy is achieved by layering. A --surface-container-low card should sit atop a --surface background.
  • Glassmorphism Rule: Floating navigation and headers must use --surface with 60-80% opacity and --glass-blur (24px) backdrop-blur.

2b. Midnight Palette (Dark Mode)

The Midnight variant transposes Crystalline Zest into a warm-dark register. We avoid cold blue-blacks and pure #000; the canvas instead reads as a darkened citrus liqueur — deep, slightly warm, with the same yellow accent punching through.

The Background Gradient (Dark)

  • Top (Night Ice): --surface-container-lowest (#0E0E0B)
  • Bottom (Steeped Juice): Transitioning toward #1F1A0E (warm dark amber).

Surface Scale (Dark)

Mirrors the light scale but inverted in luminance with a faint yellow undertone. These values override the base tokens inside [data-md-color-scheme="zest-dark"]:

  • --surface-container-lowest (#0E0E0B) — deepest layer.
  • --surface (#1A1813)
  • --surface-container-low (#1F1D17)
  • --surface-container (#25221B)
  • --surface-container-high (#2D2922)
  • --outline-variant: rgba(255, 255, 255, 0.10)

Glass Tokens (Dark)

Pure backdrop-blur over dark loses contrast. Dark glass uses a tinted-dark fill (so the surface is visible even without a busy backdrop) and a faint yellow-tinted border to retain Crystalline Zest's signature:

  • --glass-bg: rgba(45, 41, 33, 0.55)
  • --glass-bg-dense: rgba(45, 41, 33, 0.85)
  • --glass-bg-hover: rgba(60, 54, 42, 0.75)
  • --glass-border: rgba(252, 216, 70, 0.18) — yellow at low alpha
  • --glass-blur: 24px (unchanged; layered over the tinted fill it still adds depth without losing readability)

Text Hierarchy (Dark)

Inverted scale, warm-leaning whites (avoid cool cyan-whites):

  • --text-on-light (#FFFFFF)
  • --text-primary (#F2EFE5) — body text and headings.
  • --text-secondary (#C7C2B5)
  • --text-nav (#A8A39A)
  • --text-muted (#837F75)
  • --text-light (#5C594F)

Body text should maintain at least 4.5:1 contrast against the gradient.

Shadows (Dark)

Light-mode shadows are tuned to the on-surface color (rgba(45, 47, 47, ...)) and disappear on dark. Dark shadows use plain black at higher alpha plus the existing yellow-glow tokens for primary buttons:

  • --shadow-light: 0 4px 16px rgba(0, 0, 0, 0.35)
  • --shadow-medium: 0 8px 32px rgba(0, 0, 0, 0.45)
  • --shadow-heavy: 0 14px 52px rgba(0, 0, 0, 0.60)
  • --shadow-ambient: 0 12px 48px rgba(0, 0, 0, 0.40)
  • --shadow-yellow and --shadow-yellow-hover — unchanged. The yellow glow is part of the brand and reads beautifully on dark.

Accent Invariants

These are deliberately unchanged across light and dark — they are the "citrus" of the brand and pop equally well on both surfaces:

  • --primary-yellow (#FCD846)
  • --primary-yellow-dark (#FAF972) — used for hover/highlights
  • --tertiary (#3C6531) — lemon-leaf green
  • --on-primary (#000) — black text on yellow buttons stays black even in Midnight mode

.ice-card — Midnight Recipe

[data-md-color-scheme="zest-dark"] .ice-card {
  background: var(--glass-bg);                  /* tinted dark, not white-on-dark */
  backdrop-filter: blur(var(--glass-blur));     /* 24px */
  border: 1px solid var(--glass-border);        /* yellow at 18% alpha */
  box-shadow: var(--shadow-ambient);
}

The yellow-tinted border is the dark-mode analogue of the light-mode "felt, not seen" ghost border — it gives ice cards a warm halo on dark surfaces without being literal.

Do's and Don'ts (Dark)

  • Do keep --on-primary as #000 on yellow surfaces in dark mode — the contrast ratio against #FCD846 is unchanged.
  • Do prefer tinted-dark fills over white-at-low-alpha for glass surfaces. White glass on dark backdrops looks washed out and washes out the text on top.
  • Don't use pure #000 as a background. The lowest surface (--surface-container-lowest) is #0E0E0B — slightly warm, slightly off-black, to keep the citrus character.
  • Don't invert --tertiary (lemon leaf green). It already has enough luminance to read on dark; lightening it would push toward an unrelated mint hue.

3. Typography: Editorial Authority

We pair the geometric precision of Plus Jakarta Sans for impact with the high-legibility of Manrope for narrative, and Consolas/Monaco for code.

  • Display & Headlines (--font-display): Plus Jakarta Sans. Used for headings, buttons, and high-impact UI. Tight tracking, heavy weight (700-800).
  • Body & Labels (--font-body): Manrope. Set in --text-primary (#2D2F2F) for maximum contrast.
  • Code (--font-mono): Consolas, Monaco, Courier New. Used in code blocks, terminal cards, and API samples.
  • The Hierarchy Strategy: Use extreme scale differences. Section headings use clamp(1.35rem, 2.4vw, 2.1rem) while body stays at ~0.88-1rem.

4. Elevation & Depth: Tonal Layering

We do not use structural lines. We use physics.

The Layering Principle

Depth is achieved by "stacking" tones:

  • Level 0: Background Gradient.
  • Level 1: --glass-bg rgba(255,255,255,0.4) — The "Glass" layer (ice cards, panels).
  • Level 2: --glass-bg-hover rgba(255,255,255,0.65) — Active/hover states.
  • Level 3: --surface-container-lowest (#FFFFFF) — Solid "Ice" for maximum pop.

Shadows

All shadows use the on-surface color (45, 47, 47), never pure black:

  • --shadow-light: 0 4px 16px at 4% opacity. Resting cards.
  • --shadow-medium: 0 8px 32px at 6% opacity. Hover states.
  • --shadow-heavy: 0 14px 52px at 8.5% opacity. Hero panels and elevated elements.
  • --shadow-ambient: 0 12px 48px at 5% opacity. Default ice-card shadow.
  • --shadow-yellow: 0 12px 48px rgba(252,216,70,0.3). Primary buttons.
  • --shadow-yellow-hover: 0 16px 56px rgba(252,216,70,0.38). Primary button hover.

Ghost Borders

For essential accessibility on white-on-white elements, use --outline-variant (rgba(45,47,47,0.15)). It should be felt, not seen.

Roundedness

  • --radius-card (3rem): Ice cards, demo panels, value cards.
  • --radius-xl (1.5rem): Console panels, API sample blocks.
  • --radius (1rem): Buttons, interactive elements, inner containers.
  • --radius-btn (9999px): Pill-shaped CTA buttons and download links.

5. Components

The Ice Card (.ice-card)

The foundational glassmorphic component. All card-like containers inherit from this:

background: var(--glass-bg);           /* rgba(255,255,255,0.4) */
backdrop-filter: blur(var(--glass-blur)); /* 24px */
border: 1px solid var(--glass-border); /* rgba(255,255,255,0.6) */
border-radius: var(--radius-card);     /* 3rem */
box-shadow: var(--shadow-ambient);

Used by: value cards, tech spec cards, demo panel, dev button, release card, console cards.

Buttons

  • Primary (Yellow): --primary-yellow background, --on-primary (#000) text, --shadow-yellow glow. Pill-shaped (--radius-btn).
  • Secondary (Glass): Inherits .ice-card base. --text-primary text. Hover lifts to --glass-bg-hover.
  • Section CTA: Same as primary, with min-width: 320px and open_in_new icon for external links.
  • Download Link: Same as primary, used in the Getting Started section.

Console Card (.gs-console)

Ice card with monospace content for terminal commands:

  • Inherits .ice-card for the glassmorphic shell.
  • pre uses white-space: pre; overflow-x: auto for horizontal scroll on long commands.
  • Copy button positioned absolutely, top-right. Turns yellow on hover/copied.

Platform Selector

Row of platform icon buttons:

  • Default: opacity: 0.75, transparent background.
  • Active: opacity: 1, --glass-bg-hover background, --shadow-medium, slight scale-up.

Page Spacing Scale

The homepage uses a perfect-fourth (1.333) ratio spacing scale:

--page-space-base: 2rem
--page-space-sm:   base           ≈ 2rem
--page-space-md:   base × 1.333   ≈ 2.66rem
--page-space-lg:   base × 1.333²  ≈ 3.55rem
--page-space-xl:   base × 1.333³  ≈ 4.73rem
--page-space-xxl:  base × 1.333⁴  ≈ 6.31rem

Section top padding: --page-space-xxl. Heading margins: --page-space-sm. Internal gaps use fractional multiples of --page-space-base.

6. Do's and Don'ts

Do:

  • Do use large amounts of white space (vertical "breathing room") to simulate clarity.
  • Do ensure text contrast ratios exceed 7:1, especially on glassmorphic panels over the yellow gradient.
  • Do use the --tertiary green only as a "flavor" accent—like a mint leaf in a drink.
  • Do use --on-primary (#000) for text on yellow buttons. It must be high contrast.
  • Do use the .ice-card base class for all glassmorphic containers rather than duplicating properties.
  • Do reference CSS variables for colors, shadows, and fonts. Avoid hardcoding values that have tokens.

Don't:

  • Don't use any dark browns or muddy yellows (#695B00) as button text. Use --on-primary (#000) instead.
  • Don't use 100% opaque, hard-edged cards. Everything should feel like it has a degree of light transmission.
  • Don't use traditional "Drop Shadows" with pure black. Use the ambient shadow tokens defined in Section 4.
  • Don't use dividers to separate list items; use tonal shifts or vertical gaps.
  • Don't use section label "chips" on every section. Reserve them for sections that need categorical context.