✦

This page covers the complete setup path. If you already know the basics, jump to the section you need using the headings below.

1. Install

Install the packages you need. Start with tokens and components — everything else is optional.

Install packages

# pnpm (recommended)
pnpm add @stareezy-ui/tokens @stareezy-ui/components

# yarn
yarn add @stareezy-ui/tokens @stareezy-ui/components

# npm
npm install @stareezy-ui/tokens @stareezy-ui/components

Optional packages — install only what you need:

# Build-time compiler (Babel/Vite/Metro) — zero runtime cost
pnpm add -D @stareezy-ui/compiler

# Atomic CSS sheet management
pnpm add @stareezy-ui/stylesheet

# Utilities and platform helpers
pnpm add @stareezy-ui/core

2. Create your config

Create a stareezy.config.ts (or ui.config.ts) at the root of your project. This is the single source of truth for your design system — themes, custom tokens, breakpoints, and shorthands.

stareezy.config.ts

// stareezy.config.ts
import { createUi, token, themes } from '@stareezy-ui/tokens'

export const ui = createUi({
  // Register all four built-in themes
  themes: {
    aurora:        themes.aurora,
    dark:          themes.dark,
    light:         themes.light,
    'steins-gate': themes['steins-gate'],
  },

  // Your custom token groups — fully typed on ui.tokens
  tokens: {
    brand: {
      primary:   token('#FF6B35', 'brand-primary'),
      secondary: token('#004E89', 'brand-secondary'),
    },
  },

  // Responsive breakpoints (mobile-first, min-width in px)
  media: {
    sm: 480,
    md: 768,
    lg: 1024,
    xl: 1280,
    '2xl': 1536,
  },

  // Prop shorthands — these become valid BoxProps automatically
  shorthands: {
    bg:  'backgroundColor',
    p:   'padding',
    px:  'paddingHorizontal',
    py:  'paddingVertical',
    m:   'margin',
    mx:  'marginHorizontal',
    my:  'marginVertical',
    br:  'borderRadius',
    f:   'flex',
    w:   'width',
    h:   'height',
  } as const,
})

// ── Module augmentation ──────────────────────────────────────────────────
// This makes your shorthands flow into BoxProps as typed props.
// Without this, TypeScript won't know about your custom shorthands.
type AppConfig = typeof ui
declare module '@stareezy-ui/tokens' {
  interface SzrCustomConfig extends AppConfig {}
}

export default ui

ℹ

The as const on shorthands is required — it tells TypeScript to infer the literal types of the keys so the module augmentation works correctly.

3. Wrap your app

Add ThemeProvider at the root of your app. Pass your default theme name.

Root layout / App.tsx

// app/_layout.tsx (Expo Router) or App.tsx (React Native)
import { ThemeProvider } from '@stareezy-ui/tokens'

export default function RootLayout({ children }) {
  return (
    <ThemeProvider theme="aurora">
      {children}
    </ThemeProvider>
  )
}

// Next.js — app/layout.tsx
import { ThemeProvider } from '@stareezy-ui/tokens'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider theme="aurora">
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

4. Use theme-reactive props

The t accessor returns ThemeToken references. Pass them as props — they resolve to the current theme's value at render time and update automatically when the theme switches.

Theme-reactive component

import { t } from '@stareezy-ui/tokens'
import { Box, Text } from '@stareezy-ui/components'

function Card() {
  return (
    // t.* props resolve to the CURRENT theme's value at render time
    <Box
      bg={t.backgrounds.secondary}
      borderColor={t.border.primaryBrand}
      borderWidth={1}
      rounded={12}
      p={16}
    >
      <Text
        type="M-heading-bold"
        style={{ color: t.text.primary }}
        text="Hello, Stareezy UI"
      />
      <Text
        type="M-paragraph-regular"
        style={{ color: t.text.secondary }}
        text="This text color switches with the theme."
      />
    </Box>
  )
}

// aurora      → bg: beauBlue[50], border: #00ff88, text: #f0f0f8
// dark        → bg: raisinBlack[600], border: #024cce, text: #f0f6fc
// steins-gate → bg: midnightNavy, border: #4a9eff, text: #e8dcc8

5. Use static tokens

For values that should be the same across all themes, use static tokens directly. These always resolve to their fixed .value.

Static token props

import { colors, spacing, radius } from '@stareezy-ui/tokens'
import { Box } from '@stareezy-ui/components'

// Static tokens — always the same value regardless of theme
<Box
  bg={colors.celurenBlue[500]}   // always #024CCE
  p={spacing[4]}                 // always 16px
  rounded={radius.md}            // always 10px
/>

