Write components ¶

Start here when writing UI. Use the component reference for the full contract, Tailwind for styling, and $cicadel-components as the reusable agent skill. The examples below are copied into a generated app and executed by TestComponentAuthoringGuide; they are not pseudocode.

Ask your agent ¶

text

Read https://cicadel.fauzaanu.com/en/dev/howto/component-authoring/index.md.
Add [screen] to my application using typed Cicadel components.
Inspect the current app structure, compose the page from explicit props and slots,
and connect its handler and route. Build the UI and test its rendered output.

Translate what you know ¶

React habit	Cicadel equivalent
Function component with typed props	Private `.templ` function; public `ui.Definition[Props, Slots]` contract
`<Card title="Hello">…</Card>`	`@Card.Call(CardProps{Title: "Hello"}, CardSlots{Children: ...})`
`children` / a ReactNode prop	`ui.Content` fields named `Children`, `Footer`, etc.
Fragment `<>…</>`	Private markup helper via `ui.Fragment(helper(...))`, or `ui.Group(...)`
`{title}`	`{ p.Title }` (text escapes automatically)
`{items.map(...)}`	A multiline Go `for` block
Conditional JSX	A multiline Go `if` or `switch` block
Default/destructured props	Go zero values plus a pure `Defaults` function
`className`, `htmlFor`	HTML `class`, `for`
Boolean HTML prop	`disabled?={ p.Disabled }`
Utility classes	Tailwind v4, complete class strings in source
Context provider / hook state	Explicit typed inputs; handlers load data and process POSTs
`onClick` / hydration	Not part of this server engine; use links/forms for server interactions
`key`	No reconciliation runtime, so no key prop; keep DOM IDs unique for labels

Think “props down, markup composed, HTML returned.” Cicadel borrows composition, not React’s JavaScript runtime. Do not introduce JSX, hooks, npm or a browser CDN script to author these components. Tailwind uses a pinned standalone build tool.

A complete card and list page ¶

Generate a project with module path example.com/componentguide, run go mod tidy, and install the CSS compiler once with go tool cicadel ui css install. Add the following files. Their package is an ordinary local Go app; no new module is needed.

Public contract: apps/dashboard/card.go ¶

package dashboard

import (
    "fmt"
    "github.com/fauzaanu/cicadel/ui"
)

type CardProps struct {
    Title string
    Tone string
}
type CardSlots struct { Children, Footer ui.Content }

var Card = ui.Definition[CardProps, CardSlots]{
    Name: "dashboard:card",
    Source: "apps/dashboard/card.templ",
    Defaults: func(p CardProps) CardProps {
        if p.Tone == "" { p.Tone = "neutral" }
        return p
    },
    Validate: func(p CardProps, s CardSlots) error {
        if err := ui.Required("Title", p.Title); err != nil { return err }
        if s.Children.Empty() { return fmt.Errorf("Children slot is required") }
        if p.Tone != "neutral" && p.Tone != "success" {
            return fmt.Errorf("unknown Tone %q", p.Tone)
        }
        return nil
    },
    Body: card,
}

func cardClasses(tone string) string {
    if tone == "success" { return "rounded-xl border border-emerald-300 bg-emerald-50 p-6" }
    return "rounded-xl border border-slate-200 bg-white p-6"
}

Zero Tone means neutral; zero Title or absent children is an error. Footer is optional. False/zero are not universally “missing.” Use pointer props only when omission must differ from a supplied false/zero. Defaults must not mutate objects referenced by caller-owned maps, slices, or pointers.

Markup: apps/dashboard/card.templ ¶

templ

package dashboard

templ card(p CardProps, s CardSlots) {
    <section class={ cardClasses(p.Tone) }>
        <h2 class="text-xl font-semibold text-slate-900">{ p.Title }</h2>
        <div class="mt-3 text-slate-700">@s.Children</div>
        if !s.Footer.Empty() {
            <footer class="mt-4 text-sm text-slate-500">@s.Footer</footer>
        }
    </section>
}

@s.Children inserts a typed fragment. { p.Title } inserts escaped text. They are deliberately different operations. Use complete literal utility names in Go variants; Tailwind cannot evaluate "bg-" + color + "-50".

Composition: apps/dashboard/page.templ ¶

templ

package dashboard

import "github.com/fauzaanu/cicadel/ui"
import "github.com/fauzaanu/cicadel/ui/layout"

templ itemFooter() {
    <a class="underline hover:text-indigo-600" href="/">Back to home</a>
}

templ dashboardBody(rows []Item) {
    <div class="mx-auto max-w-3xl space-y-6 px-6 py-12">
        <h1 class="text-3xl font-bold">Dashboard</h1>
        if len(rows) == 0 {
            <p>No items yet.</p>
        }
        for _, row := range rows {
            @Card.Call(CardProps{Title: row.Title, Tone: row.Tone}, CardSlots{
                Children: ui.Text(row.Description),
                Footer: ui.Fragment(itemFooter()),
            })
        }
    </div>
}

templ dashboardPage(rows []Item) {
    @layout.Page.Call(layout.Props{Title: "Dashboard", Stylesheet: "/static/app.css"},
        layout.Slots{Children: ui.Fragment(dashboardBody(rows))})
}

Private helpers need no separate public definition when they don’t declare a reusable validated contract. ui.Text is for request text; ui.Fragment adapts compiled markup, never strings. ui.Group combines already-typed fragments.

Handler and registration: apps/dashboard/app.go ¶

