visuals: technology marks, area icons, client wall, two diagrams

Phase 7 (AUD-149), cheapest first.

- internal/brand: vendored Simple Icons path data (CC0) for 50 marks, looked up
  by the technology label the content already uses. Inline SVG, 16 px,
  currentColor, no request and no font. tools/gen_brand_icons.sh regenerates it.
- Six hand-drawn area icons replace the two-letter badges in the nav and on the
  landing cards; the evidence index gets a seventh.
- TechChips renders a mark where one exists and plain text where one does not,
  so a missing icon reads as a decision rather than a broken image.
- Client wall: 45 names as one typeface, one size, one grid of equal tiles, and
  the reason for no logo collage written on the page. No mark invented.
- Two diagrams, authored in-repo: homelab topology (platform-network.md) and
  the RAG pipeline (ai-rag-corpus.md), each referenced from the page it explains.
- Content images now carry intrinsic width/height, loading="lazy" and
  decoding="async" at render time; a site test fails the build if an image
  ships without them.
- Topbar is two rows at desktop: the area names plus marks no longer overlap the
  search form (Lighthouse target-size was failing at 1440 px).
- Favicon, so the browser stops requesting a missing /favicon.ico.

Satisfies: logos on every area page, area icons in nav and cards, two diagrams
referenced from their pages, images sized and lazy, Lighthouse >= 95 held.

(cherry picked from commit a473e4738a3751418c2097df2bcf0568fb6d0208)
This commit is contained in:
2026-10-28 15:50:08 +11:00
parent 59580b6e45
commit a76882de67
18 changed files with 914 additions and 51 deletions

90
internal/brand/brand.go Normal file
View File

@@ -0,0 +1,90 @@
// Package brand holds the small monochrome technology marks the site inlines
// beside a technology name.
//
// A mark is path data for a 24x24 viewBox, drawn with fill="currentColor" so it
// inherits the chip's colour and adds no request, no font and no layout shift.
// Marks are opt-in: a technology with no published mark renders as text alone,
// which is the honest default and keeps the chips from looking broken.
//
// The path data is vendored (see icons_gen.go and tools/gen_brand_icons.sh),
// not fetched at build or request time. The marks are trademarks of their
// owners and are used only to identify the technology named beside them.
package brand
import "strings"
// slugs maps a technology label, lowercased, to its Simple Icons slug. Labels
// are the ones the content uses; aliases point at the same mark.
var slugs = map[string]string{
"javascript": "javascript",
"php": "php",
"python": "python",
"home assistant": "homeassistant",
"raspberry pi": "raspberrypi",
"pi": "raspberrypi",
"nixos": "nixos",
"nix": "nixos",
"qdrant": "qdrant",
"prefect": "prefect",
"n8n": "n8n",
"mqtt": "mqtt",
"langgraph": "langgraph",
"langchain": "langchain",
"ffmpeg": "ffmpeg",
"zigbee": "zigbee",
"three.js": "threedotjs",
"react": "react",
"proxmox": "proxmox",
"mysql": "mysql",
"postgres": "postgresql",
"postgresql": "postgresql",
"caddy": "caddy",
"tailscale": "tailscale",
"neovim": "neovim",
"htmx": "htmx",
"go": "go",
"docker": "docker",
"compose": "docker",
"borg": "borgbackup",
"sqlite": "sqlite",
"spotify": "spotify",
"rabbitmq": "rabbitmq",
"openrouter": "openrouter",
"obsidian": "obsidian",
"niri": "niri",
"gitea": "gitea",
"ghostty": "ghostty",
"gemini": "googlegemini",
"deepseek": "deepseek",
"c++": "cplusplus",
"typescript": "typescript",
"zsh": "zsh",
"minimax": "minimax",
"esp32": "espressif",
"esp32-cam": "espressif",
"grafana": "grafana",
"wireguard": "wireguard",
"nginx": "nginx",
"linux": "linux",
"zig": "zig",
"huggingface": "huggingface",
"ollama": "ollama",
}
// Mark returns the path data for a technology label and whether one exists.
// The lookup is case-insensitive and tolerates the surrounding whitespace that
// hand-written front-matter tends to carry.
func Mark(label string) ([]string, bool) {
slug, ok := slugs[strings.ToLower(strings.TrimSpace(label))]
if !ok {
return nil, false
}
paths, ok := marks[slug]
return paths, ok
}
// Has reports whether a technology label has a published mark.
func Has(label string) bool {
_, ok := Mark(label)
return ok
}

