elements

README

FastyGo Elements

Official repository: github.com/fastygo/elements

Why Elements exists

UI8Kit ships a self-contained minimum: Go/templ primitives, layout grammar, token-based styling, and a small set of browser behaviors (accordion, combobox, dialog, tabs, tooltip, …). That is enough to build UIs, but not enough to cover every WAI-ARIA APG pattern or every complex widget (menus, tree, grid keyboard model, disclosure, carousel, …) without bloating the kit.

Blocks and applications need copyable, stable widgets with clear contracts — not page-specific markup scattered across products.

Elements sits between UI8Kit and Blocks:

Layer	Responsibility
UI8Kit	Atoms + neutral composites; Go primitives and minimal ui8kit JS.
Elements (this repo)	Copy-first widgets — behavior + composition; JS extends ui8kit with APG-aligned patterns where the kit stops.
Blocks	Page organisms built directly on UI8Kit.
App	Brand, routes, data, one-off screens.

So: Elements exists so complexity and ARIA-heavy behavior have a clean source template, with a stable API, instead of ad-hoc duplication across blocks or apps.

---

Standards (defaults)

• Widgets, not scenes. Elements encode reusable controls (date picker shell, menu pattern, modal shell, data table keyboard region). Hero CTAs, marketing layout, campaign copy do not belong here.
• Copy-first dependencies: Elements may depend on UI8Kit only — not on Blocks, other Elements, apps, or workspace-local packages. See .cursor/rules/elements-layer.mdc.
• Go / templ: use only explicit Tailwind utility classes that pass .ui8px policy.
• No semantic/custom classes: do not ship named CSS classes, custom CSS, brand classes, or part-class override APIs.
• JavaScript: Ship Elements/js that assumes ui8kit is loaded first; add new window.ui8kit.* (or a thin elements namespace delegating to it) for APG patterns not covered by UI8Kit/js. Roadmap: .project/APG-JS-ROADMAP.md.
• Quality: Widget-scoped linting and a11y (e.g. ESLint on JS, axe on fixtures). Full-page and app flows are validated in Blocks or apps. See .project/VALIDATION-AND-TOOLING.md.

---

UI8Kit in one sentence

Go: typed primitives (Button, Box, Card, Field, …) and helpers — tokens and structure, not product chrome.
JS: a small window.ui8kit surface for patterns already in the kit — not a full copy of every W3C APG widget.

Elements in one sentence

Go: compositional templ components built only from UI8Kit and intended for cloning.
JS: the rest of the APG behavioral surface the product stack needs, implemented once and reused — aligned with APG, not a fork of the APG repo’s own CI toolchain.

Packages

• commerce: copy-first commerce controls such as quantity stepper and price range.
• selection: copy-first selection controls such as swatches.
• toggles: copy-first header controls for language switching and dark mode. These components preserve the UI8Kit header hooks and can be passed into ui8kit/layout.Shell through ThemeToggleComponent.

---

Project metadata

Path	Purpose
.project/APG-JS-ROADMAP.md	APG pattern parity: UI8Kit vs Elements backlog
.project/VALIDATION-AND-TOOLING.md	Linting / a11y split across Elements, Blocks, apps

---

FastyGo stack

Repository	Role
framework	Core framework and examples
ui8kit	Go/templ primitives + minimal ui8kit JS
elements	Reusable widgets + APG-oriented JS (this repo)
blocks	Page-level organisms

---

Local development

Use the cross-repo workspace when changing UI8Kit, Elements, Blocks, and Framework together:

cd e:/_@Go/.WorkSpace-Framework
go work sync

This module uses a pseudo-zero github.com/fastygo/ui8kit requirement plus a local replace:

replace github.com/fastygo/ui8kit => ../@UI8Kit

Run checks from this directory. ui8px is intentionally not installed as a dependency; call it through npx:

go test ./...
npx ui8px@latest lint ./...
npx ui8px@latest lint ./... --learn
npx ui8px@latest validate patterns ./...

Replace pseudo-zero versions with tagged releases only when publishing stable module versions.

---

License

This project is licensed under the MIT License — see LICENSE.

Documentation

Overview

Package elements contains reusable UI widgets built on UI8Kit primitives.

Concrete widget families live in subpackages such as navigation, toggles, account, dialogs, commerce, and selection.