Reference
⬢

Architecture

How Stareezy UI is organized as a monorepo with strict dependency boundaries.

Package Structure

stareezy-ui/
├── packages/
│   ├── tokens/       # Token definitions, theme system, serialization
│   ├── core/         # Utilities, hooks, platform helpers
│   ├── runtime/      # Style registry and platform adapters
│   ├── stylesheet/   # Atomic CSS sheet management (web)
│   ├── compiler/     # Babel/Vite build-time transform
│   └── components/   # 17+ cross-platform components
└── apps/
    ├── docs/         # This documentation site
    ├── storybook/    # Component stories
    └── playground/   # Live code editor

Package Responsibilities

pkg
@stareezy-ui/tokensdeps: none

Token factory, all token definitions, theme system, serialization. Zero dependencies.

pkg
@stareezy-ui/coredeps: tokens

Shared utilities, platform detection, hooks from rekosistem-components.

pkg
@stareezy-ui/runtimedeps: tokens, stylesheet

Style registry, O(1) token-to-style lookup, web and RN platform adapters.

pkg
@stareezy-ui/stylesheetdeps: runtime

Atomic CSS sheet management, CSS variable injection into document.head.

pkg
@stareezy-ui/compilerdeps: tokens (build-time only)

Babel/Vite/Metro plugin: extracts token refs at build time, emits atomic CSS.

pkg
@stareezy-ui/componentsdeps: tokens, core, runtime

All 17+ UI components rebuilt from rekosistem-components.

Token Flow

1
Definition — Tokens are defined in packages/tokens as frozen objects with { __token: true, id, value }
2
Compilation — The compiler detects token props at build time and replaces them with atomic CSS class names
3
Runtime — The runtime maintains a StyleRegistry (Map) populated once at init; resolve(token) is O(1)
4
Rendering — Components receive class names (web) or StyleSheet IDs (RN) — no string parsing, no object merging

Atomic CSS Strategy

Each token maps to exactly one CSS class. Theme switching requires zero JavaScript re-renders:

.sz-bg-celurenBlue-500 {
  background-color: var(--celurenBlue-500);
}

/* Theme override — only a data-theme attribute change needed */
[data-theme="dark"] {
  --celurenBlue-500: #4E82DD;
}

Tree Shaking

Every token category lives in its own file. Importing colors does not pull in spacing, radius, or typography. The compiler's dead-code elimination removes any tokens not referenced in your component tree.

✦
The packages/tokens package has zero runtime dependencies — no React, no React Native, no UI framework. It can be used in any JavaScript environment.

Property-Based Testing

Correctness properties are validated with fast-check (minimum 100 iterations per property):

✓Token factory shape
✓Token structural equality
✓Spacing token types
✓Semantic token equality
✓Theme provider re-renders
✓Compiler prop replacement
✓CSS deduplication
✓Runtime resolve stability
✓Serialization round-trip