Skip to content

About

A workshop of small, copyable UI widgets — skeletons, button states, avatar loading, orbs and transitions. Next.js + Tailwind, zero runtime dependencies beyond React.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Playground

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

What's in it

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

How it's laid out

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:

  1. src/lab has no dependencies beyond React. No component library, no animation library, no next/* imports. That is what makes a widget droppable into any React project. Styling uses Tailwind utilities plus the CSS variables in src/app/globals.css — rename those tokens to match the host project.
  2. Metadata and demos are separate modules. meta.ts is plain data that server components read; demos.tsx is "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.

Theming

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 .dark class, which swaps our tokens;
  • color-scheme on <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.

Adding a widget

  1. Write the component in src/lab/<category>/<Name>.tsx.

  2. 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;
  3. Register the demo in src/registry/demos.tsx.

  4. 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.

Adding a category

Append to categories in src/registry/types.ts and add the id to CategoryId.

About

A workshop of small, copyable UI widgets — skeletons, button states, avatar loading, orbs and transitions. Next.js + Tailwind, zero runtime dependencies beyond React.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages