Add shared React UI package

.github/workflows/ci.yml

@@ -18,3 +18,4 @@ jobs:
       - run: npm ci
       - run: npm run check
       - run: npm pack --dry-run
+      - run: npm pack --dry-run --workspace @protocol-works/ui

.gitignore

@@ -1,4 +1,4 @@
 node_modules/
+packages/*/dist/
 *.tgz
 .DS_Store
-

AGENTS.md

@@ -5,12 +5,22 @@
 This repository owns the reusable [protocol]works design-system foundation shared by product
 repositories. The first package is `@protocol-works/design-tokens`.
 
+## Packages
+
+- `@protocol-works/design-tokens` at the repository root is the CSS-first, platform-neutral
+  foundation.
+- `@protocol-works/ui` under `packages/ui/` owns portable React primitives proven across product
+  repositories.
+
 ## Boundaries
 
 - Keep the token package CSS-first and platform-neutral.
 - Shared brand primitives, typography, motion, geometry, and theme values belong here.
-- Product-specific semantic roles, runtime theme persistence, and application components stay in
-  their consuming repositories until at least two consumers need the same contract.
+- Portable component contracts needed by at least two consumers belong in `@protocol-works/ui`.
+- Product-specific semantic roles, runtime theme persistence, framework adapters, and domain
+  components stay in their consuming repositories.
+- Do not add Next.js, Tauri, or another product runtime as a UI package dependency.
+- Publish UI components through direct subpath exports; consumers should not need a barrel import.
 - Do not add a token compiler while CSS remains sufficient for every consumer.
 - Keep raw values in namespaced `--pw-*` custom properties. Tailwind aliases may be unnamespaced
   because they intentionally define the shared utility vocabulary.
@@ -22,7 +32,8 @@ Run before committing:
 ```bash
 npm run check
 npm pack --dry-run
+npm pack --dry-run --workspace @protocol-works/ui
 ```
 
 Tests must protect the public token names, Tailwind utility generation, light/dark theme values,
-and required contrast.
+required contrast, UI subpath exports, server rendering, and packaged files.

README.md

@@ -2,14 +2,19 @@
 
 Shared design foundations for [protocol]works products.
 
-The initial package, `@protocol-works/design-tokens`, is deliberately smaller than a component
-library. It owns the brand palette, canonical light and dark theme values, typography, bundled
-font dependencies, motion, geometry, and Tailwind CSS v4 aliases. Each product continues to own
-its application-specific semantic roles, component APIs, and runtime theme persistence.
+The repository publishes two layers:
+
+- `@protocol-works/design-tokens` owns the brand palette, canonical light and dark theme values,
+  typography, bundled fonts, motion, geometry, and Tailwind CSS v4 aliases.
+- `@protocol-works/ui` owns portable React primitives established across [protocol]works products.
+
+Products continue to own runtime theme persistence, framework adapters, product-specific semantic
+roles, and domain components.
 
 ## Status
 
-`0.x` foundation. Published publicly as `@protocol-works/design-tokens`.
+`0.x` foundation. `@protocol-works/design-tokens` is published publicly; `@protocol-works/ui` is
+prepared independently under `packages/ui/`.
 
 ## Install
 
@@ -50,6 +55,32 @@ preference.
 `border-rule`, `bg-accent-clay`, `font-sans`, `text-body`, `rounded-tight`, `duration-quick`,
 and `ease-edit`.
 
+## React UI
+
+Install the token and UI packages together:
+
+```bash
+npm install @protocol-works/design-tokens @protocol-works/ui
+```
+
+Register the compiled component sources after importing Tailwind and the token foundation:
+
+```css
+@import "tailwindcss";
+@import "@protocol-works/design-tokens";
+@import "@protocol-works/ui/tailwind.css";
+```
+
+Import components directly so consumers only load what they use:
+
+```tsx
+import { Button } from "@protocol-works/ui/button";
+import { Stack } from "@protocol-works/ui/stack";
+import { Heading } from "@protocol-works/ui/heading";
+```
+
+See [`packages/ui/README.md`](./packages/ui/README.md) for the complete component catalogue.
+
 ## Fonts
 
 DM Sans, DM Mono, and DM Serif Display are delivered through Fontsource packages and are bundled
@@ -66,4 +97,5 @@ MIT. See [`LICENSE`](./LICENSE).
 npm install
 npm run check
 npm pack --dry-run
+npm pack --dry-run --workspace @protocol-works/ui
 ```