UI stack
The Primebrick frontend UI is built from five layered technologies. Each layer builds on the one below it. Before reading the component catalog, learn the basics of each layer on its official site — this page only explains how they combine inside Primebrick.
Layering
The five layers
1. Tailwind CSS™
Utility-first CSS framework and the source of all design tokens (colors,
radius, spacing). Primebrick uses Tailwind CSS™ v4 with the Vite plugin.
Global styles and shadcn CSS variables live in src/app.css.
- Repo path: configured via
@tailwindcss/vite; tokens insrc/app.css - Companions:
tailwind-merge,tailwind-variants,class-variance-authority,tw-animate-css - Learn the basics: https://tailwindcss.com
src/app.css also defines Primebrick-specific @utility helpers beyond raw
tokens — the PB logo gradient family (sky-400 → indigo-400, oblique
top-left → bottom-right):
| Utility | Effect | Used by |
|---|---|---|
border-{tone}-gradient | 1px gradient border, neutral fill | Button variant="outline", in-card list items |
border-{tone}-gradient-soft | Gradient border + tinted gradient fill | Button variant="soft" |
bg-primary-gradient-soft | Tinted gradient fill only (no border) | Elements flush inside bordered containers |
shadow-primary-gradient | Two directional glows simulating the gradient (sky TL → indigo BR) | All dropdown surfaces — baked into DropdownMenu.Content, DropdownMenu.SubContent, Popover.Content |
The shadow utility is the standard for floating menu surfaces: it replaces
shadow-md/shadow-lg inside the shared dropdown components, so every
dropdown menu and popover gets the same gradient glow with zero per-instance
classes. Do not apply it to dialogs, sheets, tooltips, or inline cards.
2. BITS UI™
Headless, accessible Svelte™ component primitives (the Svelte™ equivalent of
Radix UI). shadcn-svelte™ is built on top of BITS UI™. You rarely use BITS UI™
directly in Primebrick — you use the shadcn-svelte™ wrappers in
src/lib/components/ui/. Reach for BITS UI™ only when you need a primitive
shadcn-svelte™ does not wrap.
- Repo path: npm dependency
bits-ui@2.18.1(not vendored) - Learn the basics: https://www.bits-ui.org
3. shadcn-svelte™
The primary primitive layer. Components are vendored (copy-pasted) into
src/lib/components/ui/ — they are not an npm dependency. Configuration lives
in components.json: style: "nova", baseColor: "zinc", iconLibrary: "lucide",
registry https://shadcn-svelte.com/registry. Add new primitives with
npx shadcn-svelte@latest add <name>.
- Repo path:
src/lib/components/ui/<name>/(31 vendored primitives in Primebrick) - Companions:
formsnap(form layer),paneforge(resizable),runed(runes utilities),svelte-sonner(toast) - Learn the basics: https://www.shadcn-svelte.com · https://www.shadcn-svelte.com/docs/components
4. more-shadcn-svelte™
A community registry (kevwpl/more-shadcn-svelte) extending shadcn-svelte™ with
components the base registry lacks. Same copy-paste model. Add components with
npx shadcn-svelte@latest add https://more-shadcn.noair.fun/r/<name>.json.
Primebrick vendors 5 components from this registry:
| Component | Path |
|---|---|
| Color Picker | src/lib/components/ui/color-picker/ |
| Dock | src/lib/components/ui/dock/ |
| Sortable | src/lib/components/ui/sortable/ |
| Timeline | src/lib/components/ui/timeline/ |
| Wheel Picker | src/lib/components/ui/wheel-picker/ |
- Learn the basics: https://more-shadcn.noair.fun · https://github.com/kevwpl/more-shadcn-svelte
5. shadcn-svelte-extras™
A second community registry (ieedan/shadcn-svelte-extras) of turn-key
components. Same copy-paste model. Add components with
npx shadcn-svelte@latest add https://shadcn-svelte-extras.com/r/<name>.json.
Primebrick vendors 3 components from this registry:
| Component | Path |
|---|---|
| Copy Button | src/lib/components/ui/copy-button/ |
| Password | src/lib/components/ui/password/ |
| Window | src/lib/components/ui/window/ |
- Learn the basics: https://www.shadcn-svelte-extras.com · https://github.com/ieedan/shadcn-svelte-extras
When to use which
Before writing a new component, check the layers in this order:
- shadcn-svelte™ (
src/lib/components/ui/) — does a primitive already exist? - shadcn-svelte-extras™ — does a turn-key component exist on the extras site?
- more-shadcn-svelte™ — does a component exist on the more-shadcn site?
- BITS UI™ — does a headless primitive exist that none of the above wrap?
- Custom — only if none of the above fit. Custom components live under
src/lib/components/(root),src/lib/components/<feature>/, orsrc/lib/components/ui/<name>/when they extend a primitive.
Vendored primitives stay in src/lib/components/ui/. App-specific and
domain components live in feature subdirectories
(auth/, entity-list-table/, forms/, sidebar/, toasts/,
date-dropper/) or as root files (AppShell.svelte, CommandPalette.svelte,
etc.).
Provenance
Because all three registries use the copy-paste model, vendored components
carry no attribution comments in source. Provenance for every component is
recorded in docs/dev-guide/_extracted/component-provenance.json
(hand-maintained, not synced to the docs site). The
Component catalog groups every component by
origin.
Next steps
- Component catalog — every custom/wrapped component, grouped by origin
- Getting started — stack, commands, project layout
- API reference — full prop tables for every component