base-themes 0.1.2 → 0.1.3

package/skills/base-themes/SKILL.md

@@ -1,32 +1,34 @@
 ---
 name: base-themes
-description: Install and extend the Base Themes React component kit built on Base UI primitives, with Bento, shadcn, and neo brutalism styles, blocks, theme tokens, and registry metadata. Use when adding Base Themes components, blocks, custom themes, or installation guidance to a React app.
+description: Install, inspect, customize, and verify the Base Themes React component kit built on Base UI primitives. Use when adding Base Themes components, blocks, theme styles, registry/source-copy plans, or agent-safe UI customization to a React app.
 ---
 
 # Base Themes
 
-## Quick Start
+Base Themes is a package-first React component system built on `@base-ui/react`. It ships typed component wrappers, CSS token themes, 20 visual styles, product blocks, registry metadata, CLI helpers, and agent-readable docs.
 
-Install the package and peer dependencies in the target React app. Prefer this npm package flow for normal usage:
+## Prefer Package Installs
+
+Install the package and peer dependencies in the target React app:
 
 ```bash
 npm install base-themes @base-ui/react react react-dom
 ```
 
-Import the styles once:
+Import the bundled CSS once at app startup:
 
 ```tsx
 import 'base-themes/styles.css'
 ```
 
-Use a packaged component:
+Render components inside a themed root. Use `data-style` for the visual system and `data-theme` for light or dark mode:
 
 ```tsx
 import { Button, Select } from 'base-themes'
 
-export function Example() {
+export function SettingsPanel() {
   return (
-    <div data-style="bento" data-theme="light">
+    <section data-style="bento" data-theme="light">
       <Button>Save changes</Button>
       <Select
         id="density"
@@ -34,83 +36,185 @@ export function Example() {
         defaultValue="comfortable"
         items={{ compact: 'Compact', comfortable: 'Comfortable', spacious: 'Spacious' }}
       />
-    </div>
+    </section>
   )
 }
 ```
 
-Registry metadata is available from the package when an agent or script needs to inspect components, blocks, dependencies, or required files:
+React 18.2+ and React 19 are supported by peer dependencies. The Vite, dashboard, and theme-customization examples build against React 18; the Next.js example builds against React 19.
+
+## Machine-Readable Metadata
+
+Use package exports before scraping docs:
 
 ```ts
 import registry from 'base-themes/registry.json'
+import shadcnRegistry from 'base-themes/shadcn-registry.json'
+import buttonItem from 'base-themes/registry/items/button.json'
+import blockMeta from 'base-themes/block-meta.json'
+import componentMeta from 'base-themes/component-meta.json'
+import staticPageMeta from 'base-themes/static-page-meta.json'
+import themeMeta from 'base-themes/theme-meta.json'
+import tokenContract from 'base-themes/token-contract.json'
 ```
 
-This skill markdown is included in the installed package at `node_modules/base-themes/skills/base-themes/SKILL.md` and exposed as `base-themes/skill` for tools that read package exports.
+The same metadata is hosted when the docs site is deployed:
+
+- `/registry/registry.json`
+- `/registry/shadcn-registry.json`
+- `/registry/items/button.json`
+- `/registry/block-meta.json`
+- `/registry/component-meta.json`
+- `/registry/static-page-meta.json`
+- `/registry/theme-meta.json`
+- `/llms.txt`
+- `/llms-full.txt`
+
+This skill markdown is included at `node_modules/base-themes/skills/base-themes/SKILL.md` and exported as `base-themes/skill` for tools that read package exports.
 
-For source-copy installs only, copy the component wrappers and styles:
+## CLI Workflows
+
+Use the CLI to inspect coverage, generate source-copy plans, and diagnose real apps:
 
 ```bash
-cp -R src/components/ui ./target-app/src/components/ui
-cp -R src/styles ./target-app/src/styles
+npx base-themes list
+npx base-themes list --json
+npx base-themes plan button select block:dashboard-shell theme:enterprise
+npx base-themes plan button select block:dashboard-shell theme:enterprise --json
+npx base-themes add button select block:dashboard-shell theme:enterprise --target . --dry-run
+npx base-themes add button select block:dashboard-shell theme:enterprise --target . --dry-run --json
+npx base-themes doctor .
+npx base-themes doctor . --json
 ```
 
