Color tokens

All colours go through CSS custom properties so each tenant theme swaps the palette at :root[data-theme="<tenant>"]. Use semantic tokens (--text-muted, --danger) over raw hex anywhere outside the package's themes.css.

Surface

• --bg-primary page background
• --bg-elevated cards, nav drawer, inputs
• --bg-tag chips, subtle fills

Text

• --text-primary body, headings
• --text-muted meta, hints, labels
• --text-faint de-emphasised meta, dropped

Border

• --border-subtle default field, card edge
• --border-focus focused input, active field

Semantic

• --accent primary action, active state
• --success done, paid, healthy
• --warning snoozed, due soon
• --danger errors, destructive actions

Buttons

Four variants, each backed by a Go const on ButtonVariant. The variant value IS the CSS class suffix so adding a new style is one Go const + one CSS rule.

@Button(ButtonPrimary, "button", false) { Capture }

@Button(ButtonSecondary, "button", false) { Cancel }

@Button(ButtonGhost, "button", false) { Edit }

@Button(ButtonDestructive, "button", false) { Drop }

Links

Default, muted (for row meta), arrow (for section-to-section navigation). The arrow variant lifts on hover to telegraph the destination.

@Link(LinkDefault, "#") { view all captures }

@Link(LinkMuted, "#") { 2 days ago }

@Link(LinkArrow, "#") { go to triage }

Chips

Compact state and kind labels. Soft variants (success / warning / danger) pair a background tint with the matching text colour so the tone reads at a glance in dense rows.

@Chip(ChipStatus, "active")

@Chip(ChipKind, "payment")

@Chip(ChipLocation, "Sendai")

@Chip(ChipSuccess, "paid")

@Chip(ChipWarning, "snoozed")

@Chip(ChipDanger, "overdue")

Keyboard chord

Single visual unit for any keypress hint. Compose multi-key chords as one string ("⌘K") rather than chaining multiple Kbd calls — the design treats each chip as one unit.

@Kbd("Esc")

@Kbd("⌘K")

Press @Kbd("⌘B") to toggle the nav.

Status dot

Tiny coloured circle that pairs with adjacent label text. Four tone variants. Site-specific score-coloured variants (e.g. a 0–10 motivation scale) live in the consuming site, not here.

@StatusDot(StatusDotActive, "active") in progress

@StatusDot(StatusDotSnoozed, "snoozed") deferred to next week

@StatusDot(StatusDotDone, "done") shipped 2 days ago

@StatusDot(StatusDotDropped, "dropped") dropped — not pursuing

Avatar

Circular image at two sizes — small for dense list rows, large for detail headers — with an initials fallback when no image is set. Private-file consumers point the URL at an auth-gated serve route that redirects to a presigned URL (ADR 0036).

Small — image

dense list rows

@Avatar(AvatarSmall, url, "AL", "Ada Lovelace")

Large — image

detail headers

@Avatar(AvatarLarge, url, "AL", "Ada Lovelace")

Initials fallback

no image uploaded

AL

@Avatar(AvatarLarge, "", "AL", "Ada Lovelace")

Tabs

Segmented control for in-page view switching. The active tab carries the underline; one Tab per --view=… filter.

@Tabs("Filter") {
    @Tab("#", "Active", true)
    @Tab("#", "Snoozed", false)
    @Tab("#", "Dormant", false)
    @Tab("#", "Done", false)
    @Tab("#", "Dropped", false)
    @Tab("#", "All", false)
}

Combobox

Free-text input + autocomplete dropdown. Type to create; press ↓ then Enter to attach an existing item. It submits two fields — the typed text and a hidden id — so one input means both "create this" and "attach that". Transport-agnostic: the consumer wires hx-get to fill the listbox. Pair with one @ComboboxScript() per page.

@Combobox(ComboboxParams{
    ID: "task-add", TextName: "title", ValueName: "task_id",
    Placeholder: "Add or find a task…",
    InputAttrs: templ.Attributes{
        "hx-get": "/today/suggest", "hx-trigger": "keyup changed delay:150ms",
        "hx-target": "#task-add-listbox",
    },
}) {
    // listbox filled by the server as the user types:
    @ComboboxOption(task.ID, task.Title, nil)
}
// once per page:
@ComboboxScript()

Entity card

Standard chrome for detail pages: title + optional kind chip on the header, key-value fields in a two-column grid below.

@Card() {
    @CardHeader("Yuki Tanaka") {
        @Chip(ChipKind, "person")
    }
    @CardFields() {
        @CardField("Email") { yuki@example.jp }
        @CardField("Lives in") { Sendai, Miyagi }
        @CardField("Last contact") {
            <time class="time" datetime="2026-05-12">May 12 · 18:20</time>
        }
    }
}

