base-themes 0.1.1 → 0.1.3

package/docs/registry-access-telemetry.md

@@ -0,0 +1,87 @@
+# Registry Access Telemetry
+
+Use this checklist after the docs site is deployed to measure whether registry metadata, `llms.txt`, `llms-full.txt`, CLI docs, and agent workflow pages are actually being consumed.
+
+Registry access is supporting evidence for adoption. It does not replace the public completion gate in [adoption-dashboard.md](./adoption-dashboard.md), but it shows whether the agent-native and source-copy parts of the strategy are getting real traffic.
+
+## Routes To Track
+
+Track these production paths in CDN, Cloudflare, or server access logs:
+
+| Route | Signal |
+| --- | --- |
+| `/registry/registry.json` | Tools or users are fetching the full source-copy registry. |
+| `/registry/shadcn-registry.json` | Tools or users are fetching the shadcn-compatible catalog. |
+| `/registry/items/*.json` | Tools or users are fetching item-level component, block, theme, or `meta.agent` metadata. |
+| `/registry/block-meta.json` | Tools or docs consumers are reading block route, title, category, description, and export metadata. |
+| `/registry/component-meta.json` | Tools or docs consumers are reading component metadata. |
+| `/registry/theme-meta.json` | Tools or docs consumers are reading theme metadata. |
+| `/llms.txt` | AI agents, search tools, or humans are discovering agent-readable entry points. |
+| `/llms-full.txt` | AI agents or search tools are fetching the full component, theme, block, registry, and verification context. |
+| `/docs/registry` | Users are evaluating source-copy registry usage. |
+| `/docs/cli` | Users are evaluating CLI workflows such as `list`, `plan`, and `doctor`. |
+| `/docs/agent-usage` | Users are evaluating the agent-native workflow. |
+
+## Export Format
+
+Export sanitized access rows as JSON, JSONL, or CSV. Useful fields are:
+
+| Field | Accepted Names |
+| --- | --- |
+| Path or URL | `path`, `Path`, `uri`, `URI`, `url`, `URL`, `requestUrl` |
+| Status | `status`, `Status` |
+| Referrer | `referer`, `referrer`, `Referer`, `Referrer` |
+| User agent | `userAgent`, `user_agent`, `User-Agent` |
+| Timestamp | `timestamp`, `datetime`, `date` |
+
+Keep exports sanitized. Do not include IP addresses, cookies, request headers, emails, or full query strings. The telemetry importer only needs the path-level signal.
+
+Example JSONL:
+
+```jsonl
+{"path":"/registry/registry.json","status":200,"referer":"https://base-themes.bangwu.me/docs/registry","userAgent":"curl/8"}
+{"path":"/registry/shadcn-registry.json","status":200,"referer":"https://base-themes.bangwu.me/llms.txt","userAgent":"agent-discovery"}
+{"path":"/registry/items/button.json","status":200,"referer":"https://base-themes.bangwu.me/llms.txt","userAgent":"agent-discovery"}
+{"path":"/registry/items/block-dashboard-shell.json","status":200,"referer":"https://base-themes.bangwu.me/docs/agent-usage","userAgent":"agent-discovery"}
+{"path":"/registry/block-meta.json","status":200,"referer":"https://base-themes.bangwu.me/docs/registry","userAgent":"agent-discovery"}
+{"path":"/registry/items/theme-enterprise.json","status":200,"referer":"https://base-themes.bangwu.me/themes/enterprise","userAgent":"agent-discovery"}
+{"url":"https://base-themes.bangwu.me/llms.txt","status":200,"userAgent":"agent-discovery"}
+{"url":"https://base-themes.bangwu.me/llms-full.txt","status":200,"userAgent":"agent-discovery"}
+```
+
+## Import Command
+
+Run telemetry with the access export:
+
+```bash
+REGISTRY_ACCESS_EXPORT=path/to/registry-access.jsonl npm run telemetry:collect
+```
+
+You can combine it with other provider exports:
+
+```bash
+REGISTRY_ACCESS_EXPORT=path/to/registry-access.jsonl ANALYTICS_EXPORT=path/to/analytics-events.jsonl SEARCH_CONSOLE_EXPORT=path/to/search-console-export.csv npm run telemetry:collect
+```
+
+The report summarizes total matched registry/agent requests, requests for each registry artifact, standard registry item requests, component/block/theme item request breakdowns, block/component/theme metadata requests, `/llms.txt`, `/llms-full.txt`, registry docs, CLI docs, agent docs, top paths, top item paths, top referrers, and top user agents.
+
+Before trusting a new export shape, run the bundled fixture check:
+
+```bash
+npm run telemetry:fixtures
+```
+
+The checked registry fixture lives at `research/telemetry-fixtures/registry-access.jsonl` and covers full registry, shadcn registry, component item, block item, theme item, metadata, `llms.txt`, `llms-full.txt`, and CLI-doc access rows.
+
+## Decision Rules
+
+- If `/registry/registry.json` has traffic but npm downloads do not move, improve registry install examples and source-copy docs.
+- If `/registry/shadcn-registry.json` or `/registry/items/*.json` has traffic, prioritize deterministic item metadata, `meta.agent` quality, and stable shadcn-compatible paths before adding more decorative docs.
+- If theme item requests lead block or component item requests, improve theme-to-component install examples and route users toward `examples/theme-customization`.
+- If block item requests lead component item requests, improve block copy plans, block screenshots, and product-screen examples.
+- If `/registry/block-meta.json` has traffic but block item requests do not, make registry block item URLs and `npx base-themes plan block:<name>` examples more visible from block routes.
+- If `/llms.txt` has traffic but `/docs/agent-usage` does not, make the agent workflow route easier to discover from the discovery file and README.
+- If `/llms-full.txt` has traffic but item JSON does not, move registry item examples higher in the full agent context.
+- If `/docs/cli` has traffic but few install command copies or GitHub clicks, improve `npx base-themes doctor .` placement and troubleshooting examples.
+- If registry artifacts have no traffic after announcements, include direct registry and `llms.txt` links in release posts and docs CTAs.
+- If user agents show known coding agents or package tools, prioritize deterministic metadata, stable URLs, and source-copy planning over decorative docs changes.