-Import the tokens once from app CSS:
+Use `base-themes/registry.json` for the internal source-copy manifest. Use `base-themes/shadcn-registry.json`, package item exports such as `base-themes/registry/items/button.json`, or hosted `/registry/items/*.json` when a shadcn-compatible catalog or item-level `meta.agent` guidance is more useful.
 
-```css
-@import './styles/tokens.css';
-```
+Use `plan --json` before source-copying. It resolves package dependencies, all registry style files, block files, component files, available styles, missing names, package item imports such as `base-themes/registry/items/button.json`, hosted item URLs, block `meta.agent.registryItems`, theme `data-style` steps from requests such as `theme:enterprise`, and generated `meta.agent.packageInstall` / `meta.agent.sourceCopy` steps. The CLI is intentionally a planner, not a file copier; agents should make target paths, import rewrites, formatting, and lockfile changes explicitly in the destination app.
+
+Use `add --dry-run --json` when the user explicitly wants source files copied from the package registry. `add` copies only registry-listed style, block, and component files into `--target`, skips existing files by default, and requires `--force` before overwriting. After copying, review imports and run the target app's formatter, lint, tests, and build.
 
-## Workflows
+Use `list --json` before choosing components, blocks, or themes. Use `doctor --json` after installation. It checks package dependencies, the `base-themes/styles.css` side-effect import, and `data-style` / `data-theme` wiring. WARN output includes concrete fixes, docs URLs, and bug-report guidance.
 
-### Add A Component
+Use `base-themes/token-contract.json` before generating theme overrides. The stable public customization surface is `data-style`, `data-theme`, and the `--bt-*` tokens; legacy variables without the prefix remain 0.x compatibility aliases.
 
-1. For package installs, import the component from `base-themes` and import `base-themes/styles.css` once.
-2. For source-copy installs, check `registry/registry.json` or `base-themes/registry.json` for the component entry.
-3. Copy every file listed in the entry's `files` array.
-4. Ensure `src/styles/tokens.css`, `src/styles/shadcn.css`, `src/styles/neo-brutalism.css`, and `src/styles/themes.css` are imported by the target app when source-copying.
-5. Install dependencies from the registry `dependencies` array.
-6. Import the component from `src/components/ui`.
+## Add Components
 
-### Add A Block
+1. For package consumers, import components from `base-themes` and keep `base-themes/styles.css` imported once.
+2. For source-copy consumers, run `npx base-themes plan <component...>` or read `base-themes/registry.json`.
+3. Copy every file from the plan's component files and style files.
+4. Install dependencies from the plan.
+5. Preserve labels, focus behavior, disabled states, and keyboard interactions from the docs.
+6. Run registry, lint, test, build, and package smoke checks before returning the change.
 
-1. Open `registry/registry.json` and find the block under `blocks`.
-2. Copy the components listed in the block's `components` array.
-3. Recreate the block layout from `/blocks` or adapt it into the target route.
-4. Keep block styles token-based; avoid hard-coded one-off colors.
+## Add Blocks
 
-### Customize Theme
+1. Run `npx base-themes plan block:<block-name>` to resolve block source and component dependencies.
+2. Copy the block files and required component files together.
+3. Keep block styles token-based and responsive; do not hard-code one-off colors when semantic tokens exist.
+4. Link users to `/blocks/<block-name>` or registry metadata when explaining what was copied.
 
