refactor!: rebuild the component library on Base UI + Tailwind v4 for UI3

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-workspace.yaml') }}
+      - run: pnpm -F @thinkbuff/figma-react exec playwright install --with-deps chromium
+      - run: pnpm build
+      - run: pnpm check
+      - run: pnpm typecheck
+      - run: pnpm test
+      - name: generated theme css is committed
+        run: git diff --exit-code -- packages/theme/src/css/

.github/workflows/pages.yml

@@ -0,0 +1,37 @@
+name: pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm pages:build
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site/figma
+      - id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write # create the GitHub release
+  id-token: write # npm provenance / trusted publishing
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+
+      # A mistyped tag publishes the wrong version; refuse early.
+      - name: tag matches package version
+        run: |
+          pkg=$(node -p "require('./package.json').version")
+          [ "$GITHUB_REF_NAME" = "v$pkg" ] || {
+            echo "::error::tag $GITHUB_REF_NAME does not match package.json version v$pkg"
+            exit 1
+          }
+
+      - run: pnpm install --frozen-lockfile
+      - uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-workspace.yaml') }}
+      - run: pnpm -F @thinkbuff/figma-react exec playwright install --with-deps chromium
+      - run: pnpm check
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm build
+
+      # Auth is npm trusted publishing (OIDC) — no token needed.
+      - name: publish to npm
+        run: pnpm -r publish --provenance --no-git-checks
+
+      - name: create github release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ver="${GITHUB_REF_NAME#v}"
+          awk -v v="$ver" '$0=="## v"v{f=1;next} f&&/^## /{exit} f' CHANGELOG.md > notes.md
+          gh release create "$GITHUB_REF_NAME" --notes-file notes.md --verify-tag

.gitignore

@@ -51,3 +51,17 @@ coverage
 
 # parcel-bundler cache (https://parceljs.org/)
 .cache
+
+# storybook static build output
+storybook-static
+
+# assembled github pages site (scripts/pages.ts)
+site/
+.vitest
+
+# Devin local config
+.devin/*.local.json
+
+# Local Design file working-copy links and component audits
+docs/figma-ui3-design.md
+docs/audit/

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "vitest.explorer",
+    "oxc.oxc-vscode",
+    "antfu.pnpm-catalog-lens",
+    "bradlc.vscode-tailwindcss"
+  ]
+}

.vscode/settings.json

@@ -1,32 +1,32 @@
 {
-  "editor.formatOnSave": false,
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+  "editor.defaultFormatter": "oxc.oxc-vscode",
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit",
+    "source.fixAll.oxc": "explicit",
     "source.organizeImports": "never"
   },
-  "eslint.useFlatConfig": true,
-  "eslint.workingDirectories": [
-    {
-      "pattern": "./apps/*/"
-    },
-    {
-      "pattern": "./packages/*/"
-    }
-  ],
-  "eslint.validate": [
-    "javascript",
-    "javascriptreact",
-    "typescript",
-    "typescriptreact"
-  ],
-  "typescript.tsdk": "node_modules/typescript/lib",
-  "cSpell.words": [
-    "onbrand",
-    "oncomponent",
-    "ondanger",
-    "ondisabled",
-    "oninverse",
-    "onselected",
-    "onwarning"
-  ]
+  "editor.quickSuggestions": {
+    "strings": "on"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[yaml]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "explorer.fileNesting.enabled": true,
+  "explorer.fileNesting.patterns": {
+    "package.json": "package-lock.json, pnpm*, .yarnrc*, yarn*, .eslint*, eslint*, .oxlint*, oxlint*, .oxfmt*, oxfmt*, .prettier*, prettier*, .editorconfig",
+    "tsconfig.json": "tsconfig.*.json, env.d.ts, *.tsbuildinfo",
+    "vite.config.*": "jsconfig*, vitest.config.*, playwright.config.*"
+  },
+  "files.associations": {
+    "*.css": "tailwindcss"
+  },
+  "tailwindCSS.classAttributes": ["class", "className"],
+  "tailwindCSS.classFunctions": ["cn", "cva", "clsx", "addClassName"]
 }

AGENTS.md