package/docs/release-announcement-kit.md

@@ -0,0 +1,229 @@
+# Release Announcement Kit
+
+Base Themes needs public adoption evidence, not just local release readiness. Use this kit after a verified release to turn the package, docs, blocks, CLI, and registry work into measurable external signals.
+
+## Goal
+
+Drive real users from discovery to installation, feedback, stars, forks, issues, pull requests, and gallery submissions.
+
+The current completion gate for the strategy is external evidence that enough users are willing to use the project. Local checks can prove readiness, but they cannot prove adoption.
+
+## Shareable Positioning
+
+Short version:
+
+> Accessible Base UI components. 20 themes. Registry-ready. Agent-friendly.
+
+Long version:
+
+> Base Themes is a type-safe React component system built on Base UI. It ships accessible component wrappers, CSS-token themes, 20 curated visual styles, source-copyable registry metadata, blocks, examples, and an agent-friendly workflow for customizing product UI.
+
+Use these points consistently:
+
+- Built on `@base-ui/react` accessible primitives.
+- Supports React 18.2+ and React 19.
+- Includes 20 visual styles through `data-style` and `data-theme`.
+- Ships 40 components, 8 blocks, 18 pages, and registry metadata.
+- Includes `npx base-themes list`, `plan`, `add`, and `doctor`.
+- Provides Vite, dashboard, theme-customization, Next.js, and registry-copy examples.
+- Published from GitHub Actions with npm provenance.
+
+## Release Checklist Extension
+
+Run the normal [release checklist](../RELEASE.md) first. After publish and docs deploy, complete these adoption steps:
+
+1. Confirm the new package version is visible on npm.
+2. Confirm the docs site deploy includes current SEO routes, theme pages, block pages, and CLI docs.
+3. Submit and inspect search entry points with [search-console-setup.md](./search-console-setup.md) so SEO routes can produce measurable discovery signals.
+4. If website funnel measurement is enabled, validate the receiver with `npm run analytics:check` and build the docs site with `VITE_ANALYTICS_ENDPOINT` from [analytics-setup.md](./analytics-setup.md).
+5. If CDN or server access logs are available, prepare registry and agent-route exports with [registry-access-telemetry.md](./registry-access-telemetry.md).
+6. Run `npm run build` and `npm run bundle:report -- --json > path/to/bundle-report.json` if you want the telemetry report to compare campaign conversion with bundle budgets.
+7. Run `npm run telemetry:collect` or `BUNDLE_REPORT_EXPORT=path/to/bundle-report.json npm run telemetry:collect` and save the report.
+8. Run `npm run launch:status -- --live` to confirm whether the public adoption gate is still unmet or externally validated against current GitHub/npm data before writing announcement copy.
+9. Run `npm run launch:actions -- --live` when the gate is still unmet, or `npm run launch:campaign` when you want to write the live campaign JSON and Markdown pack to `research/`, then use the generated star, fork, and external issue/PR actions to choose the next announcement wave.
+10. Run `npm run community:issues` and publish two or three seed issues from [contributor-issue-seeds.md](./contributor-issue-seeds.md), so external users have an immediate good-first action after starring or forking.
+11. Enable or verify GitHub Discussions with a `Show and tell` category that uses [.github/DISCUSSION_TEMPLATE/show-and-tell.yml](../.github/DISCUSSION_TEMPLATE/show-and-tell.yml), so lightweight usage posts do not need to become permissioned gallery issues immediately.
+12. Run `npm run release:announce` to render current-count release, social, forum, directory, command, and call-to-action copy from `package.json` and `registry/registry.json`.
+13. Run `npm run launch:check` to verify release copy, contributor seed issue URLs, community links, telemetry docs, and the public adoption gate before sharing externally.
+14. Create a GitHub release with the announcement copy below or the generated copy, then link one or two published seed issues.
+15. Pin or feature one screenshot that shows a real block, not only swatches.
+16. Share the release in at least three external channels.
+17. Ask for one concrete action in each post: star the repo after trying it, fork it and run the Fork-to-first-change workflow, try `npx base-themes add button select --target . --dry-run`, run `npx base-themes doctor .`, open a Show and tell Discussion, submit a gallery issue, or comment on a good-first issue.
+18. Re-run `npm run telemetry:collect` and `npm run launch:status` after 24 hours, 7 days, and 30 days.
+19. Record which channels produced stars, forks, issues, PRs, discussions, gallery submissions, npm download slope, search impressions, registry/agent requests, docs traffic, or bundle-performance-related conversion changes.
+
+The generated channel checklist and channel copy include `utm_campaign`, `utm_source`, `utm_medium`, and `utm_content` on each `primaryLink`. Use the attributed links from the copy instead of replacing them with bare repo or docs URLs when website analytics is enabled, so `npm run telemetry:collect` can summarize top campaigns, sources, mediums, and campaign/source conversion funnels from route views, install command copies, and GitHub outbound clicks.
+
+The generated announcement and launch-action JSON also include `shareAssets`: attributed block, theme, comparison, and CLI routes paired with preview image URLs and usage guidance for social posts, forums, and devtool directories. Each generated channel checklist entry includes `shareAssetIds` so the launch-action output maps every promotion channel to the exact screenshots or routes to use. `launch:status` and `launch:actions` include `signalTrends` from the previous telemetry report when one exists, including older Markdown-only reports, so each wave can compare public signal slope instead of only one snapshot. `launch:actions` also emits a `promotionWave` that binds each channel to its ready-to-post copy, target adoption signals, attributed primary link, share assets, action, and measurement plan, plus a `campaignChecklist` for pre-promotion checks, channel execution, and T+1/T+7/T+30 telemetry follow-up. Each checklist item includes record fields for post URLs, publish timestamps, telemetry report paths, status scores, and decision notes.
+
+`launch:campaign` writes dated files under `research/`. If a campaign Markdown file already contains filled record fields such as `Post URL:` or `Telemetry report path:`, the command refuses to overwrite it. Move filled evidence to a separate ledger or rerun with `--force` only when replacing the filled evidence is intentional.
+
+The write path also refuses to save a campaign pack when telemetry is incomplete. Rerun after GitHub/npm telemetry succeeds, or pass `--allow-incomplete` only when intentionally saving a diagnostic pack that must not be used as complete adoption evidence.
+
+## Announcement Assets
+
+Recommended screenshots or routes to share:
+
+- `/themes/bento` for the default visual system.
+- `/themes/enterprise` for operational product UI.
+- `/themes/terminal` for a distinctive developer-tool style.
+- `/blocks/dashboard-shell` for a product-screen proof point.
+- `/blocks/data-table` for dense workflow credibility.
+- `examples/dashboard` for a runnable product-screen package integration.
+- `examples/theme-customization` for token override, brand color, radius, font, and density customization.
+- `/docs/cli` for registry and source-copy workflow proof.
+
+Recommended commands to include:
+
+```bash
+npm install base-themes @base-ui/react react react-dom
+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
+npm run example:theme-customization:build
+npm run example:registry-copy -- plan button select block:dashboard-shell theme:enterprise --json
+```
+
+Render current release copy from source data:
+
+```bash
+npm run release:announce
+npm run release:announce -- --json
+npm run launch:check
+npm run telemetry:check -- --live
+npm run launch:status
+npm run launch:status -- --live
+npm run launch:actions
+npm run launch:actions -- --live
+npm run launch:actions -- --live --write
+npm run launch:campaign
+```
+
+## GitHub Release Draft
+
+```md
+Base Themes now ships as a Base UI-first React theme component system with:
+
+- 40 typed React components built on `@base-ui/react`
+- 20 CSS-token visual styles with light and dark modes
+- 8 source-copyable product blocks
+- shadcn-style registry metadata for components, blocks, pages, and themes
+- CLI helpers: `list`, `plan`, `add`, and `doctor`
+- Vite, dashboard, theme-customization, Next.js, and registry-copy examples
+- axe, package smoke, SEO, registry, and theme preview checks
+
+Try it:
+
+```bash
+npm install base-themes @base-ui/react react react-dom
+npx base-themes doctor .
+```
+
+Useful links:
+
+- Docs: https://base-themes.bangwu.me
+- Registry: https://base-themes.bangwu.me/registry/registry.json
+- Agent discovery: https://base-themes.bangwu.me/llms.txt
+- Full agent context: https://base-themes.bangwu.me/llms-full.txt
+- Blocks: https://base-themes.bangwu.me/blocks
+- CLI: https://base-themes.bangwu.me/docs/cli
+
+If you try it, please star or fork the repo, open an issue for missing components or rough edges, start a Show and tell Discussion, or submit a real usage example through the community gallery issue template.
+```
+
+## Social Drafts
+
+### X / Bluesky
+
+```text
+I shipped a stronger Base Themes release:
+
+- Base UI-first React components
+- 20 CSS-token visual styles
+- 8 product blocks
+- shadcn-style registry metadata
+- CLI: list, plan, add, doctor, and JSON output for agents
+- React 18 + 19 support
+
+Try:
+npx base-themes doctor .
+
+https://github.com/markbang/base-themes
+```
+
+### Hacker News / Reddit
+
+```text
+Show HN: Base Themes - accessible Base UI React components with 20 themes
+
+Base Themes is an open-source React component system built on @base-ui/react. It provides typed wrappers, CSS-variable themes, 20 curated visual styles, source-copyable registry metadata, product blocks, and CLI helpers for checking integration.
+
+The project is package-first rather than template-first: install from npm, import one CSS file, set data-style/data-theme, and use the components or blocks. It also ships registry metadata for tools that prefer source-copy workflows.
+
+The part I am most interested in getting feedback on: does the Base UI-first + registry + agent-friendly workflow solve a real gap for teams that like shadcn-style ownership but want a packaged multi-theme system?
+
+Repo: https://github.com/markbang/base-themes
+Docs: https://base-themes.bangwu.me
+```
+
+### Product Hunt / Directory Submission
+
+```text
+Base Themes is a React component system built on Base UI. It ships accessible typed components, 20 CSS-token visual styles, source-copyable registry metadata, product blocks, and CLI checks for integrating the package into Vite or Next.js apps.
+```
+
+## Calls To Action
+
+Rotate calls to action instead of asking for everything at once:
+
+- Star the repo if the Base UI-first direction is useful.
+- In social, forum, and directory posts, phrase the star ask as evidence after trying the package, not as generic promotion.
+- Run `npx base-themes add button select --target . --dry-run` or `npx base-themes doctor .` in a Vite or Next.js app and report rough edges.
+- Pick one published good-first issue from `npm run community:issues` output and comment before opening a PR.
+- Open an issue for the component, block, or theme that would make the package usable in a real project.
+- Open a Show and tell Discussion with what worked, what was missing, and which `data-style` you used.
+- Submit a screenshot or repo through the community gallery template after using Base Themes.
+- Fork the repo if you want to add a theme, block, or docs example, then run the Fork-to-first-change workflow with `npm run example:theme-customization:build` or `npm run example:registry-copy -- plan button select block:dashboard-shell theme:enterprise --json` before sharing the result.
+
+## Adoption Completion Gate
+
+Treat the strategy as externally validated only when at least three of these four public signals pass in a telemetry report:
+
+| Signal | Threshold | Source |
+| --- | --- | --- |
+| npm weekly downloads | `>= 100` and stable or growing | `npm run telemetry:collect` |
+| GitHub stars | `>= 10` | `npm run telemetry:collect` |
+| External issues or PRs | At least one non-maintainer issue or PR beyond release automation | `npm run telemetry:collect` plus issue review |
+| Forks | `>= 1` | `npm run telemetry:collect` |
+
+Use private analytics as supporting evidence when available:
+
+- Cloudflare unique visitors and route views.
+- GitHub outbound clicks from docs, grouped by `repo-star`, `repo-fork`, `show-and-tell`, `feature-request`, `bug-report`, and `gallery-submission` targets.
+- Install command copies.
+- Theme, block, and CLI page depth.
+- Registry artifact requests, `/llms.txt` requests, and `/llms-full.txt` requests.
+- Search Console impressions and queries.
+- Community gallery submissions.
+
+## Follow-Up Telemetry Schedule
+
+Collect and compare telemetry at:
+
+- T+0: immediately after publish and docs deploy.
+- T+1 day: early social response.
+- T+7 days: npm weekly download slope and GitHub activity.
+- T+30 days: sustained interest, search indexing, and community submissions.
+
+Each pass should answer:
+
+- Which channel produced measurable activity?
+- Which route or screenshot earned the most interest?
+- What blocked installation or first use?
+- What component, block, or theme did users ask for repeatedly?
+- Should the next iteration improve package reliability, blocks, docs SEO, or agent-native registry workflow?