List row

Whole-row clickable surface — wrap row contents in <a class="list-row"> for a single hit area. Hovers lift to --bg-tag.

@ListRows("") {
    @ListRow("", "#") {
        @ListRowLabel() { Renew passport }
        @ListRowMeta() { due Jun 1 }
    }
    @ListRow("", "#") {
        @ListRowLabel() { Pay NHK bill }
        @ListRowMeta() { Jan 12 }
    }
}

Breadcrumb

Single-page nav chrome with a back arrow. Optional right-aligned action button (Edit / Archive); more than one action wants a dedicated toolbar instead.

@Breadcrumb("#", "All tasks")

@Breadcrumb("#", "All projects") {
    @BreadcrumbAction("#") { Edit }
}

Page section

Standard subsection chrome. PageSection uses an <h3>; PageSectionTop uses an <h2> for the single page-level heading on new / edit pages.

@PageSection("Members") {
    <p>Section body content goes here.</p>
}

@PageSectionTop("Edit profile") {
    <p>Top-level form content.</p>
}

Button row

Flex container for action button groupings. Pairs of primary / destructive on detail pages, or grouped secondary actions in a card footer.

@ButtonRow() {
    @Button(ButtonPrimary, "button", false) { Complete }
    @Button(ButtonDestructive, "button", false) { Drop }
}

Input field

The typed wrapper over a single <label> + <input> — what forms would otherwise hand-roll. Type defaults to text and ID to Name; an empty Value shows the placeholder. For paired numeric bounds reach for the Range field; for typeahead, the Combobox. HTMX-agnostic — wire hx-* on the enclosing form.

@InputField(InputFieldParams{
    Label: "Display name", Name: "display_name",
    Value: "Aiko", Placeholder: "e.g. Aiko",
})

@InputField(InputFieldParams{
    Label: "Goal weight (kg)", Name: "goal_weight", Type: "number",
    Value: "70", Min: "1", Max: "500", Step: "0.1",
})

@InputField(InputFieldParams{
    Label: "Sex", Name: "sex", Value: "male", Disabled: true,
})

Range field

Paired Min / Max <input type="number"> for bounded numeric filters. Uses real number inputs (not a custom slider) so step buttons, keyboard, and screen readers work natively — chosen for audiences where two-handle sliders would be a usability tax. HTMX wiring lives on the consumer's form.

@RangeField(RangeFieldParams{
    Label: "Price", Unit: "£",
    NameMin: "min_price", NameMax: "max_price",
    Min: 0, Max: 100000, Step: 1000,
    ValueMin: "20000", ValueMax: "",
})

@RangeField(RangeFieldParams{
    Label: "Floor area", Unit: "m²",
    NameMin: "min_area", NameMax: "max_area",
    Min: 0, Max: 100, Step: 1,
})

Photo gallery

Data-driven thumbnail grid (PhotoGallery([]PhotoGalleryImage)) plus one reused native <dialog> lightbox per page. Thumbnails are real <a> links to the full image, so with JS off they still open the photo; with JS the PhotoGalleryScript IIFE intercepts the click and opens the lightbox (prev / next, arrow keys, Esc, backdrop dismiss). Thumbnails are the full image scaled by CSS — no thumbnail generation. Emit @PhotoGalleryLightbox() + @PhotoGalleryScript() once per page (this gallery page mounts them below so the demo is live).

@PhotoGallery([]PhotoGalleryImage{
    {URL: photo.URL(), Alt: photo.Caption},
    // …one per photo…
})
// once per page, after the grid:
@PhotoGalleryLightbox()
@PhotoGalleryScript()

Donut

Static, server-known part/whole breakdown as an inline <svg> donut + legend (Donut(DonutView)) — zero JS, themed entirely through CSS custom properties so it recolours the instant the theme toggles (the reason it is inline SVG, not Chart.js; ADR 0040). Each wedge's Kind picks its fill by visual role: a muted chart-cat hue for a Category, solid grey for a Muted "other" bucket, a hatch for a Hatched remainder/surplus wedge. Graduated from brain's budget category-breakdown and nutrition macro donuts once the technique had two consumers (ADR 0020). Toggle the theme above to watch the wedges re-tint live.

@Donut(DonutView{
    CenterLabel: "¥260,000", CenterSub: "planned out",
    Note: "Over by ¥20,000", NoteTone: DonutNoteDanger,
    Wedges: []DonutWedge{
        {Label: "Rent", Kind: DonutCategory, ColorIndex: 0, Pct: 45, Offset: 0, ...},
        {Label: "Uncategorized", Kind: DonutMuted, Pct: 10, Offset: 90, ...},
    },
})

