Quick Start

Get the IO Design System running in your project in under five minutes. This guide covers installation, font setup, design token configuration, and environment variables.

Create a new project

Scaffold a Next.js App Router project with TypeScript and Tailwind CSS.

bash

pnpm create next-app io-app --typescript --tailwind --app
cd io-app

Install dependencies

Add the design system package.

bash

pnpm add @io/design-system

Configure fonts

Self-host Inter (300--700) and JetBrains Mono (400--500) via next/font/google. Set CSS variables on the html element so design tokens can reference them.

tsx

1// src/app/layout.tsx2import { Inter, JetBrains_Mono } from "next/font/google";3import "./globals.css";45const inter = Inter({6  variable: "--font-inter",7  subsets: ["latin"],8  weight: ["300", "400", "500", "600", "700"],9});1011const jetbrainsMono = JetBrains_Mono({12  variable: "--font-jetbrains-mono",13  subsets: ["latin"],14  weight: ["400", "500"],15});1617export default function RootLayout({18  children,19}: {20  children: React.ReactNode;21}) {22  return (23    <html lang="en" className={`${inter.variable} ${jetbrainsMono.variable}`}>24      <body>{children}</body>25    </html>26  );27}

Add design tokens

Define the full set of CSS custom properties in your global stylesheet. These tokens drive every component and pattern in the system.

css

1/* src/app/globals.css */2@import "tailwindcss";34:root {5  --bg-page: #fafafa;6  --bg-surface: #ffffff;7  --bg-alt: #f5f5f5;8  --primary-gradient: linear-gradient(135deg, #1db954, #059669);9  --primary-solid: #1db954;10  --text-primary: #0a0a0a;11  --text-secondary: #525252;12  --border: #e5e5e5;13  --radius-sm: 8px;14  --radius-md: 12px;15  --radius-lg: 16px;16  --shadow-sm: 0 1px 3px rgba(0,0,0,0.08);17  --shadow-glow: 0 4px 20px rgba(29,185,84,0.3);18}

Environment configuration

Create a .env.local file with your site metadata.

bash

# .env.local
NEXT_PUBLIC_SITE_NAME="IO Design System"
NEXT_PUBLIC_SITE_URL="https://io.design"

Next steps

Now that your project is configured, explore the design philosophy that guides every decision in the system.

Design Principles