package/docs/search-console-setup.md

@@ -0,0 +1,111 @@
+# Search Console Setup
+
+Use this checklist after the docs site is deployed. It turns the SEO route work into measurable search evidence for the adoption dashboard.
+
+## Goal
+
+Prove that Base Themes can be discovered from search, not only from direct links or npm.
+
+Search evidence is supporting evidence for adoption. It does not replace the public completion gate in [adoption-dashboard.md](./adoption-dashboard.md), but it helps explain why npm downloads, stars, forks, and issues are moving or stalled.
+
+## Property Setup
+
+1. Add `https://base-themes.bangwu.me` as a URL-prefix property in Google Search Console.
+2. Verify ownership with the Cloudflare-recommended method available to the maintainer account.
+3. Submit the sitemap:
+
+```text
+https://base-themes.bangwu.me/sitemap.xml
+```
+
+4. Confirm the generated robots file is reachable:
+
+```text
+https://base-themes.bangwu.me/robots.txt
+```
+
+5. Confirm the agent discovery file is reachable:
+
+```text
+https://base-themes.bangwu.me/llms.txt
+```
+
+## URL Inspection Queue
+
+Request indexing for the routes most likely to convert searchers into users:
+
+| Route | Why It Matters |
+| --- | --- |
+| `/` | Primary package positioning and install path. |
+| `/docs/installation` | Highest-intent install query target. |
+| `/docs/base-ui-vs-shadcn` | Comparison query target for Base UI and shadcn users. |
+| `/docs/registry` | Registry/source-copy workflow target. |
+| `/docs/cli` | CLI and integration-check workflow target. |
+| `/docs/agent-usage` | Agent-native workflow target. |
+| `/docs/examples` | Fresh-install examples and framework integration target. |
+| `/themes` | Theme discovery hub. |
+| `/themes/bento` | Default visual system and social preview route. |
+| `/themes/enterprise` | Operational SaaS/product UI query target. |
+| `/themes/terminal` | Distinctive developer-tool style query target. |
+| `/blocks` | Blocks discovery hub. |
+| `/blocks/dashboard-shell` | Product-screen proof point. |
+| `/blocks/data-table` | Dense workflow proof point. |
+| `/components/button` | Common component query target. |
+| `/components/select` | Accessibility and form-control query target. |
+| `/components/dialog` | Overlay/focus-management query target. |
+
+## Query Categories
+
+Track queries by intent instead of only watching total impressions:
+
+| Category | Example Queries | Useful When |
+| --- | --- | --- |
+| Brand | `base themes`, `base-themes`, `markbang base themes` | Confirms announcements create branded demand. |
+| Base UI | `base ui themes`, `base ui react components`, `base ui component library` | Confirms the primary positioning is discoverable. |
+| shadcn comparison | `base ui vs shadcn`, `shadcn base ui`, `shadcn registry themes` | Confirms comparison content reaches high-intent users. |
+| Registry | `react component registry`, `shadcn style registry`, `llms.txt ui library` | Confirms source-copy and agent metadata work as acquisition hooks. |
+| Theme styles | `react terminal theme`, `enterprise react ui theme`, `data dense dashboard ui` | Confirms visual styles create long-tail discovery. |
+| Components | `base ui button theme`, `accessible react select`, `react dialog base ui` | Confirms component docs are discoverable. |
+
+## Metrics To Record
+
+Record these values beside each telemetry pass in `research/telemetry-YYYY-MM-DD.md` or in the release notes:
+
+| Metric | Healthy Early Signal |
+| --- | --- |
+| Indexed pages | Sitemap routes start appearing as indexed instead of discovered-only. |
+| Total impressions | Growing week over week after announcements and indexing. |
+| Clicks | Any non-zero clicks for install, comparison, registry, CLI, theme, or block pages. |
+| CTR | Pages with impressions but low CTR need title and description adjustments. |
+| Average position | Long-tail pages moving into top 30 are candidates for deeper examples. |
+| Top queries | Queries should map to Base UI, shadcn comparison, registry, theme, or component intent. |
+| Top pages | Clicks should not land only on the homepage; docs, themes, blocks, and components should earn depth. |
+
+To include exported Search Console rows in the telemetry report, export a query or page performance CSV/JSON from Search Console and run:
+
+```bash
+SEARCH_CONSOLE_EXPORT=path/to/search-console-export.csv npm run telemetry:collect
+```
+
+The importer accepts common columns such as `Query`, `Page`, `Clicks`, `Impressions`, `CTR`, and `Position`, plus Search Console API-style JSON rows with `keys`, `clicks`, `impressions`, `ctr`, and `position`.
+
+## Launch-Day Checklist
+
+After each release announcement:
+
+1. Run `npm run build && npm run seo:check` before deploy.
+2. Deploy the docs site.
+3. Open `/sitemap.xml`, `/robots.txt`, `/llms.txt`, `/llms-full.txt`, `/registry/registry.json`, and one theme page from production.
+4. Submit the sitemap in Search Console.
+5. Request indexing for the URL inspection queue above.
+6. Share the routes listed in [release-announcement-kit.md](./release-announcement-kit.md) so Search Console can correlate announcement demand with landing pages.
+7. Check Search Console again at T+1 day, T+7 days, and T+30 days.
+8. Record whether search produced clicks, impressions, or new queries that should become docs pages.
+
+## Decision Rules
+
+- If pages are not indexed after a week, inspect canonical URLs, sitemap entries, robots rules, response status, and duplicate titles.
+- If impressions grow but clicks stay flat, rewrite titles/descriptions for the affected route group and rerun `npm run seo:check`.
+- If query demand clusters around a missing comparison, component, block, or framework workflow, create a focused docs page instead of broad homepage copy.
+- If search clicks appear but npm downloads, stars, issues, or forks do not move, improve install snippets, examples, and page-level CTAs on those landing routes.
+- If Search Console shows only branded queries, keep external sharing active and add deeper non-brand content around Base UI, registry, themes, and migration workflows.

