Merge pull request #2482 from GCWing/gcwing/design-system-foundation

feat(design-system): establish independent UI foundation

Author: GCWing

design-system/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+## Scope
+
+This file applies to `design-system/**`. Repository-wide rules in the root `AGENTS.md` still apply.
+
+## Architecture
+
+- Public packages live under `packages/`; private authoring and validation tools live under `tooling/`; Design Lab lives under `apps/`.
+- `@bitfun/ui` owns React anatomy, behavior, accessibility, and stable variants. It must remain independent from product routes, stores, locale catalogs, Tauri APIs, and concrete themes.
+- `@bitfun/design-tokens` owns theme-independent names and system scales. `@bitfun/theme-bitfun` supplies replaceable reference and semantic values.
+- Components consume semantic or system CSS variables. Raw colors are forbidden in public component CSS. Component-private variables use the `--_` prefix.
+- Files under `dist/` are generated and must not be edited or committed.
+- Design Lab may alias `@bitfun/ui` to source only during Vite development for HMR. Its production build must consume package exports.
+- `@bitfun/ui/registry` is the source of truth for published components. Design Lab derives navigation, counts, token scopes, and detail routes from that registry; Lab-only previews or copy must never add, retain, or remove a package component.
+
+## Publication boundary
+
+- Public manifests expose only `dist/`, README, and package metadata.
+- React and React DOM stay peer dependencies of `@bitfun/ui`.
+- Workspace dependencies use the `workspace:` protocol and must be converted to semver ranges by `pnpm pack`.
+- New public package boundaries require a real consumer; do not create empty placeholder packages.
+
+## Verification
+
+Use the narrowest matching command:
+
+```bash
+pnpm run design-system:build
+pnpm run design-system:test
+pnpm run design-system:check
+```
+
+Run `pnpm run design-system:check` for cross-package or release-boundary changes. Token and theme changes must also run the repository-level `pnpm run theme:color-audit:all`.
+
+Do not use browser automation or mock screenshots as visual proof. Design Lab is the manual authoring surface; source, build, HTTP, and package checks do not establish final visual fidelity.

design-system/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CWing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

design-system/README.md

@@ -0,0 +1,40 @@
+# BitFun Design System
+
+This directory is an independently buildable and publishable design-system boundary inside the BitFun monorepo.
+
+It deliberately does not depend on Web UI routes, stores, locale catalogs, Tauri APIs, or product-domain state. Applications consume only package exports.
+
+## Packages
+
+- `@bitfun/design-tokens`: token contract, system scales, density modes, and generated CSS/TypeScript artifacts.
+- `@bitfun/theme-bitfun`: replaceable BitFun light, dark, and high-contrast theme values.
+- `@bitfun/ui`: theme-independent React primitives and components.
+- `@bitfun/token-engine`: private build-time token resolver shared by packages and authoring tools.
+- `@bitfun/design-lab`: private standalone preview and token-authoring application.
+
+The BitFun theme uses a two-layer color model. Foundational colors use named numeric scales such as `ref.color.neutral.50` and `ref.color.blue.500`; mode-specific semantic colors map those values to UI roles. Reference colors are available to authoring tools as data, but emit no runtime CSS variables and are never a component styling contract.
+
+Design Lab exposes an Overview, a searchable component catalog with interactive component-detail workbenches, a Design Tokens workbench for non-color contracts, and a dedicated Colors reference page. Colors reads the generated semantic theme catalog and foundational reference scales directly from `@bitfun/theme-bitfun`, compares Light, Dark, High Contrast Light, and High Contrast Dark values in one table, and documents scale, palette, and resolved mapping relationships without duplicating source values. The Design Tokens workbench keeps typography, spacing, geometry, motion, layer, opacity, and shadow authoring separate, combines a selectable token table with a focused inspector, renders token-driven previews, and can filter the catalog by component ownership. Edits are scoped to the active density and theme modes, update the effect preview immediately, persist as a local draft, and can be exported. In local development, its loopback-only authoring bridge validates changes, writes the owning token source document, rebuilds the package, and rolls back the source if validation fails.
+
+`@bitfun/ui/registry` is the component source of truth. Design Lab derives its component navigation, counts, token scopes, and detail routes from that package export; adding Lab copy or a preview cannot publish a component or keep a removed component alive.
+
+## Commands
+
+```bash
+pnpm run design-system:dev
+pnpm run design-system:build
+pnpm run design-system:test
+pnpm run design-system:check
+```
+
+The Design Lab development entry uses source aliases for component HMR. Its production build consumes the public package exports, so authoring convenience cannot silently become the published contract.
+
+## Dependency direction
+
+```text
+token-engine -> design-tokens -> theme-bitfun
+design-tokens -------------> ui
+design-tokens + theme-bitfun + ui -> design-lab
+```
+
+`@bitfun/ui` never depends on a concrete theme. A consumer imports a theme package and UI styles separately.

design-system/apps/design-lab/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en-US">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
+    <title>BitFun Design Lab</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

design-system/apps/design-lab/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@bitfun/design-lab",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Standalone authoring and preview application for the BitFun design system",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 4178 --strictPort",
+    "build": "tsc -p tsconfig.json --noEmit && vite build",
+    "test": "node --test vite/*.test.mjs && pnpm run type-check",
+    "type-check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@bitfun/design-tokens": "workspace:^",
+    "@bitfun/theme-bitfun": "workspace:^",
+    "@bitfun/ui": "workspace:^",
+    "lucide-react": "^0.541.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@bitfun/token-engine": "workspace:*",
+    "@types/node": "^20.10.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.6.0",
+    "typescript": "~5.8.3",
+    "vite": "^7.0.4"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}