bible/rules/patterns/web-visual-baseline/contract.md

Contract: Web Visual Baseline

Version: 1.0

Scope

Defines the default visual baseline for future web applications in this ecosystem.

This is the single visual style for the ecosystem. The canonical reference files are vendored in this pattern:

• assets/view.css
• assets/view.html
• assets/upload.html

When a project does not already have an established design system, use this baseline by default. Copyable starter CSS and HTML live in README.md next to this contract.

Core Direction

• Prefer a clean, data-first interface over decorative marketing UI.
• Default to server-rendered HTML with simple CSS.
• Optimize for scanability, density, and operational clarity.
• Use restrained visual hierarchy, not novelty effects.
• Reuse the baseline directly when possible; copying the canonical CSS and adapting tokens is allowed.

Canonical Visual Language

• Dark application header on top.
• White page background and white content surfaces.
• Light secondary surfaces for headers and table heads.
• Thin gray borders with a subtle shadow.
• Small radii (4px).
• Dense but readable typography (14px/1.5 baseline).
• Blue accent in the #2185d0 family for primary actions and active accents.
• Tables and key-value layouts as the primary presentation pattern.
• Status communicated with both text and color.

Typography

• Use Lato, "Helvetica Neue", Arial, Helvetica, sans-serif unless a project has an approved alternative.
• Page titles are compact and strong, not oversized hero typography.
• Section titles should be clear and structural.
• Avoid display fonts, novelty fonts, and oversized marketing headings in application UI.

Layout Primitives

• page-header: dark global header with page title and compact actions.
• page-main: centered content area with generous outer margin and bounded max width.
• panel: white surface with border, light shadow, and simple heading strip.
• section-card: heading followed by table/content block.
• table-wrap: horizontal overflow container for dense data tables.

Preferred Components

• Key-value tables for singleton object/detail views.
• Dense data tables for repeated records.
• Compact upload/open panels when local file input is needed.
• Quiet header actions for secondary navigation.
• Clear primary buttons for the main action on a screen.
• Simple alert/error boxes with border + tinted background.

Status Rules

• OK: green
• Warning: amber
• Critical: red
• Unknown: gray
• Empty: light gray

Status must not rely on color alone. Show text or another explicit indicator together with the color treatment.

Responsive Rules

• Keep desktop density high.
• Collapse grids to one column on small screens.
• Preserve table readability with horizontal scrolling instead of destructive cardification by default.
• Header actions may wrap or stack on mobile, but should remain compact.

Forbidden Drift

• Do not default to glassmorphism, blurred shells, floating neon gradients, or soft-dribbble styling.
• Do not replace dense tables with oversized card grids when the data is inherently tabular.
• Do not introduce arbitrary color coding for non-status fields.
• Do not use oversized border radii, heavy shadows, or large empty spacing as the default application style.
• Do not import a SPA/dashboard aesthetic unless the product explicitly requires it.

Relationship To Other UI Contracts

• Use this contract as the visual baseline.
• Use table-management for shared table geometry and interaction seams.
• Use controls-selection for button hierarchy, filters, and bulk selection semantics.
• Pattern-specific contracts may override details only when they document the reason.