@Donut(DonutView{
    CenterLabel: "¥180,000", CenterSub: "planned out",
    Wedges: []DonutWedge{
        {Label: "Rent", Kind: DonutCategory, ColorIndex: 0, ...},
        {Label: "Unplanned", Kind: DonutHatched, Pct: 20, Offset: 80, ...},
    },
})

@Donut(DonutView{
    CenterLabel: "1,850", CenterSub: "kcal",
    Wedges: []DonutWedge{
        {Label: "Protein", Kind: DonutCategory, ColorIndex: 0, Pct: 30, ...},
        // …one per macro…
    },
})

Full-bleed section chrome for marketing landing pages — composed by consumers into MarketingNav → MarketingHero → MarketingSections → MarketingFooter. See the assembled preview at /landing/japan-at-night.

Section intro

Eyebrow label + h2 title + free-form body slot. Left variant for most sections, center variant for closing CTA panels.

@SectionIntro(SectionIntroLeft, "What this is", "The Sendai your guidebook doesn't know.") {
    <p class="marketing-body">Iroha Yokocho. Bunka Yokocho. …</p>
}

@SectionIntro(SectionIntroCenter, "Ready?", "Come find the Sendai I love.") {
    <p class="marketing-lede">Small groups, flexible dates…</p>
    @Button(ButtonPrimary, "button", false) { Book a night → }
}

Marketing section

Vertical-padded wrapper that gives every band the same rhythm and border. Optional id makes the section a jump target for in-page nav links.

@MarketingSection("the-night") {
    @SectionIntro(SectionIntroLeft, "What this is", "…") {
        <p class="marketing-body">…</p>
    }
    @FeatureGrid() { … }
}

Marketing nav

Top-of-page nav band — brand wordmark, inline link group, and right-aligned CTA pill. The theme toggle drops in as a child between links and CTA.

@MarketingNav() {
    @NavBrand("Japan at Night")
    @NavLinks() {
        @NavLink("#the-night", "The night")
        @NavLink("#guide", "Your guide")
        @NavLink("#faq", "FAQ")
    }
    @NavCTA("#book", "Book a night")
}

Marketing hero

Full-bleed hero band. Image slot + caption slot composed as children — copy lives in the consumer's HeroCaption, not in typed args, so i18n and multi-line headlines aren't foreclosed.

@MarketingHero() {
    @HeroImage() {
        <img src="…" alt="…"/>
    }
    @HeroCaption() {
        <h1 class="marketing-h1">An evening in Sendai's hidden alleyways.</h1>
        <p class="marketing-lede">Hole-in-the-wall bars, locals-only counters…</p>
        @Button(ButtonPrimary, "button", false) { Book a night → }
    }
}

Feature grid

3-up grid of accent-glyph + title + body cards, collapses to 1-up on mobile. Variable child count.

@FeatureGrid() {
    @Feature("Hidden spots") { … body … }
    @Feature("Tailored to you") { … body … }
    @Feature("Local welcome") { … body … }
}

Step grid

Numbered "how it works" sequence — image + accent circle + title + body per step. CSS reorders so the photo reads first visually while screen readers get number+title up front.

@StepGrid() {
    @Step(1, "Iroha Yokocho") {
        @StepImage() { <img src="…" alt="…"/> }
        @StepBody() { Sushi, sake, and small plates… }
    }
    @Step(2, "Bunka Yokocho") { … }
    @Step(3, "Craft cocktails") { … }
}

Review grid

2-up testimonial cards with N filled-star glyphs, italicised quote, and attribution. Stars rendered with clip-path so they pick up --accent in every theme.

@ReviewGrid() {
    @Review(5, "Calder L. · March 2025") {
        Ali showed all the hidden experiences that only a local would really know.
    }
    @Review(5, "Alex W. · December 2024") {
        One of my most memorable nights out ever.
    }
}

FAQ list

Native <details> / <summary> accordion — accessible by default, no JS, screen readers announce the open/closed state correctly.

@FAQList() {
    @FAQ("Do I need to speak any Japanese?") {
        <p class="marketing-body">No — Ali guides in English…</p>
    }
    @FAQ("What if I have dietary restrictions?") { … }
    @FAQ("How long is the tour?") { … }
}

Marketing footer

Left-aligned brand text + right-aligned link group. Flex-wraps on narrow screens.

@MarketingFooter() {
    @FooterText() { Japan at Night · Sendai }
    @FooterLinks() {
        @FooterLink("#", "Instagram")
        @FooterLink("#", "Contact")
        @FooterLink("#", "© 2026")
    }
}