Stareezy UI

Overview

createUi is the single entry point for configuring Stareezy UI. Call it once at app startup — before rendering any components — and it returns a typed config object you can import anywhere.

✦

Think of it like createTamagui from Tamagui, or extendTheme from Chakra UI. One call, full control.

Quick Start

import { createUi, token } from '@stareezy-ui/tokens'

export const ui = createUi({
  tokens: {
    brand: {
      primary:   token('#FF6B35', 'brand-primary'),
      secondary: token('#004E89', 'brand-secondary'),
    },
  },
  breakpoints: {
    sm: 640,
    md: 768,
    lg: 1024,
  },
  defaultTheme: 'light',
})

// Fully typed — autocomplete works on your custom tokens
ui.tokens.brand.primary.value   // "#FF6B35"
ui.tokens.brand.primary.name    // "brand-primary"
ui.breakpoints.sm               // 640

Integration by Framework

Next.js (App Router)

Create a lib/ui.ts file and call createUi there. Import it in your root layout.tsx so it runs before any component renders.

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

export const ui = createUi({
  tokens: {
    brand: {
      primary: token('#FF6B35', 'brand-primary'),
    },
  },
})

// app/layout.tsx
import '@/lib/ui'   // side-effect import — registers config globally
import { ThemeProvider } from '@stareezy-ui/tokens'

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

Vite / React SPA

Call createUi at the top of your main.tsx before ReactDOM.createRoot.

// main.tsx
import { createUi } from '@stareezy-ui/tokens'
import { ThemeProvider } from '@stareezy-ui/tokens'
import ReactDOM from 'react-dom/client'
import App from './App'

createUi({
  tokens: { /* your tokens */ },
  defaultTheme: 'light',
})

ReactDOM.createRoot(document.getElementById('root')!).render(
  <ThemeProvider theme="light">
    <App />
  </ThemeProvider>
)

React Native / Expo

Call createUi at the top of your root App.tsx before the component definition.

// App.tsx
import { createUi } from '@stareezy-ui/tokens'
import { ThemeProvider } from '@stareezy-ui/tokens'

createUi({
  defaultTheme: 'light',
  breakpoints: { sm: 480, md: 768, lg: 1024, xl: 1280, '2xl': 1536 },
})

export default function App() {
  return (
    <ThemeProvider theme="light">
      {/* your app */}
    </ThemeProvider>
  )
}

⚠

Call createUi exactly once. Calling it again replaces the global singleton, which will reset any breakpoints or tokens registered after the first call.

Custom Tokens

Pass a tokens object where each key is a namespace and each value is a record of Token values created with the token() helper.

import { createUi, token } from '@stareezy-ui/tokens'

const ui = createUi({
  tokens: {
    // Each key becomes a top-level namespace
    brand: {
      primary:   token('#FF6B35', 'brand-primary'),
      secondary: token('#004E89', 'brand-secondary'),
      accent:    token('#F7C59F', 'brand-accent'),
    },
    size: {
      icon: token(24, 'size-icon'),
      avatar: token(40, 'size-avatar'),
    },
  },
})

// Access alongside built-in tokens
ui.tokens.brand.primary.value   // "#FF6B35"
ui.tokens.colors.celurenBlue    // built-in still available
ui.tokens.spacing               // built-in still available

Custom Breakpoints

Override any or all of the five default breakpoints (min-width in px, mobile-first). Unspecified keys keep their defaults.

const ui = createUi({
  breakpoints: {
    sm: 640,   // default: 480
    md: 768,   // default: 768
    lg: 1024,  // default: 1024
    xl: 1280,  // default: 1280
    '2xl': 1536, // default: 1536
  },
})

// Breakpoints are stored on globalThis so Box / responsive props pick them up
// automatically — no extra wiring needed.

ℹ

Breakpoints are written to globalThis.__stareezy_breakpoints__ so the components package can read them without a circular dependency. You never need to reference this directly.

Lazy Token Registration

Use registerTokens to add token groups after the initial call — useful for plugin-style extensions or code-split token sets.

import { ui } from '@/lib/ui'

// Returns a new config with the merged tokens — fully typed
const extendedUi = ui.registerTokens({
  illustration: {
    hero: token('/images/hero.svg', 'illustration-hero'),
  },
})

extendedUi.tokens.illustration.hero.value // '/images/hero.svg'

Runtime Breakpoint Updates

Call updateBreakpoints to adjust breakpoints at runtime, for example when adapting to a device's screen density.

import { ui } from '@/lib/ui'

ui.updateBreakpoints({ sm: 600 })
// globalThis.__stareezy_breakpoints__ is updated immediately

Reading the Active Config

Use getUiConfig() to read the current singleton from anywhere — useful inside utility functions or hooks that don't have direct access to the config object.

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

function getCurrentBreakpoints() {
  const config = getUiConfig()
  if (!config) throw new Error('createUi() has not been called yet')
  return config.breakpoints
}

API Reference

createUi(config?)

Prop	Type	Description
`tokens`	`CustomTokenGroups`	Custom token namespaces merged with built-in tokens.
`breakpoints`	`Partial<UiBreakpointConfig>`	Override default responsive breakpoints (min-width px, mobile-first).
`defaultTheme`	`"light" \| "dark" \| ThemeOverride`	Default theme applied when no ThemeProvider is present. Defaults to "light".

UiConfig (return value)

Property	Type	Description
`tokens`	`BuiltinTokens & TTokens`	All built-in tokens merged with your custom groups.
`breakpoints`	`UiBreakpointConfig`	Resolved breakpoint config.
`defaultTheme`	`"light" \| "dark" \| ThemeOverride`	The resolved default theme.
`registerTokens(newTokens)`	`UiConfig<T & TNew>`	Add more token groups after initial setup. Returns a new typed config.
`updateBreakpoints(overrides)`	`void`	Mutate breakpoints at runtime and sync to globalThis.

getUiConfig()

Returns the active UiConfig singleton, or null if createUi has not been called yet.