--- title: UI primitives summary: The 36 primitive families of src/components/ui, their folder contract, the canonical Button, and the shared dialog and overlay infrastructure. sources: - src/components/ui/README.md - src/components/ui/button/Button.astro - src/components/ui/dialog/Dialog.astro - src/components/ui/_dialog.ts - src/components/ui/_overlay.css - src/components/ui/accordion/AccordionItem.astro updated: 2026-08-15 --- # UI primitives 36 families, all under src/components/ui. The written contract is src/components/ui/README.md; this page maps how it plays out in the code. ## Folder anatomy `ui//.astro` plus `index.ts` re-exporting the component and its tv() config. Composites (card, dialog, dropdown, table, tabs) have one file per part and a single barrel. Two shared files sit at the root of ui/ and are not primitives: _dialog.ts (the modal controller) and _overlay.css (scrim and overlay animations). ## The canon: Button (src/components/ui/button/Button.astro) Read it before writing any primitive. It demonstrates every convention: - Exported tv() config (Button.astro:9) with base classes including `rounded-pill` (:11), seven variants (hero, primary, dark, outline, glass, ghost, link; :17-29), five sizes (:31-37), defaults (:39). - `VariantProps` merged into platform props typed as a union of `HTMLAttributes<"button">` and `HTMLAttributes<"a">` (:44-47). - Tag polymorphism: `const Tag = href ? "a" : "button"` (:50). - Caller classes merged through the config, `data-slot="button"` on the root (:53-57). Other components reuse the exported config instead of copying classes; that is the point of exporting it. ## Platform first, verified The library leans on native behavior before scripts: - Dialog and Sheet are native `