🎨 Modern Design: Clean, professional components following modern design principles
♿ Accessible: Built on Radix UI primitives for excellent accessibility out of the box
🎯 TypeScript: Full TypeScript support for better developer experience
🎨 Customizable: Easy to customize with Tailwind CSS classes
⚡ Lightweight: Optimized bundle size with tree-shaking support
🔧 Flexible: Easy to integrate with any React project

📦 Installation

Install the design system as a dependency in your project:

npm install @arcadeai/design-system
# or
pnpm add @arcadeai/design-system
# or
yarn add @arcadeai/design-system

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom tailwindcss lucide-react

Required versions:

React: ^19.1.0
React DOM: ^19.1.0
Tailwind CSS: ^4.1.10
Lucide React: ^0.522.0

🚀 Quick Start

1. Import Styles

Import the design system styles in your main CSS file or at the root of your application:

@import '@arcadeai/design-system/index.css';

2. Configure Tailwind CSS

Ensure your Tailwind CSS configuration is compatible with the design system. The design system uses Tailwind CSS v4 with specific configurations.

3. Use Components

Import and use components in your React application:

import { Button, Card, Input } from '@arcadeai/design-system';

function MyApp() {
  return (
    <Card>
      <Input placeholder="Enter your email" />
      <Button>Submit</Button>
    </Card>
  );
}

shadcn Registry

The design system is also available as a shadcn registry, allowing you to install individual components directly into your project using the shadcn CLI.

Setup

Add the registry to your components.json:

{
  "registries": {
    "@arcadeai": "https://ds.arcade.dev/r/{name}.json"
  }
}

Install the theme and apply tokens:
```
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):
```
import "@/components/tokens.css";
```

Install components:

npx shadcn@latest add @arcadeai/button
npx shadcn@latest add @arcadeai/card

Optionally install fonts and icons:

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:

npx shadcn@latest add @arcadeai/demo

Building the Registry

To build the registry from source:

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:

Build the registry:
```
bun run build:registry
```
Serve the registry locally:
```
npx serve public -p 3333 --cors
```

Create a new Vite + React + TypeScript project and initialize shadcn:

bun create vite arcade-registry-test --template react-ts
cd arcade-registry-test
bun install
npx shadcn@latest init

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:
```
rm src/index.css
```
Then remove the import './index.css' line from src/main.tsx.

In your test project's components.json, point to the local server:

{
  "registries": {
    "@arcadeai": "http://localhost:3333/r/{name}.json"
  }
}

Install the theme, a component, and the demo smoke test:

npx shadcn@latest add @arcadeai/arcadeai-theme
npx shadcn@latest add @arcadeai/button
npx shadcn@latest add @arcadeai/demo

Use the demo in src/App.tsx to verify the full setup:

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

Node.js (v18 or higher)
pnpm (recommended) or npm

Getting Started

Clone the repository:

git clone https://github.com/ArcadeAI/Design-System
cd @arcadeai/design-system

Install dependencies:
```
pnpm install
```
View components in Storybook:
```
pnpm dev
```

🏗️ Technology Stack

This design system is built on top of:

shadcn/ui - A collection of re-usable components built using Radix UI and Tailwind CSS
Radix UI - Unstyled, accessible components for building high‑quality design systems
Tailwind CSS - Utility-first CSS framework for rapid UI development
TypeScript - Type-safe JavaScript for better developer experience
Storybook - Component development and documentation

🎨 Design Tokens

The design system uses Tailwind CSS for consistent spacing, colors, typography, and other design tokens. When adding new components:

Use existing Tailwind classes when possible
Follow the established color palette
Maintain consistent spacing and typography scales

🔧 Contributing

Adding Icons

To add a new icon to the design system:

Add the SVG file: Place your SVG icon in /lib/assets/icons/

# Example: adding a new "example" icon
cp example.svg lib/assets/icons/

Generate the React component: Run the icon generation script
```
pnpm generate-icons
```

Use the icon: The generated React component will be automatically available

import { ExampleIcon } from '@arcadeai/design-system/components/ui/atoms/icons';

Adding Toolkits

To add a new toolkit to the system:

Navigate to the toolkits metadata: Open lib/metadata/toolkits.ts

Add your toolkit entry: Add a new entry to the TOOLKITS array

{
   id: 'X',
   label: 'X',
   isBYOC: false,
   isPro: false,
   publicIconUrl: `${PUBLIC_ICON_URL}/x.svg`,
   icon: Icons.X,
   // Other properties...
}

Adding OAuth Providers

To add a new OAuth provider:

Navigate to OAuth providers metadata: Open lib/metadata/oauth-providers.ts

Add OAuth identifiers: Define your OAuthId and OAuthProviderId

export const OAuthId = {
  Asana: 'arcade-asana',
  Atlassian: 'arcade-atlassian',
  // Add to the respective id
}

export const OAuthProviderId = {
  Asana: 'asana',
  Atlassian: 'atlassian',
  // Add to the respective provider id
}

Choose the appropriate category:

For prebuilt OAuth providers: Add a record to PREBUILT_OAUTH_PROVIDERS
For custom OAuth providers: Add it to OTHER_OAUTH_PROVIDERS

// Example for prebuilt provider
export const PREBUILT_OAUTH_PROVIDERS: OAuthCatalogue[] = [
   {
     id: OAuthId.Asana,
     provider_id: OAuthProviderId.Asana,
     name: 'Asana',
     description: 'Authorize tools and agents with Asana',
     publicIconUrl: `${PUBLIC_ICON_URL}/asana.svg`,
     icon: Asana,
     docs: '<https://docs.arcade.dev/home/auth-providers/asana>',
   },
   // Add to the respective array
]

Development Workflow

Make your changes following the patterns above
Test your changes in Storybook: pnpm dev
Run tests: pnpm test
Build the project: pnpm build
Submit a pull request with your changes

Built with ❤️ by the Arcade team

FAQs

What is @arcadeai/design-system?

Is @arcadeai/design-system popular?

Is @arcadeai/design-system well maintained?

Package last updated on 24 Feb 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@arcadeai/design-system

Arcade Design System

✨ Cool Features