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".
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- framework/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adversarial-testsSkill
- app-introspectSkill
- chaos-testSkill
- component-buildSkill
- eval-reportSkill
- gofastr-docsSkill
- gofastr-hostSkill
- gofastr-mcp-debugSkill
- log-debugSkill
- plain-wordsSkill
- primitives-sweepSkill
- review-gateSkill
- twin-sweepSkill
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
- Very specific: line 37
Never open a bespoke EventSource on an app surface.
- Distinctive: line 54
Correct: no full reload either way.
- Very specific: line 87
Every token (style.Color, style.Spacing, style.Shadow, etc.) has a .CSS() method that returns var(--<category>-<name>).
- Very specific: line 146
core-ui/patterns/is deleted: Every pattern moved to framework/ui on its framework/headless primitive (accordion and nestedlist are … - Very specific: line 215
If any of those tempt you, the model is being violated.
≈ “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.
Files
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):
- Client signals (
data-cui-signal-*): UI-only state, zero server. - RPC: user acts, server renders from the DB, runtime swaps. The default for anything touching data. Stateless; any replica answers.
- Polling (
data-cui-poll,widget Builder.Poll): passive freshness (dashboards, counters, statuses). No held connection, no fanout needed. - SSE push (the single
/__gofastr/ssebus): ONLY for semantics that need a connection: presence, collaborative editing, sub-second internal dashboards. Push-only, never responses to user actions. RequiresWithFanout+WithSecret/GOFASTR_SECRETmulti-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
| Need | Use |
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 token | framework/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.Themein anAppThemestruct + add brand fields. style.CSSCustomPropertiesOf(theme)walks the canonical + embedded fields, emits:root { --…: ...; }.
Hard rules:
- ❌ Never write literal
#hexcolors in component CSS. Alwaysvar(--color-x)ort.Colors.X.CSS(). - ❌ Don't try
MergeThemes(...); it was removed. Mutate fields directly. - ✅
app.WithTheme(theme)is the binding pattern. The host emits:rootfrom 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 cascadeFramework 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 + throttledrequestIdleCallbackprefetch.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() stringfrom a component package. Register viaRegisterStyleand wrap viaWrapHTML. - ❌ 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);ComponentSheetrejects them at process startup. - ✅ Use
&inComponentSheetto reference the marker element itself. - ✅ Test CSS without chromedp by building the
ComponentSheetdirectly.
Runtime data-attributes (do not invent new ones without updating the doc)
| Attribute | Effect |
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|attr | Element 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:
- Initial load:
ScreenLoader.Load(ctx)reads?p=2etc. and SSR's page 2. - Click in-island button: RPC returns new HTML AND
X-Gofastr-Push-State: ?p=3header → runtime applies pushState (no fetch). - Browser back: popstate → runtime fetches screen partial for the new URL → swap → cached for instant forward.
- 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-Stateresponse 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-spaor 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
EventSourceoutside 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.
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
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.