package/docs/theme-token-contract.md

@@ -0,0 +1,113 @@
+# Theme Token Contract
+
+Base Themes uses this document and `src/styles/tokenContract.json` as the public theme token contract for the 0.x line.
+
+## Version
+
+- Contract version: `0.1.0`
+- Stable public prefix: `--bt-`
+- Required theme attributes: `data-style` and `data-theme`
+- Supported style variants are listed in `registry/registry.json` and mirrored in the standard registry artifacts under `registry/shadcn-registry.json` and `registry/items/theme-*.json`.
+
+The package still keeps legacy variables such as `--bg`, `--surface`, `--accent`, and `--theme-focus` for compatibility. New docs, examples, registry metadata, and agent workflows should prefer the `--bt-*` tokens below.
+
+## Public Tokens
+
+Semantic tokens:
+
+- `--bt-bg`: page background.
+- `--bt-fg`: primary foreground text.
+- `--bt-text`: default body text.
+- `--bt-muted-fg`: secondary text and labels.
+- `--bt-surface`: default panel or control surface.
+- `--bt-surface-muted`: subtle grouped surface.
+- `--bt-surface-strong`: high-contrast surface used for inverse controls.
+- `--bt-border`: default border color.
+- `--bt-border-strong`: higher emphasis border color.
+- `--bt-primary`: primary action color.
+- `--bt-primary-hover`: primary action hover or pressed color.
+- `--bt-primary-fg`: text/icon color on primary actions.
+- `--bt-secondary`: secondary action color.
+- `--bt-secondary-fg`: text/icon color on secondary actions.
+- `--bt-info`: informational accent color.
+- `--bt-success`: success accent color.
+- `--bt-danger`: danger/error accent color.
+- `--bt-danger-fg`: text/icon color on danger actions.
+- `--bt-ring`: focus ring color.
+
+Shape and typography tokens:
+
+- `--bt-radius`: default large radius.
+- `--bt-radius-sm`: compact control radius.
+- `--bt-font-sans`: sans-serif font stack.
+- `--bt-font-mono`: monospace font stack.
+- `--bt-shadow`: default elevated shadow.
+- `--bt-shadow-strong`: high emphasis shadow.
+
+Component alias tokens:
+
+- `--bt-button-bg`: default button background.
+- `--bt-button-fg`: default button foreground.
+- `--bt-button-border`: button border color.
+- `--bt-input-bg`: input background.
+- `--bt-input-fg`: input foreground.
+- `--bt-input-border`: input border color.
+- `--bt-select-popup-bg`: select/menu popup background.
+- `--bt-select-popup-fg`: select/menu popup foreground.
+- `--bt-tabs-active-bg`: active tab background.
+- `--bt-tabs-active-fg`: active tab foreground.
+
+Motion and density tokens:
+
+- `--bt-border-width`: default control border width.
+- `--bt-font-weight`: default control font weight.
+- `--bt-duration`: default interaction transition duration.
+- `--bt-letter-spacing`: default control letter spacing.
+- `--bt-control-height`: default control height for dense customization.
+
+## Public Boundary
+
+Treat the tokens above, `data-style`, and `data-theme` as the stable public surface. Theme-specific implementation variables without the `--bt-` prefix are compatibility aliases in the 0.x line and may be normalized before a future stable release.
+
+Docs-only tokens such as `--topbar-bg`, `--card-bg`, and `--hero-text` belong to the documentation site shell. They are not a package component API and should not be required by consumer apps.
+
+## Customization
+
+Override tokens on a themed root or in app CSS after importing `base-themes/styles.css`:
+
+```css
+.brand-shell {
+  --bt-primary: #2563eb;
+  --bt-primary-hover: #1d4ed8;
+  --bt-radius: 10px;
+  --bt-radius-sm: 8px;
+  --bt-font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+  --bt-control-height: 36px;
+}
+
+.brand-shell[data-theme='dark'] {
+  --bt-bg: #0b1120;
+  --bt-surface: #111827;
+  --bt-fg: #f8fafc;
+  --bt-primary: #60a5fa;
+}
+```
+
+For current 0.x builds, the shipped CSS maps each `--bt-*` token to the matching legacy implementation token. If a component still reads a legacy token directly, override both names during migration:
+
+```css
+.brand-shell {
+  --bt-primary: #2563eb;
+  --accent: var(--bt-primary);
+}
+```
+
+## Validation
+
+Run the token contract check after editing theme variables, theme metadata, registry style variants, or token docs:
+
+```bash
+npm run tokens:check
+```
+
+The check verifies that every public `--bt-*` token exists in `src/styles/tokens.css`, maps to a legacy compatibility token, every registry style has token coverage plus a light or dark mode override where needed, and this documentation covers the public names.

package/examples/dashboard/README.md

@@ -0,0 +1,24 @@
+# Base Themes Dashboard Example
+
+This Vite example shows a product-style dashboard assembled from the public `base-themes` package surface. It combines shipped blocks, components, registry metadata, theme switching, and package CSS in one app-like screen.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://localhost:5177`.
+
+## Verify
+
+```bash
+npm run build
+```
+
+The example intentionally imports only documented package paths:
+
+- `base-themes`
+- `base-themes/styles.css`
+- `base-themes/registry.json`

package/examples/dashboard/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en" data-theme="light" data-style="enterprise">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Base Themes Dashboard Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>