Quick Start

This guide walks you through adding the LOKE Design System to an existing React project. By the end, you'll have a working setup with components rendering correctly.

The design system is designed to be plug-and-play. Install it, import the styles, and start using components — no additional configuration required.

1. Install the package

# bun (recommended)
bun add @loke/design-system

# npm
npm install @loke/design-system

# pnpm
pnpm add @loke/design-system

To use icons, also install the icon package:

bun add @loke/icons

2. Check your TypeScript config

The design system uses the exports field in package.json for granular imports. Your tsconfig.json must use a module resolution strategy that supports this.

Set the following in your tsconfig.json:

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler"
  }
}

If you see Cannot find module '@loke/design-system/button' errors, this is almost always a moduleResolution issue. The "nodenext" setting can cause problems with package exports — switch to "bundler" to resolve it.

3. Import the styles

Add the design system stylesheet to your app's root layout or entry point. This single import provides all component styles, theme variables, and color tokens.

Next.js

// app/layout.tsx
import "@loke/design-system/styles";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Vite / other frameworks

// main.tsx or index.tsx
import "@loke/design-system/styles";
import { createRoot } from "react-dom/client";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(<App />);

That's the only setup step. The design system ships pre-compiled CSS — you don't need to install or configure Tailwind CSS, PostCSS, or any other CSS tooling.

4. Use your first component

Import components individually from their specific paths:

import { Button } from "@loke/design-system/button";

export function MyPage() {
  return (
    <div>
      <h1>Hello, Design System</h1>
      <Button>Click me</Button>
    </div>
  );
}

Components are imported from @loke/design-system/<component-name> — not from the package root. This keeps your bundles small through tree-shaking.

// Correct
import { Button } from "@loke/design-system/button";
import { Card, CardHeader, CardTitle, CardContent } from "@loke/design-system/card";
import { Input } from "@loke/design-system/input";

// Wrong — there is no barrel export
import { Button } from "@loke/design-system";

5. Build a simple page

Here's a more complete example combining several components:

import { Button } from "@loke/design-system/button";
import { Card, CardHeader, CardTitle, CardContent, CardFooter } from "@loke/design-system/card";
import { Input } from "@loke/design-system/input";
import { Label } from "@loke/design-system/label";
import { Stack } from "@loke/design-system/stack";

export function LoginPage() {
  return (
    <Stack gap={6} alignItems="center" justifyContent="center" padding={4}>
      <Card className="w-full max-w-sm">
        <CardHeader>
          <CardTitle>Sign in</CardTitle>
        </CardHeader>
        <CardContent>
          <Stack gap={4}>
            <div>
              <Label htmlFor="email">Email</Label>
              <Input id="email" type="email" placeholder="you@example.com" />
            </div>
            <div>
              <Label htmlFor="password">Password</Label>
              <Input id="password" type="password" />
            </div>
          </Stack>
        </CardContent>
        <CardFooter>
          <Button className="w-full">Sign in</Button>
        </CardFooter>
      </Card>
    </Stack>
  );
}

Dark mode

The design system supports dark mode via a CSS class. Add the dark class to your <html> element to activate it:

// Toggle dark mode
document.documentElement.classList.toggle("dark");

All components and color tokens automatically adapt when dark mode is active.

What's included

When you import @loke/design-system/styles, you get:

Component styles — all visual styles for every component
Color tokens — semantic colors like primary, secondary, muted, destructive
Dark mode — automatic dark mode support via the .dark class
Base styles — sensible defaults for borders, backgrounds, and typography
Common CSS utilities — a set of pre-compiled utility classes for spacing, layout, and more

You do not need to install Tailwind CSS separately. The design system bundles everything it needs.

If you want to use Tailwind CSS utilities beyond what the design system provides (e.g., for custom layout or one-off styling), see the Tailwind CSS Guide for setup instructions.

import "@loke/design-system/styles";

This import must run before any components render.

Components look unstyled or broken

Check that you don't have conflicting global CSS that resets component styles. The design system's base layer sets border-color and outline on all elements — other CSS resets may conflict.

Next steps

Component Guide — overview of all available components
Layout Primitives — Box, Stack, Columns for building page layouts
Tailwind CSS Guide — using Tailwind alongside the design system
Color System — brand colors and semantic tokens
Icons — the LOKE icon library

Design System