In-app gallery and technical docs
The Nuxt app exposes two browse hubs that share the same URL state (useBrowseQuery): a root page, a grid, and filter / group controls. Docs (and /code) use the browse toolbar; the gallery folds its controls into one floating menu.
| Route | Role | Chrome |
|---|---|---|
/gallery |
Full-screen social-style gallery (reels, stills, code, diagrams) | Primary nav label Gallery; own full-bleed gallery layout |
/docs |
Technical documentation sourced from the repo docs/ markdown tree |
Work sub-nav (AppWorkSubNav) — not in AppPrimaryNav |
/docs/... |
Individual spec / runbook rendered from that markdown | Linked from the docs catalog; Work sub-nav stays on Work pages only |
Public primary rail is About / Work / Gallery / Code / Writing. Docs, AI Lab (/ai-lab), and Process (/process) live under Work — see portfolio-august-launch.md.
Browse toolbar (AppBrowseToolbar)
Docs and /code share one toolbar (the gallery’s controls live in its menu; see Gallery):
- One control per facet — a segmented group (View · Group · Filter, the facets a page passes) on wide screens; at the tablet breakpoint and below, Group and Filter become labelled native
<select>s (44px, the OS picker on touch, “Label · count” options) laid out in an even grid. CSS shows exactly one control per facet at each width, so screen readers never meet a duplicate, and the toolbar’sminmax(0, 1fr)track keeps it from pushing the page sideways./codeuses the same toolbar, and its snippet tabs become a labelled picker with ‹ › buttons on narrow screens. The old mobile<select>swap is gone, so each facet has exactly one control at every width. - Snippet tabs (
/code) —/codeswitches between its snippet tabs and the picker with a container query on the page (tabs only when the page is ≥ 48rem wide), so a 768px tablet keeps the picker. (The toolbar’s one-rowinlineprop was removed with the gallery redesign; its styles are archived.) - Counts — each Group / Filter option shows how many items it would show given the other facet (
count); options at0are disabled unless selected. - Status line — “Showing N of M posts/documents” in an
aria-live="polite"region, plus Clear filters when a filter or the search text is set (changing only the view does not count). - Search — Docs shows a labelled Search field (was “Query”).
- URL state — pages bind the toolbar through
useBrowseQuery()(app/composables/useBrowseQuery.ts, a thinuseRouteQueryState(browseCodec, …)from@tgmc/nuxt-layer-uithat also follows back / forward and same-path links), which reads/writesview,group,kindandq(plusitemandsorton pages whose defaults define them:/code’sitemis the selected snippet; the gallery menu uses the same composable, itssortdefaults tonewestand is never a filter) withrouter.replace(shareable, Back-safe, no extra history). Other query keys such as Gallery’sspecimenare preserved.app/app.vuekeysNuxtPagewithpageKeyFor()(full path minus these keys), so filter changes update the page in place instead of remounting it — focus stays in Search (or the gallery menu). Pure helpers:core/web/shared/browse-query.ts(readBrowseQuery,writeBrowseQuery,isFiltered).
Page fit: /docs uses the prose fit (data-fit="prose"); /code uses the fluid fit (data-fit="fluid", the viewport width inside the page padding) with the toolbar’s Package facet plus item for the selected snippet. The gallery is full bleed in its own layout (below).
Gallery
/gallery should feel like a social media app: edge-to-edge pieces at their real shape, and one tap to a full-screen view that is also the feed. Spec: docs/superpowers/specs/2026-10-19-gallery-redesign-design.md.
Content lives in core/web/content/gallery.json (Nuxt Content gallery collection). Posts are flattened from categories (flattenGalleryPosts); each may carry date (ISO), caseStudy (a site path) and source (a public-repo link built with core/web/shared/public-repo.ts).
When adding posts, run node scripts/gallery-dates.js --write. It fills each missing date with the first git commit date of the post’s media file (exhibit.src, else exhibit.poster, else image) under core/web/public, or with a placeholder (2026-01-01 minus category index x 30 + item index days) when there is no tracked file, so builds on Lambda / S3 never read files. Replace any date by editing the JSON.
- Layout —
app/layouts/gallery.vue+gallery.scss(definePageMeta({ layout: 'gallery' })): no site header, footer, breadcrumb orAppDepthField; a skip link tomain#gallery_main;AppPersonalizestays mounted for the menu’s Personalize. The page is a full-bleed block (.gallery-page, no gutter); itsh1(the hero title) is sr-only. Details: project structure. - Menu —
GalleryMenu(app/components/gallery/GalleryMenu.vue): one floating icon button top-right (“Gallery menu”,aria-expanded; a dot plus sr-only “filters active” when a filter is set). It opens a glass panel (glass-overlay): a right side panel in landscape from the tablet breakpoint ((orientation: landscape) and (min-width: 48em)), else a panel from the top; both scroll inside themselves (400 % zoom). Top to bottom: the title “Gallery” and the count (“N posts”, or “N of M posts” when filtered, polite); Back (the previous in-app page fromhistory.state.back, else Home), Home and the site links; Play feed (the full view at the first visible piece; disabled when nothing matches); Group, Filter and Sort (“Label · count” options,0disabled unless selected; aUiSelectButtonchip group each with a fine pointer, labelled native<select>s under(pointer: coarse)) and Clear filters; Personalize; the social links; Get in touch (mailto). A non-modal disclosure: Esc or the close button returns focus to the menu button; an outside click or tabbing out of the panel closes it, so focus never sits under the panel. When the full view opens over it (browser Forward to?item=), the panel closes without taking focus and leaves Esc to the viewer (suspended). The hero, the browse toolbar, the Grid / Feed view control, the feed cards (GalleryFeedCard) and the bottom contact CTA are gone (styles archived undertheme/core/scss/_archive/2026-10-19-gallery-redesign/). - Grid and previews —
GalleryGrid(app/components/gallery/GalleryGrid.vue): edge-to-edge justified rows (justifyRows,core/web/shared/gallery-justify.ts). Each tile keeps its ratio (galleryRatio), each full row fills the width exactly (0.25rem gaps; widths floored to 1/64 px) and the last row keeps the target height. Target row height by grid width: 12rem below 30em, 15rem below 64em, 18rem below 120em, else 20rem. Before measurement (SSR, first paint) tiles wrap with flex-grow by ratio. Each tile is one button named “title, kind, platform” (the visible title and tags show on hover / focus) with an inset focus ring;?specimen=<id>marks and focuses a tile. Silent previews (video tiles only; never under reduced motion, never while the full view is open): with a mouse or trackpad on hover and on keyboard focus; on touch devices ((hover: none)) one tile at a time, the first video tile in grid order that is at least half in view, and only on a fast connection (useGalleryPreview:navigator.connectioneffectiveType: '4g'ortype: 'wifi', and nosaveData; unknown counts as slow). An empty filter shows “Nothing matches the filter …” with Clear filters, which moves focus to the first tile once the tiles are back. Tiles fetch their photos at the post’s own ratio, sized from the tallest row and the measured rem. - Sort — Newest (default), Oldest, A–Z, Z–A (
GALLERY_SORTS,sortGalleryPosts). It lives in?sort=(newestis omitted; an unknown value reads as newest) and never counts as a filter. - Full view = the feed —
GalleryViewer(app/components/gallery/GalleryViewer.vue): a tile, the menu’s Play feed and a?item=<id>link all open one piece at a time over a blurred copy of its own colours, in the grid’s order (filter + sort), never wrapping. A modal dialog named by the post title and described by its position (inert background, body scroll locked); the grid stays mounted under it with its previews suspended (suspended). Previous / Next buttons (disabled at the ends), Up / Down / Page Up / Page Down (left to a focused code block, video or field, and to a focused scroll box while it can still scroll that way: the details body and an overflowing diagram or text piece become focusable regions when they overflow, WCAG 2.1.1), and a vertical touch / pen swipe (≥ 15 % of the viewport height or a fast flick; never a mouse drag, which selects text, nor one starting in code or with a selection;touch-action: pan-x,overscroll-behavior: contain) move between pieces, and the position (“3 of 15”) is announced politely on each move or filter change. Only the piece and its two neighbours mount (preloaded:preload="metadata", eager images, requested viewport-wide at the post’s own ratio viaGalleryExhibitimageRatio/sizes, which the grid tiles use too); media leaving the stage is paused. Tab wraps inside the dialog (useFocusTrap). Escape or Close returns focus to the grid tile of the piece last shown, scrolled into view (instantly under reduced motion); if the grid no longer lists it, to the grid’s first control, else the menu button (only while the reader is still on/gallery: a link out leaves focus to the next page). Under reduced motion, starting the video from its own controls counts as Play (the exhibit’splayevent). Accepted limit: while focus is inside Chrome’s built-in video controls, Escape never reaches the page (Chrome sends no key events from there); Shift+Tab back to the video, where Escape works (interaction-redesign.md § TODO). - Details panel and immersive mode —
GalleryInfoPanel(app/components/gallery/GalleryInfoPanel.vue) shows the open piece’s title, category · date (Intl.DateTimeFormat('en', { dateStyle: 'medium' })on the ISO date read as a UTC day), description (summary), tags (stack) and anactionsslot (Share / case study / source). In landscape from the tablet breakpoint and at least 30em tall ((orientation: landscape) and (min-width: 48em) and (min-height: 30em), so landscape phones stay immersive) the viewer opens in the standard layout: the piece whole (contain) on the left and the panel as a glass right column. Its width is arole="separator"(aria-valuenow/-min/-maxin rem, a 44px grab zone centred on the panel edge, half over the stage; the panel root isoverflow: visible, overriding the theme’ssection { overflow: hidden }, and only its body scrolls): pointer drag with pointer capture (a press beside the edge keeps its offset, so the panel never jumps), Left / Right ± 1rem, Home / End to the bounds, clamped to 18rem … 40vw (the minimum wins on narrow screens), remembered inlocalStoragegallery-panel-widthand re-clamped on resize (the chosen width returns when there is room). The bar’s Immersive view toggle (one label;aria-pressedcarries the state, the icon switches maximize / minimize) switches to immersive: the piece fills the whole screen with the glass bar floating over its top edge (always shown; its title is sr-only there, the overlay shows it) over a top scrim; photos and video cover, code and diagrams stay whole and scroll, starting below the bar (its measured height, applied as an inlinepadding-topon the slide), and the details become a glass overlay over a scrim (collapsed: title + actions; More / Less,aria-expanded, opens the rest in place; text in ink / ink-muted, ≥ 4.5:1 over a white frame). The choice lasts for the open session (moving pieces keeps it; a new open starts standard). In portrait, below the breakpoint or on a landscape phone the viewer is always immersive and the toggle is hidden (a chosen immersive view returns when rotating back; focus on a control that disappears goes to the dialog). Escape first leaves a chosen immersive view (focus stays on the toggle), then closes. - Contrast on glass — the menu, the viewer bar and the details panel are
glass-overlay(88%--theme-surface-colorover whatever is behind), so their colours are measured on the worst backdrop: white behind in dark mode, black behind in light mode. Control outlines there — the menu’s outlined buttons (Play feed, Clear filters, Personalize), the Group / Filter / Sort chip groups, the touch<select>s, the Share fallback’s link field — and the details panel’s separator grip use the ink-muted role--theme-text-secondary-color(5.5:1 dark, 5.9:1 light on the worst glass; hover / drag turns the grip--theme-text-color). The grip straddles the panel edge, so its left half sits over the stage (the blurred piece under a 55%--theme-main-background-colorwash), where the pill alone fell to 1.8:1 (dark, white behind) and 2.6:1 (light, black behind): it carries a 1px--theme-text-colorring (box-shadow), ≥ 3.8:1 dark / 5.2:1 light against the stage over any backdrop and ≥ 11:1 on the glass (measured in Chrome at 1440: ring 12.0:1 dark / 7.4:1 light against the stage, pill 5.6:1 / 3.8:1); under forced colours the shadow drops and theCanvasTextfill carries it. The site’s outlined secondary border (the 8%--theme-border-colorhairline) measured 1.2:1 there and the strong border role 2.4:1 (dark) / 2.9:1 (light), under the 3:1 of WCAG 1.4.11. The “filters active” dot is border-drawn (forced colours repaint it) in--theme-link-color(4.3:1 dark, 5.2:1 light; the primary fill was 2.1:1 in dark mode). Get in touch is always solid (owner rule 2026-10-19):UiButton flat, the--theme-primary-fill-colorfill with the--theme-on-primary-colorlabel (5.8:1 dark, 4.7:1 light), never the gradient. Measured in Chrome at 1440 and 375 px, both modes (2026-10-19). Tests:core/web/tests/gallery-contrast.spec.ts(the roles on the worst glass and the rules that use them),gallery-menu.spec.ts; replaced styles intheme/core/scss/_archive/2026-10-19-gallery-contrast/. - Actions and playback —
GalleryViewerfills the details panel’sactionsslot (standard panel and the immersive overlay, collapsed or open). Share usesnavigator.share({ title, url })where there is a share sheet (dismissing it is silent), elsenavigator.clipboard.writeText(url)with a politerole="status"message “Link copied” (cleared after 4 s), else a focused read-only field with the status “Copy this link”. The link isgalleryShareUrl()(shared/gallery-viewer.ts): the page’s ownlocation.origin+ path with only?item=<id>— never the filters. Open case study (caseStudy, aNuxtLink; leaving/galleryunmounts the viewer, and Back returns to the same piece) and View source code (source,target="_blank" rel="noopener noreferrer"with the “(opens in a new tab)” note) show only when the post has the field. The shown video plays muted, looping and inline in both layouts; a Pause button (one label,aria-pressed,pause/playicon; WCAG 2.2.2) stops it, holds while the reader moves from piece to piece, resets on close, and gives way when the video’s own play control starts it again; a Sound button (one label,aria-pressed, volume icon) unmutes it. The choice follows the reader from piece to piece (and follows the video’s own native controls throughGalleryExhibit’smutedprop /muted-changeevent) and resets on close. Under reduced motion (the OS setting or the site’s motion setting) nothing autoplays: a 44px Play video button starts the piece (muted, then Sound appears and takes focus), and the next video asks again (Pause then appears beside Sound). Neighbouring pieces stay paused. - Links —
?item=is written only byuseGalleryViewerRoute()(app/composables/useGalleryViewerRoute.ts): opening pushes one history entry (marked inhistory.state), moving between pieces replaces it, and closing goes back over that entry (so the menu’s Back still leaves the page), or replaces withoutitemfor a shared link;dismiss()always replaces (and clears the flag). The page’s browse defaults includeitem: '', so filter / sort writes keep it. On the page (one watcher onitem+ the visible posts), an unknownitemis dropped; a newitemthe filter hides clears the filter and opens; a filter change (Back / Forward on?group=) that hides the open piece closes the viewer — both drops are adismiss, so they never undo the filter. Pure helpers:core/web/shared/gallery-viewer.ts(neighbour,resolveOpenItem). The old?view=feedno longer opens anything. - Group — series (
Reels,Scripts,Code Snippets,3D / XR,Other Samples). - Filter —
Images,Video,Code,Diagrams.
Performance (100+ posts)
Built for a hundred or more posts without virtualization or pagination (revisit past ~300 posts; see the TODO):
- Grid media is lazy:
loading="lazy",decoding="async", videopreload="none"until previewed, and photos requested at the tile’s own size (sizes), never full screen. - Previews play only for the hovered / focused tile, or on touch for the first video tile in view (one
IntersectionObserverover the video tiles), so only one preview moves at a time. - The viewer mounts only the current piece and its two neighbours, never every post.
- Rows are recomputed only when the measured width (or the posts) change, at most once per frame (
ResizeObserver+requestAnimationFrame).
Helpers: core/web/shared/gallery-types.ts (flattenGalleryPosts, filterGalleryPosts, sortGalleryPosts, GALLERY_SORTS, resolveGalleryAspect, resolveGalleryPlatform, galleryRatio, GALLERY_PLATFORM_LABEL), core/web/shared/gallery-justify.ts and core/web/shared/gallery-viewer.ts. Components: app/components/gallery/ (GalleryMenu, GalleryGrid, GalleryViewer, GalleryInfoPanel, GalleryExhibit); composables useGalleryPreview and useGalleryViewerRoute. Tests: core/web/tests/gallery-*.spec.ts; e2e: core/web-e2e/src/e2e/gallery-viewer.cy.ts.
SSR / script-setup contract: Pug templates must not call those helpers on _ctx. Bind them in <script setup> (e.g. GalleryGrid’s tiles computed, which maps posts to { ratio, tags, name, style }) so Nuxt SSR does not warn about missing instance properties.
Technical documentation
Markdown under repo docs/ is ingested in place by the docs collection (REPO_DOCS_DIR in core/web/shared/docs-source.ts). Do not copy or move those files into core/web/content/. Editing a file under docs/ updates both GitHub/Pages sources and the next Nuxt Content build for in-app /docs.
Whenever those pages change, follow the documentation sync checklist (catalogs, related hubs, and matching inline comments).
At build time Nuxt Content parses the tree into the Content SQLite dump. Lambda (SYS_ENV=test / production) and Docker local/dev images restore that dump from host .output/<sysEnv> — the original .md files are not required on the runtime image. Dockerfile.app copies that output tree; it does not COPY docs or rebuild Nuxt.
Excludes: Jekyll index.md / _*.md, design-history superpowers/ and plans/. The in-app catalog groups by path prefix (App, Agents, Packages, Developer tooling, Ops & delivery).
Links: write them for GitHub (relative to the .md file). Nuxt Content keeps them relative and drops .md, so on /docs/** the global ProseA (app/components/ProseA.global.vue → docsLinkHref in core/web/shared/docs-links.ts) resolves each against the page’s route (which mirrors the file tree) and maps it:
- a published doc → its lowercase route (
./web/README.md→/docs/web/readme; a folder link → the folder’sreadme); - an excluded doc (
superpowers/,plans/,_*) or a repo file / folder that is not an app route (../docker/,../AGENTS.md) → the public repo (likwidmack/portfolio,blobfor files,treefor folders); - app routes, anchors and external URLs are left alone.
core/web/tests/docs-links.spec.ts pins the mapping and keeps UNPUBLISHED_DOC_DIRS in step with DOCS_COLLECTION_EXCLUDE.
UML-style diagrams:
- Mermaid fences render lazily as sanitized SVG on
/docs, with source preserved for SSR, failure and the source disclosure. Normal fences retain their highlighted code. Diagram-authored configuration, actions and external resources are disabled. See renderer contract. - Structured diagrams on Gallery / Product continue to use
AppArchitectureDiagram(SVG, no Mermaid runtime).
See architecture.md for the diagram hub (C4, API UML, wireframes, sequences).
Fetch path: fetchContentCollection('docs', { mode: 'all' | 'first', path }) — same Nitro API as other collections. Do not call client queryCollection().