@@ -0,0 +1,90 @@
+# AGENTS.md
+
+Component library for Figma/FigJam plugin UIs: `packages/react` (React + Base UI
++ Tailwind v4) over shared tokens in `packages/theme`. `playground/` is a
+consumer smoke test. Layering, token rules, naming and release policy:
+`docs/architecture.md`; decisions in `docs/adr/`; vocabulary in `GLOSSARY.md`.
+Per-component design audits live in `docs/audit/` (gitignored, local only).
+
+## Layout
+
+- Tests live in `packages/<pkg>/tests/` mirroring `src/` (e.g.
+  `src/components/x/x.test.tsx` → `tests/components/x/x.test.tsx`); shared
+  helpers in `packages/react/tests/test-utils/`; never colocate tests in `src/`.
+- React tests import sources via the `~` alias (`~/components/x/x`); theme and
+  utils tests use relative `../src/...` paths.
+
+## Verify
+
+- `pnpm test` — unit + browser tests.
+- `pnpm test:visual` — pixel-exact screenshot suite (207 baselines). CI does not
+  run it; always run locally before finishing UI work.
+- `pnpm typecheck`, `pnpm check`, `pnpm build`.
+- `pnpm deps` — taze interactive dependency updates (`-r -I -l`).
+- `pnpm -F @thinkbuff/figma-react build-storybook` after component changes.
+
+## Visual tests
+
+- Baselines: `packages/react/tests/visual/__screenshots__/*-chromium-darwin.png`.
+  `pnpm test:visual:update` rewrites them — inspect every changed image before
+  committing; an update bakes whatever rendered, including bugs.
+- Vite can serve stale styles: a "no diff" result may be a cached render, not a
+  real match. The vrt scripts clear `node_modules/.vite` first. To verify a
+  suspicious result, dump computed styles:
+  `VRT_PROBE="<story id>" pnpm -F @thinkbuff/figma-react probe`.
+- `pnpm vrt:diff -- [vitest args]` snapshots baselines, re-runs the update and
+  lists which shots changed (before-copies under `$TMPDIR/figma-vrt-diff/`).
+- An update run can rewrite PNGs byte-differently with identical pixels; compare
+  decoded pixels against `HEAD` with PIL
+  `ImageChops.difference(a.convert('RGB'), b.convert('RGB')).getbbox()` (RGBA
+  `getbbox()` only checks alpha) and `git restore` the pixel-identical ones
+  before committing.
+- The comparator is pixelmatch with `threshold: 0` — strict, any changed pixel
+  counts.
+
+## Theme (`packages/theme`)
+
+- Token values live only in `tokens/*.json`. `tokens/colors/*`, `sizing.json`
+  and `typography.json` come from `pnpm tokens:import <dir>` (a Figma "Export
+  modes" folder; copy it out of `~/Downloads` first — the sandbox can't read
+  it); `elevation.json` and `extensions.json` are hand-maintained. Never edit
+  imported files by hand unless the Design file can't be exported.
+- `src/css/**` is generated by `pnpm generate:css` — edit `tokens/` or
+  `src/theme/`, never the output. CI fails on uncommitted drift.
+- Styles resolve through built artifacts: `styles.css` imports the theme's
+  `dist/css` and scans `packages/react/dist` via `@source`. After adding a
+  utility or changing classes, rebuild (`pnpm build`) or VRT/Storybook renders
+  stale CSS with silently missing rules.
+- `--figma-color-*` values are injected by the Figma editor at runtime
+  (`themeColors: true`); see `docs/figma-runtime-colors.md` to extract them.
+- Register every new utility family in `packages/react/src/utils/cn.ts`
+  (tailwind-merge groups) or `cn()` merges it into the wrong group.
+- Elevation/shadow variables live in the per-theme blocks (`.figma-light`,
+  `.figma-dark`, `.figjam`), not `@theme`, so nested `.figma-dark` resolves dark
+  values.
+- Design reference: the UI3 Design file (official community file linked in
+  `docs/architecture.md` §1). Match component sets by page and set name, never
+  by node id; working-copy links live in the gitignored
+  `docs/figma-ui3-design.md`.
+
+## Components (`packages/react`)
+
+- Base UI conventions: `render` prop (never `asChild`), `aria-expanded` for
+  open-state styling, `addClassName` for callback classNames, `cn()` to merge.
+- Controlled `Tabs.Root value` scrolls the tab list to the end on mount (Base UI
+  composite scrolls the active item into view). Prefer `defaultValue` unless
+  external state control is required.
+- Prefer canonical Tailwind forms (`data-popup-open`, `inset-0.5`,
+  `-top-1.25`) over bracket variants and arbitrary values.
+- Component styles are cva variants in `<name>-variants.ts` (or inline classes)
+  built only from Utility contract classes; `packages/react/styles.css`
+  `@layer components` is only for what cva cannot express (keyframes,
+  third-party DOM).
+
+## Commits
+
+- Conventional Commits (commitlint enforced); pre-commit runs `vp check --fix`
+  on staged files.
+- File names are kebab-case (`unicorn/filename-case` is an error); conventional
+  uppercase files like `README.md` and `AGENTS.md` are the exception.
+- Do not kill listeners on dev ports (Storybook uses 6006) you did not start.