API Reference
◎

createUi

The Stareezy UI configuration factory — themes, tokens, shorthands, breakpoints, and module augmentation.

Overview

createUi() is the single entry point for configuring Stareezy UI. Call it once at app startup in a stareezy.config.ts file, export the result, and import it wherever you need typed token access.

✦
The recommended pattern is a dedicated stareezy.config.ts at your project root. The compiler reads this file automatically to pick up your custom shorthands at build time.

Full config example

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

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

  // 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 },

  // Named font configs
  fonts: {
    inter: {
      family: 'Inter, system-ui, sans-serif',
      size: { sm: token(14, 'inter-sm'), md: token(16, 'inter-md') },
    },
  },

  // Named animation presets
  animations: {
    fadeIn: { duration: motion.duration.enter, easing: motion.easing.easeOut },
  },

  // Global settings
  settings: {
    allowedStyleValues: 'somewhat-strict',
    defaultFont: 'inter',
  },

  // Prop shorthands — registered as valid BoxProps via module augmentation
  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,  // ← as const is required for module augmentation to work
})

// ── Module augmentation ──────────────────────────────────────────────────
// 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 key types so the module augmentation works. Without it, shorthands are typed as Record<string, string> and no props are added.

Module augmentation — typed shorthands

The declare module block is what makes custom shorthands appear as valid BoxProps. Once declared, TypeScript autocompletes them everywhere:

// After module augmentation:
<Box bg={t.backgrounds.primary} br={12} f={1} />
//   ↑ typed    ↑ typed          ↑ typed  ↑ typed

// Without augmentation — TypeScript error:
<Box br={12} />  // ❌ Property 'br' does not exist on type 'BoxProps'

// With augmentation — valid:
<Box br={12} />  // ✅ br → borderRadius, fully typed

ui.t — theme-reactive accessor

The returned config exposes ui.t — the same t accessor available from the standalone import. Pass these as component props for theme-reactive colors:

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

// ui.t is identical to importing t from '@stareezy-ui/tokens'
<Box bg={ui.t.backgrounds.primary} color={ui.t.text.primary} />

// Custom tokens are on ui.tokens
<Box bg={ui.tokens.brand.primary} />

// Both work together
<Box
  bg={ui.t.backgrounds.secondary}
  borderColor={ui.tokens.brand.primary}
  br={12}
/>

Framework integration

1
Next.js (App Router)
// stareezy.config.ts — at project root
import { createUi, themes } from '@stareezy-ui/tokens'
export const ui = createUi({ themes: { aurora: themes.aurora } })
type AppConfig = typeof ui
declare module '@stareezy-ui/tokens' {
  interface SzrCustomConfig extends AppConfig {}
}

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

export default function RootLayout({ children }) {
  return (
    <html lang="en"><body>
      <ThemeProvider theme="aurora">{children}</ThemeProvider>
    </body></html>
  )
}
2
Vite / React SPA
// main.tsx
import './stareezy.config'  // must be first import
import { ThemeProvider } from '@stareezy-ui/tokens'
import ReactDOM from 'react-dom/client'
import App from './App'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <ThemeProvider theme="aurora"><App /></ThemeProvider>
)
3
React Native / Expo
// App.tsx
import './stareezy.config'  // must be first import
import { ThemeProvider } from '@stareezy-ui/tokens'

export default function App() {
  return (
    <ThemeProvider theme="aurora">
      {/* your app */}
    </ThemeProvider>
  )
}
⚠
Import stareezy.config.ts exactly once, as the first import in your entry file. Calling createUi() again replaces the global singleton.

createUi() options

OptionTypeDescription
themesRecord<string, ThemeTokenMap>Named themes — aurora, dark, light, steins-gate, or custom.
tokensCustomTokenGroupsCustom token namespaces merged with built-in tokens.
mediaPartial<UiBreakpointConfig>Responsive breakpoints (min-width px, mobile-first). Supersedes breakpoints.
shorthandsRecord<string, string> as constProp shorthand mappings. as const required for module augmentation.
fontsRecord<string, FontConfig>Named font families with size, weight, lineHeight token scales.
animationsRecord<string, AnimationPreset>Named animation presets referencing motion token values.
settingsUiSettingsallowedStyleValues, defaultFont, disableSSR.
defaultTheme"light" | "dark" | ThemeOverrideDefault theme when no ThemeProvider is present. Defaults to "light".

UiConfig return value

Property / MethodTypeDescription
tThemeTokenAccessorTheme-reactive token accessor — same as standalone t import.
tokensBuiltinTokens & TTokensAll built-in + custom token groups.
shorthandsRecord<string, string>Registered prop shorthand mappings.
breakpointsUiBreakpointConfigResolved breakpoint config.
getTheme(name)ThemeTokenMapFull token map for a named theme. Throws ThemeNotFoundError if not registered.
getFont(name)FontConfigFont config for a named font. Throws FontNotFoundError if not registered.
getMedia()UiBreakpointConfigResolved media query breakpoint map.
getTokens()BuiltinTokens & TTokensReturns the merged token registry.
registerTokens(t)UiConfig<T & TNew>Add more token groups after initial setup. Returns a new typed config.
updateBreakpoints(o)voidMutate breakpoints at runtime and sync to globalThis.