A workshop for small, reusable UI pieces — skeletons, button states, avatar loading, orbs and transitions. Every widget is tunable in the browser and copyable into another project as a single file.
npm run dev # http://localhost:3100
npm run build| Category | Widgets |
|---|---|
| Skeletons | base Skeleton, text block, card, list rows, table, swap & anti-flash |
| Buttons | variants, async state machine |
| Avatars | avatar with load/error/fallback, stacked group |
| Orbs | gradient orb, pulse orb, aurora backdrop |
| Transitions | fade swap, auto height, stagger |
src/
lab/ the actual widgets — this is the part you copy out
skeleton/ button/ avatar/ orb/ transition/
registry/
meta.ts one entry per widget: blurb, prop controls, source files
demos.tsx slug → demo component (client only)
entries/ one demo per widget
types.ts control schema types
components/ the playground shell (sidebar, stage, knobs, code panel)
lib/ cn(), source reader, syntax highlighter
app/
[category]/[slug]/ the lab page
api/avatar/ local avatar source with controllable latency + failure
Two rules keep it working:
src/labhas no dependencies beyond React. No component library, no animation library, nonext/*imports. That is what makes a widget droppable into any React project. Styling uses Tailwind utilities plus the CSS variables insrc/app/globals.css— rename those tokens to match the host project.- Metadata and demos are separate modules.
meta.tsis plain data that server components read;demos.tsxis"use client". A"use client"module cannot hand a plain object to a server component, so they cannot be merged.
The code panel reads each widget's source off disk at request time, so what you copy is always the real file — it can't drift from the demo.
Every colour is a CSS variable declared in src/app/globals.css — the light palette
on :root inside @theme, the dark overrides in a .dark block. Nothing in
src/lab hardcodes a colour, so retheming is a matter of rewriting those tokens.
The sidebar control has three states: system, light, dark. The choice
persists in localStorage, and an inline script in layout.tsx applies it before
first paint so the page never flashes the wrong theme. That script sets two things:
- the
.darkclass, which swaps our tokens; color-schemeon<html>, which is what makes native selects, range inputs, the colour picker and scrollbars follow the app rather than the OS.
While the preference is "system", a matchMedia listener tracks OS changes live.
-
Write the component in
src/lab/<category>/<Name>.tsx. -
Add a demo at
src/registry/entries/<slug>.tsx—"use client", default-export a component taking{ v }(the live control values):"use client"; import type { DemoComponentProps } from "../types"; function Demo({ v }: DemoComponentProps) { return <MyThing size={v.size as number} />; } export default Demo;
-
Register the demo in
src/registry/demos.tsx. -
Add an entry to
src/registry/meta.ts:{ slug: "my-thing", title: "My thing", category: "orbs", blurb: "One sentence on what it does and the detail worth noticing.", files: ["orb/MyThing.tsx"], // relative to src/lab controls: { size: { kind: "number", label: "Size", min: 20, max: 200, step: 2, value: 80, unit: "px" }, }, usage: `<MyThing size={80} />`, }
The page, sidebar entry, index card and static route appear on their own. Add a
preview to src/components/Thumb.tsx if you want it to look right on the index.
Control kinds: select, boolean, number, color, text.
Append to categories in src/registry/types.ts and add the id to CategoryId.