@arcadeai/design-system

Arcade Design System

A modern React component library that ensures consistent UI across all our applications, built with TypeScript, Tailwind CSS and shadcn/ui.

✨ Cool Features

• 🎨 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