XLP-UI

XLP-UI is a multi-brand React component library and theming system built on Chakra UI v3.

It is designed for white-label and microfrontend use cases where each host application can switch brands, inject token overrides, and consume a shared set of themed UI primitives without coupling components to raw design values.

Features

• Multi-brand token architecture: BrandTokens -> Semantic Tokens -> Component Recipes
• React 19 and strict TypeScript support
• Chakra UI v3 system-based theme generation
• Runtime brand registration with registerBrand()
• Provider-based theme isolation for microfrontends
• Prebuilt themed components for common form and action patterns

Package

• Package name: @adil-hammad-xelops/el-magico-ui
• Module output: ESM and CJS
• Types: bundled in dist/index.d.ts

Installation

npm install @adil-hammad-xelops/el-magico-ui

Peer dependencies:

• react >= 19
• react-dom >= 19
• @chakra-ui/react >= 3
• @emotion/react >= 11
• @tanstack/react-query >= 5

Quick Start

Wrap your app with RootProvider when you want both theming and React Query wiring:

import { createRoot } from "react-dom/client"
import { RootProvider, XlpButton } from "@adil-hammad-xelops/el-magico-ui"

function App() {
  return <XlpButton>Click me</XlpButton>
}

createRoot(document.getElementById("root")!).render(
  <RootProvider brandId="default">
    <App />
  </RootProvider>,
)

If you only want the theme layer, use AppThemeProvider directly:

import { AppThemeProvider } from "@adil-hammad-xelops/el-magico-ui"

export function AppShell() {
  return <AppThemeProvider brandId="meridian">...</AppThemeProvider>
}

Built-in Brands

The library currently exposes these built-in token sets:

• default
• brandA
• brandB
• meridian

You can inspect the current registry through getRegisteredBrands().

Public API

Main exports from src/index.ts:

• Providers: RootProvider, AppThemeProvider
• Theme utilities: useTheme, registerBrand, resolveBrandTokens, getRegisteredBrands, createTheme
• Built-in token sets: defaultTokens, brandATokens, brandBTokens, meridianTokens
• Components: XlpButton, XlpInput, XlpTextarea, XlpSelect, XlpSwitch, XlpRadioGroup
• Theme/domain types: BrandTokens, ThemeContextValue, ColorScale, and shared app types from src/types

Theme Architecture

This repository enforces a strict separation of concerns:

1. src/theme/brands/*/tokens.ts Raw brand values only.
2. src/theme/semantic/* Stable semantic abstractions generated from brand tokens.
3. src/theme/components/* Chakra recipes that consume semantic tokens only.

Rules:

• Do not hardcode colors, spacing, radii, or border widths in components.
• Do not bypass semantic tokens from component recipes.
• Brand-specific changes should happen in token files first.

Custom Brands

Register a custom brand before mounting the provider:

import {
  registerBrand,
  RootProvider,
  type BrandTokens,
} from "@adil-hammad-xelops/xelops-ui"

const acmeTokens: BrandTokens = {
  // full token object
} as const

registerBrand("acme", acmeTokens)

export function Root() {
  return <RootProvider brandId="acme">...</RootProvider>
}

You can also supply partial runtime overrides:

import { useMemo } from "react"
import { RootProvider, type BrandTokens } from "@adil-hammad-xelops/el-magico-ui"

export function Root() {
  const tokenOverrides = useMemo<Partial<BrandTokens>>(
    () => ({
      radii: { md: "1rem" },
    }),
    [],
  )

  return (
    <RootProvider brandId="default" tokenOverrides={tokenOverrides}>
      ...
    </RootProvider>
  )
}

Components

Available base components:

• XlpButton
• XlpInput
• XlpTextarea
• XlpSelect
• XlpSwitch
• XlpRadioGroup

These components are theme-aware and intended to be consumed instead of raw Chakra components in feature code.

Development

Scripts:

• npm run dev - start the Vite dev server
• npm run build - build types and library bundles
• npm run build:types - emit declaration files only
• npm run preview - preview the Vite build locally

Project Structure

src/
  components/
  providers/
  theme/
    brands/
    components/
    semantic/
    context.tsx
    createTheme.ts
    index.ts
    provider.tsx
    registry.ts
    types.ts
  types/

Design Token Translation

This repo also contains internal agent/skill workflows for translating Figma token exports into the BrandTokens model.

Relevant repo assets:

• .github/skills/figma-token-theme-translator/
• .github/agents/figma-token-architect.agent.md

Those are internal workflow helpers and are not part of the published runtime package.

Build Output

The package publishes from dist/:

• dist/el-magico-ui.es.js
• dist/el-magico-ui.cjs.js
• dist/index.d.ts

License

ISC