Wiz'rd

Getting Started

Follow these steps after downloading your theme.

Option A — CSS Custom Properties

1. Create a Next.js app

npx create-next-app@latest my-app
cd my-app

2. Install the factory tokens package

npm install @toucan-ui/tokens

3. Place your downloaded CSS file

Copy the downloaded custom.css file into your project:

cp ~/Downloads/custom.css ./app/themes/custom.css

4. Import in app/layout.tsx

Import the base tokens first, then your theme override:

import '@toucan-ui/tokens/css';
import './themes/custom.css';

5. Add recommended app globals

Factory doesn't ship a CSS reset — add these baseline styles to your global stylesheet:

/* app/globals.css */
*,
*::before,
*::after {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: var(--text-font-family);
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

6. Add data-theme attribute to <html>

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

7. Build a page using factory components

import { Section, Wrapper, Heading, Text, Button } from '@toucan-ui/core';

export default function Home() {
  return (
    <Section padding="lg">
      <Wrapper>
        <Heading level={1}>Hello, custom!</Heading>
        <Text>Your theme is working.</Text>
        <Button variant="primary">Get Started</Button>
      </Wrapper>
    </Section>
  );
}

Option B — JSON Tokens (Style Dictionary)

1. Create a Next.js app and install Style Dictionary

npx create-next-app@latest my-app
cd my-app
npm install style-dictionary

2. Extract the ZIP into a tokens/ directory

unzip ~/Downloads/custom-tokens.zip -d ./tokens

3. Create a Style Dictionary config

Create style-dictionary.config.json in your project root:

{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "app/themes/",
      "files": [
        {
          "destination": "custom.css",
          "format": "css/variables",
          "options": {
            "selector": "[data-theme=\"custom\"]"
          }
        }
      ]
    }
  }
}

4. Add a build script and run it

Add to your package.json scripts, then run:

// package.json
"scripts": {
  "build:tokens": "style-dictionary build"
}

// Terminal
npm run build:tokens

5. Import the generated CSS and add data-theme to <html>

// app/layout.tsx
import '@toucan-ui/tokens/css';
import './themes/custom.css';

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

6. Add recommended app globals

Factory doesn't ship a CSS reset — add these baseline styles to your global stylesheet:

/* app/globals.css */
*,
*::before,
*::after {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: var(--text-font-family);
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

7. Build a page

import { Section, Wrapper, Heading, Text, Button } from '@toucan-ui/core';

export default function Home() {
  return (
    <Section padding="lg">
      <Wrapper>
        <Heading level={1}>Hello, custom!</Heading>
        <Text>Your theme is working.</Text>
        <Button variant="primary">Get Started</Button>
      </Wrapper>
    </Section>
  );
}