mchus/bible
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add chart-based web visual baseline contract

Browse Source
This commit is contained in:
Michael Chus
2026-04-22 20:52:14 +03:00
parent 472b3e10d9
commit d2600f1279
2 changed files with 304 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
rules/patterns/web-visual-baseline/contract.md Normal file
View File

@@ -0,0 +1,302 @@
# Contract: Web Visual Baseline
Version: 1.0
## Scope
Defines the default visual baseline for future web applications in this ecosystem.
The canonical reference is the UI style from:
- `/Users/mchusavitin/Documents/git/chart/web/static/view.css`
- `/Users/mchusavitin/Documents/git/chart/web/templates/view.html`
- `/Users/mchusavitin/Documents/git/chart/web/templates/upload.html`
When a project does not already have an established design system, use this baseline by default.
## 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.
## Copyable Starter CSS
Use this as the default starting point for new web apps:
```css
:root {
--bg: #ffffff;
--surface: #ffffff;
--surface-2: #f9fafb;
--border: rgba(34, 36, 38, 0.15);
--border-lite: rgba(34, 36, 38, 0.1);
--ink: rgba(0, 0, 0, 0.87);
--muted: rgba(0, 0, 0, 0.6);
--accent: #2185d0;
--accent-dark: #1678c2;
--accent-bg: #dff0ff;
--ok: #16ab39;
--warn: #f2711c;
--crit: #db2828;
--header-bg: #1b1c1d;
--radius: 4px;
--shadow: 0 1px 2px 0 rgba(34, 36, 38, 0.15);
--content-width: 1500px;
}
* {
box-sizing: border-box;
}
body {
margin: 0;
background: var(--bg);
color: var(--ink);
font: 14px/1.5 Lato, "Helvetica Neue", Arial, Helvetica, sans-serif;
}
.page-header {
display: flex;
align-items: center;
justify-content: space-between;
gap: 16px;
padding: 14px 24px;
background: var(--header-bg);
}
.page-header h1 {
margin: 0;
font-size: 18px;
font-weight: 700;
color: rgba(255, 255, 255, 0.9);
}
.page-main {
width: min(var(--content-width), calc(100vw - 48px));
margin: 28px auto 56px;
}
.panel {
margin-bottom: 28px;
overflow: hidden;
background: var(--surface);
border: 1px solid var(--border);
border-radius: var(--radius);
box-shadow: var(--shadow);
}
.panel > h2 {
margin: 0;
padding: 13px 16px;
background: var(--surface-2);
border-bottom: 1px solid var(--border);
font-size: 13px;
font-weight: 700;
}
.table-wrap {
overflow-x: auto;
}
.kv-table,
.data-table {
width: 100%;
border-collapse: collapse;
background: var(--surface);
}
.kv-table th,
.kv-table td,
.data-table th,
.data-table td {
padding: 11px 14px;
text-align: left;
vertical-align: top;
border-top: 1px solid var(--border-lite);
}
.kv-table th,
.data-table th {
background: var(--surface-2);
border-top: 0;
border-bottom: 1px solid var(--border-lite);
font-weight: 700;
white-space: nowrap;
}
.data-table tbody tr:hover {
background: rgba(0, 0, 0, 0.04);
}
.button-primary {
display: inline-block;
padding: 8px 18px;
border: none;
border-radius: var(--radius);
background: var(--accent);
color: #fff;
font: inherit;
font-weight: 700;
text-decoration: none;
cursor: pointer;
}
.button-primary:hover {
background: var(--accent-dark);
}
.header-action {
display: inline-block;
padding: 6px 14px;
border-radius: var(--radius);
background: rgba(255, 255, 255, 0.12);
color: rgba(255, 255, 255, 0.85);
text-decoration: none;
font-size: 13px;
font-weight: 700;
}
.header-action:hover {
background: rgba(255, 255, 255, 0.2);
}
.status-ok { color: var(--ok); }
.status-warning { color: var(--warn); }
.status-critical { color: var(--crit); }
.status-unknown { color: rgba(0, 0, 0, 0.45); }
@media (max-width: 720px) {
.page-header {
flex-direction: column;
padding: 12px 16px;
}
.page-main {
width: calc(100vw - 24px);
margin-top: 20px;
}
}
```
## Copyable Starter HTML
```html
<header class="page-header">
<h1>Application Title</h1>
<a class="header-action" href="/back">Back</a>
</header>
<main class="page-main">
<section class="panel">
<h2>Overview</h2>
<div class="table-wrap">
<table class="kv-table">
<tbody>
<tr>
<th>Host</th>
<td>server-01</td>
</tr>
<tr>
<th>Status</th>
<td><span class="status-ok">OK</span></td>
</tr>
</tbody>
</table>
</div>
</section>
<section class="panel">
<h2>Devices</h2>
<div class="table-wrap">
<table class="data-table">
<thead>
<tr>
<th>Name</th>
<th>Vendor</th>
<th>Status</th>
</tr>
</thead>
<tbody>
<tr>
<td>NIC 1</td>
<td>Intel</td>
<td><span class="status-warning">Warning</span></td>
</tr>
</tbody>
</table>
</div>
</section>
</main>
```