Skip to content

docs: redesign the site as a Blender viewport session #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TMHSDigital merged 1 commit into from
Jul 3, 2026
Merged

docs: redesign the site as a Blender viewport session #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 31 additions & 48 deletions docs/gallery/DESIGN_NOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,48 +1,31 @@
# Gallery design direction — prototype for the Option-2 fleet facelift

This local gallery (`docs/gallery/`, generated by `scripts/build_gallery.py` from
`examples/gallery.json`) is the **deliberate prototype** for the eventual shared-template
facelift tracked in [Developer-Tools-Directory#86](https://github.com/TMHSDigital/Developer-Tools-Directory/issues/86)
and the ROADMAP "Fleet Pages examples support" candidate. The markup here is throwaway on
migration; the **data** (`gallery.json`) and the **visual direction** below are what carry over.

## Tokens (aligned to the fleet landing page so the two never clash)

| Token | Dark | Light | Notes |
| --- | --- | --- | --- |
| `--bg` | `#0d1117` | `#f6f8fa` | matches landing's GitHub-dark base |
| `--surface` | `#161b22` | `#ffffff` | card background |
| `--surface-2` | `#1c2128` | `#f0f2f5` | toggle / inline code |
| `--border` | `#30363d` | `#d0d7de` | |
| `--text` | `#e6edf3` | `#1f2328` | |
| `--text-dim` | `#8b949e` | `#656d76` | secondary text |
| `--accent` / `--accent-light` | `#7c3aed` / `#a78bfa` | same | from `site.json`; shared with landing |
| `--radius` / `--radius-lg` | `8px` / `12px` | — | cards use `-lg` |
| font | `'Inter', system-ui…` | — | landing ships the Inter webfont; the prototype uses the same stack and falls back to system sans (no coupling to the fleet font files) |

## Type scale
- Page title `h1`: `clamp(1.9rem, 4vw, 2.6rem)`, `letter-spacing: -0.02em` — fluid hero.
- Card title `h2`: `1.22rem`.
- Body: `1rem` / `line-height: 1.6`; secondary `0.9rem`; tag `0.68rem` uppercase.

## Layout
- Container `max-width: 1080px`, centered, `1.25rem` side padding.
- Grid: **1 column** mobile → **2 columns at ≥720px**, `align-items: stretch` so paired cards share a row height.
- **Heroes are a uniform 16:9** (`aspect-ratio: 16/9; object-fit: cover`). This was a deliberate revision: the first cut used mixed aspects (8:3 swatch panorama + 16:9 stills) with `align-items: start`, which — confirmed by headless screenshots — left a ragged empty gap under the short card on desktop. The swatch hero was re-rendered at 16:9 so all three share an aspect; with uniform heroes `object-fit: cover` no longer crops anything. Keep new heroes 16:9.
- Card is a flex column; the "View example" link is pinned to the bottom (`margin-top: auto`) so footers align across a row. Hover lifts `-3px` with an accent-tinted border and soft shadow.

## Theme
- Tri-state **auto / light / dark** mirroring the landing: `data-theme` on `<html>`, persisted in `localStorage['theme']` — **the same key the landing uses**, so a visitor's choice carries across both pages.
- FOUC guard runs before first paint. `theme-color` meta per scheme. Toggle cycles auto→light→dark with a sun/moon glyph and an accurate `aria-label`.

## Navigation / discoverability
- The landing→gallery link is **template-blocked** (the landing nav is fleet-generated). The gallery compensates with self-sufficient outbound nav: a top-bar **back link to the landing** (`../`) and a **GitHub repo link**, plus per-card links to each example on GitHub. A visitor who arrives via the README or a direct link can always navigate out.

## Accessibility
- Skip-to-content link; `:focus-visible` outlines (accent, 2px); `prefers-reduced-motion` disables hover transform + smooth scroll; descriptive `alt` per hero ("`<name> — <what it teaches>`"); single `h1`, card titles as `h2`.

## What the fleet template should adopt (not the markup, the direction)
1. The token set above as CSS variables, light/dark parity with the existing landing palette.
2. An **Examples grid** section reading `gallery.json` (per-entry `name/dir/teaches/witnessesFix/hero/preview`), cards styled as here.
3. A **nav link to the gallery** (closes the landing→gallery cross-link gap — impossible today without a template edit).
4. Standardize heroes at **16:9** with `object-fit: cover` and `align-items: stretch` for an even grid; pin card footers (`margin-top: auto`). (Supersedes the first cut's mixed-aspect/`align-items: start` approach, which read as ragged — see Layout.)
# Site design — the Blender viewport system

The whole site (landing page `docs/index.html` via `scripts/site/`, gallery
`docs/gallery/` via `scripts/build_gallery.py`) shares one design system: the
site reads as a Blender viewport session. This replaced the earlier purple
fleet-template look (2026-07-03); the previous plan to upstream that look into
the shared template was dropped — the fleet template only scaffolds new tools,
and each tool's site evolves independently after that.

## Vocabulary

- **Conceit**: topbar = Blender's topbar, footer = its status bar, sections =
its panels (caret + mono label headers), hero = a viewport with a
perspective grid floor, red-X/green-Y origin lines, and HUD overlays in the
corners (mode, axis gizmo, statistics overlay with the pack counts, render
status `smoke-gated · exit 0`).
- **Color**: Blender panel grays (`#1a1b1e` bg, `#222327` panel, `#3a3b40`
border). ONE accent: selection orange `#ff8c19` (Blender's selected-object
outline; cards use it as a hover outline). Axis colors
`#ff3352 / #8bdc00 / #2890ff` appear only in the gizmo and grid origin
lines — they encode, never decorate. Dark only; there is no theme toggle.
- **Type**: Barlow Condensed 600 uppercase for display; Inter for body;
JetBrains Mono for every HUD label, stat, name, and chip. Fonts are
self-hosted in `scripts/site/fonts/` and deployed to `docs/fonts/` by the
landing build — gallery pages reference them at `../fonts/` / `../../fonts/`.
- **Copy**: benefit-led headers ("Every render here is a CI artifact"), the
smoke-gate claim is the headline thesis.

Keep both builders in this system when editing either; the tokens are
duplicated (template.html.j2 and build_gallery.py SHELL) — change them in
both places.
Loading
Loading