component-build
Skill24 starsChanged yesterdayMITView on GitHub
Auto-loads when building, adding, or extending a UI component, widget, island, or any surface in the GoFastr framework, including modals, drawers, dropdowns, toasts, sidebars, banners, popovers, and any other interactive primitive. Encodes the "minimal-register + SSR-inline + hydrate" contract every component must follow. Triggers on phrases like "add a widget", "build a component", "new modal", "create dropdown", "add island", "wire a surface", or whenever the work touches core-ui/widget/, core-ui/widget/preset/, framework/ui/, or registers a widget.Definition.
- Sends data out
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
- eval-reportSkill
- gofastr-docsSkill
- gofastr-hostSkill
- gofastr-mcp-debugSkill
- gofastr-uiSkill
- log-debugSkill
- plain-wordsSkill
- primitives-sweepSkill
- review-gateSkill
- twin-sweepSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
When you add a new field to the registry: add it to serveWidgetList in core-ui/widget/server.go, then to the runtime consumers that read …
- Very specific: line 76
When you ship a new widget preset: confirm the chrome HTML appears in curl http://localhost:.../some-page | grep <distinctive-text>.
- Distinctive: line 88
Never write a runtime path that builds DOM the server could have built.
- Distinctive: line 97
If you're adding a network call to a mount path, the bar is: "can the server have already given us this on the response that brought us …
- Distinctive: line 138
Before claiming a component works:
- Very specific: line 181
Avoid timing flakes: use chromedp.Sleep with a window 2-3x the debounce-or-animation duration, not 100ms because "feels enough".
- Distinctive: line 184
When the static-shape test passes but the interaction test fails, that's the bug you would have shipped without it.
- Very specific: line 230
1. Per-instance state, never module globals: Use a WeakMap keyed by the wrapper element, plus a sibling Set for iteration:
- Very specific: line 278
4. Tear down rollback timers on re-entry: If your error path schedules a setTimeout to revert state, store the timer id on the button and …
- Distinctive: line 308
NOT a thing; it renders unstyled native buttons.
- Very specific: line 326
Verify with pixels, not probes: go test ≠ "works in a browser" (see gofastr-ui + AGENTS.md Hard rule 9).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Building a component: the contract every primitive follows
This is the framework's pattern for any UI surface that needs server-rendered HTML, client-side hydration, and an optional dismiss/lifecycle. The shipped presets (Modal, Drawer, ToastStack, Popover) all follow it. New surfaces must follow it.
Do not build a component that downloads its HTML through a JSON catalog,
constructs DOM at runtime when SSR would have done it, or fires per-mount
network calls for state it doesn't have. Those mistakes have happened in
this repo and produce the same symptoms each time: empty view-source, slow
first-open, redundant /state round-trips, deep-link flicker.
The four-rule contract
1. Register MINIMAL metadata, fetch chrome lazily
The registry (/__gofastr/widgets) is an index, not a payload. Each entry
ships only the data the runtime needs to decide what to do:
{
"name": "components-confirm",
"position": "center",
"backdrop": true,
"closeOnEscape": true,
"stylePath": "/core-ui/widget/components-confirm/style.css",
"chromePath": "/core-ui/widget/components-confirm/chrome",
"statePath": "/core-ui/widget/components-confirm/state", // omitted when no signals
"deepLinkKey": "modal",
"deepLinkValue": "user-edit",
"deepLinkParams": ["user_id"]
}Chrome HTML is fetched from chromePath only when the runtime actually needs
it, and only when SSR hasn't already inlined the element. The state endpoint
is omitted entirely when the widget declared no signals.
When you add a new field to the registry: add it to serveWidgetList in
core-ui/widget/server.go, then to the runtime consumers that read the
catalog JSON: core-ui/runtime/frag/widgets-boot.js (the boot catalog
fetch and auto-mount pass; widgets-boot-static.js is its static-export
twin) and core-ui/runtime/src/widgets.js (the demand module that fetches
chrome from chromePath). Then document the field.
core-ui/runtime/runtime.js is GENERATED: composeFull() in
core-ui/runtime/runtime.go stitches frag/*.js into one IIFE, so an edit
to runtime.js never reaches the browser. Edit the fragments, then regenerate
the on-disk file:
GOFASTR_UPDATE_RUNTIME_JS=1 go test ./core-ui/runtime/ -run TestComposedRuntimeMatchesOnDiskFile2. SSR-inline whenever the URL says the surface should be open
In framework/uihost, every registered widget is walked per-request:
deeplinked widget whose key/value matches r.URL.Query() → inline OPEN
hidden widget that doesn't match → inline with [hidden]
visible (non-hidden) widget → inline OPENThe widget chrome lands just before </body>. The runtime's _mountByName
checks for an existing [data-cui-widget="<name>"] root before fetching
chromePath. If one exists, the runtime hydrates in-place. View-source
shows the modal. Refreshing a deep-link paints instantly with no flicker.
When you ship a new widget preset: confirm the chrome HTML appears in
curl http://localhost:.../some-page | grep <distinctive-text>. Zero hits
means the SSR-inline path didn't fire.
3. Hydrate, don't reconstruct
mountWidget takes either an existingEl (SSR-inline path) OR a chromeHTML
string (lazy-fetch path). Both reach the same wired state: handlers, focus
trap, scroll lock, signal listeners. When dismissed, a hydrated widget is
hidden in place (hidden attribute), never detached, so re-opening
doesn't refetch.
Never write a runtime path that builds DOM the server could have built.
4. Skip the network call when there's nothing to fetch
cfg.statePathis absent when the widget has no signals → no/statefetch.cfg.chromePathis bypassed when SSR-inline succeeded → no chrome fetch.- Toast push is
X-Gofastr-Toastresponse header on an existing RPC, not a separate SSE channel → no per-page connection budget cost.
If you're adding a network call to a mount path, the bar is: "can the server have already given us this on the response that brought us here?" Almost always yes.
Building a new widget preset, step by step
// 1. preset.go: return a Builder with sensible defaults.
func Dropdown(name string) *widget.Builder {
return widget.New(name).
Mount(widget.TopLeft).
Hidden(). // click-to-open
Role("menu").
// …other defaults
}
// 2. host wires it once at startup.
def := preset.Dropdown("user-menu").
LabelledBy("user-menu-title").
Slot("body", ...).
Build()
widget.Mount(r, &def) // registers metadata + the three /style.css /state /chrome routes
// 3. trigger element in any screen.
<button data-cui-open="user-menu">Open</button>
// 4. (optional) deep link
preset.Modal("user-edit").
Hidden().
DeepLink("modal", "user-edit").
DeepLinkParam("user_id").
Slot("body", &UserEditForm{}).
Build()
// 5. (optional) server response triggers a toast
ui.AddToastSuccess(w, "Saved", "Your changes are persisted.", 5000)
w.WriteHeader(http.StatusNoContent)Verifying you got it right
Before claiming a component works:
- Lint:
go run ./cmd/check-cspis clean (no inlinestyle=/<script>). - Unit:
go test ./framework/ui/... ./core-ui/widget/...is green. - SSR inline:
curl http://localhost:8082/<page> | grep "<distinctive text from the slot>"returns ≥ 1 match. - Zero ghost network calls: open Playwright, click the trigger,
browser_network_requestsshows no/state, no/chrome, no/widgetsrequest fires per open (the registry fetch is once at boot). - Hydration roundtrip: opening + closing + reopening exercises both paths; verify nothing is detached or refetched.
- A11y, for backdrop'd surfaces:
role,aria-modal,aria-labelledbyset; focus moves in on open, traps via Tab, returns on close; body scroll locks while open. - Browser-verified: actually open the page in a browser before
claiming done.
go testpassing is necessary, not sufficient.
Interaction tests, not attribute tests
Attribute checks (role, aria-*, classes) are necessary but NEVER
sufficient. A component with the right role="combobox" and the right
aria-expanded="false" can be totally broken: the RPC might not fire,
the listbox might never open, Enter might pick the wrong option. Every
component PR must include chromedp e2e tests that:
- Click / type / press keys through every primary user flow.
- Assert DOM changes that prove the runtime hook actually ran:
- Combobox: type → option count goes from 0 to N,
aria-expandedflips to"true", Enter setsinput.valueto the picked option'sdata-value. - Tree: clicking the toggle (or pressing ArrowRight) flips
aria-expanded="true"AND populates<ul role="group">children. - CopyButton: click →
data-hui-copy-state="done"on the wrapper, thedata-hui-copy-statussibling reads the copy sentence (clear then frame); ifToastOnCopy=true, the toast stack receives the title. - ConfirmAction: trigger click → modal visible, Cancel autofocused; Esc → modal closed, modal stack empty.
- FilterChipBar: click × → chip count decreases by 1 (server-driven re-render via signal swap).
- SegmentedControl: click option N →
input:checkedvalue matches,getBoundingClientRect()of options are equal width.
- Combobox: type → option count goes from 0 to N,
- Use real keys:
chromedp/kb.ArrowDown,kb.Enter,kb.Escape, not literal ANSI escape strings. - Avoid timing flakes: use
chromedp.Sleepwith a window 2-3x the debounce-or-animation duration, not 100ms because "feels enough".
When the static-shape test passes but the interaction test fails, that's the bug you would have shipped without it. Always add both.
CSS contract: one registry, no manual wiring
Every styled package registers its stylesheet via
registry.RegisterStyle and wraps its top-level rendered element in
Style.WrapHTML(...). That covers framework/ui/*
and widget chrome. (core-ui/patterns/ is deleted; a composed
pattern is a framework/ui component on its framework/headless
primitive.)
The runtime emits a data-cui-comp="<name>" marker on the wrapper,
the SSR collector scans the rendered HTML, and CSS auto-loads: one
<link> per used component per page, dedup'd globally.
// framework/ui/foo.go: canonical component shape (on its headless
// primitive for the structure + accessibility contract)
var fooStyle = registry.RegisterStyle("ui-foo", fooCSS)
func fooCSS(_ style.Theme) string { return fooBaseCSS }
func Foo(cfg FooConfig) render.HTML {
return fooStyle.WrapHTML(headless.Foo(headless.FooProps{...}, classes))
}
const fooBaseCSS = `[data-cui-comp="ui-foo"] .fui-foo { ... }`Do NOT export func BaseCSS() string from a component package.
That was the legacy pattern contract: host apps had to import the
package AND concatenate BaseCSS() into their custom CSS, and a
single missed concat shipped a component without any styling on the
live site (the 2026-05-19 nestedlist incident).
Selectors stay class-based (.foo, .nested-list); the marker
only signals to the auto-loader "fetch this stylesheet". Apps don't
need any setup; the CSS just appears on every page that renders the
component.
Runtime-module contract: per-instance state + CSRF + a11y
Any component that ships a JavaScript counterpart in
core-ui/runtime/src/<name>.js follows three non-negotiable rules.
Module-scope globals are bugs waiting for the second instance to land.
1. Per-instance state, never module globals. Use a WeakMap
keyed by the wrapper element, plus a sibling Set for iteration:
var stateByEl = new WeakMap();
var active = new Set();
function setupOne(el) {
if (el.__fuiBound) return;
el.__fuiBound = true;
stateByEl.set(el, { failureCount: 0, timer: null });
active.add(el);
// …
}
document.addEventListener('gofastr:navigate', function () {
active.forEach(function (el) {
var s = stateByEl.get(el);
if (s && s.timer) clearInterval(s.timer);
// IntersectionObserver → call .disconnect(); EventSource → .close()
});
active.clear();
requestAnimationFrame(function () { scan(document); });
});2. CSRF token forwarding. State-changing fetches (POST / PUT
/ PATCH / DELETE) must forward the page's CSRF token:
var headers = { 'Accept': 'application/json' };
var meta = document.querySelector('meta[name="csrf-token"]');
if (meta && meta.getAttribute('content')) {
headers['X-CSRF-Token'] = meta.getAttribute('content');
}
fetch(url, { method: 'POST', credentials: 'same-origin', headers: headers });Apps emit the meta tag via uihost.WithHeadHTML(...) and verify the
token server-side. OptimisticAction's runtime is the canonical
example. Without this, any cross-origin form on a logged-in user's
browser can fire the action.
3. Pending-state a11y. Async clicks set aria-busy="true" +
disabled on the trigger element during the in-flight RPC and clear
both on commit / error / idle. Without this, keyboard Enter / Space
fires duplicates and screen readers don't announce the change.
4. Tear down rollback timers on re-entry. If your error path
schedules a setTimeout to revert state, store the timer id on the
button and clearTimeout it at the top of the next click handler.
The race is real: error → user clicks → new fetch goes pending →
the old 600ms timer fires → state clobbered back to idle while the
new RPC is still in flight.
Anti-patterns this skill exists to prevent
- ❌ Module-scope state in a runtime module; see the runtime-module contract above. The next demo will mount two of the widget and reveal the bug.
- ❌ State-changing fetches without
X-CSRF-Token; see the runtime- module contract. - ❌ Async triggers without
aria-busy/disabledduring pending; see the runtime-module contract. - ❌ Exporting
BaseCSS()from a component package. Useregistry.RegisterStyle+Style.WrapHTMLinstead. See the CSS contract section above. - ❌ Embedding full chrome HTML in
/__gofastr/widgetsJSON catalog. - ❌ Calling
/stateon mount when the widget has no signals. - ❌ Constructing DOM in the runtime when the server already rendered it.
- ❌ Opening per-page SSE for surfaces that fire once per session.
- ❌ Inline
style="…"attributes (strict CSP strips them). - ❌ "Open the modal client-side then hope SSR caught up". SSR-inline first.
- ❌ Hand-rolling
<button class="ui-btn …">(orclass="fui-button …") instead ofui.Button(...). The framework class isfui-button, emitted only by the class map insideui.Button/ui.LinkButton(with thedata-cui-compmarker so the CSS auto-loads; the marker and the sheet registration keep theui-buttonNAME).ui-btnIS NOT a thing; it renders unstyled native buttons. Always compose with the typed framework components. - ❌ Reading form data with
req.FormValue()when the runtime POSTs JSON.dispatchRPCserializes non-multipart forms as JSON (Content-Type: application/json); only manualURLSearchParamsPOSTs (SortableList's commit) are form-encoded. Use a helper that handles both. - ❌ Writing the response body before setting a custom header.
Go's
net/httpsends headers automatically on the firstWrite, silently dropping any laterw.Header().Set(...). Set headers FIRST. - ❌ Mounting Modal/Drawer/Popover presets without
.Pages("/route"): every page on the site pays for the chrome registration even if it'll never open them. Page-scope demo widgets.
Related skills
gofastr-ui: the broader SSR-with-hydration architecture this builds on.gofastr-docs: docs ship with the same commit as a new component.- Verify with pixels, not probes:
go test≠ "works in a browser" (see gofastr-ui + AGENTS.md Hard rule 9).
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.