160
internal/brand/icons_gen.go Normal file

File diff suppressed because one or more lines are too long

View File

@@ -37,22 +37,21 @@ type Area struct {
Title string
Role string
Blurb string
Gutter string // two-letter mark used by the nav and the stage panel
}
// Areas is the fixed navigation order from reference/content-map.md.
var Areas = []Area{
{Key: "ai", Title: "AI & Agentic Systems", Role: "AI / LLM Engineer", Gutter: "AI",
{Key: "ai", Title: "AI & Agentic Systems", Role: "AI / LLM Engineer",
Blurb: "Harnesses, subagents and skills, memory, model routing and cost, retrieval, voice, guardrails, agent observability."},
{Key: "platform", Title: "Platform & Infrastructure", Role: "Platform / DevOps Engineer", Gutter: "PL",
{Key: "platform", Title: "Platform & Infrastructure", Role: "Platform / DevOps Engineer",
Blurb: "Declarative hosts, packaging, a fifty-container Docker estate, networking, storage and restore-tested backups, observability."},
{Key: "edge", Title: "Edge & Devices", Role: "Edge / IoT Engineer", Gutter: "ED",
{Key: "edge", Title: "Edge & Devices", Role: "Edge / IoT Engineer",
Blurb: "Twenty-node fleet on constrained devices, custom radio, solar power, deep sleep, sensors and actuation — and the failures."},
{Key: "products", Title: "Products", Role: "", Gutter: "PR",
{Key: "products", Title: "Products", Role: "",
Blurb: "Three active businesses, built and run rather than advised on."},
{Key: "history", Title: "History", Role: "", Gutter: "HI",
{Key: "history", Title: "History", Role: "",
Blurb: "2000–2014: agencies, clients, engagements, and the code that survives from them."},
{Key: "about", Title: "About", Role: "", Gutter: "AB",
{Key: "about", Title: "About", Role: "",
Blurb: "The narrative, the non-IT work that came first, education, and how to get in touch."},
}

View File

@@ -4,9 +4,15 @@ import (
"bytes"
"fmt"
stdhtml "html"
"image"
_ "image/jpeg"
_ "image/png"
"io"
"os"
"path"
"path/filepath"
"regexp"
"strconv"
"strings"
"github.com/alecthomas/chroma/v2"
@@ -76,6 +82,7 @@ func (r *Renderer) Transform(doc *ast.Document, reader text.Reader, pc parser.Co
node.Destination = r.rewrite(current, string(node.Destination), false)
case *ast.Image:
node.Destination = r.rewrite(current, string(node.Destination), true)
r.sizeImage(current, node)
}
return ast.WalkContinue, nil
})
@@ -108,6 +115,70 @@ func (r *Renderer) rewrite(from *Document, dest string, image bool) []byte {
return []byte(dest)
}
// sizeImage records an image's intrinsic size and loading hints on the node, so
// the rendered page reserves the space before the file arrives. Without this the
// text jumps as each image lands, which is the most visible performance defect a
// page of diagrams can have.
//
// Only the four attributes in goldmark's image filter are used, and only when a
// real size is known: an unknown asset keeps the browser's own behaviour.
func (r *Renderer) sizeImage(from *Document, node *ast.Image) {
if r.set == nil || from == nil {
return
}
dest := string(node.Destination)
if strings.Contains(dest, "://") || strings.HasPrefix(dest, "data:") {
return
}
rel := dest
if strings.HasPrefix(rel, "/assets/") {
rel = "assets/" + strings.TrimPrefix(rel, "/assets/")
} else if i := strings.IndexAny(rel, "#?"); i >= 0 {
rel = rel[:i]
}
w, h, ok := imageSize(filepath.Join(r.set.Root, filepath.FromSlash(path.Clean(rel))))
if !ok {
return
}
node.SetAttributeString("width", []byte(strconv.Itoa(w)))
node.SetAttributeString("height", []byte(strconv.Itoa(h)))
node.SetAttributeString("loading", []byte("lazy"))
node.SetAttributeString("decoding", []byte("async"))
}
// svgSize reads width and height from the root element of an SVG. The diagrams
// in content/assets are authored in this repository with explicit dimensions,
// so a viewBox alone is not expected to occur.
var svgSizeRe = regexp.MustCompile(`<svg[^>]*\swidth="(\d+(?:\.\d+)?)(?:px)?"[^>]*\sheight="(\d+(?:\.\d+)?)(?:px)?"`)
// imageSize returns the intrinsic pixel size of a content asset.
func imageSize(abs string) (int, int, bool) {
f, err := os.Open(abs)
if err != nil {
return 0, 0, false
}
defer f.Close()
if strings.HasSuffix(strings.ToLower(abs), ".svg") {
head := make([]byte, 4096)
n, _ := f.Read(head)
m := svgSizeRe.FindSubmatch(head[:n])
if m == nil {
return 0, 0, false
}
w, err1 := strconv.ParseFloat(string(m[1]), 64)
h, err2 := strconv.ParseFloat(string(m[2]), 64)
if err1 != nil || err2 != nil || w <= 0 || h <= 0 {
return 0, 0, false
}
return int(w + 0.5), int(h + 0.5), true
}
cfg, _, err := image.DecodeConfig(f)
if err != nil || cfg.Width <= 0 || cfg.Height <= 0 {
return 0, 0, false
}
return cfg.Width, cfg.Height, true
}
// docKey carries the document being rendered through the parser context so
// the link rewriter knows what "relative" means.
var docKey = parser.NewContextKey()

View File

@@ -59,7 +59,7 @@ func (Shell) Nav(area string) []templates.NavItem {
items = append(items, templates.NavItem{
Title: a.Title,
Href: "/" + a.Key + "/",
Gutter: a.Gutter,
Area: a.Key,
Current: a.Key == area,
})
}

View File

@@ -263,3 +263,35 @@ func TestSearchIndexFollowsContent(t *testing.T) {
t.Errorf("token found at %s, want /edge/edge-fleet/", results[0].URL)
}
}
// TestImagesReserveTheirSpace is the layout-shift guard: every image a content
// page carries must declare its intrinsic size and load lazily, so a page of
// diagrams and screenshots never reflows as the files arrive.
func TestImagesReserveTheirSpace(t *testing.T) {
s := newSite(t)
seen := 0
for _, d := range s.Content.Docs {
html := d.HTML
for i := 0; ; i++ {
start := strings.Index(html, "<img ")
if start < 0 {
break
}
end := strings.Index(html[start:], ">")
if end < 0 {
break
}
tag := html[start : start+end+1]
html = html[start+end+1:]
seen++
for _, want := range []string{`width="`, `height="`, `loading="lazy"`, `alt="`} {
if !strings.Contains(tag, want) {
t.Errorf("%s: image tag missing %s: %s", d.Path, want, tag)
}
}
}
}
if seen == 0 {
t.Fatal("no images found in content; the guard is not exercising anything")
}
}

View File

@@ -0,0 +1,6 @@
<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
<rect width="32" height="32" rx="7" fill="#0b0d10"/>
<rect x="0.75" y="0.75" width="30.5" height="30.5" rx="6.25" fill="none" stroke="#33404d" stroke-width="1.5"/>
<path d="M11.2 22.2c-1.9-.5-3-1.7-3-3.5h2.6c0 .9.5 1.4 1.5 1.6.9.2 1.6 0 1.8-.6.2-.6-.2-1-.9-1.2l-2-.4c-2-.4-3-1.4-3-3 0-2 1.6-3.3 4.1-3.4v-1.9h1.9v1.9c2 .2 3.1 1.4 3.2 3.2h-2.6c-.1-.8-.6-1.2-1.4-1.3-.8-.1-1.4.2-1.4.7-.1.5.3.8 1 .9l2 .4c2 .4 3 1.5 3 3.2 0 2.1-1.7 3.4-4.2 3.5v1.9h-1.9z" fill="#6ee7c6"/>
<path d="M19.6 10.3h4.9c1.9 0 3.1 1.1 3.1 2.8 0 1.1-.5 1.9-1.4 2.3 1.1.3 1.7 1.2 1.7 2.5v1.9h-2.6v-1.6c0-.9-.4-1.3-1.3-1.3h-1.8v-2.3h1.5c.7 0 1.1-.3 1.1-.9s-.4-.9-1.1-.9h-1.5z" fill="#b3bcc8"/>
</svg>

After

Width:  |  Height:  |  Size: 761 B

View File

@@ -151,13 +151,22 @@ samp {
/* ---- chrome ------------------------------------------------------------ */
/*
Two rows: the name and the search on the first, the six areas plus the index
on the second. The area names are long and the marks made them longer, so a
single row either overlapped the search form or scrolled the nav out of
reach. Two rows give every link a real target at every width.
*/
.topbar {
position: sticky;
top: 0;
z-index: 20;
display: grid;
grid-template-columns: var(--nav-w) minmax(0, 1fr) auto;
gap: var(--pad);
grid-template-columns: var(--nav-w) minmax(0, 1fr);
grid-template-areas:
"brand search"
"nav nav";
gap: 0.5rem var(--pad);
align-items: center;
padding: 0.7rem var(--pad);
background: color-mix(in srgb, var(--bg) 92%, transparent);
@@ -165,6 +174,21 @@ samp {
border-bottom: 1px solid var(--line);
}
.brand {
grid-area: brand;
}
.nav-search {
grid-area: search;
justify-self: end;
width: min(28rem, 100%);
}
.nav-rail {
grid-area: nav;
min-width: 0;
}
.brand {
display: flex;
align-items: center;
@@ -241,17 +265,25 @@ samp {
box-shadow: inset 0 -2px 0 var(--accent);
}
.nav-gutter {
font-family: var(--font-mono);
font-size: 0.68rem;
letter-spacing: 0.08em;
/* The area mark replaces the old two-letter badge. It is decoration; the nav
label beside it is the accessible name. */
.nav-mark {
display: inline-flex;
align-items: center;
color: var(--text-muted);
}
.nav-current .nav-gutter {
.nav-link:hover .nav-mark,
.nav-current .nav-mark {
color: var(--accent);
}
.area-icon {
display: block;
width: 20px;
height: 20px;
}
/* ---- shell ------------------------------------------------------------- */
.shell {
@@ -564,8 +596,9 @@ samp {
color: var(--text-muted);
}
.pillar-gutter {
font-family: var(--font-mono);
.pillar-mark {
display: inline-flex;
align-items: center;
color: var(--accent);
}
@@ -600,6 +633,11 @@ samp {
color: var(--text-muted);
}
.pillar-go {
font-weight: 600;
border-bottom: 0;
}
.pillar-count {
font-family: var(--font-mono);
font-size: 0.74rem;
@@ -644,8 +682,11 @@ samp {
list-style: none;
}
.tech li {
padding: 0.12rem 0.45rem;
.tech-chip {
display: inline-flex;
align-items: center;
gap: 0.35rem;
padding: 0.14rem 0.45rem;
border: 1px solid var(--line);
border-radius: var(--radius-sm);
font-family: var(--font-mono);
@@ -653,6 +694,67 @@ samp {
color: var(--text-dim);
}
/* Monochrome and currentColor, so the chip and the mark share one colour and
no icon ever adds a request. */
.tech-mark {
display: block;
flex: none;
width: 16px;
height: 16px;
fill: currentColor;
opacity: 0.85;
}
.tech-chip:hover {
border-color: var(--line-strong);
color: var(--text);
}
.tech-chip:hover .tech-mark {
opacity: 1;
}
/* ---- client wall ------------------------------------------------------- */
/*
One typeface, one size, one tile. Mixed brand marks would read as broken;
a consistent grid reads as deliberate. Tiles are the same height whatever
the length of the name, so the wall never looks like a failed image load.
*/
.client-wall {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(10.5rem, 1fr));
gap: 1px;
margin: 1rem 0 1.6rem;
padding: 1px;
background: var(--line);
border: 1px solid var(--line);
border-radius: var(--radius-sm);
overflow: hidden;
list-style: none;
}
.client-tile {
display: flex;
align-items: center;
justify-content: center;
min-height: 4.2rem;
padding: 0.6rem 0.75rem;
background: var(--surface);
text-align: center;
}
.client-name {
font-size: 0.88rem;
line-height: 1.25;
letter-spacing: 0.01em;
color: var(--text-dim);
text-wrap: balance;
}
.client-tile:hover .client-name {
color: var(--text);
}
.doc-head {
padding-bottom: 1.1rem;
border-bottom: 1px solid var(--line);

View File

@@ -17,6 +17,7 @@ templ Layout(v LayoutView) {
<title>{ v.Title }</title>
<meta name="description" content={ v.Description }/>
<meta name="color-scheme" content="dark"/>
<link rel="icon" href="/static/favicon.svg" type="image/svg+xml"/>
<link rel="stylesheet" href="/static/site.css"/>
<link rel="stylesheet" href="/static/chroma.css"/>
<script src="/static/htmx.min.js" defer></script>
@@ -68,7 +69,8 @@ templ Nav(items []NavItem, current string) {
templ navLinks(items []NavItem, current string) {
for _, it := range items {
<a href={ templ.SafeURL(it.Href) } class={ navClass(it) } aria-current={ currentAttr(it) }>
<span class="nav-gutter" aria-hidden="true">{ it.Gutter }</span>
<span class="nav-mark">@AreaIcon(it.Area)
</span>
<span class="nav-title">{ it.Title }</span>
</a>
}
@@ -76,7 +78,8 @@ templ navLinks(items []NavItem, current string) {
templ evidenceLink(current string) {
<a href="/evidence/" class={ navClassFor(current == "evidence") }>
<span class="nav-gutter" aria-hidden="true">EV</span>
<span class="nav-mark">@AreaIcon("evidence")
</span>
<span class="nav-title">Evidence index</span>
</a>
}
@@ -178,7 +181,8 @@ templ FragmentView(f stage.Fragment) {
</header>
switch f.Kind {
case stage.KindText:
<div class="frag-text">@f.Body</div>
<div class="frag-text">@f.Body
</div>
case stage.KindCode:
if f.Code != nil {
<figure class="code">
@@ -263,7 +267,8 @@ templ EvidenceTable(rows []EvidenceRow) {
templ PillarCard(c PillarCardView) {
<article class="pillar">
<p class="pillar-kicker">
<span class="pillar-gutter" aria-hidden="true">{ c.Area.Gutter }</span>
<span class="pillar-mark">@AreaIcon(c.Area.Key)
</span>
if c.Area.Role != "" {
<span>{ c.Area.Role }</span>
}
@@ -283,11 +288,7 @@ templ PillarCard(c PillarCardView) {
</ul>
}
if len(c.Tech) > 0 {
<ul class="tech" aria-label="Technology">
for _, t := range c.Tech {
<li>{ t }</li>
}
</ul>
@TechChips(c.Tech)
}
<p class="pillar-foot">
<span class="pillar-count">{ strconv.Itoa(c.Pages) } pages</span>

View File

@@ -0,0 +1,67 @@
package templates
import "gitea.lab.audasmedia.com.au/sam/ai-resume/internal/brand"
// AreaIcon is the mark for one area of the site. The six marks are drawn here,
// geometrically, in one visual language: 24x24, 1.6 px stroke, round caps, no
// fill, colour inherited from the text. They are decoration only — the label
// beside them carries the meaning — so every one is aria-hidden.
//
// "evidence" is the seventh mark: the index, not an area.
templ AreaIcon(area string) {
<svg class="area-icon" viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
switch area {
case "ai":
<circle cx="5.5" cy="6.5" r="2.5"/>
<circle cx="18.5" cy="6.5" r="2.5"/>
<circle cx="12" cy="17.5" r="2.5"/>
<path d="M8 6.5h8"/>
<path d="M6.7 8.8 10.8 15.6"/>
<path d="M17.3 8.8 13.2 15.6"/>
case "platform":
<rect x="3.5" y="3.5" width="17" height="4.6" rx="1.5"/>
<rect x="3.5" y="9.7" width="17" height="4.6" rx="1.5"/>
<rect x="3.5" y="15.9" width="17" height="4.6" rx="1.5"/>
<path d="M7 5.8h2M7 12h2M7 18.2h2"/>
case "edge":
<rect x="2.5" y="13" width="9" height="8" rx="1.5"/>
<circle cx="7" cy="17" r="1.6"/>
<path d="M15 11.5a3.5 3.5 0 0 1-3.5 3.5"/>
<path d="M18 11.5a6.5 6.5 0 0 1-6.5 6.5"/>
case "products":
<path d="M12 3.2 19 7.3v9.4L12 20.8 5 16.7V7.3z"/>
<path d="M5 7.3l7 4.1 7-4.1"/>
<path d="M12 11.4v9.4"/>
case "history":
<circle cx="12" cy="12" r="8.5"/>
<path d="M12 7v5.2l3.4 2.1"/>
case "about":
<circle cx="12" cy="8.4" r="3.6"/>
<path d="M5.4 20a6.6 6.6 0 0 1 13.2 0"/>
case "evidence":
<path d="M6.8 3.4h7.2l4 4v13.2H6.8z"/>
<path d="M14 3.4v4h4"/>
<path d="M9.6 14.2l2 2 3.6-4.1"/>
}
</svg>
}
// TechChips is the technology list on a page. A chip carries a published mark
// when one exists and plain text when it does not, so a missing icon reads as a
// design decision rather than a broken image.
templ TechChips(items []string) {
<ul class="tech" aria-label="Technology">
for _, t := range items {
<li class="tech-chip">
if paths, ok := brand.Mark(t); ok {
<svg class="tech-mark" viewBox="0 0 24 24" width="16" height="16" aria-hidden="true" focusable="false">
for _, d := range paths {
<path d={ d } fill="currentColor"/>
}
</svg>
}
<span>{ t }</span>
</li>
}
</ul>
}

View File

@@ -17,7 +17,6 @@ templ HomePage(v HomeView) {
</p>
@SearchForm("", "hero-search")
</section>
<section class="pillars" aria-label="Six areas">
for _, c := range v.Cards {
@PillarCard(c)
@@ -46,14 +45,9 @@ templ DocPage(v DocView) {
}
</div>
if len(v.Tech) > 0 {
<ul class="tech" aria-label="Technology">
for _, t := range v.Tech {
<li>{ t }</li>
}
</ul>
@TechChips(v.Tech)
}
</header>
<div class="prose">
@v.Body
</div>
@@ -97,7 +91,6 @@ templ DocPage(v DocView) {
</ul>
</section>
}
<footer class="doc-foot">
<p>Last verified { v.Doc.LastVerified } · <code>content/{ v.Doc.Path }</code></p>
</footer>
@@ -207,15 +200,21 @@ templ StreamPage(v StreamView) {
<p class="doc-claim">This page renders the same layout and the same panel as every other page. Its panel is bound to an event stream instead of pre-rendered files, and no layout code changed.</p>
</header>
<div class="prose">
<p>The presentation panel is a content sink. In Mode A it takes pre-rendered fragments over
<p>
The presentation panel is a content sink. In Mode A it takes pre-rendered fragments over
HTMX: you click a row in an evidence table and one file is swapped in. On this page the same
panel is bound to <code>/api/stage/stream</code> and receives { strconv.Itoa(v.Frames) } fragments
over server-sent events, one after another.</p>
<p>Fragments are pushed, not requested. Nothing about the panel — its markup, its fragment
over server-sent events, one after another.
</p>
<p>
Fragments are pushed, not requested. Nothing about the panel — its markup, its fragment
view, its empty state — knows the difference. That is the point: the Phase 5 console
re-points this panel at retrieval output and the layout does not change.</p>
<p class="section-note">This demonstration streams the artefacts already built for the site, with
no model in the loop. It exists to prove the transport, not to pretend an AI is answering.</p>
re-points this panel at retrieval output and the layout does not change.
</p>
<p class="section-note">
This demonstration streams the artefacts already built for the site, with
no model in the loop. It exists to prove the transport, not to pretend an AI is answering.
</p>
</div>
if len(v.Fragment) > 0 {
<section class="doc-sub">

View File

@@ -23,7 +23,7 @@ import (
type NavItem struct {
Title string
Href string
Gutter string
Area string
Current bool
}