// Access raw values for non-Box contexts
const style = {
  backgroundColor: colors.celurenBlue[500].value,  // "#024CCE"
  padding: spacing[4].value,                        // 16
  borderRadius: radius.md.value,                    // 10
}

6. Use your custom tokens

Custom tokens registered in createUi() are available on ui.tokens with full type safety.

Custom token access

import { ui } from './stareezy.config'

// Fully typed — TypeScript knows about your custom tokens
ui.tokens.brand.primary.value   // "#FF6B35"
ui.tokens.brand.secondary.value // "#004E89"

// Use in components
<Box bg={ui.tokens.brand.primary} />

// ui.t is the same as the standalone t accessor
<Box bg={ui.t.backgrounds.primary} />

7. Switch themes

Use useThemeSwitch to switch themes from anywhere in the tree. All components using t.* props update automatically.

Theme switcher component

import { useThemeSwitch } from '@stareezy-ui/tokens'

function ThemeSwitcher() {
  const { theme, setTheme } = useThemeSwitch()

  return (
    <div style={{ display: 'flex', gap: 8 }}>
      {['aurora', 'dark', 'light', 'steins-gate'].map((name) => (
        <button
          key={name}
          onClick={() => setTheme(name)}
          style={{
            fontWeight: theme === name ? 700 : 400,
            opacity: theme === name ? 1 : 0.6,
          }}
        >
          {name}
        </button>
      ))}
    </div>
  )
}

8. Add the build-time compiler (optional)

Add the plugin to your build tool config. It reads stareezy.config.ts from your project root automatically — you don't pass the config path, just like Tamagui's @tamagui/babel-plugin.

Vite (Next.js, Vite apps)

// vite.config.ts
import { stareezyVitePlugin } from '@stareezy-ui/compiler'

export default {
  plugins: [stareezyVitePlugin()],
  // ↑ reads stareezy.config.ts automatically — no path needed
}

Babel + Metro (React Native / Expo)

// babel.config.js
const { stareezyBabelPlugin } = require('@stareezy-ui/compiler')

module.exports = {
  presets: ['babel-preset-expo'],
  plugins: [stareezyBabelPlugin()],
  // ↑ reads stareezy.config.ts automatically — no path needed
}

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config')
const config = getDefaultConfig(__dirname)
config.transformer = {
  ...config.transformer,
  babelTransformerPath: require.resolve('@stareezy-ui/compiler/metro'),
  // ↑ reads stareezy.config.ts automatically — no path needed
}
module.exports = config

✦

The compiler finds stareezy.config.ts by searching process.cwd() (your project root). As long as the file is there, the plugin picks up your shorthands automatically.

9. Custom shorthands in action

Once you've declared your shorthands in stareezy.config.ts and added the module augmentation, TypeScript knows about them everywhere:

// With the shorthands from step 2:
// bg → backgroundColor, br → borderRadius, f → flex

// ✅ These are now valid typed props — TypeScript autocompletes them
<Box bg={t.backgrounds.primary} br={12} f={1} />
<Box bg={colors.celurenBlue[500]} p={16} m={8} />

// ✅ Works with tokens, ThemeTokens, and plain values
<Box bg={t.backgrounds.primary} />   // ThemeToken — switches with theme
<Box bg={colors.celurenBlue[500]} /> // Token<string> — always #024CCE
<Box bg="#FF6B35" />                 // plain string — always this color

10. Resolve ThemeTokens manually

When you need the raw string value inside a component (e.g. for a canvas, SVG, or non-Box element), use useResolveThemeToken:

import { t, useResolveThemeToken } from '@stareezy-ui/tokens'

function MyCanvas() {
  const brandColor = useResolveThemeToken(t.text.importantBrand)
  // aurora      → "#00ff88"
  // steins-gate → "#4a9eff"
  // dark/light  → "#024cce"

  return <canvas style={{ borderColor: brandColor }} />
}

Summary

Install

pnpm add @stareezy-ui/tokens @stareezy-ui/components

Config

Create stareezy.config.ts with createUi() + module augmentation

ThemeProvider

Wrap your app root with <ThemeProvider theme="aurora">

t.* props

Use t.backgrounds.primary, t.text.primary for theme-reactive colors

Static tokens

Use colors.celurenBlue[500], spacing[4] for fixed values

Custom tokens

Access ui.tokens.brand.primary with full type safety

Theme switching

useThemeSwitch().setTheme('steins-gate') — all components update

Compiler

stareezyVitePlugin() or stareezyBabelPlugin() for zero runtime cost

ℹ

The full API reference is in the Token API and Theming guides. The Token Explorer lets you browse all 300+ tokens visually.

Quick Start