homelab/apps/web/DESIGN.md

Design System Documentation: The Tactical Monolith

1. Overview & Creative North Star

Creative North Star: The Tactical Monolith

This design system is built to evoke the sensation of interacting with a high-clearance orbital research terminal. Inspired by the brutalist, data-heavy aesthetic of Marathon and the high-fidelity grit of neon-punk, this system rejects "soft" modernism in favor of Authoritative Utility.

We achieve a premium feel not through decoration, but through extreme precision. The design breaks the "template" look by utilizing a strict 0px border-radius across all elements, creating a sense of indestructible, industrial hardware. We leverage intentional asymmetry—placing heavy data blocks against expansive voids—and high-contrast typography scales to ensure the UI feels like a functional tool rather than a marketing site.

---

2. Colors & Surface Architecture

The palette is rooted in deep obsidian (surface) and punctuated by high-frequency neons.

The "No-Line" Rule

Standard 1px borders are strictly prohibited for sectioning. Structural boundaries must be defined solely through:

1. Tonal Shifts: Placing a surface_container_low section against a surface background.
2. Color Blocking: Using a high-contrast primary or secondary block to terminate a layout section.

Surface Hierarchy & Nesting

Treat the interface as a physical stack of hardware modules.

• Base Layer: surface (#0b0f10) or surface_container_lowest (#000000) for the deep background.
• Module Layer: Use surface_container (#151a1c) for primary content areas.
• Active Layer: Use surface_bright (#272d2f) for interactive or elevated data modules. Each inner container should be at least one tier higher or lower than its parent to define its importance without needing a stroke.

The "Glass & Gradient" Rule

To add "soul" to the utilitarian grid, use Glassmorphism for floating HUD elements. Apply surface_container_high at 60% opacity with a backdrop-filter: blur(20px). Signature Textures: Incorporate subtle linear gradients (e.g., primary to primary_container) on hero CTAs to simulate the glow of a phosphor monitor.

---

3. Typography: The Industrial Voice

The typography is a dialogue between two distinct voices: the Command Voice (Space Grotesk) and the Data Stream (Inter).

• Display & Headlines (Space Grotesk): These should feel massive and structural. Use display-lg for hero statements, ensuring tight letter-spacing (-0.02em) to mimic industrial stamping.
• Body & Titles (Inter): High-readability sans-serif for technical descriptions.
• Labels (Space Grotesk): All-caps monospaced-style accents used for metadata, status indicators, and micro-copy.
• Hierarchy as Identity: Use a dramatic scale jump between display-lg and label-sm to create a "technical blueprint" feel. Titles should often be accompanied by a label-sm prefix (e.g., "01 // ARCHIVE") to reinforce the lab aesthetic.

---

4. Elevation & Depth: Tonal Layering

In a world of 0px radius and dark mode, depth is created through light and atmosphere, not shadows.

• The Layering Principle: Avoid "drop shadows" on cards. Instead, stack surface_container_highest on top of surface_container_low. The contrast in luminosity provides the "lift."
• Ambient Shadows: If a floating element (like a modal) requires a shadow, use a large, 64px blur with 8% opacity using the primary color (#aaffdc) to create a "neon glow" rather than a grey shadow.
• The "Ghost Border" Fallback: For input fields or secondary containers, use a "Ghost Border": the outline_variant token at 15% opacity. This provides just enough definition for accessibility without breaking the monolithic aesthetic.
• Atmospheric Layers: Overlay a 2px scanline pattern (linear-gradient) at 3% opacity over the entire viewport to simulate a CRT terminal.

---

5. Components

Buttons

• Primary: Solid primary background with on_primary text. 0px radius. Hover state: primary_dim with a 1px "glitch" offset (shift the button 2px right/down).
• Secondary: Ghost style. outline color at 20% opacity for the border. On hover, fills with secondary (#ff51fa) and shifts text to on_secondary.
• Tertiary: Text only in tertiary (#f3ffca), prefixed with a geometric icon (e.g., [>]).

Chips (Data Tags)

• Used for status (e.g., "STABLE", "ERROR").
• Style: Solid surface_container_highest background, label-sm typography. Status-specific accents use error (#ff716c) or primary.

Lists & Data Grids

• Forbid Divider Lines. Separate list items using the spacing scale (e.g., spacing.4 gap) or alternating backgrounds (surface_container_low vs surface_container_highest).
• Include a label-sm timestamp or hex-code for every list item to maintain the lab aesthetic.

Input Fields

• Text Inputs: Rectangular, surface_container_low background.
• Indicator: A 2px vertical bar of primary on the left side of the input to indicate focus, rather than a full-box outline.
• Helper Text: Use label-sm in on_surface_variant.

Tooltips

• High-contrast: tertiary (#f3ffca) background with on_tertiary text.
• 0px radius. Appears instantly (no fade) to mimic terminal responsiveness.

---

6. Do's and Don'ts

Do:

• Do use the Spacing Scale strictly. Gaps should feel intentional and rhythmic.
• Do use "UI Glitches" (chromatic aberration or slight element offsets) sparingly on hover states or page transitions.
• Do use bold, geometric iconography (strokes of 2px+) that aligns with the 0px corner logic.
• Do leverage the secondary magenta and tertiary lime for critical alerts and "live" data streams.

Don't:

• Don't use a border-radius > 0px. Ever.
• Don't use standard "web safe" blue for links. Use primary (cyan) or secondary (magenta).
• Don't use soft transitions. Prefer "hard" cuts or rapid 150ms linear eases to maintain a technical, high-performance feel.
• Don't center-align long-form text. Keep everything left-aligned to a rigid grid to maintain the "log file" aesthetic.

Accessibility Note:

While we utilize high-contrast neons, ensure that all on_surface text maintains at least a 4.5:1 contrast ratio against its respective surface_container. When using neons like tertiary for background elements, always use the dedicated on_tertiary (#516700) for text to ensure legibility.