Get started

Ten minutes from npm install to a working Oshon button on screen. Read every step — non-obvious gotchas are flagged ⚠ Heads up and the matching error messages are in Troubleshooting.

1. Create a fresh Next.js project

Already have a React project? Skip to step 2.

Run this in a terminal where you want the project folder created:

pnpm create next-app@latest my-oshon-app
# or:  npm  create next-app@latest my-oshon-app
# or:  yarn create next-app   my-oshon-app

Answer the prompts like this (defaults work for everything else):

• TypeScript? Yes
• ESLint? Yes
• Tailwind CSS? Yes  (Oshon needs Tailwind v4 — Next.js 15.1+ ships v4 by default)
• App Router? Yes
• Customize the import alias? No

Once the install finishes, change into the folder and start the dev server:

cd my-oshon-app
pnpm dev
# Next.js prints "ready - started server on http://localhost:3000"

Open http://localhost:3000 in your browser. You should see the default Next.js welcome page. Stop the server (Ctrl + C in the terminal) before continuing.

2. Install Oshon

Oshon ships as three packages: tokens (the design tokens), primitives (the headless behavior), and components (the visible React components). Install all three at once:

pnpm add @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives
# or:  npm install @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives
# or:  yarn add    @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives

3. Wire the design tokens into Tailwind

Oshon is a two-layer system that runs on top of Tailwind v4:

1. @oshon-ai/tokens/css declares ~200 CSS custom properties like --oshon-color-primary-500.
2. @oshon-ai/tokens/tailwind tells Tailwind v4 how to map utility class names (bg-primary-500, text-on-surface, etc.) to those custom properties via its @theme directive.
3. @source points Tailwind at the Oshon component package so it generates the utility classes those components use. Oshon ships its class names inside the component JS, and Tailwind v4 skips node_modules by default — without this line the components render as unstyled grey boxes.

All three must be loaded as CSS statements (not JS imports) so Tailwind's compiler sees them at build time. Open app/globals.css and replace its contents with:

@import 'tailwindcss';
@import '@oshon-ai/tokens/css';
@import '@oshon-ai/tokens/tailwind';

/* REQUIRED — without this, Tailwind never sees Oshon's component classes
   and every component renders as an unstyled box. The path is relative to
   THIS file; for the App Router (app/globals.css) it's ../node_modules.
   Add a line per Oshon package you install (e.g. .../data). */
@source '../node_modules/@oshon-ai/components';

/* your own global styles below — they cascade after Oshon's defaults */

4. Render your first component

Open app/page.tsx and replace its contents with this:

'use client';

import { ButtonHug } from '@oshon-ai/components';

export default function HomePage() {
  return (
    <main style={{ padding: 32 }}>
      <h1>Oshon test</h1>
      <ButtonHug onClick={() => alert('hello Oshon')}>
        Click me
      </ButtonHug>
    </main>
  );
}

Save the file, run pnpm dev again, and reload the browser. You should see:

5. Add icons

Components with an icon prop — ButtonIconOnly, leadingIcon slots, GlobalToolbar actions — take a ReactNode, so feed them real icons, not emoji. Oshon ships 1,700+ icons (Lucide-derived, stroke-style) with @oshon-ai/components — no extra install. They live at a dedicated subpath, deliberately kept out of the main barrel so names like Search, Menu, and Calendar don't collide with the same-named components:

import { ButtonIconOnly } from '@oshon-ai/components';
import { Search, Plus, Settings } from '@oshon-ai/components/icons';

export function Toolbar() {
  return (
    <>
      <ButtonIconOnly icon={<Search />} aria-label="Search" />
      <ButtonIconOnly icon={<Plus />} aria-label="Add item" />
    </>
  );
}

Icons are plain SVG components — no @source line needed for them (that's only for the utility-class components).

6. Apply your brand color

Oshon's killer feature is three-seed theming — pick a primary, secondary, and tertiary hex color and the entire 44-shade palette regenerates in one DOM write.

Add a 'use client' bootstrap component that applies your theme on mount. Create app/theme-bootstrap.tsx:

'use client';

import { useEffect } from 'react';
import { applyTheme } from '@oshon-ai/tokens';

/**
 * Drop your brand colors here. Every Oshon component on the page —
 * the entire palette ramps from 50 to 950 — re-tints on mount.
 */
export function ThemeBootstrap() {
  useEffect(() => {
    applyTheme({
      primarySeed: '#0c66e4',   // your brand blue
      secondarySeed: '#a55593', // your brand magenta
      tertiarySeed: '#67ac5c',  // your brand green
    });
  }, []);
  return null;
}

Import and render the bootstrap inside the <body> of your root layout:

import { ThemeBootstrap } from './theme-bootstrap';

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

Reload the browser. The button (and every other Oshon component on the page) is now tinted with your brand blue.

7. Where to go next

• Components catalog — every component, with code samples, live preview, and props reference. Start with Button, Input, Modal, and SideNav — those four cover 80% of a typical app shell.
• Theming — the deep dive on the three-seed palette, dark mode, and a11y tier switching.
• Troubleshooting — the question-by-question fixes for "I followed the steps but X isn't working".
• Stuck? Email support@oshon.ai. We answer within 1 business day for paying customers.