-Override variables in `src/styles/tokens.css`, or add style-specific overrides under `[data-style='shadcn']` and `[data-style='neo-brutalism']`:
+Useful block requests include:
+
+```bash
+npx base-themes plan block:dashboard-shell
+npx base-themes plan block:data-table
+npx base-themes plan block:theme-showcase-card
+```
+
+## Customize Themes
+
+Start from an existing `data-style` and override semantic CSS variables in app CSS. Avoid a JavaScript theme runtime unless the target app already has one.
 
 ```css
 :root {
-  --bg: #f8fafc;
-  --surface: #ffffff;
-  --text-strong: #111827;
-  --accent: #f97316;
+  --bt-primary: #2563eb;
+  --bt-secondary: #0f766e;
+  --bt-radius: 10px;
+  --bt-radius-sm: 8px;
+  --bt-font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
 }
 
 [data-theme='dark'] {
-  --bg: #0b1120;
-  --surface: #111827;
-  --text-strong: #f1f5f9;
-  --accent: #fb923c;
+  --bt-bg: #0b1120;
+  --bt-surface: #111827;
+  --bt-fg: #f8fafc;
+  --bt-primary: #60a5fa;
 }
 ```
 
+For current 0.x builds, mirror a `--bt-*` override to the matching legacy token when the target component still reads the legacy variable directly, for example `--accent: var(--bt-primary)`.
+
+Use `examples/theme-customization` when validating brand color, radius, font, density, and copyable CSS-variable workflows.
+
+## Runnable Examples
+
+Use examples to verify real package integration paths:
+
+```bash
+npm run example:vite:build
+npm run example:dashboard:build
+npm run example:theme-customization:build
+npm run example:next:build
+npm run example:registry-copy -- button select block:dashboard-shell theme:enterprise
+npm run example:registry-copy -- plan button select block:dashboard-shell theme:enterprise --json
+```
+
+Choose the example by question:
+
+- `examples/vite`: fresh React 18 Vite install with package CSS, components, `useTheme`, and registry JSON.
+- `examples/dashboard`: product dashboard composed from shipped blocks, controls, registry metadata, and theme switching.
+- `examples/theme-customization`: token overrides for brand color, radius, font, density, and copyable variables.
+- `examples/next`: Next.js App Router / React 19 integration.
+- `examples/registry-copy`: CLI-aligned list, plan, add dry-run, and doctor proof for source-copy tools.
+
 ## Verification
 
-Run these checks after changing components, registry, blocks, or theme tokens:
+Run these after changing package exports, components, registry, docs, blocks, theme tokens, examples, or agent workflow docs:
 
 ```bash
-node scripts/validate-registry.mjs
+npm run registry:check
+npm run tokens:check
 npm run lint
+npm run test
 npm run build
+npm run seo:check
+npm run bundle:report
+npm run bundle:report -- --json
+npm run telemetry:check
+npm run telemetry:check -- --live
+npm run telemetry:fixtures
+npm run launch:status
+npm run launch:status -- --live
+npm run launch:actions
+npm run launch:actions -- --live
+npm run launch:campaign
+npm run package:smoke
+```
+
+Run targeted checks when relevant:
+
+```bash
+npm run community:check
+npm run community:issues -- --json
+npm run analytics:check
+npm run telemetry:collect -- --json
+npm run themes:e2e
+npm run previews:check
+npm run example:theme-customization:build
 ```
 
-Use the docs app for manual verification:
+`themes:e2e` and `previews:check` require `agent-browser`. Use `npm run community:check` when editing issue templates, contributor seed issues, gallery wording, or `.github/labels.json`. Use `npm run community:issues` before announcements to render good-first issue URLs or GitHub CLI commands; it does not publish issues by itself.
+
+Use `npm run telemetry:check` before claiming adoption progress. It validates the latest saved telemetry report: four public signals, a three-signal completion threshold, `externallyValidated` derived from the score, and no telemetry collection errors. Use `npm run telemetry:check -- --live` to validate a fresh no-write GitHub/npm collection. A release can be ready while adoption remains unvalidated.
+
+Use `npm run telemetry:fixtures` when editing telemetry import logic or adoption docs. It imports bundled sanitized Search Console, website analytics, registry access, community proof, and bundle report exports from `research/telemetry-fixtures` so private-provider parsing stays covered without real credentials.
+
+Use `npm run launch:status` after `npm run telemetry:collect` to read the latest telemetry JSON and summarize the public adoption score, missing signals, recommended good-first issue URLs, telemetry collection errors, supporting evidence, and next launch actions. Use `npm run launch:status -- --live` before external promotion when the latest saved report may be stale.
+
+Use `npm run launch:actions` while the public adoption gate is still unmet. It converts missing star, fork, external issue/PR, or download signals into a concrete action list with links, commands, recommended good-first issue URLs, share assets, a promotion wave, and a campaign checklist. Use `npm run launch:actions -- --live` to build that action list from current GitHub/npm data without writing a telemetry report. Use `npm run launch:campaign` before external promotion to write the live campaign JSON and Markdown pack to `research/`.
+
+Use `npm run bundle:report -- --json` when checking website performance budgets. It emits app JS, largest JS, total JS, gzip sizes, and budget results for CI or telemetry-style consumption. Import that output with `BUNDLE_REPORT_EXPORT=path/to/bundle-report.json npm run telemetry:collect` when comparing performance budgets with adoption-funnel telemetry.
+
+## Adoption Feedback
 
