155 lines
7.4 KiB
Markdown
155 lines
7.4 KiB
Markdown
# 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.
|