agentleFS
DonaldMurilloDonaldMurillo/gofastr/.claude/skills/gofastr-ui/SKILL.md

gofastr-ui

Skill24 starsChanged 2 days agoMITView on GitHub

Auto-loads when working on UI, runtime, or framework/uihost code in the GoFastr repo. Encodes the SSR-with-hydration architecture (no hard refresh, page-nav swaps content, in-page state stays on its route as query params or islands) and the failure modes that have already happened. Triggers on edits to core-ui/, framework/ui/, framework/uihost/, examples/site/, or runtime.js, and on phrases like "pagination", "sort header", "tab click", "navigation", "SPA", "hydration".

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never open a bespoke EventSource on an app surface.

    line 37
  2. Distinctive:

    Correct: no full reload either way.

    line 54
  3. Very specific:

    Every token (style.Color, style.Spacing, style.Shadow, etc.) has a .CSS() method that returns var(--<category>-<name>).

    line 87
  4. Very specific:

    core-ui/patterns/ is deleted: Every pattern moved to framework/ui on its framework/headless primitive (accordion and nestedlist are …

    line 146
  5. Very specific:

    If any of those tempt you, the model is being violated.

    line 215

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

GoFastr UI architecture: load this before writing UI code

This skill auto-loads whenever you touch the UI surface. The model has been misread three times in this repo. The canonical document is core-ui/ARCHITECTURE.md. Read it now if you have not already.

The model (one paragraph)

SSR-first. Server fully renders every page on first request. runtime.js hydrates the existing DOM (no re-render). Cross-page navigation (/a → /b) is client-side via partial fetch + cache, no hard refresh. In-page state changes (pagination, sort, filter, expand) are islands: a click fires an RPC, the server returns new island HTML, the runtime swaps just that island's content.

The reactivity ladder: pick the cheapest rung that works

Liveness escalates through four rungs; each is opt-in and pull beats push (canonical doc: framework/docs/content/reactivity.md):

  1. Client signals (data-cui-signal-*): UI-only state, zero server.
  2. RPC: user acts, server renders from the DB, runtime swaps. The default for anything touching data. Stateless; any replica answers.
  3. Polling (data-cui-poll, widget Builder.Poll): passive freshness (dashboards, counters, statuses). No held connection, no fanout needed.
  4. SSE push (the single /__gofastr/sse bus): ONLY for semantics that need a connection: presence, collaborative editing, sub-second internal dashboards. Push-only, never responses to user actions. Requires WithFanout + WithSecret/GOFASTR_SECRET multi-replica.

State lives in the DB or the client signal store, never in server RAM. Never open a bespoke EventSource on an app surface; the bus is the only push channel. (Dev-mode tooling like framework/dev livereload and kiln's build-mode reload ships its own; that's the whole exception class.)

The failure modes: refuse to do these

❌ Treating in-page state as a new route

Symptom: page 2 or a sort order gets a path of its own (/orders/page/2), or a pager embedded in a card does a full reload. Correct: a list screen's own sort, page and filter live in its query string, and its links are normal <a href="?p=2"> navigations the client router intercepts. A region embedded in a page (a pager inside a card, an expand) is an island: its controls fire an RPC and the server returns the new rendered rows. framework/ui.Pagination renders the anchors for both.

❌ Hard refresh on every interaction

Symptom: clicking a sort header reloads the whole page. Correct: no full reload either way. A list screen's sort header is a query-string link the router intercepts; a table embedded in a page sorts by island RPC, and the runtime swaps just that island.

❌ Client-only after hydration

Symptom: pagination math lives in JS; the server doesn't know about page 2. Correct: server is the source of truth. Always. JS shipped to the browser is the generic runtime (runtime.js), never feature-specific code.

❌ Reaching for SSE when a cheaper rung works

Symptom: a metrics card / status badge / count subscribes to the SSE bus (or worse, opens its own EventSource) just to stay fresh. Correct: rung 3, data-cui-poll (page region) or Builder.Poll (widget). SSE is earned by presence/collab/sub-second semantics only, and always via the shared bus.

What you compose

NeedUse
Static HTML primitive (<button>, <h1>, <table>)core-ui/html
A composed UI pattern (accordion, tabs, pagination, breadcrumbs)framework/ui/<Name> (on its framework/headless primitive)
A semantic component (PageHeader, FormField, DataTable)framework/ui/
An island (server-rendered, server-state-owning, RPC-updatable)core-ui/widget (builder API: New(name).Slot(...).RPC(...))
A theme tokenframework/ui/theme (canonical typed style.Theme; mutate fields directly)
An interactive component (RPC, signals, widget chaining)core-ui/interactive (OnClick(html, Post("/path").OnSuccess(...)))
Per-component CSS (loaded on demand, dedup'd, never re-fetched)core-ui/registry (RegisterStyle + Style.WrapHTML)

Theme: typed, always emits var()

The framework's design tokens live in style.Theme, a typed Go struct. Every token (style.Color, style.Spacing, style.Shadow, etc.) has a .CSS() method that returns var(--<category>-<name>). Build-time literal resolution is gone: every reference goes through a CSS variable, which is what lets section-level theme overrides cascade.

Common patterns:

  • Override one token: t.Colors.Primary = style.Color{Name: "primary", Value: "#14B8A6"}.
  • App-extended tokens: embed style.Theme in an AppTheme struct + add brand fields.
  • style.CSSCustomPropertiesOf(theme) walks the canonical + embedded fields, emits :root { --…: ...; }.

Hard rules:

  • ❌ Never write literal #hex colors in component CSS. Always var(--color-x) or t.Colors.X.CSS().
  • ❌ Don't try MergeThemes(...); it was removed. Mutate fields directly.
  • ✅ app.WithTheme(theme) is the binding pattern. The host emits :root from the theme and components reference it.

For section-level theme overrides (dark sidebar in a light app, branded sections, multi-tenant subtrees), use style.RegisterThemeOverride + ui.Themed:

var Dark = style.RegisterThemeOverride(darkTheme)

ui.Themed(Dark,
    ui.Section(ui.SectionConfig{Heading: "Dark"},
        ui.Button(ui.ButtonConfig{Label: "OK"}),
    ),
) // wrapped subtree's var(--color-*) reads from Dark via CSS cascade

Framework emits a .cui-theme-<hash> block in app.css; the CSS cascade does the rest. Content-addressed: registering the same theme twice ships CSS once.

Per-component CSS: the registry pattern

Component-owned CSS ships as a real <link> (never inline), loaded lazily on first appearance, dedup'd globally, and always scoped to [data-cui-comp="<name>"]. Global resets / typography / theme tokens stay in theme.css or WithCustomCSS.

// styles_mything.go: registration + builder
var myThingStyle = registry.RegisterStyle("ui-my-thing", myThingCSS)

func myThingCSS(t style.Theme) string {
    return style.NewComponentSheet("ui-my-thing", t).
        Rule("&").Set("display", "flex").End().              // & = the marker element
        Rule(".header").Set("font-weight", "700").End().     // descendant
        Rule(".body").Set("padding", "{spacing.lg}").End().
        MustBuild()
}

// at the render site: wrap the outer tag with .WrapHTML
func MyThing(cfg MyThingConfig) render.HTML {
    return myThingStyle.WrapHTML(html.Div(html.DivConfig{Class: "ui-my-thing"}, …))
}

Load modes:

  • LoadAuto (default): load when marker first hits DOM. SSR emits link on pages that use it.
  • LoadPrewarm: same as Auto + throttled requestIdleCallback prefetch.
  • LoadAlways: emit link on every page (use for chrome on essentially every screen).

core-ui/patterns/ is deleted. Every pattern moved to framework/ui on its framework/headless primitive (accordion and nestedlist are ui.Collapsible; infinitescroll is gone) — compose those; do not recreate a pattern package. A func BaseCSS() string export is forbidden: the 2026-05-19 nestedlist incident shipped without styling because the host's theme.go was never updated to concatenate it.

Hard rules:

  • ❌ Never export func BaseCSS() string from a component package. Register via RegisterStyle and wrap via WrapHTML.
  • ❌ Never write inline <style> blocks for component CSS; always go through the registry.
  • ❌ Never write selectors that try to escape the scope (body, html, :root, *, ::backdrop); ComponentSheet rejects them at process startup.
  • ✅ Use & in ComponentSheet to reference the marker element itself.
  • ✅ Test CSS without chromedp by building the ComponentSheet directly.

Runtime data-attributes (do not invent new ones without updating the doc)

AttributeEffect
data-cui-rpc="<path>"Click/submit fires HTTP request
data-cui-rpc-signal="<name>"Response body becomes the value of signal <name>
data-cui-signal="<name>" mode=text|number|html|attrElement auto-updates when the signal changes
data-cui-poll="<interval>" + data-cui-poll-src="<path>"Region re-fetches + swaps on the interval (≥5s, jittered, pauses hidden)
data-cui-open="<widget>"Opens a mounted widget
data-cui-comp="<name>"Marker for a registered styled component: runtime loads /__gofastr/comp/<name>.css once

The runtime + the data-attributes ARE the API surface for hydration. Adding new attributes requires updating core-ui/ARCHITECTURE.md and the runtime test suite. Every attribute is a public contract.

URL as source of truth

State worth bookmarking / refreshing / back-buttoning lives in the URL. The flow:

  1. Initial load: ScreenLoader.Load(ctx) reads ?p=2 etc. and SSR's page 2.
  2. Click in-island button: RPC returns new HTML AND X-Gofastr-Push-State: ?p=3 header → runtime applies pushState (no fetch).
  3. Browser back: popstate → runtime fetches screen partial for the new URL → swap → cached for instant forward.
  4. Refresh: same URL → SSR renders the right state.

Before you ship UI code, check

  • Initial render is full SSR: refresh on the URL produces the same DOM.
  • No path of its own for in-page state: a list screen's sort/page/filter are query-string links; an embedded region's are an island RPC.
  • In-page state worth sharing/bookmarking is in the URL via the X-Gofastr-Push-State response header.
  • No location.href = … in JS or in the server response.
  • No JS feature code; only the generic runtime.
  • Cross-page links are normal <a>; the runtime intercepts them transparently for the partial-fetch + cache flow.
  • ScreenLoader.Load(ctx) populates state from route params + query so deep-links / refresh / SSG all work.

Stop and re-read core-ui/ARCHITECTURE.md if

  • You're about to write data-cui-spa or any "opt into SPA mode" attribute.
  • You're about to give pagination or sort a path of its own, or make an embedded region's pager reload the page.
  • You're about to add a runtime endpoint that's not part of the SSR / page-nav / island-RPC / poll / SSE-push grid.
  • You're about to open an EventSource outside the shared bus, or use SSE for something polling would cover.
  • You're about to write client-side feature logic (sorting, filtering, paginating, validating) in JS.

If any of those tempt you, the model is being violated. Stop, ask the user to confirm a deviation, and document the new pattern in core-ui/ARCHITECTURE.md before shipping.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.