-- `/components/button` for component pages
-- `/blocks` for block examples
-- `/themes` for token customization
-- `/docs/installation` for install instructions
+If installation, doctor, registry-copy, example, or customization flows fail in a real app, open the smallest useful GitHub signal: bug report with WARN output, feature request for a missing component/block/theme, or community gallery submission for real usage.

package/src/blocks/AuthCard.tsx

@@ -0,0 +1,29 @@
+import { Button } from '../components/ui/Button'
+import { Field } from '../components/ui/Field'
+import { Input } from '../components/ui/Input'
+import { Separator } from '../components/ui/Separator'
+import { Switch } from '../components/ui/Switch'
+import './Blocks.css'
+
+export function AuthCard() {
+  return (
+    <section className="base-block" aria-label="Authentication card block">
+      <div>
+        <h2 className="base-block-title">Sign in to workspace</h2>
+        <p className="base-block-copy">A focused authentication card with remembered-device controls.</p>
+      </div>
+      <div className="base-block-form">
+        <Field label="Email">
+          <Input id="block-auth-email" type="email" placeholder="you@example.com" />
+        </Field>
+        <Field label="Password">
+          <Input id="block-auth-password" type="password" placeholder="Enter password" />
+        </Field>
+        <Switch id="block-auth-remember" label="Remember this device" />
+        <Button type="button">Continue</Button>
+        <Separator />
+        <Button type="button" variant="outline">Continue with SSO</Button>
+      </div>
+    </section>
+  )
+}

package/src/blocks/Blocks.css

