# Layouts & Vibe — a plain-language guide For authors (and the `/studio` agent) choosing how a page looks. Everything here is **opt-in**: set nothing and you get the clean default. Every effect degrades gracefully (reduced-motion / reduced-transparency / unsupported browsers fall back), and backgrounds always keep text legible. You set the vibe with an `appearance` object — on `site.config.json` (the site default), or on a single page's JSON (which wins). It has four knobs: **layout**, **background**, **surface**, **fx**. ```json "appearance": { "layout": "flow" | "bento", "background": "none" | "aurora" | "mesh" | "cover" | "image", "bgImage": "/assets/img/bg/whatever.jpg", // only with background: "image" "surface": "solid" | "glass", "fx": ["scanlines", "grain", "vignette"] } ``` --- ## 1. Content types — what you're making | Type | URL | It's for | Has | |---|---|---|---| | **release** | `/releases//` | an album / EP / single | cover, streaming players, optional tracklist | | **editorial** | `/blog//` | a post, tutorial, or behind-the-scenes | a rich body of blocks | | **review** | `/reviews//` | gear / plugin / pack | star rating, pros & cons, specs | | **profile** | `/profile//` | about / bio | bio prose + links | --- ## 2. Layout — how the card listings are arranged Applies to the home and the section index pages (`/releases/`, `/blog/`, …). - **flow** *(default)* — a clean, even grid. Looks right with **any** number of items. The safe pick. - **bento** — a magazine-style mosaic. The card that has an image becomes a big hero tile; the rest pack around it. Looks best with **4+ items and at least one cover image**. With few/no images it falls back to a tidy grid. > On phones both collapse to a single column automatically. --- ## 3. Background — the full-page backdrop - **none** *(default)* — the plain themed background. Maximum readability. - **aurora** — a soft glow generated from your accent color. Subtle and modern; no image needed. - **mesh** — a richer multi-point generated gradient. A bit more presence than aurora. - **cover** — the page's *own* cover art, blurred and darkened behind the content. Cohesive for a release (the art becomes the room). - **image** — a specific image you supply via `bgImage` (a band photo, a studio shot, a nebula). Drop the file in `assets/img/bg/` first. A contrast scrim is always laid over the background so titles and body text stay readable. --- ## 4. Surface — how cards & players look - **solid** *(default)* — opaque cards. Crisp on a plain background. - **glass** — frosted, translucent cards that float over the backdrop. **Use with a background** (otherwise there's nothing to frost). Auto-falls back to solid where unsupported. --- ## 5. FX — cinematic overlays (combine freely) - **scanlines** — a faint CRT shimmer. Techy / retro / sci-fi. - **grain** — film grain. Analog / cinematic / "studio." - **vignette** — darkened edges that focus the eye on the center. All FX sit *over the background, behind your text* (so words stay sharp) and switch off under reduced-motion / reduced-transparency. --- ## 6. Recipes — copy these | Want | `appearance` | |---|---| | **Cinematic album page** | `{ "background":"image", "bgImage":"/assets/img/bg/band.jpg", "surface":"glass", "fx":["scanlines"] }` | | **Making-of / studio feature** | `{ "background":"image", "bgImage":"/assets/img/bg/studio.jpg", "surface":"glass", "fx":["grain","vignette"] }` | | **Cohesive release (use its own art)** | `{ "background":"cover", "surface":"glass" }` | | **Subtle modern landing** | `{ "background":"aurora", "surface":"glass" }` | | **Clean editorial read** | *(omit appearance — let the words breathe)* | --- ## 7. Blocks — the editorial body pieces What you stack inside an editorial `body` (releases/reviews/profiles use a smaller subset): - **prose** — Markdown text (the workhorse). - **hero** — a banner image with a headline. - **audioEmbed** — a platform player with a switcher (Spotify / YouTube Music / SoundCloud …). - **pullQuote** — a large quoted line with attribution. - **image** / **figure** — a picture; `figure` adds a caption and can go **wide** or **full-bleed**. - **signalChain** — a numbered gear / routing path (very music-production). - **statBand** — a full-width "by the numbers" strip. - **sectionDivider** — a movement marker (eyebrow + title) for chapter rhythm. - **sectionBreakdown** — an annotated arrangement timeline (time · section · meter · note). - **abCompare** — two players side by side ("hear the difference"). - **code** — a monospaced code/patch block. --- ## 8. The /studio vibe wizard When making a page, pick the vibe **with the human in plain language** — don't assume. One or two questions usually settles it: 1. *Clean and readable, or cinematic with a full background?* 2. *Background: an image you'll supply (band/studio shot), the cover art, or a generated glow?* 3. *Any retro FX (scanlines / grain / vignette)? Frosted glass cards?* Then set `appearance` from their answers (default to nothing if unsure). Never force a vibe the human didn't ask for. --- ## 9. Ideas for future layouts (not built yet) Candidates if authors ask: a **list** layout (compact text rows for archive-heavy blogs), a **magazine** layout (one large feature + a sidebar of smaller items), a **gallery** layout (image-first masonry for photo/art posts), and a **split-hero** release page (cover left, tracklist right). Each would be a new `layout`/renderer value — propose before building. ## 10. Landing layout + homeContent (added 2026-07-23) `layout: "landing"` renders a cinematic single page: a full-height centered hero (the `hero` block gained optional `kicker` / `tagline` / `sub`), gradient wordmark headline, accent-underlined `##` sections, wrap-friendly code blocks. Pair with `background: "image"` — landing deepens the dim (near-solid at the foot) so long sections stay readable over art. Site config `homeContent: "/"` promotes that item's body to the home page; the item leaves the collection (no own URL, no index/feed/sitemap entries). Together they make a product landing page: one content JSON, one line of config.