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

7.4 KiB

Contract: Web Visual Baseline

Version: 1.3

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. Copy assets/view.css as the starting stylesheet and adapt tokens; do not rewrite it from prose.

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.

Icons and Offline Assets

  • Use ready-made SVG icons from Lucide for new actions. Do not draw icon paths, generate pictograms with AI, or mix icon families within the same interface. Reuse the project's existing icon aliases and shared rendering helper.
  • Vendor the SVG geometry and its license in the source tree. Record the icon name and upstream source. Downloading an asset is a development step only.
  • Collect icons in one local SVG sprite of named symbol elements. Render them through one shared template/helper using svg and use; do not paste a new SVG body into each button or page. Preserve the library's geometry.
  • Use a 24 x 24 viewBox, fill="none", stroke="currentColor", stroke width 2, round line caps and joins. Size and color come from shared icon/button CSS.
  • An icon-only action needs both title and aria-label. Decorative SVGs have aria-hidden="true" and must not receive keyboard focus.
  • A button that has an icon shows only the icon. The action name lives in title and aria-label; do not put a text label next to the icon. Items of a popup menu (role="menuitem") keep their text, because the menu has no other way to tell them apart.
  • Modal footer actions use text labels without icons; modal header controls follow the shared modal-workflows contract.
  • One icon means one action across the whole interface. Restore, refresh, restart, connection test and similar actions each get their own distinct icon; never reuse one icon for a different action. Keep the action-to-icon table in the project documentation.
  • The stroke-only rule applies in every container, not only in .icon-btn: any other place that renders an icon (header button, status cell, badge) must set fill: none and stroke: currentColor as well. An SVG without them renders as a filled black blob.
  • Centre the icon in its button on both axes. Where a layout rule changes a button's display (for example to inline-flex inside a table cell), it must also set justify-content: center and align-items: center; otherwise the icon sticks to the left edge. An action column holds a fixed number of equal slots (an empty slot where an action does not apply), so icons do not shift from row to row.
  • An icon that depends on data (a status, a kind) is chosen on the server by one mapping function; the page and live refresh only print its name.
  • Embed all UI assets in the application binary: templates, scripts, styles, icons, fonts and any third-party UI code. Go applications use go:embed and serve these assets themselves. System fonts are allowed without downloads.
  • The application and its UI must start and work without access to public websites. No CDN, remote font, external icon service, package manager or separately installed UI library may be a runtime prerequisite. Explicit connections to configured application data sources are a separate concern.

Data Formatting

  • Money: no minor units (no cents/kopecks) — round to whole currency units for display. Group thousands with a non-breaking space ( ), not a comma or dot — e.g. $13 320, not $13,320.00. The ru-RU locale's own toLocaleString() grouping character is already a non-breaking space, so Math.round(value).toLocaleString('ru-RU') satisfies this directly without hand-rolled grouping logic.
  • Dates that only need day-level (not time-of-day) precision — a delivery ETA, a planning/reorder date — are shown as an ISO week number: W32. When a table row aggregates several dates that disagree (e.g. several purchase lots under one order with different ETAs), show the week range instead: W32-34. Audit-trail timestamps (created/updated-at) are exempt — show those as ordinary dates, since collapsing them to a week would hide the information they exist to convey.

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.