@@ -0,0 +1,182 @@
+.base-block {
+  display: grid;
+  gap: 16px;
+  padding: 18px;
+  border: 1px solid var(--bt-border);
+  border-radius: var(--bt-radius);
+  color: var(--bt-text);
+  background: var(--bt-surface);
+  box-shadow: var(--bt-shadow-strong);
+}
+
+.base-block-header,
+.base-block-row,
+.base-block-actions {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.base-block-header,
+.base-block-row {
+  justify-content: space-between;
+}
+
+.base-block-title {
+  margin: 0;
+  color: var(--bt-fg);
+  font-size: 16px;
+  font-weight: 760;
+}
+
+.base-block-copy {
+  margin: 4px 0 0;
+  color: var(--bt-muted-fg);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.base-block-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(130px, 1fr));
+  gap: 12px;
+}
+
+.base-block-stat,
+.base-block-panel,
+.base-block-list-item {
+  padding: 12px;
+  border: 1px solid var(--bt-border);
+  border-radius: var(--bt-radius-sm);
+  background: var(--bt-surface-muted);
+}
+
+.base-block-stat strong,
+.base-block-metric {
+  display: block;
+  color: var(--bt-fg);
+  font-size: 24px;
+  font-weight: 780;
+}
+
+.base-block-stat span,
+.base-block-muted {
+  color: var(--bt-muted-fg);
+  font-size: 12px;
+}
+
+.base-block-list {
+  display: grid;
+  gap: 10px;
+}
+
+.base-block-list-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.base-block-list-main {
+  min-width: 0;
+}
+
+.base-block-list-main strong {
+  display: block;
+  overflow: hidden;
+  color: var(--bt-fg);
+  font-size: 14px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.base-block-list-main span {
+  display: block;
+  margin-top: 2px;
+  color: var(--bt-muted-fg);
+  font-size: 12px;
+}
+
+.base-block-table {
+  width: 100%;
+  border-collapse: collapse;
+  overflow: hidden;
+  border: 1px solid var(--bt-border);
+  border-radius: var(--bt-radius-sm);
+  font-size: 13px;
+}
+
+.base-block-table th,
+.base-block-table td {
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--bt-border);
+  text-align: left;
+}
+
+.base-block-table th {
+  color: var(--bt-muted-fg);
+  background: var(--bt-surface-muted);
+  font-size: 12px;
+  font-weight: 720;
+}
+
+.base-block-table td {
+  color: var(--bt-text);
+}
+
+.base-block-table tr:last-child td {
+  border-bottom: 0;
+}
+
+.base-block-pill {
+  display: inline-flex;
+  align-items: center;
+  min-height: 22px;
+  padding: 0 8px;
+  border: 1px solid var(--bt-border);
+  border-radius: 999px;
+  color: var(--bt-fg);
+  background: var(--bt-surface);
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.base-block-form {
+  display: grid;
+  gap: 12px;
+}
+
+.base-block-split {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 16px;
+  align-items: start;
+}
+
+.base-block-price {
+  color: var(--bt-fg);
+  font-size: 30px;
+  font-weight: 820;
+}
+
+.base-block-price span {
+  color: var(--bt-muted-fg);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+@media (max-width: 640px) {
+  .base-block-header,
+  .base-block-row,
+  .base-block-actions,
+  .base-block-list-item,
+  .base-block-split {
+    align-items: stretch;
+    flex-direction: column;
+    grid-template-columns: 1fr;
+  }
+
+  .base-block-actions {
+    display: grid;
+  }
+}

package/src/blocks/CommandPaletteBlock.tsx

@@ -0,0 +1,32 @@
+import { Button } from '../components/ui/Button'
+import { Combobox } from '../components/ui/Combobox'
+import './Blocks.css'
+
+const commands = [
+  { value: 'create-theme', label: 'Create theme' },
+  { value: 'open-registry', label: 'Open registry' },
+  { value: 'view-components', label: 'View components' },
+]
+
+export function CommandPaletteBlock() {
+  return (
+    <section className="base-block" aria-label="Command palette block">
+      <div>
+        <h2 className="base-block-title">Command Palette</h2>
+        <p className="base-block-copy">A quick-action panel for product navigation, search, and agent-oriented commands.</p>
+      </div>
+      <Combobox label="Jump to" placeholder="Search commands..." options={commands} />
+      <div className="base-block-list">
+        {commands.map((command) => (
+          <div className="base-block-list-item" key={command.value}>
+            <div className="base-block-list-main">
+              <strong>{command.label}</strong>
+              <span>{command.value}</span>
+            </div>
+            <Button type="button" variant="ghost">Run</Button>
+          </div>
+        ))}
+      </div>
+    </section>
+  )
+}

package/src/blocks/DashboardShell.tsx

@@ -0,0 +1,36 @@
+import { Button } from '../components/ui/Button'
+import { Meter } from '../components/ui/Meter'
+import { Progress } from '../components/ui/Progress'
+import './Blocks.css'
+
+const stats = [
+  { label: 'Revenue', value: '$48.2k' },
+  { label: 'Active seats', value: '1,248' },
+  { label: 'Deploys', value: '36' },
+]
+
+export function DashboardShell() {
+  return (
+    <section className="base-block" aria-label="Dashboard shell block">
+      <div className="base-block-header">
+        <div>
+          <h2 className="base-block-title">Operations Dashboard</h2>
+          <p className="base-block-copy">A compact dashboard header with metrics, progress, and a primary action.</p>
+        </div>
+        <Button variant="outline">Export</Button>
+      </div>
+      <div className="base-block-grid">
+        {stats.map((stat) => (
+          <div className="base-block-stat" key={stat.label}>
+            <strong>{stat.value}</strong>
+            <span>{stat.label}</span>
+          </div>
+        ))}
+      </div>
+      <div className="base-block-panel">
+        <Progress value={72} showValue aria-label="Quarterly target" />
+      </div>
+      <Meter value={84} showValue aria-label="System health" />
+    </section>
+  )
+}

package/src/blocks/DataTableBlock.tsx

@@ -0,0 +1,44 @@
+import { Button } from '../components/ui/Button'
+import { Select } from '../components/ui/Select'
+import './Blocks.css'
+
+const statusItems = {
+  all: 'All statuses',
+  active: 'Active',
+  pending: 'Pending',
+}
+
+const rows = [
+  { project: 'Checkout refresh', owner: 'Ava', status: 'Active' },
+  { project: 'Theme QA', owner: 'Mina', status: 'Pending' },
+  { project: 'Registry docs', owner: 'Noah', status: 'Active' },
+]
+
+export function DataTableBlock() {
+  return (
+    <section className="base-block" aria-label="Data table block">
+      <div className="base-block-header">
+        <div>
+          <h2 className="base-block-title">Projects</h2>
+          <p className="base-block-copy">A small operational table with filters and row status badges.</p>
+        </div>
+        <Select id="block-project-status" defaultValue="all" items={statusItems} />
+      </div>
+      <table className="base-block-table">
+        <thead>
+          <tr><th>Project</th><th>Owner</th><th>Status</th></tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={row.project}>
+              <td>{row.project}</td>
+              <td>{row.owner}</td>
+              <td><span className="base-block-pill">{row.status}</span></td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      <Button type="button" variant="outline">View all projects</Button>
+    </section>
+  )
+}

package/src/blocks/PricingPanel.tsx

@@ -0,0 +1,28 @@
+import { Button } from '../components/ui/Button'
+import { Checkbox } from '../components/ui/Checkbox'
+import './Blocks.css'
+
+const features = ['Unlimited themes', 'Registry metadata', 'Agent workflow docs']
+
+export function PricingPanel() {
+  return (
+    <section className="base-block" aria-label="Pricing panel block">
+      <div className="base-block-split">
+        <div>
+          <h2 className="base-block-title">Team plan</h2>
+          <p className="base-block-copy">A compact pricing panel for SaaS settings, upgrade, or billing screens.</p>
+        </div>
+        <div className="base-block-price">$29<span>/seat</span></div>
+      </div>
+      <div className="base-block-list">
+        {features.map((feature) => (
+          <div className="base-block-list-item" key={feature}>
+            <Checkbox defaultChecked aria-label={feature} />
+            <div className="base-block-list-main"><strong>{feature}</strong></div>
+          </div>
+        ))}
+      </div>
+      <Button type="button">Upgrade plan</Button>
+    </section>
+  )
+}

package/src/blocks/SettingsForm.tsx

@@ -0,0 +1,37 @@
+import { Button } from '../components/ui/Button'
+import { Field } from '../components/ui/Field'
+import { Fieldset } from '../components/ui/Fieldset'
+import { Input } from '../components/ui/Input'
+import { Select } from '../components/ui/Select'
+import { Switch } from '../components/ui/Switch'
+import './Blocks.css'
+
+const densityItems = {
+  compact: 'Compact',
+  comfortable: 'Comfortable',
+  spacious: 'Spacious',
+}
+
+export function SettingsForm() {
+  return (
+    <section className="base-block" aria-label="Settings form block">
+      <div>
+        <h2 className="base-block-title">Workspace Settings</h2>
+        <p className="base-block-copy">A production-style settings form for team preferences and workspace defaults.</p>
+      </div>
+      <Fieldset legend="Workspace">
+        <div className="base-block-form">
+          <Field label="Workspace name" description="Visible to invited team members.">
+            <Input id="block-workspace-name" defaultValue="Product Operations" />
+          </Field>
+          <Select id="block-density" label="Interface density" defaultValue="comfortable" items={densityItems} />
+          <Switch id="block-weekly-summary" defaultChecked label="Send weekly summary" />
+          <div className="base-block-actions">
+            <Button type="button">Save settings</Button>
+            <Button type="button" variant="outline">Cancel</Button>
+          </div>
+        </div>
+      </Fieldset>
+    </section>
+  )
+}