Playground UI

A small, personal React UI component library built with Tailwind CSS and Class Variance Authority (CVA).
Designed for use across projects to provide a consistent design system while remaining easy to integrate.

Package: @jpotin/playground-ui
Version: 1.0.3

Goals

• Provide a minimal set of accessible components (Button, Input, Label, Slider, …).
• Keep CSS non-invasive: expose theme tokens as CSS variables globally, but avoid forcing global resets.
• Allow consumers to opt into automatic background/text via a .ui wrapper.
• Compatible with projects using Tailwind — Storybook-ready.

Installation

Using pnpm:

pnpm add @jpotin/playground-ui

Or Yarn / npm equivalent.

After installing, import the built CSS in the consuming app (or let Vite/PostCSS produce it during your build if you bundle the library alongside your app):

import "@jpotin/playground-ui/dist/playground-ui.css";

JS/TS component import:

import { Button, Input, Label, Slider } from "@jpotin/playground-ui";

How theming works

• Theme tokens (colors, radii, ring, etc.) are defined as CSS variables and are exposed globally. They are available on:

  • :root
  • html[data-theme="dark"] / html[data-theme="light"]
  • [data-theme="dark"] / [data-theme="light"]

• This allows theme toggles (for example, Storybook's theme addon) to work by setting data-theme on an ancestor element.

• The library does NOT apply global background/text styles by default. If you want automatic background/text, wrap the UI area in a .ui element:

<div class="ui" data-theme="dark">
  <button class="ui:bg-primary ui:text-primary-foreground">Click</button>
</div>

• The components themselves use ui:-prefixed classes (import-based prefix), so authoring remains consistent (e.g., ui:bg-primary, ui:hover:bg-primary/90). The library CSS uses the import-based Tailwind prefix, so you do not need to set a prefix in your Tailwind config.

Usage example

Simple button usage:

import React from "react";
import { Button } from "@jpotin/playground-ui";
import "@jpotin/playground-ui/dist/playground-ui.css";

export default function App() {
  return (
    <div className="ui" data-theme="light">
      <Button>Primary</Button>
    </div>
  );
}

CVA variants are used internally. You can pass component props or className as usual.

Storybook

Storybook is configured for the library and imports the library CSS in .storybook/preview.ts. To run Storybook locally:

pnpm install
pnpm run storybook

You can also view the hosted Storybook online: https://joska-p.github.io/playground-ui/

The theme addon sets data-theme on the story wrapper so theme variables resolve automatically.

Development

• Full build (JS + extracted CSS via Vite):

  pnpm run build

• Quick CSS-only iteration (if needed with local tailwind CLI):

  pnpm exec tailwindcss -i lib/styles.css -o dist/playground-ui.css --minify --config tailwind.config.js

Notes:

• lib/main.ts imports lib/styles.css to ensure the CSS is included during Vite builds.
• PostCSS/Tailwind is used during Vite builds; the repo contains a PostCSS config to run Tailwind.

Publishing

When ready to publish:

1. Bump the version in package.json.
2. Build the package (pnpm run build).
3. Publish the dist artifacts (e.g., via npm publish or your preferred registry workflow).

Contributing

This repo is primarily for personal use but patches are welcome if you want to suggest improvements. Keep changes small and focused.

License

MIT