@puzzle-ui/theme 0.2.0 → 0.4.0

package/README.md

@@ -1,113 +1,99 @@
-# @puzzle-ui/theme
+---
+title: Getting Started
+description: Install Puzzle in your React app, build your first interface, and customize the theme.
+---
 
-Puzzle's theme system: semantic design tokens, light/dark color schemes,
-typography, Google Fonts, and configurable link and image components.
+> \[!WARNING\] **Puzzle is not ready for production use.**
+>
+> This project is under active development. APIs, component props,
+> package exports, styling, and internal implementation may change
+> without notice. Components may be incomplete, and testing,
+> accessibility, documentation, and framework compatibility are not yet
+> guaranteed. Use it for experimentation and evaluation only---not for
+> production applications.
 
-> Puzzle is under active development. APIs and framework compatibility may
-> change; use it for experimentation and evaluation rather than production.
+Puzzle is a TypeScript and React UI component library built around reusable components and shared design tokens. Its components are composable and router-independent, with styling supplied by `"@puzzle-ui/theme`. The framework is setup to be compatible with `Next.js`, `Tanstack Start` and `react-router`.
 
-## Installation
+**Puzzle is under active development and is not ready for production use.** APIs, props, exports, and styling may change without notice. Accessibility and framework compatibility are still being tested. Use the project for experimentation and evaluation.
 
-```sh
-npm install @puzzle-ui/theme
-# or
-bun add @puzzle-ui/theme
-# or
-pnpm add @puzzle-ui/theme
-# or
-yarn add @puzzle-ui/theme
-```
+## Prerequisites
 
-Requires React and React DOM 19 (`^19.0.0`) and a CSS-aware application
-bundler. Styles are imported by the package; no separate stylesheet or
-Tailwind setup is required.
+- A package manager: npm, Bun, pnpm, or Yarn.
+- An existing React application with a bundler that supports CSS imports, such as Vite.
+- Familiarity with React and TypeScript. The UI and theme packages require React and React DOM 19 or later within the supported React 19 range.
 
-## Usage
+## Set up a new project
 
-```tsx
-import { Theme } from "@puzzle-ui/theme";
+Simple run our @puzzle-ui/create project template to get started.
 
-export const App = () => (
-  <Theme
-    theme="system"
-    tokens={{ radius: { md: "0.5rem" } }}
-  >
-    <main>Your application</main>
-  </Theme>
-);
+npm:
+
+```bash
+npx @puzzle-ui/create
 ```
 
-Use one root theme for your application. By default it follows the system
-color scheme, emits `--puzzle-*` CSS custom properties, and applies global
-styles. Set `globalStyles={false}` to opt out of the global defaults.
-
-## Configuration
-
-| Prop | Purpose |
-| --- | --- |
-| `theme` | `"light"`, `"dark"`, or `"system"`; defaults to `"system"`. |
-| `scope` | `"root"` for document-wide styling or `"local"` for a subtree. |
-| `tokens` | Deep-partial overrides of color, typography, spacing, radius, layout, motion, and other design tokens. |
-| `colorTheme` | Select a built-in palette, such as `"cobalt-sky"`. |
-| `fonts` | Configure Google Fonts for heading, body, and accent roles. |
-| `components` | Override link and image rendering. |
-| `nonce` | CSP nonce for injected style elements. |
-
-Local themes do not apply global styles. Fonts configured through `fonts`
-load external Google Fonts stylesheets; omit this prop to avoid those
-requests.
-
-## Use tokens in your styles
-
-```css
-.panel {
-  color: var(--puzzle-color-text);
-  background: var(--puzzle-color-surface);
-  padding: var(--puzzle-space-4);
-  border-radius: var(--puzzle-radius-md);
-}
+bun:
+
+```bash
+bunx @puzzle-ui/create
 ```
 
-## Router integration
+Puzzle can set up a new project for you with the following framework options:
 
-For routers whose links use `to`, configure the destination prop:
+- Basic React app
+- Tanstack start
+- Next.js
 
-```tsx
-import { Link } from "@tanstack/react-router";
+Furthermore you can choose to install tailwindcss or not.
+It directly installs all dependencies and sets up the project for you.
 
-<Theme components={{ link: { component: Link, hrefProp: "to" } }}>
-  <AppContent />
-</Theme>;
-```
+## Set up in an existing project:
+
+Install the UI library and theme package in your application's directory. Choose your package manager below:
 
-Components using `href` can be passed directly. Use `link: null` or
-`image: null` to restore native elements in a subtree.
+npm:
 
-## Exports
+```bash
+npm install @puzzle-ui/ui --save
+```
 
-The root exports `Theme`, `GoogleFont`, `createGoogleFontUrl`, `BREAKPOINTS`,
-and their configuration types. Context helpers are available through
-`@puzzle-ui/theme/components-context` and `@puzzle-ui/theme/scope-context`.
+bun:
 
-ESM and CommonJS builds with matching TypeScript declarations are included.
-CSS imports require a bundler rather than a bare Node.js runtime.
+```bash
+bun add @puzzle-ui/create
+```
 
-See the repository's [theme documentation](../../apps/site/content/docs/theme)
-for token references, fonts, colors, and component overrides.
+pnpm:
 
-## Development
+```bash
+pnpm add @puzzle-ui/ui
+```
 
-```sh
-# From the repository root
-npm run build --workspace=@puzzle-ui/theme
+yarn:
 
-# From this package directory
-bun run vitest
+```bash
+yarn add @puzzle-ui/ui
 ```
 
-`prepack` rebuilds the package before packing or publishing. See the root
-[publishing guide](../../README.md#publishing-packages).
+These commands install published packages; they do not clone the repository or build its workspaces. Puzzle does not require Bun in your application. React and React DOM are peer dependencies and should already be installed in your app.
 
-## License
+## Your first interface
 
-MIT. See [LICENSE](../../LICENSE); the published license is at `dist/LICENSE`.
+Import components from `"@puzzle-ui/ui` and wrap your application in `Theme` from `"@puzzle-ui/theme`:
+
+```tsx
+import { Theme } from "@puzzle-ui/theme";
+import { Button } from "@puzzle-ui/ui";
+
+export const App = () => (
+  <Theme>
+    <main>
+      <h1>Hello, Puzzle</h1>
+      <p>Build your interface with reusable components and shared tokens.</p>
+      <Button onClick={() => window.alert("Welcome to Puzzle!")}>
+        Get started
+      </Button>
+    </main>
+  </Theme>
+);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puzzle-ui/theme",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Theme components for Puzzle",
   "license": "MIT",
   "publishConfig": {
@@ -51,13 +51,14 @@
   ],
   "scripts": {
     "build": "tsdown",
+    "typecheck": "tsc --noEmit -p .",
     "vitest": "bunx vitest run",
-    "vitest:watch": "bunx vitest",
+    "vitest:watch": "bunx vitest run --watch --passWithNoTests",
     "clean": "rm -rf dist",
     "prepack": "tsdown"
   },
   "dependencies": {
-    "@puzzle-ui/core": "^0.2.0"
+    "@puzzle-ui/core": "^0.4.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",