In an unbundled component registry, the source code is the product, not an npm package. Consumers install files directly into their repository and own them permanently.
To ensure components remain modular, readable, and easy to modify, UIPKGE strictly enforces boundaries between three architectural layers: Primitives, Blocks, and Pages.
Every item in UIPKGE belongs to one distinct layer with its own clear responsibilities.
Abstracts low-level mechanics: focus rings, keyboard navigation, ARIA states, theme tokens, and animation physics.
Composes primitives into a self-contained UI section or interaction pattern. Internals are visible and top-to-bottom so they can be customized instantly.
A full-viewport route template or multi-feature console. Bundles global layout shells, persistent sidebars, header chrome, and multi-view navigation.
When building or maintaining blocks in UIPKGE, follow these six non-negotiable standards.
A block is designed to be embedded into an existing screen. It must never assume full viewport control (min-h-screen), full-page sticky sidebars, top navbars, or URL routing. If an item requires an entire browser viewport and coordinates multiple disparate workflows, it is classified as registry:page.
In an unbundled registry, users copy the code to customize it. Blocks must read top-to-bottom at the call site. Tile titles, metric figures, badges, and action buttons should be visibly declared inline. Never create opaque wrapper primitives that hide HTML markup behind deep, generic configuration objects.
Each block should solve exactly one user job to be done (e.g. "Review and approve contractor timesheets", "Inspect database schema drift", or "Configure environment variables"). Never bundle 4 unrelated sub-applications (billing, audits, user management, and telemetry) into a single monolithic block.
A block manages its own interactive UI state (search filters, sorting, tab selections, modal toggles) using standard local reactivity (ref / useState). It must never assume global external state managers (Pinia, Redux, Zustand) or hardcoded backend fetch endpoints.
Single block files have a 500 LOC soft cap to ensure they can be understood in a single reading. When a block is genuinely rich (e.g. kanban-task-board or virtual-tour-panorama), decompose it into co-located subcomponents and register all files in the sidecar manifest.
Component markup should not be drowned in 300 lines of hardcoded mock records. A block ships with a lean default seed (1–3 realistic items) or extracts fixture datasets to a dedicated companion file (<block-name>-data.ts). Rich multi-scenario fixtures belong in Astro demo stories.
Ask these three questions when designing, auditing, or implementing any new component:
If yes without breaking the surrounding layout, it is a Block. If it requires full viewport height and app-level navbars, it is a Page.
If it combines Cards, Badges, Buttons, and Sparklines into a visible layout, it is a Block. If it only handles mechanics and focus for a single element, it is a Primitive.
If the JSX or template reads top-to-bottom with visible markup, it meets our craft bar. If changes require reverse-engineering generic wrapper props, it is over-abstracted.
Comparison of layout-hiding abstractions versus raw primitive composition.
<!-- BANNED: Layout-hiding generic props -->
<StatGrid
:data="kpis"
title-key="label"
metric-key="val"
trend-key="diff"
card-variant="outline"
/>
<!-- Consumer cannot easily:
- Add a tooltip to card #2
- Swap an icon for an avatar
- Change the font size of one metric
--><!-- COMPLIANT: Composed Primitives -->
<KpiGrid class="grid-cols-1 sm:grid-cols-3">
<Card class="p-4">
<div class="flex items-center justify-between">
<span class="text-xs text-muted-foreground">Revenue</span>
<Badge variant="outline">+14.2%</Badge>
</div>
<div class="mt-2 text-2xl font-bold">$48,200</div>
<Sparkline :data="trend" class="mt-3 h-8" />
</Card>
</KpiGrid>Standard packaging layout in both packages/registry-vue/blocks/ and packages/registry-react/blocks/:
