npm package: @jpotin/playground-ui
Description: A UI library for React
Author: jpotin@gmail.com
Latest version: 1.0.4

# 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:

```sh
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):

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

JS/TS component import:

```js
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:

```html
<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:

```jsx
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:

```sh
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):
  ```sh
  pnpm run build
  ```
- Quick CSS-only iteration (if needed with local tailwind CLI):
  ```sh
  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