package dashboard

import (
    "context"
    "log/slog"
    "net/http"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/response"
    "github.com/fauzaanu/cicadel/ui"
    "github.com/fauzaanu/cicadel/urls"
)

type Item struct { Title, Description, Tone string }
type LoadItems func(context.Context) ([]Item, error)

func New(load LoadItems) cicadel.App {
    return cicadel.App{
        Name: "dashboard",
        Components: []ui.Export{Card.Export(1)},
        Routes: []urls.Route{urls.Path("GET", "/dashboard", "dashboard:index",
            func(w http.ResponseWriter, r *http.Request) {
                rows, err := load(r.Context())
                if err != nil { response.Error(w, 500); return }
                err = (ui.Renderer{}).HTML(r.Context(), w, 200, ui.Fragment(dashboardPage(rows)))
                if err != nil {
                    slog.ErrorContext(r.Context(), "render dashboard", "error", err)
                    if !ui.Committed(err) { response.Error(w, 500) }
                }
            }),
        },
    }
}

The loader is explicit and can query through your application’s DB; the component never discovers a request-wide map. Keep permissions in the handler/query scope. For the runnable demo, replace the starter’s empty app list with this loader:

package project

import (
    "context"
    "example.com/componentguide/apps/dashboard"
    "github.com/fauzaanu/cicadel"
    "gorm.io/gorm"
)

func InstalledApps(_ *gorm.DB) ([]cicadel.App, error) {
    return []cicadel.App{dashboard.New(func(ctx context.Context) ([]dashboard.Item, error) {
        return []dashboard.Item{{Title: "Ready", Description: "Typed props and slots work.", Tone: "success"}}, ctx.Err()
    })}, nil
}

For your own module, substitute its import path. Local direct calls to Card use that definition. For an overridable library, resolve through ComponentRegistry and inject the resulting definition into the page factory; see the override recipe.

Behavioral tests: apps/dashboard/app_test.go ¶

package dashboard

import (
    "context"
    "strings"
    "testing"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/apptest"
    "github.com/fauzaanu/cicadel/ui"
)

func TestDashboard(t *testing.T) {
    attack := `<script>alert("x")</script>`
    app := apptest.New(t, apptest.Settings(), []cicadel.App{
        New(func(context.Context) ([]Item, error) {
            return []Item{{Title: attack, Description: attack}}, nil
        }),
    })
    res := apptest.NewClient(app).Get(t, "/dashboard").Status(t, 200)
    res.Contains(t, `rel="stylesheet"`).Contains(t, `href="/static/app.css"`)
    res.Contains(t, "Back to home").Contains(t, "border-slate-200")
    if strings.Contains(string(res.Body), "<script>") { t.Fatal("unescaped input") }
}

func TestCardContractAndEmptyList(t *testing.T) {
    renderer := ui.Renderer{}
    if _, err := renderer.Render(t.Context(), Card.Call(CardProps{Title: "x"}, CardSlots{})); err == nil {
        t.Fatal("missing children accepted")
    }
    if _, err := renderer.Render(t.Context(), Card.Call(CardProps{Title: "x", Tone: "invalid"}, CardSlots{Children: ui.Text("x")})); err == nil {
        t.Fatal("invalid tone accepted")
    }
    out, err := renderer.Render(t.Context(), ui.Fragment(dashboardPage(nil)))
    if err != nil || !strings.Contains(string(out), "No items yet.") { t.Fatalf("%s: %v", out, err) }
}

Tests inspect behavior rather than accepting an entire HTML snapshot. Add assertions for your fields, labels, error relationships, links and authorization requirements.

The short edit loop ¶

go tool cicadel ui build
go tool cicadel ui check --json
go test -race ./...
go run manage.go check

Restart go run manage.go runserver to load rebuilt embedded markup/CSS. Commit .templ, ordinary Go, CSS input/config, generated Go and generated CSS together. ui check reports missing/stale artifacts; ui build fixes them. Do not hand-edit generated output. The initial starter CSS is already compiled, so first run does not download a compiler or require Node. After UI changes, install the tool once and rebuild. Installed library class sources belong in ui.css.json packages.

Common mistakes to avoid ¶

Write multiline if/for blocks, not JavaScript ternaries or inline JSX blocks.
Use class, not className; complete utility names, not dynamic name fragments.
ui.Merge merges tokens, not Tailwind conflict groups. p-2 p-6 does not promise that the last prop wins. Select a single spacing variant instead.
Pass slot values explicitly. { children... } is intentionally unsupported.
Keep CSS outside markup. Inline styles, scripts, event attributes and active SVG are not in the initial component contract; don’t work around that with raw HTML.
Preserve CSRF and accessible errors using ui/form, with explicit session tokens.
Fix failures in authored source. JSON diagnostics point to source components and preserve generated Go positions; never fix a type error in *_templ.go.

For targeted form/default/forwarding repairs, see the skill’s pattern reference.

Make the skill available to your coding agent ¶

The repository keeps the portable skill at skills/cicadel-components/, including its focused patterns and debugging reference. Repository AGENTS.md points agents to it for UI tasks. With Codex, copy that directory into ${CODEX_HOME:-$HOME/.codex}/skills/ (or use your skill installer), then invoke $cicadel-components. Keep the reference directory with SKILL.md; it does not require browser tools or a runtime plugin. Other coding agents can read the same Markdown instructions directly. Refresh/reopen the agent session if its skill catalog was loaded before installation.