{"_id":"@adilhammad/el-magico-ui","_rev":"8-73aebe9203aaa14018dd328380d64e7d","name":"@adilhammad/el-magico-ui","dist-tags":{"latest":"1.0.6"},"versions":{"1.0.4":{"name":"@adilhammad/el-magico-ui","version":"1.0.4","keywords":[],"author":"","license":"ISC","_id":"@adilhammad/el-magico-ui@1.0.4","maintainers":[{"name":"adilhammad","email":"adil.hammad@outlook.fr"}],"homepage":"https://github.com/adil-hammad-xelops/el-magico-ui#readme","bugs":{"url":"https://github.com/adil-hammad-xelops/el-magico-ui/issues"},"dist":{"shasum":"acd35d13aab3126a267b00d9bcfeb4744b2d685c","tarball":"https://registry.npmjs.org/@adilhammad/el-magico-ui/-/el-magico-ui-1.0.4.tgz","fileCount":118,"integrity":"sha512-wXQL7LADzHQnqc57FikoyQOcjg7L+hxNLISuy48QSb5Bk4PLj130IqJJdma5va3H7C1IAB8Af6Saui98zxnaHQ==","signatures":[{"sig":"MEYCIQCQngN9GNGTM3ptOVr20kSEqx61TkQYcYa0yk6ODFHXHwIhAJn4kG1ReH/qoFJfYh51rseDGqa5HTzKtqWlVYXnZQ06","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":972006},"main":"./dist/el-magico-ui.cjs.js","type":"module","types":"./dist/index.d.ts","module":"./dist/el-magico-ui.es.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/el-magico-ui.es.js","require":"./dist/el-magico-ui.cjs.js"}},"scripts":{"dev":"vite","build":"vite build && tsc -p tsconfig.build.json","preview":"vite preview","publish":"npm publish --access public","storybook":"storybook dev -p 6006","build:types":"tsc -p tsconfig.build.json","prepublishOnly":"npm run build","build-storybook":"storybook build"},"_npmUser":{"name":"adilhammad","email":"adil.hammad@outlook.fr"},"repository":{"url":"git+https://github.com/adil-hammad-xelops/el-magico-ui.git","type":"git"},"_npmVersion":"9.2.0","description":"El Magico UI - Multi-brand theming system based on Chakra UI v3","directories":{},"_nodeVersion":"24.11.0","dependencies":{"react":">=19","react-dom":">=19","lucide-react":"^1.3.0","@emotion/react":">=11","@chakra-ui/react":">=3","@tanstack/react-query":">=5"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.0.10","storybook":"^8.6.18","typescript":"^5.9.3","@types/react":"^19.2.14","@types/react-dom":"^19.2.3","@storybook/blocks":"^8.6.14","@vitejs/plugin-react":"^6.0.1","@storybook/addon-a11y":"^8.6.18","@storybook/react-vite":"^8.6.18","@storybook/addon-essentials":"^8.6.14"},"peerDependencies":{"react":">=19","react-dom":">=19","@emotion/react":">=11","@chakra-ui/react":">=3","@tanstack/react-query":">=5"},"_npmOperationalInternal":{"tmp":"tmp/el-magico-ui_1.0.4_1778602216346_0.8672901894035292","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@adilhammad/el-magico-ui","version":"1.0.5","keywords":["ui-components","react","chakra-ui","theming","design-system","multi-brand"],"author":{"name":"Adil Hammad","email":"adil.hammad@example.com"},"license":"ISC","_id":"@adilhammad/el-magico-ui@1.0.5","maintainers":[{"name":"adilhammad","email":"adil.hammad@outlook.fr"}],"homepage":"https://github.com/adil-hammad-xelops/el-magico-ui#readme","bugs":{"url":"https://github.com/adil-hammad-xelops/el-magico-ui/issues"},"dist":{"shasum":"6f34d28a891b3c1309470c927cf7d1c00fd95dc9","tarball":"https://registry.npmjs.org/@adilhammad/el-magico-ui/-/el-magico-ui-1.0.5.tgz","fileCount":118,"integrity":"sha512-5Dptx1SiPgNa03aScTv5AtEjMiwnqahW/yg8PCNxHUbOFrv9Zub1MTYN5G0sc9WZyjyPCfok6qLOsx8dD9bWPg==","signatures":[{"sig":"MEQCIASdxdlKDFNEn4xiEc4hEFvrt/u/TK8SbjuFv2jNxRNeAiBs+IdWOuYzfl6i/hFHN0zAI73Bk6bMqOyhxNrbRHtxxg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":972187},"main":"./dist/el-magico-ui.cjs.js","type":"module","types":"./dist/index.d.ts","module":"./dist/el-magico-ui.es.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/el-magico-ui.es.js","require":"./dist/el-magico-ui.cjs.js"}},"scripts":{"dev":"vite","build":"vite build && tsc -p tsconfig.build.json","preview":"vite preview","publish":"npm publish --access public","storybook":"storybook dev -p 6006","build:types":"tsc -p tsconfig.build.json","prepublishOnly":"npm run build","build-storybook":"storybook build"},"_npmUser":{"name":"adilhammad","email":"adil.hammad@outlook.fr"},"repository":{"url":"git+https://github.com/adil-hammad-xelops/el-magico-ui.git","type":"git"},"_npmVersion":"9.2.0","description":"El Magico UI - A powerful multi-brand theming system for React applications, built on Chakra UI v3.","directories":{},"_nodeVersion":"24.11.0","dependencies":{"react":">=19","react-dom":">=19","lucide-react":"^1.3.0","@emotion/react":">=11","@chakra-ui/react":">=3","@tanstack/react-query":">=5"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.0.10","storybook":"^8.6.18","typescript":"^5.9.3","@types/react":"^19.2.14","@types/react-dom":"^19.2.3","@storybook/blocks":"^8.6.14","@vitejs/plugin-react":"^6.0.1","@storybook/addon-a11y":"^8.6.18","@storybook/react-vite":"^8.6.18","@storybook/addon-essentials":"^8.6.14"},"peerDependencies":{"react":">=19","react-dom":">=19","@emotion/react":">=11","@chakra-ui/react":">=3","@tanstack/react-query":">=5"},"_npmOperationalInternal":{"tmp":"tmp/el-magico-ui_1.0.5_1778604627592_0.5095286844870113","host":"s3://npm-registry-packages-npm-production"}},"1.0.6":{"name":"@adilhammad/el-magico-ui","version":"1.0.6","type":"module","description":"El Magico UI - A powerful multi-brand theming system for React applications, built on Chakra UI v3.","main":"./dist/el-magico-ui.cjs.js","module":"./dist/el-magico-ui.es.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/el-magico-ui.es.js","require":"./dist/el-magico-ui.cjs.js"}},"repository":{"type":"git","url":"git+https://github.com/adil-hammad-xelops/el-magico-ui.git"},"publishConfig":{"registry":"https://registry.npmjs.org/","access":"public"},"scripts":{"dev":"vite","build":"vite build && tsc -p tsconfig.build.json","build:types":"tsc -p tsconfig.build.json","prepublishOnly":"npm run build","preview":"vite preview","storybook":"storybook dev -p 6006","build-storybook":"storybook build","publish":"npm publish --access public"},"keywords":["ui-components","react","chakra-ui","theming","design-system","multi-brand"],"author":{"name":"Adil Hammad","email":"adil.hammad@example.com"},"license":"ISC","peerDependencies":{"@chakra-ui/react":">=3","@emotion/react":">=11","@tanstack/react-query":">=5","react":">=19","react-dom":">=19"},"dependencies":{"@chakra-ui/react":">=3","@emotion/react":">=11","@tanstack/react-query":">=5","lucide-react":"^1.3.0","react":">=19","react-dom":">=19"},"devDependencies":{"@storybook/addon-a11y":"^8.6.18","@storybook/addon-essentials":"^8.6.14","@storybook/blocks":"^8.6.14","@storybook/react-vite":"^8.6.18","@types/react":"^19.2.14","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^6.0.1","storybook":"^8.6.18","typescript":"^5.9.3","vite":"^8.0.10"},"bugs":{"url":"https://github.com/adil-hammad-xelops/el-magico-ui/issues"},"homepage":"https://github.com/adil-hammad-xelops/el-magico-ui#readme","_id":"@adilhammad/el-magico-ui@1.0.6","_nodeVersion":"24.11.0","_npmVersion":"9.2.0","dist":{"integrity":"sha512-jCKZUiKOrhwSSOikxriOgSwulN+yubqP7J95X3+0WUMH7VzmJXB+uFYyYk8dtS8HS49g8mwbfXKNgDGLiM35Cw==","shasum":"729dcb3611c966bb764f51cc618c89b671f59a24","tarball":"https://registry.npmjs.org/@adilhammad/el-magico-ui/-/el-magico-ui-1.0.6.tgz","fileCount":118,"unpackedSize":972186,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHDeu7P0pb44xhaUTQA7RSzwyGYUxMW7h0edhOUxFBs+AiBPa9kS3mVeqQnBx4O33Ytc1in2q0NnlhivyKsj+9JgOA=="}]},"_npmUser":{"name":"adilhammad","email":"adil.hammad@outlook.fr"},"directories":{},"maintainers":[{"name":"adilhammad","email":"adil.hammad@outlook.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/el-magico-ui_1.0.6_1778604771501_0.33671749875083745"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-12T16:10:16.202Z","modified":"2026-05-12T16:52:51.781Z","1.0.0":"2026-05-12T16:01:56.486Z","1.0.1":"2026-05-12T16:03:26.347Z","1.0.2":"2026-05-12T16:04:19.245Z","1.0.3":"2026-05-12T16:05:47.531Z","1.0.4":"2026-05-12T16:10:16.584Z","1.0.5":"2026-05-12T16:50:27.862Z","1.0.6":"2026-05-12T16:52:51.682Z"},"bugs":{"url":"https://github.com/adil-hammad-xelops/el-magico-ui/issues"},"author":{"name":"Adil Hammad","email":"adil.hammad@example.com"},"license":"ISC","homepage":"https://github.com/adil-hammad-xelops/el-magico-ui#readme","keywords":["ui-components","react","chakra-ui","theming","design-system","multi-brand"],"repository":{"type":"git","url":"git+https://github.com/adil-hammad-xelops/el-magico-ui.git"},"description":"El Magico UI - A powerful multi-brand theming system for React applications, built on Chakra UI v3.","maintainers":[{"name":"adilhammad","email":"adil.hammad@outlook.fr"}],"readme":"# XLP-UI\r\n\r\n`XLP-UI` is a multi-brand React component library and theming system built on Chakra UI v3.\r\n\r\nIt 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.\r\n\r\n## Features\r\n\r\n- Multi-brand token architecture: `BrandTokens -> Semantic Tokens -> Component Recipes`\r\n- React 19 and strict TypeScript support\r\n- Chakra UI v3 system-based theme generation\r\n- Runtime brand registration with `registerBrand()`\r\n- Provider-based theme isolation for microfrontends\r\n- Prebuilt themed components for common form and action patterns\r\n\r\n## Package\r\n\r\n- Package name: `@adil-hammad-xelops/el-magico-ui`\r\n- Module output: ESM and CJS\r\n- Types: bundled in `dist/index.d.ts`\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @adil-hammad-xelops/el-magico-ui\r\n```\r\n\r\nPeer dependencies:\r\n\r\n- `react >= 19`\r\n- `react-dom >= 19`\r\n- `@chakra-ui/react >= 3`\r\n- `@emotion/react >= 11`\r\n- `@tanstack/react-query >= 5`\r\n\r\n## Quick Start\r\n\r\nWrap your app with `RootProvider` when you want both theming and React Query wiring:\r\n\r\n```tsx\r\nimport { createRoot } from \"react-dom/client\"\r\nimport { RootProvider, XlpButton } from \"@adil-hammad-xelops/el-magico-ui\"\r\n\r\nfunction App() {\r\n  return <XlpButton>Click me</XlpButton>\r\n}\r\n\r\ncreateRoot(document.getElementById(\"root\")!).render(\r\n  <RootProvider brandId=\"default\">\r\n    <App />\r\n  </RootProvider>,\r\n)\r\n```\r\n\r\nIf you only want the theme layer, use `AppThemeProvider` directly:\r\n\r\n```tsx\r\nimport { AppThemeProvider } from \"@adil-hammad-xelops/el-magico-ui\"\r\n\r\nexport function AppShell() {\r\n  return <AppThemeProvider brandId=\"meridian\">...</AppThemeProvider>\r\n}\r\n```\r\n\r\n## Built-in Brands\r\n\r\nThe library currently exposes these built-in token sets:\r\n\r\n- `default`\r\n- `brandA`\r\n- `brandB`\r\n- `meridian`\r\n\r\nYou can inspect the current registry through `getRegisteredBrands()`.\r\n\r\n## Public API\r\n\r\nMain exports from `src/index.ts`:\r\n\r\n- Providers: `RootProvider`, `AppThemeProvider`\r\n- Theme utilities: `useTheme`, `registerBrand`, `resolveBrandTokens`, `getRegisteredBrands`, `createTheme`\r\n- Built-in token sets: `defaultTokens`, `brandATokens`, `brandBTokens`, `meridianTokens`\r\n- Components: `XlpButton`, `XlpInput`, `XlpTextarea`, `XlpSelect`, `XlpSwitch`, `XlpRadioGroup`\r\n- Theme/domain types: `BrandTokens`, `ThemeContextValue`, `ColorScale`, and shared app types from `src/types`\r\n\r\n## Theme Architecture\r\n\r\nThis repository enforces a strict separation of concerns:\r\n\r\n1. `src/theme/brands/*/tokens.ts`\r\n   Raw brand values only.\r\n2. `src/theme/semantic/*`\r\n   Stable semantic abstractions generated from brand tokens.\r\n3. `src/theme/components/*`\r\n   Chakra recipes that consume semantic tokens only.\r\n\r\nRules:\r\n\r\n- Do not hardcode colors, spacing, radii, or border widths in components.\r\n- Do not bypass semantic tokens from component recipes.\r\n- Brand-specific changes should happen in token files first.\r\n\r\n## Custom Brands\r\n\r\nRegister a custom brand before mounting the provider:\r\n\r\n```tsx\r\nimport {\r\n  registerBrand,\r\n  RootProvider,\r\n  type BrandTokens,\r\n} from \"@adil-hammad-xelops/xelops-ui\"\r\n\r\nconst acmeTokens: BrandTokens = {\r\n  // full token object\r\n} as const\r\n\r\nregisterBrand(\"acme\", acmeTokens)\r\n\r\nexport function Root() {\r\n  return <RootProvider brandId=\"acme\">...</RootProvider>\r\n}\r\n```\r\n\r\nYou can also supply partial runtime overrides:\r\n\r\n```tsx\r\nimport { useMemo } from \"react\"\r\nimport { RootProvider, type BrandTokens } from \"@adil-hammad-xelops/el-magico-ui\"\r\n\r\nexport function Root() {\r\n  const tokenOverrides = useMemo<Partial<BrandTokens>>(\r\n    () => ({\r\n      radii: { md: \"1rem\" },\r\n    }),\r\n    [],\r\n  )\r\n\r\n  return (\r\n    <RootProvider brandId=\"default\" tokenOverrides={tokenOverrides}>\r\n      ...\r\n    </RootProvider>\r\n  )\r\n}\r\n```\r\n\r\n## Components\r\n\r\nAvailable base components:\r\n\r\n- `XlpButton`\r\n- `XlpInput`\r\n- `XlpTextarea`\r\n- `XlpSelect`\r\n- `XlpSwitch`\r\n- `XlpRadioGroup`\r\n\r\nThese components are theme-aware and intended to be consumed instead of raw Chakra components in feature code.\r\n\r\n## Development\r\n\r\nScripts:\r\n\r\n- `npm run dev` - start the Vite dev server\r\n- `npm run build` - build types and library bundles\r\n- `npm run build:types` - emit declaration files only\r\n- `npm run preview` - preview the Vite build locally\r\n\r\n## Project Structure\r\n\r\n```text\r\nsrc/\r\n  components/\r\n  providers/\r\n  theme/\r\n    brands/\r\n    components/\r\n    semantic/\r\n    context.tsx\r\n    createTheme.ts\r\n    index.ts\r\n    provider.tsx\r\n    registry.ts\r\n    types.ts\r\n  types/\r\n```\r\n\r\n## Design Token Translation\r\n\r\nThis repo also contains internal agent/skill workflows for translating Figma token exports into the `BrandTokens` model.\r\n\r\nRelevant repo assets:\r\n\r\n- `.github/skills/figma-token-theme-translator/`\r\n- `.github/agents/figma-token-architect.agent.md`\r\n\r\nThose are internal workflow helpers and are not part of the published runtime package.\r\n\r\n## Build Output\r\n\r\nThe package publishes from `dist/`:\r\n\r\n- `dist/el-magico-ui.es.js`\r\n- `dist/el-magico-ui.cjs.js`\r\n- `dist/index.d.ts`\r\n\r\n## License\r\n\r\n`ISC`","readmeFilename":"README.md"}