Visual Design & CSS Execution Guide

The visual language of this application merges the high-density, mathematical rigor of a Linear-inspired SaaS interface with a "Liquid Glass" physical aesthetic. It relies on a strictly constrained monochrome foundation (Midnight/Obsidian), highly intentional accent colours, and depth created through translucency, backdrop blurs, and multi-layered shadows.

1. Colour Architecture: The OKLCH System

All colours must be defined and manipulated using the OKLCH colour space to ensure perceptual uniformity and accessible contrast scaling. Hexadecimal, RGB, and HSL are strictly forbidden. To allow for dynamic alpha transparency injection in CSS and Tailwind v4, colours are defined by their structural components within the @theme directive.

The Midnight / Obsidian Palette

This dark-mode default minimises ambient chrome, relying on absolute darks and stark contrasts.

Dynamic Opacity Injection

To use these variables with opacity in Tailwind v4, leverage the native CSS from syntax:

.card-glass {
  background-color: oklch(from var(--color-bg-secondary) l c h / 0.8);
}

2. Typographic Scaling (Geist)

Typography utilises the Geist font stack. It must maintain microscopic legibility for data density while offering geometric elegance for large marketing surfaces. All sizing is executed in rem units to respect browser accessibility baselines (1rem = 16px).

Tracking (letter-spacing) is mathematically tied to size: as size increases, tracking decreases to maintain optical tightness.

3. Spatial Architecture: The 8-Point Grid

All margins, paddings, gap spacings, and layout dimensions adhere to an 8-point base grid. This prevents sub-pixel rendering blur on high-density displays.

4. Layout Paradigm: The Bento Box Grid

The structural arrangement of components relies heavily on heavily compartmentalised cards that adhere to a foundational 12-column CSS Grid. Visual hierarchy is established by the surface area a card occupies.

.bento-grid {
  display: grid;
  gap: var(--space-4); /* 16px */
  grid-template-columns: repeat(12, minmax(0, 1fr));
  grid-auto-rows: 90px; /* Establishes vertical rhythm */
}
 
/* A high-priority card visually dominating the layout */
.card-primary {
  grid-column: span 8;
  grid-row: span 4;
}

5. Surface Dynamics: Borders, Radii, and Elevation

Because the colour palette is heavily constrained, the UI relies on optical illusions of depth to separate cards from the background canvas.

The 1px Subtle Border Illusion

In dark mode environments, standard borders appear harsh. Define edges using heavily transparent white strokes to simulate a microscopic physical bevel.

.surface-border {
  border: 1px solid oklch(1 0 0 / 0.08); /* Pure white, 8% opacity */
}

Concentric Corner Radii

Excessive rounding feels consumer-centric; tighter rounding conveys engineering precision.

• Outer cards use 8px (0.5rem / --space-2) radii.
• Internal nested elements scale down to 4px (0.25rem / --space-1).
• Mathematical Rule: Inner Radius = Outer Radius - Padding.

Multi-Layered Drop Shadows & Inset Lighting

Single-layer shadows fail to mimic real-world lighting. Use a 4-layer stack simulating ambient occlusion to diffuse scatter, paired with an inset rim light on the top edge.

.card-elevated {
  box-shadow: 
    0 2px 4px oklch(0 0 0 / 0.4),    /* Ambient Occlusion */
    0 4px 8px oklch(0 0 0 / 0.3),    /* Direct Shadow */
    0 8px 16px oklch(0 0 0 / 0.2),   /* Soft Penumbra */
    0 16px 32px oklch(0 0 0 / 0.1),  /* Diffuse Scatter */
    inset 0 1px 0 oklch(1 0 0 / 0.05); /* Top Rim Light */
}

6. Ambient Lighting & Mesh Textures

To break the starkness of large bento cards, employ "Ambient Mesh Textures." These are subtle washes of colour that draw the eye without overwhelming the monochrome palette.

• No Hard Edges: Gradients must fade to transparent using percentages (50% to 70%) to prevent visual banding.
• Low Chroma: Injected colours must maintain a low saturation in the OKLCH space.
• Layering: The base surface colour (--color-bg-secondary) must always be declared last as the solid fallback layer.

7. Glassmorphism & Neon Glow Effects

For global chrome elements (like the Command Palette or sticky headers) and active state highlights.

/* Glassmorphism Surface */
.glass-panel {
  background: oklch(from var(--color-bg-secondary) l c h / 0.65);
  backdrop-filter: blur(12px);
  border-bottom: 1px solid oklch(1 0 0 / 0.08);
}
 
/* Neon Glow pseudo-element placed strictly behind active components */
.neon-glow::before {
  content: "";
  position: absolute;
  inset: 0;
  background: linear-gradient(to right, oklch(0.6 0.25 290), oklch(0.65 0.25 330));
  filter: blur(20px);
  opacity: 0.5;
  z-index: -1;
}

8. Implementation & Class Usage Hierarchy

The application relies on specific utility classes defined in globals.css. Understanding when and where to apply these classes ensures optical consistency and preserves the Z-index hierarchy.

Core Surfaces (The Z-Index Hierarchy)

You have two distinct levels of "glass." Do not mix them arbitrarily.

• .glass-surface: The architectural workhorse.
  • When to use: Use this for standard bento box cards, sidebars, or any static container resting directly on the main canvas (bg-background).
  • Visuals: It features a tighter blur and a shallower ambient shadow stack.
• .glass-elevated: The overlay.
  • When to use: Reserve this strictly for floating elements that detach from the primary layout. This includes the Command Palette, dropdown menus, tooltips, and modal dialogs.
  • Visuals: It features a heavy 20px blur and a deeper, more diffuse shadow stack to physically "lift" it closer to the user.

Ambient Texture Application (The "Glow" Cards)

These classes override the standard .glass-surface to inject radial gradients. They should be used sparingly to create visual anchors and guide the user's eye.

• .card-insight (The Hero Glow)
  • When to use: Apply this only to the primary "Hero" card of a view (e.g., the "Daily Insight" or main overview brief).
  • Visuals: Injects a dual-tone purple and magenta ambient glow to create a premium, atmospheric anchor.
• .card-accent-glow (The Action Glow)
  • When to use: Use this for cards that require immediate primary user action, or to highlight a singular, highly important metric.
  • Visuals: Projects a subtle wash of the Cobalt accent colour from the top-center.
• .card-success-glow (The Positive State)
  • When to use: Apply dynamically when a bento card achieves a "completed" state (e.g., inbox zero, all tasks done).
  • Visuals: Projects a soft, organic Sage Green wash to calm the interface and signal positive feedback without relying on harsh alerts.