@geenius/ui

Foundation UI primitives, providers, pages, utilities, and design tokens for Geenius applications.

This package is UI-only. The active support matrix for this run is:

• @geenius/ui/react
• @geenius/ui/react-css
• @geenius/ui/react-native
• @geenius/ui/solidjs
• @geenius/ui/solidjs-css

Deferred UI-kit and backend-metadata folders may remain in the repository, but entries marked inScope: false are excluded from active build, lint, test, Storybook, visual, a11y, and size matrices by @geenius/release-toolkit.

Install

Install the root package and the peer dependency for the framework you use.

pnpm add @geenius/ui react react-dom

pnpm add @geenius/ui solid-js

pnpm add @geenius/ui react-native

CSS variants expose a stylesheet subpath that must be imported once by the consuming app:

import '@geenius/ui/react-css/styles.css'

import '@geenius/ui/solidjs-css/styles.css'

Public Surface

The root entrypoint re-exports shared, framework-agnostic pieces only:

import {
  DESIGN_TOKENS,
  ErrorCode,
  GeeniusError,
  GeeniusUiError,
  SHADOW_SCALE,
  UiContextError,
  UiRuntimeError,
  cn,
  cx,
  generateId,
} from '@geenius/ui'
import type {
  ButtonVariant,
  ComponentSize,
  GeeniusErrorOptions,
  SerializedGeeniusError,
  ToastMessage,
  UiErrorCode,
} from '@geenius/ui'

There is no @geenius/ui/shared subpath and no defineTheme export. Shared helpers come through the root entrypoint. UiErrorCode is the UI-specific error discriminator union: 'UI_ERROR', 'UI_CONTEXT_ERROR', and 'UI_RUNTIME_ERROR'.

Active variant entrypoints expose parity-aligned components, hooks, providers, and pages:

import {
  Button,
  Dialog,
  UIProvider,
  UIShowcasePage,
  UITokensPage,
  useClickOutside,
  useDebounce,
  useKeyboard,
  useModal,
  useToast,
} from '@geenius/ui/react'
import { Button as ReactCssButton } from '@geenius/ui/react-css'
import { Button as NativeButton, UIProvider as NativeUIProvider } from '@geenius/ui/react-native'
import { Button as SolidButton } from '@geenius/ui/solidjs'
import { Button as SolidCssButton } from '@geenius/ui/solidjs-css'

The active variants export the same hook set: useModal, useToast, useClickOutside, useDebounce, and useKeyboard.

Usage

React

import { Button, Dialog, DialogContent, DialogTrigger, UIShowcasePage } from '@geenius/ui/react'

export function Example(): JSX.Element {
  return (
    <>
      <Dialog>
        <DialogTrigger>
          <Button>Open dialog</Button>
        </DialogTrigger>
        <DialogContent>Ready to ship.</DialogContent>
      </Dialog>

      <UIShowcasePage />
    </>
  )
}

React CSS

import '@geenius/ui/react-css/styles.css'
import { Button, UIProvider, UITokensPage } from '@geenius/ui/react-css'

export function Example(): JSX.Element {
  return (
    <UIProvider>
      <Button variant="primary">Vanilla CSS</Button>
      <UITokensPage />
    </UIProvider>
  )
}

SolidJS

import { Button, Dialog, DialogContent, DialogTrigger, UIShowcasePage } from '@geenius/ui/solidjs'

export function Example() {
  return (
    <>
      <Dialog>
        <DialogTrigger>
          <Button>Open dialog</Button>
        </DialogTrigger>
        <DialogContent>Ready to ship.</DialogContent>
      </Dialog>

      <UIShowcasePage />
    </>
  )
}

SolidJS CSS

import '@geenius/ui/solidjs-css/styles.css'
import { Button, UIProvider, UITokensPage } from '@geenius/ui/solidjs-css'

export function Example() {
  return (
    <UIProvider>
      <Button variant="primary">Vanilla CSS</Button>
      <UITokensPage />
    </UIProvider>
  )
}

React Native

import { Button, UIProvider, UIShowcasePage } from '@geenius/ui/react-native'

export function Example() {
  return (
    <UIProvider>
      <Button variant="primary">Continue</Button>
      <UIShowcasePage />
    </UIProvider>
  )
}

Themes

Theme presets are prepared --gn-* token overrides from @geenius/tokens for the active web variants. Import a preset after the base stylesheet to use managed mode:

import '@geenius/ui/react-css/styles.css'
import '@geenius/ui-shared/themes/presets/sophisticated-dark/tokens.css'

Tailwind variants can also load optional preset utilities when the preset ships them:

import '@geenius/ui-shared/themes/presets/glassmorphism/tailwind.css'

Ejected mode copies the preset into the app so the buyer owns future edits:

gxli theme eject sophisticated-dark --to app/src/theme

The full catalog and authoring contract are tracked in .docs/FEATURES/packages/ui/THEME_PRESETS_SPEC.md. The preview grid is generated by the Storybook preset landing task once preview.png assets exist.

Tokens And Classes

All authored colors use OKLCH. Runtime CSS variables are supplied by @geenius/tokens under the stable --gn-* namespace.

CSS-flavored variants use .gui-* BEM-style classes, for example .gui-btn, .gui-btn--primary, and .gui-btn__icon.

Storybook

Active Storybook apps live under apps/storybook-<variant>/.storybook/:

• apps/storybook-react
• apps/storybook-react-css
• apps/storybook-react-native
• apps/storybook-solidjs
• apps/storybook-solidjs-css

They use stock Storybook v10 architecture plus the shared @geenius/storybook app wiring. Legacy v1 SPA shells, defineSurface, storybookShell.tsx, and storyRegistry.tsx are not part of the current contract.

Development

pnpm build
pnpm lint
pnpm lint:apps
pnpm type-check
pnpm test
pnpm test:gauntlet
pnpm test:all

The PR-blocking suite is pnpm test:gauntlet: lint, app lint, publish lint, type-check, unit/cross-variant tests, size budgets, supply-chain audit, and license checks.

The full release suite is pnpm test:all: gauntlet, active Storybook build/smoke, UI-only DB conformance and migration guards, e2e, a11y, visual regression, performance smoke, and coverage reporting.

Use pnpm test:mutation for the weekly mutation layer and pnpm sbom to generate CycloneDX SBOM artifacts.

Documentation

Deep requirements and support-loop tracking live in the repository-level docs:

• .docs/PRDS/packages/PACKAGE_UI_PRD.md
• .docs/PLANS/packages/PKG_UI_PLAN.md
• .docs/DOCS/PACKAGES/UI.md
• .docs/FEATURES/packages/ui/FEATURES.md

License

FSL-1.1-Apache-2.0.