@arcadeai/design-system 3.28.0 → 3.28.1

package/README.md

@@ -45,7 +45,7 @@ npm install react react-dom tailwindcss lucide-react
 Import the design system styles in your main CSS file or at the root of your application:
 
 ```css
-@import '@arcadeai/design-system/dist/assets/index.css';
+@import '@arcadeai/design-system/index.css';
 ```
 
 ### 2. Configure Tailwind CSS
@@ -69,6 +69,147 @@ function MyApp() {
 }
 ```
 
+## shadcn Registry
+
+The design system is also available as a [shadcn registry](https://ui.shadcn.com/docs/registry), allowing you to install individual components directly into your project using the `shadcn` CLI.
+
+### Setup
+
+1. Add the registry to your `components.json`:
+
+    ```json
+    {
+      "registries": {
+        "@arcadeai": "https://ds.arcade.dev/r/{name}.json"
+      }
+    }
+    ```
+
+2. Install the theme and apply tokens:
+
+    ```bash
+    npx shadcn@latest add @arcadeai/arcadeai-theme
+    ```
+
+    Then import `tokens.css` in your root component to apply the full Arcade colour palette (works around a known shadcn limitation where `cssVars` won't overwrite existing variables):
+
+    ```tsx
+    import "@/components/tokens.css";
+    ```
+
+3. Install components:
+
+    ```bash
+    npx shadcn@latest add @arcadeai/button
+    npx shadcn@latest add @arcadeai/card
+    ```
+
+4. Optionally install fonts and icons:
+
+    ```bash
+    npx shadcn@latest add @arcadeai/arcadeai-fonts
+    npx shadcn@latest add @arcadeai/icons
+    ```
+
+**Verify your setup:** Install the `demo` block to render a page that exercises theme, fonts, icons, and core components all at once — useful as a smoke test after setting up a new project:
+
+```bash
+npx shadcn@latest add @arcadeai/demo
+```
+
+### Building the Registry
+
+To build the registry from source:
+
+```bash
+bun run build:registry
+```
+
+This runs `shadcn build` using the `registry.json` config and outputs individual item JSON files to `public/r/`.
+
+### Testing Locally
+
+To test the registry without publishing:
+
+1. Build the registry:
+
+    ```bash
+    bun run build:registry
+    ```
+
+2. Serve the registry locally:
+
+    ```bash
+    npx serve public -p 3333 --cors
+    ```
+
+3. Create a new Vite + React + TypeScript project and initialize shadcn:
+
+    ```bash
+    bun create vite arcade-registry-test --template react-ts
+    cd arcade-registry-test
+    bun install
+    npx shadcn@latest init
+    ```
+
+4. **Important:** Remove Vite's default `index.css` to avoid conflicts with Tailwind CSS. Vite's template includes unlayered button/link styles that override Tailwind utilities:
+
+    ```bash
+    rm src/index.css
+    ```
+
+    Then remove the `import './index.css'` line from `src/main.tsx`.
+
+5. In your test project's `components.json`, point to the local server:
+
+    ```json
+    {
+      "registries": {
+        "@arcadeai": "http://localhost:3333/r/{name}.json"
+      }
+    }
+    ```
+
+6. Install the theme, a component, and the demo smoke test:
+
+    ```bash
+    npx shadcn@latest add @arcadeai/arcadeai-theme
+    npx shadcn@latest add @arcadeai/button
+    npx shadcn@latest add @arcadeai/demo
+    ```
+
+7. Use the demo in `src/App.tsx` to verify the full setup:
+
+    ```tsx
+    import "./App.css";
+    import { ArcadeDemo } from "@/components/ui/blocks/demo";
+
+    function App() {
+      return <ArcadeDemo />;
+    }
+
+    export default App;
+    ```
+
+### Registry Items
+
+The registry includes:
+
+- **Theme** (`arcadeai-theme`): Arcade OKLch color tokens for light and dark mode
+- **Fonts** (`arcadeai-fonts`): GT Sectra, GT Cinetype, and GT Cinetype Mono font families
+- **Icons** (`icons`): 100+ brand icons (GitHub, Slack, Google, etc.)
+- **Components**: All atoms (button, badge, card, input, etc.) and molecules
+- **Demo** (`demo`): A verification page that showcases theme, fonts, icons, and components
+
+### Registry Dependencies
+
+All registry dependencies use the `@arcadeai/` namespace prefix. When adding new items to `registry.json`, make sure `registryDependencies` entries use the fully qualified name (e.g., `@arcadeai/utils` instead of `utils`).
+
+### Known Issues
+
+- **shadcn `cssVars` don't overwrite existing values**: When the theme is installed as a transitive dependency (e.g., via `@arcadeai/demo`), the `cssVars` may not update existing variables in `App.css`. The `tokens.css` file works around this by providing all Arcade color values in unlayered `:root`/`.dark` blocks that take CSS cascade priority over shadcn's `@layer theme` defaults.
+- **Vite default `index.css` conflicts with Tailwind**: When creating a new Vite project, the default `index.css` includes unlayered `button` styles (e.g., `background-color: #f9f9f9`) that override Tailwind utilities. Remove `index.css` and its import from `main.tsx` before using Tailwind components.
+
 ## 🛠️ Development
 
 ### Prerequisites
@@ -80,22 +221,22 @@ function MyApp() {
 
 1. Clone the repository:
 
-```bash
-git clone https://github.com/ArcadeAI/Design-System
-cd @arcadeai/design-system
-```
+    ```bash
+    git clone https://github.com/ArcadeAI/Design-System
+    cd @arcadeai/design-system
+    ```
 
-1. Install dependencies:
+2. Install dependencies:
 
-```bash
-pnpm install
-```
+    ```bash
+    pnpm install
+    ```
 
-1. View components in Storybook:
+3. View components in Storybook:
 
-```bash
-pnpm dev
-```
+    ```bash
+    pnpm dev
+    ```
 
 ## 🏗️ Technology Stack