diff --git a/.github/settings/README.md b/.github/settings/README.md
index 928fd27..74430ad 100644
--- a/.github/settings/README.md
+++ b/.github/settings/README.md
@@ -1,21 +1,23 @@
# Owner-applied repository settings
-This directory is a reviewable configuration, not proof that GitHub settings
-are active. An owner with repository administration access should apply the
-main ruleset once the contribution workflow is merged and its check names exist.
+The **Reviewed main contributions** ruleset was applied and read back as active
+on 2026-11-07 UTC ([view ruleset](https://github.com/Tend-Stack/TendUI/rules/26745168)).
+This records the verified setup date; GitHub remains the source of truth for
+current enforcement. Review the live rules before changing them.
+
+To update this existing ruleset after reviewing the JSON:
```sh
-gh api --method POST repos/Tend-Stack/TendUI/rulesets --input .github/settings/main-ruleset.json
+gh api --method PUT repos/Tend-Stack/TendUI/rulesets/26745168 --input .github/settings/main-ruleset.json
```
-Read existing rulesets first. If one already has this name, update it by its ID
-with PUT rather than creating duplicates. The ruleset requires DCO and all CI,
+Do not POST another copy. The ruleset requires DCO and all CI,
one approving code-owner review, dismissal of stale approvals, approval of the
latest push, resolved conversations and an up-to-date branch. It blocks force
pushes and deletion. Repository admins have an explicit PR-only bypass for
maintainer exceptions; record the reason in the PR and preserve contributor DCO.
-Also enable GitHub private vulnerability reporting and web commit sign-off,
+Separate settings still require verification: enable GitHub private vulnerability reporting and web commit sign-off,
disable squash/rebase merges to preserve commit trailers, and allow merge commits.
Require approval for fork workflows according to the organization's trust policy.
Never run untrusted fork code on private self-hosted runners or with deployment
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 59e0495..f9c98cf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -35,6 +35,10 @@ Identify significant generated material or reused sources in the PR description.
## Workflow
+Maintainers track both repositories in the shared [TendUI project](https://github.com/orgs/Tend-Stack/projects/2).
+The board is currently private while publication review is completed; use this
+repository's issues to propose work or report bugs.
+
1. Fork the repository and create a focused branch from current `main`.
2. Make the smallest complete change; keep unrelated cleanup separate.
3. Add proportionate tests and update documentation for changed behavior.
diff --git a/README.md b/README.md
index 101bd5b..a754ce0 100644
--- a/README.md
+++ b/README.md
@@ -1,43 +1,39 @@
-# TendUI
-
-
-
+
+
-**Beautiful interfaces. No build pipeline.**
+# Beautiful interfaces. No build pipeline.
-Pure CSS. Semantic HTML. No Node.js, no npm, no bundled JavaScript.
-First-class Go and templ support.
+Pure CSS. Semantic HTML. **No Node.js, no npm, no bundled JavaScript.**
+First-class Go and templ support, with styles embedded directly in your binary.
-Use the stylesheet with any HTML stack. In Go, `//go:embed` bundles the CSS
-inside your application: build and ship one executable, with no runtime asset
-downloads. Typed templ components and optional HTMX attributes are ready when
-you need them.
+[Documentation](https://tendui.com/docs) · [Component catalog](https://tendui.com/catalog) · [Playground](https://tendui.com/playground) · [Examples](https://tendui.com/examples)
-TendUI pairs original semantic CSS with composable Go components. Build
-interfaces with native HTML, typed configuration, and application-owned behavior.
+## Small pieces. A complete starting point.
-See [migration notes](docs/tendui-migration.md) for the renamed Go module, CSS
-namespace, and use with other HTML stacks.
+| Build with | What you get |
+| --- | --- |
+| **Any HTML stack** | One semantic stylesheet for native elements, forms, cards and layouts. |
+| **Go** | Embedded assets and a standard-library HTTP handler. Build and ship one executable. |
+| **templ** | Typed component props and composable content slots; generated Go ships with the module. |
+| **Optional HTMX** | Explicit request attributes and page/fragment helpers. Your app supplies the runtime. |
-## Install and run
+Light, dark and system themes. Responsive layouts. Configurable spacing and
+surfaces. Native interactions, keyboard access and bounded CSS motion.
-Requires **Go 1.26+**, matching the pinned `github.com/a-h/templ v0.3.1100`
-runtime. The asset package imports only the standard library; the components
-have one direct Go dependency, templ. It is not a literally dependency-free
-module, and this version does not support Go 1.21.
+## Get a page running
-Install the pinned TendUI preview (API changes remain possible before a stable release):
+Use **Go 1.26+** and the pinned preview:
```sh
go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.2
```
-Generated `*_templ.go` files ship with the module, so consumers do not need
-the templ CLI to use these components from Go.
-
-A complete `main.go`:
+The asset package uses only Go's standard library. Components use **templ
+v0.3.1100** as their one direct runtime dependency. No generator is required to
+consume the included components from Go; writing your own `.templ` files needs
+the matching templ generator.
```go
package main
@@ -55,12 +51,10 @@ func main() {
mux := http.NewServeMux()
mux.Handle(tendui.AssetPath, tendui.AssetHandler())
page := components.Layout(components.LayoutProps{
- Title: "My Go app",
- Language: "en",
- Theme: components.ThemeLight,
+ Title: "Hello, TendUI", Language: "en", Theme: components.ThemeLight,
}, components.Card(components.CardProps{
Body: components.Button(components.ButtonProps{
- Text: "Hello from Go", Primary: true,
+ Text: "Build something thoughtful", Primary: true,
}),
}))
mux.Handle("/", templ.Handler(page))
@@ -68,497 +62,36 @@ func main() {
}
```
-For a complete, tested Go/templ application, see [the quickstart](docs/quickstart.md)
-and [`examples/quickstart`](examples/quickstart). To use CSS with any stack, see
-[the plain HTML example](examples/html); Go and templ are optional for that path.
-
-Run the local demos, including a component playground, form lab, dashboard,
-appearance editor, workspace, native interactions, inline editing, motion and surfaces, and theme endpoint:
-
-```sh
-go run ./examples/basic -open
-```
-
-The `-open` flag opens `http://127.0.0.1:8080/playground` in your default Linux
-browser. See [the demo guide](examples/site/README.md) for all pages and test
-scenarios. The example deliberately blocks scripts with its
-Content Security Policy. Theme switching and the form work with JavaScript
-disabled.
-
-## Packages and assets
-
-```text
-tendui.go embedded CSS handler
-static/tendui.css readable semantic stylesheet
-components/
- layout.templ document, title, language, theme, stylesheet
- theme.templ native POST theme form with optional HTMX hooks
- buttons.templ buttons and button-styled links
- cards.templ article with optional header, body, footer
- forms.templ forms, inputs, selects, checkboxes, grids
- fields.templ composable labels, help/error bindings and input addons
- controls.templ textareas, radio groups, switches, file inputs
- feedback.templ alerts, badges, linked error summaries
- shell.templ application header, sidebar, main content
- overlays.templ native dialog and popover panels
- navigation.templ breadcrumbs and bounded pagination
- tables.templ data tables with column/row contracts and state slots
- wayfinding.templ page tabs, progress steps and native disclosures
- motion.templ typed one-shot entrance effects
- states.templ loading placeholders, empty states and metrics
- appearance.go typed settings, attributes, and CSS exports
- *_templ.go generated Go, included for consumers
-render/ buffered page/fragment HTTP responses
-examples/site/ thirteen demo pages, searchable catalog, preference cookies and downloads
-```
-
-Mount `AssetHandler()` directly at `/tendui/static/`. Do **not** apply
-`http.StripPrefix`: the handler already recognizes the complete path. It serves
-only `tendui.css`, supports GET/HEAD, conditional ETag requests and byte ranges,
-and returns 404 for directories and unknown assets. Revalidation prevents a
-browser from keeping stale CSS across binary upgrades. See the
-[asset delivery guide](docs/assets.md) for cache/proxy behavior, range requests
-and verification scope.
-
-## Components
-
-All text is escaped by templ. Link and form URLs use templ's safe URL handling.
-Keep URL destinations and HTMX endpoints application-controlled. Labels wrap
-controls, so an ID is optional and repeated components do not invent duplicate
-IDs. Supply meaningful labels for every input.
-
-```templ
-@components.Form(components.FormProps{
- Action: "/profile", Method: components.MethodPost,
- HxPost: "/profile", HxTarget: "#result", HxSwap: "innerHTML",
- HxIndicator: "#saving",
-}) {
- @components.Grid(components.GridProps{}) {
- @components.Input(components.InputProps{
- Name: "email", Label: "Email", Type: components.InputEmail,
- Required: true, Autocomplete: "email",
- })
- @components.Select(components.SelectProps{
- Name: "locale", Label: "Language", Value: "en",
- Options: []components.Option{
- {Label: "English", Value: "en"},
- {Label: "Español", Value: "es"},
- },
- })
- }
- @components.Checkbox(components.CheckboxProps{
- Name: "updates", Label: "Receive updates",
- })
- @components.Button(components.ButtonProps{
- Text: "Save", Type: components.ButtonTypeSubmit, Primary: true,
- })
- Saving…
-}
-
-```
-
-`ButtonProps`, `LinkProps`, and `FormProps` expose `HxGet`, `HxPost`, `HxTarget`,
-`HxSwap`, and `HxIndicator` directly. Set either HxGet or HxPost for a request,
-not both. Empty attributes are omitted. `Button` defaults to `type="button"`
-to avoid accidental submission; `Form` defaults to GET. Primary and Outline
-can be combined. Raw buttons use the primary color by default.
-
-`CardProps` accepts `Header`, `Body`, and `Footer` components. Cards also accept
-templ children after Body. Forms and grids use templ children. Pass ordinary
-components rather than `templ.Raw` for untrusted content.
-Cards can optionally override the page's shadow with `ElevationFlat`,
-`ElevationSubtle`, `ElevationRaised`, or `ElevationFloating`. The zero value
-inherits the page setting. See [surface elevation](docs/motion.md#elevation)
-for theme tokens, nesting, outlined cards and accessibility behavior.
-
-## Appearance and application components
-
-Appearance choices are independent. The zero value preserves the original
-Indigo, comfortable, rounded defaults:
-
-```go
-appearance := components.Appearance{
- Preset: components.PresetForest,
- Density: components.DensityCompact,
- Corners: components.CornersSoft,
- Typography: components.TypographySans,
- TextSize: components.TextStandard,
- Width: components.WidthWide,
- Elevation: components.ElevationFlat,
-}
-page := components.Layout(components.LayoutProps{
- Title: "My workspace",
- Theme: components.ThemeDark,
- Appearance: appearance,
-}, body)
-```
-
-Available presets: Indigo, Neutral, Forest, Rose. Choose comfortable/compact
-spacing, rounded/nearly-square/soft corners, system sans/serif/monospace fonts,
-standard/large text, narrow/standard/wide content, and flat/subtle/raised/floating shadows.
-No font downloads are needed. Light/dark/system mode remains an independent
-`LayoutProps.Theme` setting.
+Follow the [tested Go/templ quickstart](docs/quickstart.md), or start with
+[plain HTML and CSS](examples/html) with no Go dependency. Run the full local
+showcase with `go run ./examples/basic -open`.
-`Appearance.Normalize()` validates preferences and falls back to defaults.
-`Attributes()` produces native `data-*` attributes for applications that own
-their document shell. `CSS()` exports overrides referencing TendUI's canonical
-tokens, so it **requires tendui.css** and must be loaded after it. CSS exports
-configure appearance; keep light/dark/system mode on the root HTML element.
-`LayoutProps.Head` accepts trusted application components after the base
-stylesheet, for custom stylesheet links or metadata.
+## Explore your next step
-Open `/settings` in the demo to preview, save, reset, and download appearance
-settings. `/appearance.css` and `/appearance.go` export the selected settings.
-The library owns no persistence; the example uses bounded, validated preference
-cookies. Query previews take precedence over saved preferences without changing
-them. Cookie data never controls authorization or application behavior.
-
-New components:
-
-| Component | Contract |
+| I want to… | Start here |
| --- | --- |
-| `Badge(BadgeProps)` | Text plus neutral/info/success/warning/danger tone |
-| `Alert(AlertProps)` | Title, message, optional children; `Live` opts into announcements |
-| `ErrorSummary(ErrorSummaryProps)` | Error messages linked to application-supplied field IDs |
-| `Textarea(TextareaProps)` | Label, value, rows, maximum length, required/disabled/read-only/error states |
-| `RadioGroup(RadioGroupProps)` | Native fieldset/legend and labeled options sharing one name |
-| `Switch(SwitchProps)` | Native checkbox with switch semantics and keyboard interaction |
-| `FileInput(FileInputProps)` | Native file chooser with accept/multiple/required states |
-| `AppShell(AppShellProps)` | Brand, actions, sidebar links, optional footer, and one main landmark |
-
-`CheckboxProps` now also supports `Invalid` and `DescribedBy`. Use
-`FormProps{Method: components.MethodPost, Multipart: true}` for actual uploads.
-Applications must validate file types, bound request sizes, and handle storage;
-the `accept` attribute is only a browser hint. The playground file picker does
-not upload data.
-
-Static alerts do not create live regions. Set `Live: true` for inserted feedback:
-danger uses `role="alert"`; other tones use `role="status"`. These attributes
-do not guarantee announcements on a full page navigation, so visible error
-summaries and linked field errors remain available.
-
-Use `AppShell` as the body inside `Layout`, with page content as templ children.
-It owns the main landmark; do not nest another main or application shell inside
-it. `MainID` defaults to `main` and connects the skip link. Sidebar navigation
-uses a native disclosure that works on desktop and mobile without JavaScript.
-See `/workspace` and `examples/site/workspace.templ` for a complete example.
-
-## Native interactions and navigation
-
-`Dialog` and `Popover` use native HTML. Supply a nonempty ID with no whitespace;
-invalid IDs return a render error. IDs must be unique within the document, and
-their `-title` and `-description` suffixes are reserved for accessible labels.
-
-```templ
-@components.Button(components.ButtonProps{
- Text: "Review request",
- CommandFor: "review-request",
- Command: components.DialogShowModal,
-})
-@components.Dialog(components.DialogProps{
- ID: "review-request", Title: "Review request",
- Description: "Check the details before submitting.",
-}) {
- @components.Form(components.FormProps{
- Action: "/requests/approve", Method: components.MethodPost,
- }) {
- @components.Button(components.ButtonProps{
- Text: "Approve", Type: components.ButtonTypeSubmit,
- })
- }
-}
-```
-
-Keep dialogs outside other forms. The dialog includes a native `method="dialog"`
-close form and initially focuses that non-destructive close control. Closing a
-dialog does not submit an application request; use a separate normal form for
-an action that must reach Go. Native opener/closer fields on Button always force
-`type="button"`, even if Type was set to submit. Unsupported command values
-produce an inert button. Do not combine native commands and HTMX requests on
-the same control.
-
-Modal opening uses the newer `commandfor`/`command="show-modal"` attributes.
-Provide an ordinary-page alternative for unsupported browsers, as `/interactions`
-does. No JavaScript fallback is injected. See the browser's
-[native dialog commands](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#modal_dialogs_using_invoker_commands).
-
-For popovers, use `ButtonProps{PopoverTarget: "help"}` and
-`Popover(PopoverProps{ID: "help", Title: "Help"})` with templ children. The default
-automatic mode supports dismissal outside the panel; `Mode: PopoverManual`
-requires an explicit close/toggle action. Both variants include a close button.
-`PopoverAction` supports Toggle, Show, and Hide. Panels are non-modal, centered
-by default, and do not claim ARIA menu semantics. Unsupported browsers may show
-the content inline. See the [native popover attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover).
-
-`Breadcrumbs(BreadcrumbsProps{Items: ...})` renders ancestor links and a final,
-non-linked current page. Separators are hidden from assistive technology.
-
-`Pagination(PaginationProps{Page: page, TotalPages: total, URLForPage: pageURL})`
-renders normal links, current/disabled states, and a bounded page window with
-ellipses. Zero/one-page results omit the navigation. Current page numbers are
-clamped to range; a missing URL callback for multiple pages returns a render
-error. The application supplies totals, page data, and URLs that retain its
-filters. No database, router, or query convention is imposed by the component.
-Labels can be localized through the props.
-
-The dashboard example demonstrates filter → sort → paginate on a request-owned
-copy of sample records. Page URLs preserve search, status, sorting, page size,
-and appearance query settings. Invalid or excessive page numbers are normalized;
-empty results keep their recovery link.
-
-## Themes and the zero-JavaScript contract
-
-Set `LayoutProps.Theme` to `ThemeLight` or `ThemeDark` to emit the root
-`data-theme` attribute. Leave it at `ThemeSystem` (the empty default) to follow
-`prefers-color-scheme`. Override `--tendui-*` properties in your own CSS loaded
-after TendUI. Dark tokens have no effect on explicitly light pages.
-
-`ThemeToggle()` renders a small native form that POSTs to `/api/theme/toggle`.
-Place it **outside other forms**. You can pass `ThemeToggleProps` for a localized
-label and your application's CSRF token. The consumer owns cookies, request
-protection, routing, and page rendering; the library has no global theme state.
-
-The included endpoint alternates a validated `light`/`dark` cookie and returns
-303 to the current demo when its same-origin Referer is available, otherwise to
-the homepage. Cookies are HttpOnly, SameSite=Strict, and Secure over TLS;
-the example uses Go's cross-origin request protection. Behind a TLS-terminating
-proxy, configure your application's Secure-cookie policy explicitly. The first
-example visit uses light so the server can deterministically toggle it; the
-library's system theme remains available for applications that prefer it.
-
-The button preserves the requested `hx-post="/api/theme/toggle"`,
-`hx-target="html"`, and `hx-swap="outerHTML"` attributes. These are inert without
-HTMX. **HTMX itself is JavaScript** and is never included or loaded by TendUI.
-Consumers that already use it can use the hooks without writing custom JS.
-
-A document root swap is not a reliable way to replace a page's root attributes
-and head. The example detects `HX-Request: true` and sends **200 plus
-`HX-Redirect` to the cleaned demo URL** after setting the cookie. This requests a
-full navigation. Both native and HTMX paths remove the `theme` query parameter
-so a previous preview cannot override the new cookie, while preserving other
-settings. For HTMX, a validated same-origin `HX-Current-URL` takes precedence over
-Referer; invalid values fall back to a validated Referer, then the homepage.
-Only known demo pages are accepted. These headers control presentation, not access.
-HTMX does not process its response headers on 3xx responses. See the upstream
-[redirect header documentation](https://htmx.org/headers/hx-redirect/) and
-[swap reference](https://htmx.org/attributes/hx-swap/).
-The isolated browser consumer verifies this navigation with HTMX 2.0.11 in
-Chromium, Firefox and WebKit. The runtime is a test dependency and is not bundled.
-
-## Full pages and optional HTMX fragments
-
-`render` is a standard-library-only package. Its small `Component` interface is
-implemented by templ components; no adapter or additional dependency is needed.
-Use the same route for ordinary navigation and partial updates:
-
-```go
-import (
- "log"
- "net/http"
-
- "github.com/Tend-Stack/TendUI/v2026/components"
- "github.com/Tend-Stack/TendUI/v2026/render"
-)
-
-func profileHandler(w http.ResponseWriter, r *http.Request) {
- panel := components.Alert(components.AlertProps{Title: "Profile", Message: "Your profile is ready."})
- page := components.Layout(components.LayoutProps{Title: "Profile"}, panel)
- w.Header().Set("Cache-Control", "private, no-store")
- if err := render.HTML(w, r, http.StatusOK, page, panel); err != nil {
- log.Printf("render profile: %v", err)
- }
-}
-```
-
-`HTML` chooses the fragment for `HX-Request: true`, but serves the full page for
-history restoration or boosted navigation. A nil fragment always serves the page.
-It preserves existing `Vary` values and adds the three headers that affect the
-representation. Rendering is buffered so a component error produces a generic
-500 instead of partially written HTML; errors are returned for logging. HEAD
-has no body, including on failures. After calling it, do not write another error
-response: a render failure has already sent 500, and a transport failure may
-have committed the response. Only the selected component is rendered.
-
-The helper leaves authentication, CSRF protection, cache policy, CSP and status
-selection to the application. HTMX headers are presentation hints, never proof
-of identity or permission. For cacheable pages, use representation-specific ETags.
-Buffering is intended for bounded UI pages/fragments, not streaming responses.
-
-The [inline editing example](examples/site/editing.go) pairs native form actions
-and link destinations with `HxPost`/`HxGet`, `HxTarget` and `HxSwap`. It returns
-303 after a successful native POST and 200 with the updated panel for an HTMX
-request. Invalid native submissions return 422. Invalid HTMX submissions return
-200 **with field errors and no save**, because default HTMX does not swap 422
-responses. This policy is explicit in the example, not imposed by `render.HTML`.
-See the upstream [response handling](https://htmx.org/docs/#response-handling),
-[history](https://htmx.org/docs/#history) and
-[caching](https://htmx.org/docs/#caching) documentation.
-
-The included demo remains JavaScript-free and blocks scripts with CSP. Its native
-flow and HTTP fragment contract are testable separately. Applications enabling
-HTMX must supply their own runtime and appropriate CSP; this project neither
-loads nor bundles it. The example cookie is unsigned cosmetic sample data,
-validated and escaped on every read. It is not an account/session implementation.
-
-## Motion, surfaces and useful states
-
-Cards now accept typed `Surface`, `Entry`, `Delay` and `HoverLift` options.
-Choose tinted, outlined or gradient borders; use fade, rise or scale entrances.
-`Reveal` wraps other content with the same entrance system. `Skeleton`,
-`EmptyState` and `Stat` cover loading, recovery and metric presentation.
-
-`Appearance.Motion` accepts `MotionSystem` (default) or `MotionOff`. System mode
-respects OS reduced motion. Off also disables hover displacement; CSS/Go exports
-include the choice. Entrances run once, and loading decoration stops after three
-cycles. All styling stays in the embedded CSS, with no runtime dependency.
-
-See [the motion guide](docs/motion.md), try `/motion`, and track the broader
-[product roadmap](ROADMAP.md). See the [recorded browser results](docs/release-verification.md).
-
-## Data tables and navigation patterns
-
-`DataTable` provides semantic headers/row scopes, application-owned sort URLs,
-cell component slots, striped/compact styles, and loading/empty states. The
-Dashboard uses it for bidirectional sorting and native checkbox selection review.
-`Tabs` supplies ordinary page navigation; `Steps` labels application-owned
-progress; `Disclosure` uses native details/summary with optional grouping.
-
-See the [data and navigation guide](docs/data-navigation.md) and `/patterns`
-for composition rules, working examples and validation boundaries.
-
-## Composable fields and multi-step forms
-
-`Field` pairs a raw control with its label, description and error through typed
-`FieldProps.ControlAttributes()`. `InputGroup` adds text prefixes/suffixes while
-preserving native control behavior. `ButtonProps.FormNoValidate` supports Back
-actions that submit edits without native constraints blocking navigation.
-
-The `/wizard` project-brief example preserves draft values across Back/Continue,
-checks all submitted fields on completion, and shows a validated preview without
-creating or storing a project. See [the form guide](docs/forms.md) for composition,
-validation and workflow ownership rules.
-
-The `/uploads` example connects the native file chooser to a bounded Go CSV
-preview: download a sample, upload up to 64 KiB/50 rows, and inspect validated
-results or line-specific errors. Uploaded content stays in request memory;
-nothing is saved or imported. See the form guide for limits and HTTP behavior.
-
-## Accessibility and print
-
-Palette checks cover all built-in presets across page, card and subtle surfaces.
-Print uses a neutral palette independent of the screen theme, with readable
-outlined actions and native checkbox rendering for switches. See the
-[accessibility and print guide](docs/accessibility.md) for the measured scope,
-customization rules and browser checks still required.
-
-## Layout composition
-
-`Stack` provides vertical rhythm; `Cluster` wraps actions and other related items
-into rows. Typed gap and alignment props use a density-aware spacing scale,
-preserve document order, and compose with Grid, Card and native forms. Existing
-CSS utilities retain their behavior. Try `/patterns?section=composition` or read
-[the layout guide](docs/layout.md) for spacing tokens, semantics and examples.
-
-## Reading content
-
-`Prose` styles application-owned HTML for help pages, guides and release notes.
-Choose a typed reading measure, use native headings/lists/code, and opt embedded
-widgets out of prose typography. Try `/patterns?section=reading` and see the
-[reading-content guide](docs/prose.md) for tokens, semantics and examples.
-
-## Inline icons
-
-The Icon component provides 24 original SVG drawings, compiled into Go and
-rendered inline. They inherit text color and use no external image or font files.
-Button and Link accept optional `IconBefore`, `IconAfter` and `AriaLabel` fields.
-Icon-only actions require an explicit accessible name; decorative icons stay
-hidden from assistive technology. Explore `/catalog/icon` and the
-[icon guide](docs/icons.md) for sizes, composition and verification limits.
-
-## Searchable component catalog
-
-Open `/catalog` to browse all 37 public templ components by name, category or
-usage notes. Each entry provides a preview, guidance and a downloadable `.templ`
-recipe drawn from the same source compiled for that preview. Layouts open as
-standalone pages to preserve document landmarks. Search and pagination use Go
-requests; no client runtime or external assets are added.
-
-Catalog-only CSS and recipe source are embedded in the example executable, not
-the library stylesheet. See [the catalog guide](docs/catalog.md) for recipe
-adaptation, coverage checks and validation boundaries.
-
-## Maintaining the library
-
-Only contributors changing `.templ` files need the generator:
-
-```sh
-go install github.com/a-h/templ/cmd/templ@v0.3.1100
-templ fmt .
-templ generate
-go test -race ./...
-go vet ./...
-```
-
-Commit generated Go alongside its source. A normal Go build consumes CSS
-directly through `go:embed`; CSS editing needs no asset build step. Test output
-belongs under `tests/results/` and is ignored except for its placeholder.
-
-The Go-only developer tool also checks generated-source consistency, compiles
-all catalog downloads independently, records benchmarks and builds the versioned
-review executable. See [the development guide](docs/development.md) and
-[measured performance](docs/performance.md):
-
-```sh
-go run ./cmd/tendui-dev check
-go run ./cmd/tendui-dev api
-go run ./cmd/tendui-dev generated
-go run ./cmd/tendui-dev recipes
-go run ./cmd/tendui-dev bench
-go run ./cmd/tendui-dev build
-./tests/results/demos/tendui-demo -version
-```
-
-`check` already includes `api`; the separate command is useful during API review.
-The checked-in declaration baseline catches changed props, constants, signatures
-and method sets. See [API review and migration](docs/api-compatibility.md) for
-intentional updates and the limits of this check.
-
-The [CI matrix](docs/ci.md) checks native Linux, macOS and Windows with Go 1.26.0
-and 1.27.3, plus a vulnerability scan. Browser checks cover Chromium, Firefox and
-WebKit. These jobs must pass on the preview source; see
-[preview release notes](docs/releases/2026.2.0-preview.2.md). The older
-[release verification](docs/release-verification.md) documents the pre-rename
-release only and is not evidence for the current preview.
-
-Versions follow `YEAR.RELEASE.FIX`, with SemVer prerelease suffixes for previews:
-`v2026.2.0-preview.2`. Install the explicit tag; a preview is not a stable API promise.
-Development builds use `git describe --tags --long --dirty`.
-
-Go treats 2026 as the semantic major version, so the module path ends in
-`/v2026`. A new annual line such as 2027 will need `/v2027` and consumer import
-updates. Fixes and previews on the 2026 line retain `/v2026`.
-
-## Project links
-
-- Source and issues: https://github.com/Tend-Stack/TendUI
-- Website source: https://github.com/Tend-Stack/TendUI-web
-
-Fetch and integrate GitHub `main` before contributing. See `HANDOFF.md` for the
-current development entry points and remaining release checks.
+| Find a component and copy a recipe | [Live catalog](https://tendui.com/catalog) |
+| Customize themes, forms and layouts | [Library guide](docs/library-guide.md) |
+| Test interactions and appearance | [Playground](https://tendui.com/playground) · [Motion and surfaces](https://tendui.com/motion) |
+| Work with Codex or Claude Code | [Agent setup](docs/agents.md) |
+| Add TendUI to an application | [Integration guide](docs/tendui-migration.md) |
+| Understand compatibility and verification | [API policy](docs/api-compatibility.md) · [Development guide](docs/development.md) |
-## License
+## Preview, with clear boundaries
-MIT. See [LICENSE](LICENSE).
+This is a preview; APIs may change before a stable release. Install a fixed
+version and review [release notes](docs/releases/2026.2.0-preview.2.md) when
+upgrading. Versions follow `YEAR.RELEASE.FIX`, with `-preview.N` for previews.
+The Go module uses `/v2026` for the 2026 major-version line.
-## Contributing
+Your application owns routing, authentication, request protection, persistence
+and sessions. HTMX is optional and requires application-supplied JavaScript.
-See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, review and MIT + DCO sign-off.
-Report vulnerabilities privately using [SECURITY.md](SECURITY.md); community
-participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+## Build with us
-## Coding agents
+Contributions are welcome under **MIT + DCO**. Contributors retain copyright;
+a human reviews and signs off every contribution. Start with
+[CONTRIBUTING.md](CONTRIBUTING.md), [open issues](https://github.com/Tend-Stack/TendUI/issues),
+or the [coding-agent instructions](AGENTS.md). `CLAUDE.md` imports the same guidance.
-Repository contributors should read [AGENTS.md](AGENTS.md); `CLAUDE.md` imports
-the same instructions for Claude Code. For applications using TendUI, see
-[the coding-agent guide](https://tendui.com/docs/agents) and merge its suggested
-section into your own project instructions.
+[Security reports](SECURITY.md) · [Code of conduct](CODE_OF_CONDUCT.md) · [MIT license](LICENSE) · [Website source](https://github.com/Tend-Stack/TendUI-web)
diff --git a/ROADMAP.md b/ROADMAP.md
index 28ed687..b37248c 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -70,7 +70,7 @@ stable-URL cache contract and distinguishes in-process checks from live delivery
The current preview has a complete documentation website, shared
component catalog, examples and playground, plus passing native, security and
browser verification. See [release verification](docs/release-verification.md)
-for historical pre-rename evidence. Current preview details are in
+for the published preview evidence. Preview details are in
[preview release notes](docs/releases/2026.2.0-preview.2.md).
The development tracks below describe continuing product work beyond this baseline.
diff --git a/docs/accessibility.md b/docs/accessibility.md
index 32f528e..20a3167 100644
--- a/docs/accessibility.md
+++ b/docs/accessibility.md
@@ -69,8 +69,8 @@ separate complete document when that is needed.
Custom print styling can override TendUI's important print palette with matching
important declarations in a later print stylesheet. Review the result with both
background-graphics settings. The tests guard source rules and palette ratios;
-the v2026.1.0 dashboard PDF was also reviewed for pagination, readable controls
-and background omission. This does not establish every page/theme combination.
+review rendered PDFs for pagination, readable controls and background omission.
+Automated source checks do not establish every page/theme combination.
## Consumer review matrix
diff --git a/docs/brand/README.md b/docs/brand/README.md
index 0028295..3444a59 100644
--- a/docs/brand/README.md
+++ b/docs/brand/README.md
@@ -10,3 +10,11 @@ The website repository prepares the favicon, social previews and downloadable
web assets. See `https://tendui.com/brand/github-social-preview.png` for the
1280 × 640 GitHub social preview image. Uploading a social preview in repository
settings is separate from displaying the README logo.
+
+## README banners
+
+The light and dark README banners are copied unchanged from the owner-supplied
+Tend UI Gopher Brand Kit. Source names, byte sizes and SHA-256 hashes are recorded
+in [readme-banners.json](readme-banners.json). They are documentation assets and
+are not embedded into the runtime stylesheet or website executable. The README
+uses a `picture` element to follow the reader's preferred color scheme.
diff --git a/docs/brand/readme-banner-dark.png b/docs/brand/readme-banner-dark.png
new file mode 100644
index 0000000..ef92e1c
Binary files /dev/null and b/docs/brand/readme-banner-dark.png differ
diff --git a/docs/brand/readme-banner-light.png b/docs/brand/readme-banner-light.png
new file mode 100644
index 0000000..86ca331
Binary files /dev/null and b/docs/brand/readme-banner-light.png differ
diff --git a/docs/brand/readme-banners.json b/docs/brand/readme-banners.json
new file mode 100644
index 0000000..ebee64d
--- /dev/null
+++ b/docs/brand/readme-banners.json
@@ -0,0 +1,16 @@
+[
+ {
+ "file": "readme-banner-dark.png",
+ "source": "03_web_and_social/illustrated-header-dark-1800x420.png",
+ "processing": "Copied unchanged from the owner-supplied Tend UI Gopher Brand Kit",
+ "sha256": "abfccb9cfa2169c767a213eb8fd57c07fe18984d95f917ec1731941c89293eea",
+ "bytes": 129454
+ },
+ {
+ "file": "readme-banner-light.png",
+ "source": "03_web_and_social/illustrated-header-light-1600x400.png",
+ "processing": "Copied unchanged from the owner-supplied Tend UI Gopher Brand Kit",
+ "sha256": "7a3e7ecc43532cb70d2127efefe2ddb4d9174c0af377d9d94f7d5a9d7f70ecd3",
+ "bytes": 123912
+ }
+]
diff --git a/docs/ci.md b/docs/ci.md
index 7638025..d69d6ed 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -124,5 +124,5 @@ assets. The workflow retains its reports for seven days.
Published-tag consumer installation and browser checks are independent release
gates. In-process HTTP tests and cross-compilation do not replace browser review.
-See [release verification](release-verification.md) for the v2026.1.0 exact-commit
+See [release verification](release-verification.md) for the supported preview's exact-commit
native, security, browser and published-tag installation results.
diff --git a/docs/library-guide.md b/docs/library-guide.md
new file mode 100644
index 0000000..f50a648
--- /dev/null
+++ b/docs/library-guide.md
@@ -0,0 +1,455 @@
+# TendUI library guide
+
+[Back to the project](../README.md) · [Quickstart](quickstart.md) · [Live catalog](https://tendui.com/catalog)
+
+## Packages and assets
+
+```text
+tendui.go embedded CSS handler
+static/tendui.css readable semantic stylesheet
+components/
+ layout.templ document, title, language, theme, stylesheet
+ theme.templ native POST theme form with optional HTMX hooks
+ buttons.templ buttons and button-styled links
+ cards.templ article with optional header, body, footer
+ forms.templ forms, inputs, selects, checkboxes, grids
+ fields.templ composable labels, help/error bindings and input addons
+ controls.templ textareas, radio groups, switches, file inputs
+ feedback.templ alerts, badges, linked error summaries
+ shell.templ application header, sidebar, main content
+ overlays.templ native dialog and popover panels
+ navigation.templ breadcrumbs and bounded pagination
+ tables.templ data tables with column/row contracts and state slots
+ wayfinding.templ page tabs, progress steps and native disclosures
+ motion.templ typed one-shot entrance effects
+ states.templ loading placeholders, empty states and metrics
+ appearance.go typed settings, attributes, and CSS exports
+ *_templ.go generated Go, included for consumers
+render/ buffered page/fragment HTTP responses
+examples/site/ thirteen demo pages, searchable catalog, preference cookies and downloads
+```
+
+Mount `AssetHandler()` directly at `/tendui/static/`. Do **not** apply
+`http.StripPrefix`: the handler already recognizes the complete path. It serves
+only `tendui.css`, supports GET/HEAD, conditional ETag requests and byte ranges,
+and returns 404 for directories and unknown assets. Revalidation prevents a
+browser from keeping stale CSS across binary upgrades. See the
+[asset delivery guide](assets.md) for cache/proxy behavior, range requests
+and verification scope.
+
+## Components
+
+All text is escaped by templ. Link and form URLs use templ's safe URL handling.
+Keep URL destinations and HTMX endpoints application-controlled. Labels wrap
+controls, so an ID is optional and repeated components do not invent duplicate
+IDs. Supply meaningful labels for every input.
+
+```templ
+@components.Form(components.FormProps{
+ Action: "/profile", Method: components.MethodPost,
+ HxPost: "/profile", HxTarget: "#result", HxSwap: "innerHTML",
+ HxIndicator: "#saving",
+}) {
+ @components.Grid(components.GridProps{}) {
+ @components.Input(components.InputProps{
+ Name: "email", Label: "Email", Type: components.InputEmail,
+ Required: true, Autocomplete: "email",
+ })
+ @components.Select(components.SelectProps{
+ Name: "locale", Label: "Language", Value: "en",
+ Options: []components.Option{
+ {Label: "English", Value: "en"},
+ {Label: "Español", Value: "es"},
+ },
+ })
+ }
+ @components.Checkbox(components.CheckboxProps{
+ Name: "updates", Label: "Receive updates",
+ })
+ @components.Button(components.ButtonProps{
+ Text: "Save", Type: components.ButtonTypeSubmit, Primary: true,
+ })
+ Saving…
+}
+
+```
+
+`ButtonProps`, `LinkProps`, and `FormProps` expose `HxGet`, `HxPost`, `HxTarget`,
+`HxSwap`, and `HxIndicator` directly. Set either HxGet or HxPost for a request,
+not both. Empty attributes are omitted. `Button` defaults to `type="button"`
+to avoid accidental submission; `Form` defaults to GET. Primary and Outline
+can be combined. Raw buttons use the primary color by default.
+
+`CardProps` accepts `Header`, `Body`, and `Footer` components. Cards also accept
+templ children after Body. Forms and grids use templ children. Pass ordinary
+components rather than `templ.Raw` for untrusted content.
+Cards can optionally override the page's shadow with `ElevationFlat`,
+`ElevationSubtle`, `ElevationRaised`, or `ElevationFloating`. The zero value
+inherits the page setting. See [surface elevation](motion.md#elevation)
+for theme tokens, nesting, outlined cards and accessibility behavior.
+
+## Appearance and application components
+
+Appearance choices are independent. The zero value preserves the original
+Indigo, comfortable, rounded defaults:
+
+```go
+appearance := components.Appearance{
+ Preset: components.PresetForest,
+ Density: components.DensityCompact,
+ Corners: components.CornersSoft,
+ Typography: components.TypographySans,
+ TextSize: components.TextStandard,
+ Width: components.WidthWide,
+ Elevation: components.ElevationFlat,
+}
+page := components.Layout(components.LayoutProps{
+ Title: "My workspace",
+ Theme: components.ThemeDark,
+ Appearance: appearance,
+}, body)
+```
+
+Available presets: Indigo, Neutral, Forest, Rose. Choose comfortable/compact
+spacing, rounded/nearly-square/soft corners, system sans/serif/monospace fonts,
+standard/large text, narrow/standard/wide content, and flat/subtle/raised/floating shadows.
+No font downloads are needed. Light/dark/system mode remains an independent
+`LayoutProps.Theme` setting.
+
+`Appearance.Normalize()` validates preferences and falls back to defaults.
+`Attributes()` produces native `data-*` attributes for applications that own
+their document shell. `CSS()` exports overrides referencing TendUI's canonical
+tokens, so it **requires tendui.css** and must be loaded after it. CSS exports
+configure appearance; keep light/dark/system mode on the root HTML element.
+`LayoutProps.Head` accepts trusted application components after the base
+stylesheet, for custom stylesheet links or metadata.
+
+Open `/settings` in the demo to preview, save, reset, and download appearance
+settings. `/appearance.css` and `/appearance.go` export the selected settings.
+The library owns no persistence; the example uses bounded, validated preference
+cookies. Query previews take precedence over saved preferences without changing
+them. Cookie data never controls authorization or application behavior.
+
+New components:
+
+| Component | Contract |
+| --- | --- |
+| `Badge(BadgeProps)` | Text plus neutral/info/success/warning/danger tone |
+| `Alert(AlertProps)` | Title, message, optional children; `Live` opts into announcements |
+| `ErrorSummary(ErrorSummaryProps)` | Error messages linked to application-supplied field IDs |
+| `Textarea(TextareaProps)` | Label, value, rows, maximum length, required/disabled/read-only/error states |
+| `RadioGroup(RadioGroupProps)` | Native fieldset/legend and labeled options sharing one name |
+| `Switch(SwitchProps)` | Native checkbox with switch semantics and keyboard interaction |
+| `FileInput(FileInputProps)` | Native file chooser with accept/multiple/required states |
+| `AppShell(AppShellProps)` | Brand, actions, sidebar links, optional footer, and one main landmark |
+
+`CheckboxProps` now also supports `Invalid` and `DescribedBy`. Use
+`FormProps{Method: components.MethodPost, Multipart: true}` for actual uploads.
+Applications must validate file types, bound request sizes, and handle storage;
+the `accept` attribute is only a browser hint. The playground file picker does
+not upload data.
+
+Static alerts do not create live regions. Set `Live: true` for inserted feedback:
+danger uses `role="alert"`; other tones use `role="status"`. These attributes
+do not guarantee announcements on a full page navigation, so visible error
+summaries and linked field errors remain available.
+
+Use `AppShell` as the body inside `Layout`, with page content as templ children.
+It owns the main landmark; do not nest another main or application shell inside
+it. `MainID` defaults to `main` and connects the skip link. Sidebar navigation
+uses a native disclosure that works on desktop and mobile without JavaScript.
+See `/workspace` and `examples/site/workspace.templ` for a complete example.
+
+## Native interactions and navigation
+
+`Dialog` and `Popover` use native HTML. Supply a nonempty ID with no whitespace;
+invalid IDs return a render error. IDs must be unique within the document, and
+their `-title` and `-description` suffixes are reserved for accessible labels.
+
+```templ
+@components.Button(components.ButtonProps{
+ Text: "Review request",
+ CommandFor: "review-request",
+ Command: components.DialogShowModal,
+})
+@components.Dialog(components.DialogProps{
+ ID: "review-request", Title: "Review request",
+ Description: "Check the details before submitting.",
+}) {
+ @components.Form(components.FormProps{
+ Action: "/requests/approve", Method: components.MethodPost,
+ }) {
+ @components.Button(components.ButtonProps{
+ Text: "Approve", Type: components.ButtonTypeSubmit,
+ })
+ }
+}
+```
+
+Keep dialogs outside other forms. The dialog includes a native `method="dialog"`
+close form and initially focuses that non-destructive close control. Closing a
+dialog does not submit an application request; use a separate normal form for
+an action that must reach Go. Native opener/closer fields on Button always force
+`type="button"`, even if Type was set to submit. Unsupported command values
+produce an inert button. Do not combine native commands and HTMX requests on
+the same control.
+
+Modal opening uses the newer `commandfor`/`command="show-modal"` attributes.
+Provide an ordinary-page alternative for unsupported browsers, as `/interactions`
+does. No JavaScript fallback is injected. See the browser's
+[native dialog commands](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#modal_dialogs_using_invoker_commands).
+
+For popovers, use `ButtonProps{PopoverTarget: "help"}` and
+`Popover(PopoverProps{ID: "help", Title: "Help"})` with templ children. The default
+automatic mode supports dismissal outside the panel; `Mode: PopoverManual`
+requires an explicit close/toggle action. Both variants include a close button.
+`PopoverAction` supports Toggle, Show, and Hide. Panels are non-modal, centered
+by default, and do not claim ARIA menu semantics. Unsupported browsers may show
+the content inline. See the [native popover attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover).
+
+`Breadcrumbs(BreadcrumbsProps{Items: ...})` renders ancestor links and a final,
+non-linked current page. Separators are hidden from assistive technology.
+
+`Pagination(PaginationProps{Page: page, TotalPages: total, URLForPage: pageURL})`
+renders normal links, current/disabled states, and a bounded page window with
+ellipses. Zero/one-page results omit the navigation. Current page numbers are
+clamped to range; a missing URL callback for multiple pages returns a render
+error. The application supplies totals, page data, and URLs that retain its
+filters. No database, router, or query convention is imposed by the component.
+Labels can be localized through the props.
+
+The dashboard example demonstrates filter → sort → paginate on a request-owned
+copy of sample records. Page URLs preserve search, status, sorting, page size,
+and appearance query settings. Invalid or excessive page numbers are normalized;
+empty results keep their recovery link.
+
+## Themes and the zero-JavaScript contract
+
+Set `LayoutProps.Theme` to `ThemeLight` or `ThemeDark` to emit the root
+`data-theme` attribute. Leave it at `ThemeSystem` (the empty default) to follow
+`prefers-color-scheme`. Override `--tendui-*` properties in your own CSS loaded
+after TendUI. Dark tokens have no effect on explicitly light pages.
+
+`ThemeToggle()` renders a small native form that POSTs to `/api/theme/toggle`.
+Place it **outside other forms**. You can pass `ThemeToggleProps` for a localized
+label and your application's CSRF token. The consumer owns cookies, request
+protection, routing, and page rendering; the library has no global theme state.
+
+The included endpoint alternates a validated `light`/`dark` cookie and returns
+303 to the current demo when its same-origin Referer is available, otherwise to
+the homepage. Cookies are HttpOnly, SameSite=Strict, and Secure over TLS;
+the example uses Go's cross-origin request protection. Behind a TLS-terminating
+proxy, configure your application's Secure-cookie policy explicitly. The first
+example visit uses light so the server can deterministically toggle it; the
+library's system theme remains available for applications that prefer it.
+
+The button preserves the requested `hx-post="/api/theme/toggle"`,
+`hx-target="html"`, and `hx-swap="outerHTML"` attributes. These are inert without
+HTMX. **HTMX itself is JavaScript** and is never included or loaded by TendUI.
+Consumers that already use it can use the hooks without writing custom JS.
+
+A document root swap is not a reliable way to replace a page's root attributes
+and head. The example detects `HX-Request: true` and sends **200 plus
+`HX-Redirect` to the cleaned demo URL** after setting the cookie. This requests a
+full navigation. Both native and HTMX paths remove the `theme` query parameter
+so a previous preview cannot override the new cookie, while preserving other
+settings. For HTMX, a validated same-origin `HX-Current-URL` takes precedence over
+Referer; invalid values fall back to a validated Referer, then the homepage.
+Only known demo pages are accepted. These headers control presentation, not access.
+HTMX does not process its response headers on 3xx responses. See the upstream
+[redirect header documentation](https://htmx.org/headers/hx-redirect/) and
+[swap reference](https://htmx.org/attributes/hx-swap/).
+The isolated browser consumer verifies this navigation with HTMX 2.0.11 in
+Chromium, Firefox and WebKit. The runtime is a test dependency and is not bundled.
+
+## Full pages and optional HTMX fragments
+
+`render` is a standard-library-only package. Its small `Component` interface is
+implemented by templ components; no adapter or additional dependency is needed.
+Use the same route for ordinary navigation and partial updates:
+
+```go
+import (
+ "log"
+ "net/http"
+
+ "github.com/Tend-Stack/TendUI/v2026/components"
+ "github.com/Tend-Stack/TendUI/v2026/render"
+)
+
+func profileHandler(w http.ResponseWriter, r *http.Request) {
+ panel := components.Alert(components.AlertProps{Title: "Profile", Message: "Your profile is ready."})
+ page := components.Layout(components.LayoutProps{Title: "Profile"}, panel)
+ w.Header().Set("Cache-Control", "private, no-store")
+ if err := render.HTML(w, r, http.StatusOK, page, panel); err != nil {
+ log.Printf("render profile: %v", err)
+ }
+}
+```
+
+`HTML` chooses the fragment for `HX-Request: true`, but serves the full page for
+history restoration or boosted navigation. A nil fragment always serves the page.
+It preserves existing `Vary` values and adds the three headers that affect the
+representation. Rendering is buffered so a component error produces a generic
+500 instead of partially written HTML; errors are returned for logging. HEAD
+has no body, including on failures. After calling it, do not write another error
+response: a render failure has already sent 500, and a transport failure may
+have committed the response. Only the selected component is rendered.
+
+The helper leaves authentication, CSRF protection, cache policy, CSP and status
+selection to the application. HTMX headers are presentation hints, never proof
+of identity or permission. For cacheable pages, use representation-specific ETags.
+Buffering is intended for bounded UI pages/fragments, not streaming responses.
+
+The [inline editing example](../examples/site/editing.go) pairs native form actions
+and link destinations with `HxPost`/`HxGet`, `HxTarget` and `HxSwap`. It returns
+303 after a successful native POST and 200 with the updated panel for an HTMX
+request. Invalid native submissions return 422. Invalid HTMX submissions return
+200 **with field errors and no save**, because default HTMX does not swap 422
+responses. This policy is explicit in the example, not imposed by `render.HTML`.
+See the upstream [response handling](https://htmx.org/docs/#response-handling),
+[history](https://htmx.org/docs/#history) and
+[caching](https://htmx.org/docs/#caching) documentation.
+
+The included demo remains JavaScript-free and blocks scripts with CSP. Its native
+flow and HTTP fragment contract are testable separately. Applications enabling
+HTMX must supply their own runtime and appropriate CSP; this project neither
+loads nor bundles it. The example cookie is unsigned cosmetic sample data,
+validated and escaped on every read. It is not an account/session implementation.
+
+## Motion, surfaces and useful states
+
+Cards now accept typed `Surface`, `Entry`, `Delay` and `HoverLift` options.
+Choose tinted, outlined or gradient borders; use fade, rise or scale entrances.
+`Reveal` wraps other content with the same entrance system. `Skeleton`,
+`EmptyState` and `Stat` cover loading, recovery and metric presentation.
+
+`Appearance.Motion` accepts `MotionSystem` (default) or `MotionOff`. System mode
+respects OS reduced motion. Off also disables hover displacement; CSS/Go exports
+include the choice. Entrances run once, and loading decoration stops after three
+cycles. All styling stays in the embedded CSS, with no runtime dependency.
+
+See [the motion guide](motion.md), try `/motion`, and track the broader
+[product roadmap](../ROADMAP.md). See the [recorded browser results](release-verification.md).
+
+## Data tables and navigation patterns
+
+`DataTable` provides semantic headers/row scopes, application-owned sort URLs,
+cell component slots, striped/compact styles, and loading/empty states. The
+Dashboard uses it for bidirectional sorting and native checkbox selection review.
+`Tabs` supplies ordinary page navigation; `Steps` labels application-owned
+progress; `Disclosure` uses native details/summary with optional grouping.
+
+See the [data and navigation guide](data-navigation.md) and `/patterns`
+for composition rules, working examples and validation boundaries.
+
+## Composable fields and multi-step forms
+
+`Field` pairs a raw control with its label, description and error through typed
+`FieldProps.ControlAttributes()`. `InputGroup` adds text prefixes/suffixes while
+preserving native control behavior. `ButtonProps.FormNoValidate` supports Back
+actions that submit edits without native constraints blocking navigation.
+
+The `/wizard` project-brief example preserves draft values across Back/Continue,
+checks all submitted fields on completion, and shows a validated preview without
+creating or storing a project. See [the form guide](forms.md) for composition,
+validation and workflow ownership rules.
+
+The `/uploads` example connects the native file chooser to a bounded Go CSV
+preview: download a sample, upload up to 64 KiB/50 rows, and inspect validated
+results or line-specific errors. Uploaded content stays in request memory;
+nothing is saved or imported. See the form guide for limits and HTTP behavior.
+
+## Accessibility and print
+
+Palette checks cover all built-in presets across page, card and subtle surfaces.
+Print uses a neutral palette independent of the screen theme, with readable
+outlined actions and native checkbox rendering for switches. See the
+[accessibility and print guide](accessibility.md) for the measured scope,
+customization rules and browser checks still required.
+
+## Layout composition
+
+`Stack` provides vertical rhythm; `Cluster` wraps actions and other related items
+into rows. Typed gap and alignment props use a density-aware spacing scale,
+preserve document order, and compose with Grid, Card and native forms. Existing
+CSS utilities retain their behavior. Try `/patterns?section=composition` or read
+[the layout guide](layout.md) for spacing tokens, semantics and examples.
+
+## Reading content
+
+`Prose` styles application-owned HTML for help pages, guides and release notes.
+Choose a typed reading measure, use native headings/lists/code, and opt embedded
+widgets out of prose typography. Try `/patterns?section=reading` and see the
+[reading-content guide](prose.md) for tokens, semantics and examples.
+
+## Inline icons
+
+The Icon component provides 24 original SVG drawings, compiled into Go and
+rendered inline. They inherit text color and use no external image or font files.
+Button and Link accept optional `IconBefore`, `IconAfter` and `AriaLabel` fields.
+Icon-only actions require an explicit accessible name; decorative icons stay
+hidden from assistive technology. Explore `/catalog/icon` and the
+[icon guide](icons.md) for sizes, composition and verification limits.
+
+## Searchable component catalog
+
+Open `/catalog` to browse all 37 public templ components by name, category or
+usage notes. Each entry provides a preview, guidance and a downloadable `.templ`
+recipe drawn from the same source compiled for that preview. Layouts open as
+standalone pages to preserve document landmarks. Search and pagination use Go
+requests; no client runtime or external assets are added.
+
+Catalog-only CSS and recipe source are embedded in the example executable, not
+the library stylesheet. See [the catalog guide](catalog.md) for recipe
+adaptation, coverage checks and validation boundaries.
+
+## Maintaining the library
+
+Only contributors changing `.templ` files need the generator:
+
+```sh
+go install github.com/a-h/templ/cmd/templ@v0.3.1100
+templ fmt .
+templ generate
+go test -race ./...
+go vet ./...
+```
+
+Commit generated Go alongside its source. A normal Go build consumes CSS
+directly through `go:embed`; CSS editing needs no asset build step. Test output
+belongs under `tests/results/` and is ignored except for its placeholder.
+
+The Go-only developer tool also checks generated-source consistency, compiles
+all catalog downloads independently, records benchmarks and builds the versioned
+review executable. See [the development guide](development.md) and
+[measured performance](performance.md):
+
+```sh
+go run ./cmd/tendui-dev check
+go run ./cmd/tendui-dev api
+go run ./cmd/tendui-dev generated
+go run ./cmd/tendui-dev recipes
+go run ./cmd/tendui-dev bench
+go run ./cmd/tendui-dev build
+./tests/results/demos/tendui-demo -version
+```
+
+`check` already includes `api`; the separate command is useful during API review.
+The checked-in declaration baseline catches changed props, constants, signatures
+and method sets. See [API review and migration](api-compatibility.md) for
+intentional updates and the limits of this check.
+
+The [CI matrix](ci.md) checks native Linux, macOS and Windows with Go 1.26.0
+and 1.27.3, plus a vulnerability scan. Browser checks cover Chromium, Firefox and
+WebKit. These jobs must pass on the preview source; see
+[preview release notes](releases/2026.2.0-preview.2.md) and
+[release verification](release-verification.md) for the published preview evidence.
+
+Versions follow `YEAR.RELEASE.FIX`, with SemVer prerelease suffixes for previews:
+`v2026.2.0-preview.2`. Install the explicit tag; a preview is not a stable API promise.
+Development builds use `git describe --tags --long --dirty`.
+
+Go treats 2026 as the semantic major version, so the module path ends in
+`/v2026`. A new annual line such as 2027 will need `/v2027` and consumer import
+updates. Fixes and previews on the 2026 line retain `/v2026`.
diff --git a/docs/release-verification.md b/docs/release-verification.md
index d31a8af..80ac9bb 100644
--- a/docs/release-verification.md
+++ b/docs/release-verification.md
@@ -1,53 +1,53 @@
-> Historical evidence from before the TendUI rename. The immutable tag and original module path are unchanged.
+# TendUI preview verification
-# GothUI 2026.1.0 verification
+The supported preview is `v2026.2.0-preview.2`. Install it explicitly:
-Verified on 2026-11-06. The immutable `v2026.1.0` tag points to
-`2f622c95fbf71df942822d6697093b15fc8270db`. Later documentation-only commits
-record these results without moving the release tag.
+```sh
+go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.2
+```
+
+## Published preview
+
+The following GitHub Actions runs passed for the published preview. These links
+identify the tested revision directly; later documentation updates do not extend
+those results to unrelated code changes.
| Gate | Evidence | Result |
| --- | --- | --- |
-| Native Go compatibility and security | [Verify GothUI](https://github.com/Tend-Stack/GothUI/actions/runs/42211995225) | Six native Linux/macOS/Windows jobs on Go 1.26.0/1.27.3, plus the vulnerability job, passed at the tagged commit. |
-| Real browser behavior | [Browser verification](https://github.com/Tend-Stack/GothUI/actions/runs/42211995320) | 53 passed, zero failed/flaky; one unsupported WebKit forced-color emulation check skipped. |
-| Installation from the actual tag | [Release GothUI](https://github.com/Tend-Stack/GothUI/actions/runs/42213916698) | Fresh consumer downloaded `v2026.1.0`, passed `TestPublishedModule` and `go mod verify`, with no replacement or templ generation. |
-| Release publication | [v2026.1.0](https://github.com/Tend-Stack/GothUI/releases/tag/v2026.1.0) | Published as a regular release after the tag-installation check passed. |
-| Documentation website | [Website browser checks](https://github.com/Tend-Stack/GothUI-Web/actions/runs/42212696656), [native/container checks](https://github.com/Tend-Stack/GothUI-Web/actions/runs/42212696776) | Eight browser checks passed on desktop Chromium and mobile WebKit at website commit `14874b6286e1d5cd77fc2b1628814c60a5212ae6`; native tests and the actual container smoke test passed. |
-
-## Browser scope
-
-The pinned Playwright 1.65.0 suite runs Chromium, Firefox and WebKit on the
-Ubuntu CI runner. Native flows use scripts-disabled contexts. The separate
-HTMX fixture loads a local, test-only HTMX 2.0.11 runtime and verifies fragment
-editing, validation recovery and theme redirects. Neither project bundles this
-runtime into its shipped application.
-
-Axe checks WCAG 2 A/AA and 2.1 AA rules on all 36 component detail pages in both
-themes. Application containment is checked at 320, 768 and 1920 pixels. Focused
-checks cover keyboard skip/focus, popovers, native modal focus and background
-inertness, reduced motion, explicit motion off, forced colors and print tokens.
-The Chromium dashboard PDF was reviewed: readable monochrome controls and table,
-no horizontal clipping, and headings stay with their following content.
-
-The website suite checks nine documentation/home/example routes, native theme
-navigation, catalog discovery, keyboard skip navigation, reduced motion, mobile
-containment, and the 1920-pixel maximum at a 2560-pixel viewport. Code examples
-are keyboard-focusable for horizontal scrolling. Screenshots and PDFs are
-review evidence, not pixel-by-pixel regression baselines.
+| Native Go compatibility and security | [Verify TendUI](https://github.com/Tend-Stack/TendUI/actions/runs/42313429148) | Linux, macOS and Windows on Go 1.26.0 and 1.27.3; independent vulnerability check passed. |
+| Browser behavior | [Browser verification](https://github.com/Tend-Stack/TendUI/actions/runs/42313429136) | 59 checks passed; one unsupported WebKit forced-color emulation check skipped. |
+| Installation from the published tag | [Release verification](https://github.com/Tend-Stack/TendUI/actions/runs/42313876893) | Published-tag consumer and quickstart checks passed. |
+| Release notes | [TendUI preview](https://github.com/Tend-Stack/TendUI/releases/tag/v2026.2.0-preview.2) | Prerelease; APIs may change before stable release. |
+
+On 2026-11-07, anonymous GitHub source access and the Go proxy module download
+were checked again. The downloaded module checksum matched the website's pinned
+`go.sum`. Both repositories are public; installation does not require a GitHub
+token or private-module configuration.
+
+## Website and browser coverage
+
+The website consumes the pinned preview. Its [publication-polish browser run](https://github.com/Tend-Stack/TendUI-web/actions/runs/42337550182)
+passed 20 checks on desktop Chromium and mobile WebKit. These include native
+navigation, theme changes, onboarding downloads, containment, and light/dark
+hover and keyboard-focus treatments. The [website build checks](https://github.com/Tend-Stack/TendUI-web/actions/runs/42337550151)
+also passed for that tested revision. CI success is separate from deployment;
+verify the served content after a website change is merged.
+
+The library suite exercises Chromium, Firefox and WebKit. Native flows use
+scripts-disabled contexts. Optional HTMX integration tests use a local,
+test-only runtime; TendUI does not bundle that runtime with the library.
+Automated checks cover accessibility rules, keyboard behavior, native overlays,
+reduced motion, motion opt-out, responsive containment and print styles.
## Limits and repeatability
-These results do not certify WCAG conformance, every screen reader, every
-physical device, every zoom level, or every consumer customization. WebKit
-forced-color emulation is explicitly unsupported. Assembled applications still
-need testing with their target assistive technology and supported devices.
-
-The repositories currently require GitHub authorization. Tag installation was
-verified with authorized credentials, not anonymous public access. Consumers
-need normal Git credentials and `GOPRIVATE=github.com/Tend-Stack/GothUI` while
-that visibility remains in effect.
+These checks do not certify WCAG conformance, every screen reader, every physical
+device, every zoom level, or every consumer customization. Manual assistive
+technology and physical-device reviews remain necessary. WebKit forced-color
+emulation is unsupported in the test environment and is reported as skipped.
-Workflows and fixtures are committed for repeatability. CI artifacts expire
-after seven days; focused local reports and representative render artifacts live
-under ignored `tests/results/`. No credentials or private infrastructure details
-are included in the repository or retained test reports.
+Workflows and fixtures are committed for repeatability. CI artifacts expire after
+seven days; maintainers retain concise release evidence separately. Screenshots
+and PDFs are review evidence, not pixel-by-pixel regression baselines. See
+[development](development.md), [CI](ci.md), and [accessibility](accessibility.md)
+for the checks to run when changing components or applications.
diff --git a/docs/releases/2026.1.0.md b/docs/releases/2026.1.0.md
deleted file mode 100644
index 0b061f6..0000000
--- a/docs/releases/2026.1.0.md
+++ /dev/null
@@ -1,51 +0,0 @@
-> Historical evidence from before the TendUI rename. The immutable tag and original module path are unchanged.
-
-# GothUI 2026.1.0
-
-The first GothUI release provides semantic CSS and 36 typed templ components,
-embedded directly in a Go binary. It includes 24 inline SVG icons, configurable
-appearance, native form and navigation patterns, bounded CSS motion, and
-full-page/fragment HTTP helpers.
-
-## Install
-
-```sh
-go get github.com/Tend-Stack/GothUI/v2026@v2026.1.0
-```
-
-Go 1.26 or newer is required. Components use templ v0.3.1100; generated Go is
-included. The asset and rendering packages use only the standard library.
-There is no Node/npm requirement for building an application, no external
-asset compilation, and no bundled client-side JavaScript or HTMX runtime.
-
-Repository access follows GitHub visibility. Private installations require
-normal GitHub credentials and `GOPRIVATE=github.com/Tend-Stack/GothUI`.
-
-## Explore
-
-- [Installation guide](https://gothui.com/docs/install)
-- [Component catalog and recipes](https://gothui.com/catalog)
-- [Interactive playground](https://gothui.com/playground)
-- [Application examples](https://gothui.com/examples)
-
-## Validation and scope
-
-Publication requires native Linux/macOS/Windows checks on Go 1.26.0 and 1.27.3,
-the vulnerability scan, and the Chromium/Firefox/WebKit browser suite at the
-exact tagged commit. A separate consumer installs the actual GitHub tag and
-tests rendering and embedded CSS without a local replacement or a generator
-before these notes are published.
-
-Browser coverage includes native forms with scripts disabled, component-page
-accessibility rules in both themes, narrow layouts, keyboard interactions,
-reduced motion, print, and an isolated HTMX consumer. WebKit forced-color
-emulation is unsupported and explicitly skipped. Automated rules and engine
-tests do not certify accessibility conformance, all screen-reader behavior,
-or physical-device compatibility; review assembled applications with their
-target devices and assistive technologies.
-
-Applications own routing, authentication, persistence, request protection, and
-any HTMX runtime. Native overlay commands require browser support; the examples
-include ordinary-page fallbacks. `examples/site` is reusable demonstration code,
-not part of the stable component API. Versions use `YEAR.RELEASE.FIX` and the
-2026 module line uses `/v2026`.
diff --git a/docs/releases/2026.2.0-preview.1.md b/docs/releases/2026.2.0-preview.1.md
index 2aceeb3..fe51e00 100644
--- a/docs/releases/2026.2.0-preview.1.md
+++ b/docs/releases/2026.2.0-preview.1.md
@@ -1,8 +1,7 @@
# TendUI 2026.2.0-preview.1
This is the first tagged preview under the TendUI module name, not a stable API
-commitment. It introduces the renamed module and shared SiteHeader after the
-historical pre-rename release. Old tags are not moved or rewritten.
+commitment. It includes the TendUI module and shared SiteHeader component.
```sh
go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.1
@@ -28,10 +27,5 @@ Automated browser checks include keyboard, reduced motion and accessibility
rules; manual screen-reader and physical-device testing remain outstanding.
One WebKit forced-color emulation case is unsupported and skipped.
-The privacy review found no Gitleaks credential matches in reachable history.
-Older library documentation still contains private infrastructure references.
-Review or remediate that history before making the repository public. This
-preview release does not change visibility or rewrite history.
-
-See [migration notes](../tendui-migration.md) for import, stylesheet, CSS token
-and preference-cookie changes. Previous release reports are historical only.
+See [integration guidance](../tendui-migration.md) for imports, stylesheet
+setup, CSS tokens and preference cookies.
diff --git a/docs/releases/2026.2.0-preview.2.md b/docs/releases/2026.2.0-preview.2.md
index 136fc51..bdc57b3 100644
--- a/docs/releases/2026.2.0-preview.2.md
+++ b/docs/releases/2026.2.0-preview.2.md
@@ -2,8 +2,7 @@
This preview corrects the release consumer version check from preview.1, whose
release publication was blocked by a stale test expectation. The earlier tag is
-retained unchanged. This is not a stable API commitment. It introduces the renamed module and shared SiteHeader after the
-historical pre-rename release. Old tags are not moved or rewritten.
+retained unchanged. This is not a stable API commitment. It includes the TendUI module and shared SiteHeader component.
```sh
go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.2
@@ -29,10 +28,5 @@ Automated browser checks include keyboard, reduced motion and accessibility
rules; manual screen-reader and physical-device testing remain outstanding.
One WebKit forced-color emulation case is unsupported and skipped.
-The privacy review found no Gitleaks credential matches in reachable history.
-Older library documentation still contains private infrastructure references.
-Review or remediate that history before making the repository public. This
-preview release does not change visibility or rewrite history.
-
-See [migration notes](../tendui-migration.md) for import, stylesheet, CSS token
-and preference-cookie changes. Previous release reports are historical only.
+See [integration guidance](../tendui-migration.md) for imports, stylesheet
+setup, CSS tokens and preference cookies.
diff --git a/docs/tendui-migration.md b/docs/tendui-migration.md
index d126486..bb47509 100644
--- a/docs/tendui-migration.md
+++ b/docs/tendui-migration.md
@@ -1,28 +1,26 @@
-# Moving to TendUI
+# Integrating TendUI
-TendUI is the new name of this library. Install the renamed preview explicitly:
+Install the pinned preview:
```sh
go get github.com/Tend-Stack/TendUI/v2026@v2026.2.0-preview.2
```
-The historical `v2026.1.0` tag retains its original module path and is not a
-TendUI installation target. It has not been rewritten.
+Use `github.com/Tend-Stack/TendUI/v2026` for embedded assets and
+`github.com/Tend-Stack/TendUI/v2026/components` for typed templ components.
+The root Go package is `tendui`. Authoring your own templ files requires the
+generator version listed in `go.mod`; consuming the shipped Go components does
+not require generation.
-Update Go imports to `github.com/Tend-Stack/TendUI/v2026` and the root package
-identifier to `tendui`. Regenerate your own templ files after changing imports.
-The component APIs remain available, with the additive `SiteHeader` component
-and host-page options for the example handler.
-
-The asset endpoint is now `/tendui/static/tendui.css`. Prefer `tendui.AssetPath`
+The asset endpoint is `/tendui/static/tendui.css`. Prefer `tendui.AssetPath`
and `tendui.StylesheetURL` in Go code. CSS custom properties and prefixed utility
-classes now use `tendui` rather than the previous prefix. Update application
-overrides, downloaded recipes and appearance exports together with the stylesheet.
+classes use `tendui`; keep application overrides and appearance exports aligned
+with the stylesheet version you install.
-The example site's preference cookies now use the `tendui_` prefix. Existing
-demo preferences are not migrated; visitors can save their choices again.
-The standalone examples retain their default appearance, while tendui.com
-defaults to dark and shares its theme toggle across Home, Docs and the demos.
+The demo site's preference cookies use the `tendui_` prefix. Consumer applications
+own their preference storage and routing. The standalone examples retain their
+default appearance; tendui.com defaults to dark and shares its theme toggle across
+Home, Docs and the demos.
## CSS with any HTML stack