opsfuse-ui 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (209) hide show
  1. package/.claude/settings.local.json +8 -0
  2. package/.claude/skills/brief-to-tasks/SKILL.md +74 -0
  3. package/.claude/skills/design-brief/SKILL.md +120 -0
  4. package/.claude/skills/design-flow/SKILL.md +124 -0
  5. package/.claude/skills/design-review/SKILL.md +249 -0
  6. package/.claude/skills/design-tokens/SKILL.md +198 -0
  7. package/.claude/skills/frontend-design/SKILL.md +144 -0
  8. package/.claude/skills/grill-me/SKILL.md +21 -0
  9. package/.claude/skills/information-architecture/SKILL.md +111 -0
  10. package/.claude/skills/opsfuse-color-theme/SKILL.md +251 -0
  11. package/.claude/skills/opsfuse-components/SKILL.md +1439 -0
  12. package/.claude/skills/opsfuse-setup/SKILL.md +548 -0
  13. package/.claude/skills/opsfuse-ui-consistency/SKILL.md +160 -0
  14. package/README.md +356 -0
  15. package/dist/chunk-BdsCSvBP.js +20 -0
  16. package/dist/clsx-D7D_XZ_-.js +16 -0
  17. package/dist/components/logo/LogoMaker.d.ts +43 -0
  18. package/dist/components/logo/LogoMaker.d.ts.map +1 -0
  19. package/dist/components/logo/RecruitSmartly.d.ts +4 -0
  20. package/dist/components/logo/RecruitSmartly.d.ts.map +1 -0
  21. package/dist/components/logo/SkillReady.d.ts +4 -0
  22. package/dist/components/logo/SkillReady.d.ts.map +1 -0
  23. package/dist/components/logo/TalentScan.d.ts +4 -0
  24. package/dist/components/logo/TalentScan.d.ts.map +1 -0
  25. package/dist/components/logo/Verity.d.ts +4 -0
  26. package/dist/components/logo/Verity.d.ts.map +1 -0
  27. package/dist/components/logo/WorkLog.d.ts +4 -0
  28. package/dist/components/logo/WorkLog.d.ts.map +1 -0
  29. package/dist/components/opsfuse-root.d.ts +7 -0
  30. package/dist/components/opsfuse-root.d.ts.map +1 -0
  31. package/dist/components/opsfuse-theme-provider.d.ts +15 -0
  32. package/dist/components/opsfuse-theme-provider.d.ts.map +1 -0
  33. package/dist/components/ui/Header.d.ts +17 -0
  34. package/dist/components/ui/Header.d.ts.map +1 -0
  35. package/dist/components/ui/accordion.d.ts +20 -0
  36. package/dist/components/ui/accordion.d.ts.map +1 -0
  37. package/dist/components/ui/alert-dialog.d.ts +15 -0
  38. package/dist/components/ui/alert-dialog.d.ts.map +1 -0
  39. package/dist/components/ui/alert.d.ts +26 -0
  40. package/dist/components/ui/alert.d.ts.map +1 -0
  41. package/dist/components/ui/aspect-ratio.d.ts +4 -0
  42. package/dist/components/ui/aspect-ratio.d.ts.map +1 -0
  43. package/dist/components/ui/autocomplete.d.ts +24 -0
  44. package/dist/components/ui/autocomplete.d.ts.map +1 -0
  45. package/dist/components/ui/avatar.d.ts +9 -0
  46. package/dist/components/ui/avatar.d.ts.map +1 -0
  47. package/dist/components/ui/badge.d.ts +10 -0
  48. package/dist/components/ui/badge.d.ts.map +1 -0
  49. package/dist/components/ui/breadcrumb.d.ts +12 -0
  50. package/dist/components/ui/breadcrumb.d.ts.map +1 -0
  51. package/dist/components/ui/button-group.d.ts +12 -0
  52. package/dist/components/ui/button-group.d.ts.map +1 -0
  53. package/dist/components/ui/button.d.ts +14 -0
  54. package/dist/components/ui/button.d.ts.map +1 -0
  55. package/dist/components/ui/calendar.d.ts +11 -0
  56. package/dist/components/ui/calendar.d.ts.map +1 -0
  57. package/dist/components/ui/card.d.ts +14 -0
  58. package/dist/components/ui/card.d.ts.map +1 -0
  59. package/dist/components/ui/carousel.d.ts +29 -0
  60. package/dist/components/ui/carousel.d.ts.map +1 -0
  61. package/dist/components/ui/chart.d.ts +45 -0
  62. package/dist/components/ui/chart.d.ts.map +1 -0
  63. package/dist/components/ui/checkbox.d.ts +10 -0
  64. package/dist/components/ui/checkbox.d.ts.map +1 -0
  65. package/dist/components/ui/collapsible.d.ts +6 -0
  66. package/dist/components/ui/collapsible.d.ts.map +1 -0
  67. package/dist/components/ui/combobox.d.ts +40 -0
  68. package/dist/components/ui/combobox.d.ts.map +1 -0
  69. package/dist/components/ui/command.d.ts +19 -0
  70. package/dist/components/ui/command.d.ts.map +1 -0
  71. package/dist/components/ui/context-menu.d.ts +32 -0
  72. package/dist/components/ui/context-menu.d.ts.map +1 -0
  73. package/dist/components/ui/dialog.d.ts +30 -0
  74. package/dist/components/ui/dialog.d.ts.map +1 -0
  75. package/dist/components/ui/direction.d.ts +8 -0
  76. package/dist/components/ui/direction.d.ts.map +1 -0
  77. package/dist/components/ui/drawer.d.ts +14 -0
  78. package/dist/components/ui/drawer.d.ts.map +1 -0
  79. package/dist/components/ui/dropdown-menu.d.ts +30 -0
  80. package/dist/components/ui/dropdown-menu.d.ts.map +1 -0
  81. package/dist/components/ui/empty.d.ts +12 -0
  82. package/dist/components/ui/empty.d.ts.map +1 -0
  83. package/dist/components/ui/field.d.ts +25 -0
  84. package/dist/components/ui/field.d.ts.map +1 -0
  85. package/dist/components/ui/form.d.ts +27 -0
  86. package/dist/components/ui/form.d.ts.map +1 -0
  87. package/dist/components/ui/hover-card.d.ts +7 -0
  88. package/dist/components/ui/hover-card.d.ts.map +1 -0
  89. package/dist/components/ui/input-group.d.ts +18 -0
  90. package/dist/components/ui/input-group.d.ts.map +1 -0
  91. package/dist/components/ui/input-otp.d.ts +12 -0
  92. package/dist/components/ui/input-otp.d.ts.map +1 -0
  93. package/dist/components/ui/input.d.ts +12 -0
  94. package/dist/components/ui/input.d.ts.map +1 -0
  95. package/dist/components/ui/item.d.ts +24 -0
  96. package/dist/components/ui/item.d.ts.map +1 -0
  97. package/dist/components/ui/kbd.d.ts +4 -0
  98. package/dist/components/ui/kbd.d.ts.map +1 -0
  99. package/dist/components/ui/label.d.ts +5 -0
  100. package/dist/components/ui/label.d.ts.map +1 -0
  101. package/dist/components/ui/menubar.d.ts +31 -0
  102. package/dist/components/ui/menubar.d.ts.map +1 -0
  103. package/dist/components/ui/navigation-menu.d.ts +15 -0
  104. package/dist/components/ui/navigation-menu.d.ts.map +1 -0
  105. package/dist/components/ui/pagination.d.ts +15 -0
  106. package/dist/components/ui/pagination.d.ts.map +1 -0
  107. package/dist/components/ui/popover.d.ts +11 -0
  108. package/dist/components/ui/popover.d.ts.map +1 -0
  109. package/dist/components/ui/progress.d.ts +19 -0
  110. package/dist/components/ui/progress.d.ts.map +1 -0
  111. package/dist/components/ui/radio-group.d.ts +11 -0
  112. package/dist/components/ui/radio-group.d.ts.map +1 -0
  113. package/dist/components/ui/resizable.d.ts +8 -0
  114. package/dist/components/ui/resizable.d.ts.map +1 -0
  115. package/dist/components/ui/scroll-area.d.ts +6 -0
  116. package/dist/components/ui/scroll-area.d.ts.map +1 -0
  117. package/dist/components/ui/select.d.ts +27 -0
  118. package/dist/components/ui/select.d.ts.map +1 -0
  119. package/dist/components/ui/separator.d.ts +5 -0
  120. package/dist/components/ui/separator.d.ts.map +1 -0
  121. package/dist/components/ui/shadcn/shadcn-accordion.d.ts +8 -0
  122. package/dist/components/ui/shadcn/shadcn-accordion.d.ts.map +1 -0
  123. package/dist/components/ui/shadcn/shadcn-alert-dialog.d.ts +19 -0
  124. package/dist/components/ui/shadcn/shadcn-alert-dialog.d.ts.map +1 -0
  125. package/dist/components/ui/shadcn/shadcn-avatar.d.ts +12 -0
  126. package/dist/components/ui/shadcn/shadcn-avatar.d.ts.map +1 -0
  127. package/dist/components/ui/shadcn/shadcn-combobox.d.ts +33 -0
  128. package/dist/components/ui/shadcn/shadcn-combobox.d.ts.map +1 -0
  129. package/dist/components/ui/shadcn/shadcn-dropdown-menu.d.ts +30 -0
  130. package/dist/components/ui/shadcn/shadcn-dropdown-menu.d.ts.map +1 -0
  131. package/dist/components/ui/shadcn/shadcn-empty.d.ts +12 -0
  132. package/dist/components/ui/shadcn/shadcn-empty.d.ts.map +1 -0
  133. package/dist/components/ui/shadcn/shadcn-pagination.d.ts +18 -0
  134. package/dist/components/ui/shadcn/shadcn-pagination.d.ts.map +1 -0
  135. package/dist/components/ui/shadcn/shadcn-select.d.ts +24 -0
  136. package/dist/components/ui/shadcn/shadcn-select.d.ts.map +1 -0
  137. package/dist/components/ui/shadcn/shadcn-tabs.d.ts +12 -0
  138. package/dist/components/ui/shadcn/shadcn-tabs.d.ts.map +1 -0
  139. package/dist/components/ui/shadcn/shadcn-tooltip.d.ts +11 -0
  140. package/dist/components/ui/shadcn/shadcn-tooltip.d.ts.map +1 -0
  141. package/dist/components/ui/sheet.d.ts +28 -0
  142. package/dist/components/ui/sheet.d.ts.map +1 -0
  143. package/dist/components/ui/sidebar.d.ts +70 -0
  144. package/dist/components/ui/sidebar.d.ts.map +1 -0
  145. package/dist/components/ui/skeleton.d.ts +3 -0
  146. package/dist/components/ui/skeleton.d.ts.map +1 -0
  147. package/dist/components/ui/slider.d.ts +22 -0
  148. package/dist/components/ui/slider.d.ts.map +1 -0
  149. package/dist/components/ui/sonner.d.ts +5 -0
  150. package/dist/components/ui/sonner.d.ts.map +1 -0
  151. package/dist/components/ui/spinner.d.ts +3 -0
  152. package/dist/components/ui/spinner.d.ts.map +1 -0
  153. package/dist/components/ui/switch.d.ts +12 -0
  154. package/dist/components/ui/switch.d.ts.map +1 -0
  155. package/dist/components/ui/table.d.ts +11 -0
  156. package/dist/components/ui/table.d.ts.map +1 -0
  157. package/dist/components/ui/tabs.d.ts +22 -0
  158. package/dist/components/ui/tabs.d.ts.map +1 -0
  159. package/dist/components/ui/textarea.d.ts +9 -0
  160. package/dist/components/ui/textarea.d.ts.map +1 -0
  161. package/dist/components/ui/toggle-group.d.ts +11 -0
  162. package/dist/components/ui/toggle-group.d.ts.map +1 -0
  163. package/dist/components/ui/toggle.d.ts +10 -0
  164. package/dist/components/ui/toggle.d.ts.map +1 -0
  165. package/dist/components/ui/tooltip.d.ts +15 -0
  166. package/dist/components/ui/tooltip.d.ts.map +1 -0
  167. package/dist/core.d.ts +2 -0
  168. package/dist/core.d.ts.map +1 -0
  169. package/dist/core.js +3 -0
  170. package/dist/es6-D-3xKXBT.js +24045 -0
  171. package/dist/extended.d.ts +2 -0
  172. package/dist/extended.d.ts.map +1 -0
  173. package/dist/extended.js +3 -0
  174. package/dist/hooks/use-mobile.d.ts +2 -0
  175. package/dist/hooks/use-mobile.d.ts.map +1 -0
  176. package/dist/icons.d.ts +2 -0
  177. package/dist/icons.d.ts.map +1 -0
  178. package/dist/icons.js +2 -0
  179. package/dist/index.d.ts +2 -0
  180. package/dist/index.d.ts.map +1 -0
  181. package/dist/index.js +2194 -0
  182. package/dist/input-group-DIfVGMYe.js +5196 -0
  183. package/dist/input-otp-DwLGFwVo.js +11879 -0
  184. package/dist/lib/brand-theme.d.ts +4 -0
  185. package/dist/lib/brand-theme.d.ts.map +1 -0
  186. package/dist/lib/document-dark-mode.d.ts +8 -0
  187. package/dist/lib/document-dark-mode.d.ts.map +1 -0
  188. package/dist/lib/opsfuse-portal-theme.d.ts +21 -0
  189. package/dist/lib/opsfuse-portal-theme.d.ts.map +1 -0
  190. package/dist/lib/theme-scope.d.ts +3 -0
  191. package/dist/lib/theme-scope.d.ts.map +1 -0
  192. package/dist/lib/utils.d.ts +3 -0
  193. package/dist/lib/utils.d.ts.map +1 -0
  194. package/dist/lucide-react-DLVJK_zM.js +38405 -0
  195. package/dist/public-api-core.d.ts +61 -0
  196. package/dist/public-api-core.d.ts.map +1 -0
  197. package/dist/public-api-extended.d.ts +9 -0
  198. package/dist/public-api-extended.d.ts.map +1 -0
  199. package/dist/public-api.d.ts +73 -0
  200. package/dist/public-api.d.ts.map +1 -0
  201. package/dist/recharts.d.ts +2 -0
  202. package/dist/recharts.d.ts.map +1 -0
  203. package/dist/recharts.js +2 -0
  204. package/dist/style.css +3 -0
  205. package/dist/style.layered.css +3 -0
  206. package/dist/toggle-group-D21Ul2kd.js +10171 -0
  207. package/package.json +113 -0
  208. package/scripts/postinstall.mjs +67 -0
  209. package/scripts/unwrap-css-layers.mjs +36 -0
@@ -0,0 +1,548 @@
1
+ ---
2
+ name: opsfuse-setup
3
+ description: >
4
+ Master setup skill for integrating opsfuse-ui into any React project. Covers installation,
5
+ font/CSS wiring, brand theme selection from all four themes, full component migration
6
+ (replacing existing UI with opsfuse equivalents), and applying consistent design tokens
7
+ across the entire app. Use when starting opsfuse integration or migrating an existing app.
8
+ ---
9
+
10
+ # OpsFuse UI — Integration Master Guide
11
+
12
+ You are an expert integrator for the `opsfuse-ui` React component library. Follow this guide **in order** when setting up opsfuse-ui in a new or existing project. Never skip phases — each phase depends on the previous one being correct.
13
+
14
+ ---
15
+
16
+ ## PHASE 0 — Discovery
17
+
18
+ Before touching anything, understand what you're working with:
19
+
20
+ 1. **Detect the framework** — Next.js (App Router / Pages), Vite + React, Remix, CRA, etc.
21
+ 2. **Detect the package manager** — `package.json` + lockfile (`package-lock.json` → npm, `yarn.lock` → yarn, `pnpm-lock.yaml` → pnpm, `bun.lockb` → bun).
22
+ 3. **Detect existing UI** — scan for shadcn, MUI, Chakra, Ant Design, Radix primitives, Tailwind utility classes. Note which components are used.
23
+ 4. **Detect existing global CSS** — find the entry stylesheet imported in the app root.
24
+ 5. **Find the app entry point** — `main.tsx`, `_app.tsx`, `app/layout.tsx`, `src/index.tsx`, etc.
25
+
26
+ ---
27
+
28
+ ## PHASE 1 — Installation
29
+
30
+ ### 1a. Install the package
31
+
32
+ Pick **one** install method. Submodule is preferred when the host repo should pin a specific library revision alongside application code.
33
+
34
+ #### Option A — Git submodule (recommended for monorepos / pinned source)
35
+
36
+ From the **host app** repository root:
37
+
38
+ ```bash
39
+ git submodule add git+https://code.opsfuse.com/mockinterview/opsfuse-ui.git packages/ui
40
+ git submodule update --init --recursive
41
+ ```
42
+
43
+ Add to the host `package.json`:
44
+
45
+ ```json
46
+ {
47
+ "dependencies": {
48
+ "opsfuse-ui": "file:packages/ui"
49
+ }
50
+ }
51
+ ```
52
+
53
+ Install with the detected package manager (`npm install`, `pnpm install`, etc.). On fresh clones of the host repo, run `git submodule update --init --recursive` before install.
54
+
55
+ **Pull / update submodule in the host app** (from host repo root unless noted):
56
+
57
+ | Situation | Commands |
58
+ | --------- | -------- |
59
+ | Fresh clone | `git submodule update --init --recursive` → `npm install` |
60
+ | After `git pull` on host (submodule SHA may have changed) | `git submodule update --init --recursive` → `cd packages/ui && npm run build:lib` → `npm install` in host if `packages/ui/package.json` changed |
61
+ | Pull host + sync submodules together | `git pull --recurse-submodules` (or `git config submodule.recurse true` then `git pull`) → rebuild in `packages/ui` |
62
+ | Bump library to latest remote | `cd packages/ui` → `git fetch` → `git checkout main` → `git pull` → `cd ../..` → `git add packages/ui` → commit → `npm run build:lib` in `packages/ui` → `npm install` in host if needed |
63
+
64
+ The host records which library commit is pinned; always commit `packages/ui` when intentionally upgrading the submodule.
65
+
66
+ #### Option B — Registry or git dependency
67
+
68
+ Use the detected package manager:
69
+
70
+ ```bash
71
+ # npm (registry)
72
+ npm install opsfuse-ui
73
+
74
+ # yarn
75
+ yarn add opsfuse-ui
76
+
77
+ # pnpm
78
+ pnpm add opsfuse-ui
79
+
80
+ # bun
81
+ bun add opsfuse-ui
82
+
83
+ # From private Git repo (internal, not submodule)
84
+ npm install git+https://code.opsfuse.com/mockinterview/opsfuse-ui.git#main
85
+ ```
86
+
87
+ **Peer dependencies** — opsfuse-ui requires `react` and `react-dom` (same major version). Verify they are already installed. Do not add them if they already exist.
88
+
89
+ ### 1b. TypeScript config
90
+
91
+ If the project has `tsconfig.json`, ensure `moduleResolution` is set to `"bundler"`, `"node16"`, or `"nodenext"` so `package.json` `exports` resolve correctly:
92
+
93
+ ```json
94
+ {
95
+ "compilerOptions": {
96
+ "moduleResolution": "bundler"
97
+ }
98
+ }
99
+ ```
100
+
101
+ ---
102
+
103
+ ## PHASE 2 — CSS & Font Setup
104
+
105
+ ### 2a. Import opsfuse styles
106
+
107
+ Find the app's entry file (e.g. `main.tsx`, `_app.tsx`, `app/layout.tsx`) and add the CSS import that matches the host's Tailwind version, **before the host app's own Tailwind / global stylesheet**. There are two bundles — pick one:
108
+
109
+ ```ts
110
+ // Tailwind v3 host (or no Tailwind): flat, un-layered
111
+ import "opsfuse-ui/styles.css";
112
+ // Tailwind v4 host: cascade-layered
113
+ import "opsfuse-ui/styles.layered.css";
114
+
115
+ import "./index.css"; // your app's `@import "tailwindcss"` etc. — comes AFTER
116
+ ```
117
+
118
+ For **Next.js App Router** add it first in `app/layout.tsx`; for **Pages Router** add it first in `pages/_app.tsx` — in both cases before `globals.css`.
119
+
120
+ **Which bundle and why.** Both are precompiled, self-contained CSS (you do not run Tailwind over them). Import opsfuse *before* your own CSS so your rules keep precedence and your `className` overrides on library components still take effect.
121
+
122
+ - **`styles.css` (flat) — Tailwind v3 host.** No `@layer` blocks, so v3's PostCSS never throws `@layer components is used but no matching @tailwind components directive`, and the library's un-layered utility classes correctly out-specify the host's un-layered preflight (`*{padding:0}`, element resets). Do **not** use this on a v4 host: its un-layered utilities would beat the host's layered ones (e.g. library `.px-4` would override your `md:px-8`).
123
+ - **`styles.layered.css` — Tailwind v4 host.** The library sits in low-priority `opsfuse-*` cascade layers; imported first, the host's own `base`/`utilities` layers register later and win, so the host's preflight and responsive utilities (`md:*`, `hover:*`) stay authoritative while library components still render correctly.
124
+
125
+ ### 2b. Font setup
126
+
127
+ opsfuse-ui does not bundle fonts. Wire up the host app's fonts to the `--font-sans` / `--font-mono` CSS variables.
128
+
129
+ **Next.js (recommended):**
130
+
131
+ ```tsx
132
+ // app/layout.tsx
133
+ import { Geist, Geist_Mono } from "next/font/google";
134
+
135
+ const geistSans = Geist({ subsets: ["latin"], variable: "--font-sans" });
136
+ const geistMono = Geist_Mono({ subsets: ["latin"], variable: "--font-mono" });
137
+
138
+ export default function RootLayout({
139
+ children,
140
+ }: {
141
+ children: React.ReactNode;
142
+ }) {
143
+ return (
144
+ <html lang="en" className={`${geistSans.variable} ${geistMono.variable}`}>
145
+ <body>{children}</body>
146
+ </html>
147
+ );
148
+ }
149
+ ```
150
+
151
+ **Vite / CRA** — add to the global CSS file:
152
+
153
+ ```css
154
+ /* index.css or globals.css */
155
+ @import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap");
156
+
157
+ :root {
158
+ --font-sans: "Inter", system-ui, sans-serif;
159
+ --font-mono: "Geist Mono", "Fira Code", monospace;
160
+ }
161
+ ```
162
+
163
+ If the project already has a font loaded, map it to `--font-sans` in the global CSS rather than adding a new font.
164
+
165
+ ### 2c. Tailwind v4 (if used)
166
+
167
+ If the host app uses Tailwind v4, point content at the built bundle so utility classes from the library resolve:
168
+
169
+ ```js
170
+ // tailwind.config.js or @source in your CSS
171
+ content: [
172
+ "./src/**/*.{js,ts,jsx,tsx}",
173
+ // npm / git dependency:
174
+ "./node_modules/opsfuse-ui/dist/index.js",
175
+ // git submodule at packages/ui:
176
+ "./packages/ui/dist/index.js",
177
+ ],
178
+ ```
179
+
180
+ Use the path that matches how opsfuse-ui was installed (only one of the library paths is needed).
181
+
182
+ ---
183
+
184
+ ## PHASE 3 — Theme Selection
185
+
186
+ **Ask the user:**
187
+
188
+ > Which brand theme would you like to use? Please pick one:
189
+ >
190
+ > 1. **RecruitSmartly** _(default)_ — Warm Minimal · Deep · Intelligent — Indigo primary
191
+ > 2. **SkillReady** — Warm · Confident · Growth-Oriented — Burnt Orange primary
192
+ > 3. **Verity** — Productive · Organized · Reliable — Emerald primary
193
+ > 4. **WorkLog** — Trustworthy · Precise · Authoritative — Cobalt primary
194
+
195
+ Map the choice to the `theme` prop value:
196
+
197
+ | Choice | `theme` prop | CSS class added |
198
+ | -------------- | ------------------ | -------------------------------------------- |
199
+ | RecruitSmartly | `"recruitsmartly"` | `brand-recruitsmartly` (uses indigo default) |
200
+ | SkillReady | `"skillready"` | `brand-skillready` |
201
+ | Verity | `"verity"` | `brand-verity` |
202
+ | WorkLog | `"worklog"` | `brand-worklog` |
203
+
204
+ Store the chosen value — you will need it in Phase 4.
205
+
206
+ ---
207
+
208
+ ## PHASE 4 — Provider Setup
209
+
210
+ ### 4a. Wrap the root with OpsfuseThemeProvider
211
+
212
+ Every component in opsfuse-ui requires a `.opsfuse-ui` ancestor class (provided by `OpsfuseThemeProvider`). Wrap the **entire app** once at the highest possible level.
213
+
214
+ **Next.js App Router** — wrap inside `app/layout.tsx`:
215
+
216
+ ```tsx
217
+ import { OpsfuseThemeProvider } from "opsfuse-ui";
218
+
219
+ export default function RootLayout({
220
+ children,
221
+ }: {
222
+ children: React.ReactNode;
223
+ }) {
224
+ return (
225
+ <html lang="en" className={`${geistSans.variable} ${geistMono.variable}`}>
226
+ <body>
227
+ <OpsfuseThemeProvider theme="skillready" className="min-h-svh">
228
+ {children}
229
+ </OpsfuseThemeProvider>
230
+ </body>
231
+ </html>
232
+ );
233
+ }
234
+ ```
235
+
236
+ **Vite / CRA** — wrap in `main.tsx` or `App.tsx`:
237
+
238
+ ```tsx
239
+ import { OpsfuseThemeProvider } from "opsfuse-ui";
240
+
241
+ createRoot(document.getElementById("root")!).render(
242
+ <StrictMode>
243
+ <OpsfuseThemeProvider theme="skillready" className="min-h-svh">
244
+ <App />
245
+ </OpsfuseThemeProvider>
246
+ </StrictMode>,
247
+ );
248
+ ```
249
+
250
+ ### 4b. Imperative APIs and tooltips
251
+
252
+ `OpsfuseThemeProvider` (and `OpsfuseRoot`) already mount `ConfirmationDialogProvider`, `TooltipProvider`, `AlertProvider`, `DialogProvider`, `SheetProvider`, `SliderDialogProvider`, and `Toaster`. Wrap the app once — you do not manually nest those providers in `main.tsx`.
253
+
254
+ **Imperative API reference:**
255
+ | What you call | Where it is provided |
256
+ |---------------|---------------------|
257
+ | `toast.success/error()` from "sonner" | `<Toaster />` inside `<OpsfuseThemeProvider />` |
258
+ | `showAlert({ title, description, variant })` | `<AlertProvider />` inside theme |
259
+ | `openDialog({ title, children })` | `<DialogProvider />` inside theme |
260
+ | `openSheet({ title, children, side })` | `<SheetProvider />` inside theme |
261
+ | `confirm({ title, description?, onConfirm?, ... })` | `<ConfirmationDialogProvider />` inside theme |
262
+ | `openSlider({ title, value, min, max, ... })` | `<SliderDialogProvider />` inside theme |
263
+ | Any `<Tooltip>` anywhere | `<TooltipProvider />` inside theme |
264
+
265
+ ---
266
+
267
+ ## PHASE 5 — Component Migration
268
+
269
+ Scan the codebase for existing UI and replace with opsfuse equivalents. Work file by file. Do **not** batch-replace blindly — read each file first, understand context, then migrate.
270
+
271
+ ### 5a. Component Replacement Map
272
+
273
+ | Existing pattern | opsfuse-ui replacement | Import |
274
+ | ----------------------------------------------- | ------------------------------------------------------------------- | ------------ |
275
+ | `<button>` / MUI `<Button>` / Chakra `<Button>` | `<Button variant="default">` | `opsfuse-ui` |
276
+ | `<input type="text">` / MUI `<TextField>` | `<Input label="..." />` | `opsfuse-ui` |
277
+ | `<select>` / MUI `<Select>` | `<Select>` + `<SelectTrigger>` + `<SelectContent>` + `<SelectItem>` | `opsfuse-ui` |
278
+ | `<textarea>` | `<Textarea />` | `opsfuse-ui` |
279
+ | `<label>` | `<Label htmlFor="...">` | `opsfuse-ui` |
280
+ | `<input type="checkbox">` | `<Checkbox />` | `opsfuse-ui` |
281
+ | `<input type="radio">` | `<RadioGroup>` + `<RadioGroupItem>` | `opsfuse-ui` |
282
+ | Toggle switch | `<Switch />` | `opsfuse-ui` |
283
+ | Card / Paper / Box | `<Card>` + `<CardHeader>` + `<CardContent>` | `opsfuse-ui` |
284
+ | Modal / Dialog | `<Dialog>` compound | `opsfuse-ui` |
285
+ | Destructive confirm | `confirm()` + `<ConfirmationDialogProvider />` (inside `OpsfuseThemeProvider`) | `opsfuse-ui` |
286
+ | Side panel / Drawer right | `<Sheet>` | `opsfuse-ui` |
287
+ | Bottom sheet / mobile drawer | `<Drawer>` | `opsfuse-ui` |
288
+ | Tabs | `<Tabs>` + `<TabsList>` + `<TabsTrigger>` + `<TabsContent>` | `opsfuse-ui` |
289
+ | Accordion / Collapse | `<Accordion>` compound | `opsfuse-ui` |
290
+ | Tooltip | `<Tooltip>` + `<TooltipTrigger>` + `<TooltipContent>` | `opsfuse-ui` |
291
+ | Popover / Floating panel | `<Popover>` compound | `opsfuse-ui` |
292
+ | Dropdown / Action menu | `<DropdownMenu>` compound | `opsfuse-ui` |
293
+ | Badge / Chip / Tag | `<Badge variant="default">` | `opsfuse-ui` |
294
+ | Alert / Banner | `<Alert>` + `<AlertTitle>` + `<AlertDescription>` | `opsfuse-ui` |
295
+ | Avatar / User icon | `<Avatar src={...} alt="..." fallback="AB" size="default" />` | `opsfuse-ui` |
296
+ | Skeleton / Loading placeholder | `<Skeleton />` | `opsfuse-ui` |
297
+ | Spinner / CircularProgress | `<Spinner />` | `opsfuse-ui` |
298
+ | Progress bar / LinearProgress | `<Progress value={n} />` | `opsfuse-ui` |
299
+ | Divider / `<hr>` | `<Separator />` | `opsfuse-ui` |
300
+ | ScrollArea | `<ScrollArea>` | `opsfuse-ui` |
301
+ | Data table / `<table>` | `<Table>` compound | `opsfuse-ui` |
302
+ | Breadcrumb nav | `<Breadcrumb>` compound | `opsfuse-ui` |
303
+ | Page title + breadcrumb + actions | `<PageHeader>` + optional `<Breadcrumb>` | `opsfuse-ui` |
304
+ | Pagination | `<Pagination>` compound | `opsfuse-ui` |
305
+ | Toast notification | `toast()` from `"sonner"` | `sonner` |
306
+ | Searchable dropdown | `<Combobox />` | `opsfuse-ui` |
307
+ | Command palette / ⌘K | `<Command>` compound | `opsfuse-ui` |
308
+ | Date picker | `<Calendar>` + `<Popover>` | `opsfuse-ui` |
309
+ | Sidebar layout | `<SidebarProvider>` + `<Sidebar>` compound | `opsfuse-ui` |
310
+ | Resizable panels | `<ResizablePanelGroup>` + `<ResizablePanel>` | `opsfuse-ui` |
311
+ | Recharts chart | `<ChartContainer>` + Recharts components | `opsfuse-ui` |
312
+ | Segmented button group | `<ButtonGroup>` | `opsfuse-ui` |
313
+ | Toggle / icon toggle | `<Toggle>` or `<ToggleGroup>` | `opsfuse-ui` |
314
+ | Form field with label+error | `<Field>` compound | `opsfuse-ui` |
315
+ | Input with prefix/suffix | `<InputGroup>` | `opsfuse-ui` |
316
+ | OTP input | `<InputOTP>` compound | `opsfuse-ui` |
317
+ | Keyboard shortcut | `<Kbd>` | `opsfuse-ui` |
318
+ | Empty state | `<Empty description="…" title="…" icon={…} actionLabel="…" onAction={…} />` (default import) | `opsfuse-ui` |
319
+
320
+ ### 5b. Button variant mapping
321
+
322
+ | Existing style | opsfuse-ui variant |
323
+ | ---------------------- | ----------------------- |
324
+ | Primary / filled / CTA | `variant="default"` |
325
+ | Secondary / outlined | `variant="outline"` |
326
+ | Tertiary / neutral | `variant="secondary"` |
327
+ | Ghost / icon button | `variant="ghost"` |
328
+ | Danger / delete | `variant="destructive"` |
329
+ | Text link button | `variant="link"` |
330
+
331
+ Button sizes: `size="default"` (36px) · `size="sm"` (32px) · `size="xs"` (28px) · `size="lg"` (40px) · `size="icon"` · `size="icon-sm"` · `size="icon-xs"`
332
+
333
+ ### 5c. Migration rules
334
+
335
+ 1. **Read before replacing** — always read the file before editing.
336
+ 2. **Preserve logic** — only change UI markup. Do not alter state, event handlers, data fetching, or business logic.
337
+ 3. **Map props faithfully** — `onClick`, `disabled`, `className` carry over. `variant`, `color`, `size` map per the tables above.
338
+ 4. **Icon-only buttons** — always add `aria-label`: `<Button size="icon" aria-label="Close"><XIcon /></Button>`
339
+ 5. **Form fields** — use `<Input label="Name" />` instead of separate `<Label>` + `<input>` unless you need finer control.
340
+ 6. **Destructive actions** — replace `window.confirm()` or simple confirm dialogs with `confirm({ title, description, onConfirm })` and the provider stack above; use `Button variant="destructive"` for the trigger where appropriate.
341
+ 7. **Remove old UI library imports** — after migrating a file, remove MUI/Chakra/shadcn imports that are no longer needed.
342
+
343
+ ### 5d. Lighter entrypoints (performance-sensitive apps)
344
+
345
+ For apps that don't use heavy components (charts, calendar, carousel, etc.), prefer the core entrypoint:
346
+
347
+ ```ts
348
+ import { Button, Badge, Input, Card, OpsfuseRoot } from "opsfuse-ui/core";
349
+ // Only import extended components where actually needed:
350
+ import { ChartContainer, Calendar } from "opsfuse-ui/extended";
351
+ ```
352
+
353
+ ---
354
+
355
+ ## PHASE 6 — Color & Token Migration
356
+
357
+ Replace all hardcoded colors, arbitrary Tailwind palette classes, and old theme variables with opsfuse design tokens.
358
+
359
+ ### 6a. Surface tokens (shadcn-aligned)
360
+
361
+ | Old pattern | opsfuse token |
362
+ | ------------------------------ | ----------------------------------- |
363
+ | `bg-white`, `bg-gray-50` | `bg-(--background)` (page canvas) |
364
+ | `bg-white` on cards | `bg-(--card)` |
365
+ | `bg-gray-100`, `bg-gray-200` | `bg-(--muted)` |
366
+ | `bg-gray-50` on hover rows | `bg-(--accent)` |
367
+ | `bg-white` on dropdowns/modals | `bg-(--popover)` |
368
+
369
+ ### 6b. Text tokens
370
+
371
+ | Old pattern | opsfuse token |
372
+ | -------------------------------- | ------------------------- |
373
+ | `text-gray-900`, `text-black` | `text-(--foreground)` |
374
+ | `text-gray-600`, `text-gray-700` | `text-(--subtle-foreground)` |
375
+ | `text-gray-400`, `text-gray-500` | `text-(--muted-foreground)` |
376
+ | `text-gray-300`, disabled text | `text-(--disabled-foreground)` |
377
+
378
+ ### 6c. Border tokens
379
+
380
+ | Old pattern | opsfuse token |
381
+ | ------------------------------------ | --------------------------- |
382
+ | `border-gray-100` | `border-(--border-subtle)` |
383
+ | `border-gray-200`, `border-gray-300` | `border-(--border)` |
384
+ | `border-gray-400` (active/hover) | `border-(--border-strong)` |
385
+
386
+ ### 6d. Primary / brand color tokens
387
+
388
+ | Old pattern | opsfuse token |
389
+ | ------------------------------ | --------------------------- |
390
+ | `bg-blue-600`, `bg-indigo-600` | `bg-(--primary)` |
391
+ | `text-white` on primary bg | `text-(--primary-foreground)` |
392
+ | `bg-blue-50` selected item bg | `bg-(--primary-muted)` |
393
+ | `border-blue-200` | `border-(--primary-border)` |
394
+ | `text-blue-700` on tinted bg | `text-(--primary-muted-foreground)` |
395
+
396
+ ### 6e. Semantic state tokens
397
+
398
+ | Old pattern | opsfuse token |
399
+ | -------------------------------- | ------------------------ |
400
+ | `text-green-600` / success icon | `text-(--success)` |
401
+ | `bg-green-50` success bg | `bg-(--success-muted)` |
402
+ | `text-yellow-600` / warning icon | `text-(--warning)` |
403
+ | `bg-yellow-50` warning bg | `bg-(--warning-muted)` |
404
+ | `text-red-600` / error icon | `text-(--destructive)` |
405
+ | `bg-red-50` error bg | `bg-(--destructive-muted)` |
406
+ | `text-blue-600` / info icon | `text-(--info)` |
407
+ | `bg-blue-50` info bg | `bg-(--info-muted)` |
408
+
409
+ ### 6f. Typography classes
410
+
411
+ Replace manual `text-xs text-gray-400` combos with semantic classes:
412
+
413
+ | Old pattern | opsfuse class |
414
+ | ----------------------------------------------- | ------------- |
415
+ | `text-sm text-gray-700 leading-relaxed` body | `.prose-ui` |
416
+ | `text-base text-gray-600 leading-loose` article | `.prose-body` |
417
+ | `text-xs text-gray-400` meta / timestamp | `.caption` |
418
+ | `text-xs uppercase tracking-wide` label | `.label-sm` |
419
+ | AI response text | `.prose-ai` |
420
+ | `font-mono text-sm` code/stats | `.prose-mono` |
421
+
422
+ ### 6g. Transition classes
423
+
424
+ | Old pattern | opsfuse class |
425
+ | ------------------------------------------ | -------------------- |
426
+ | `transition duration-150` on buttons/chips | `.transition-micro` |
427
+ | `transition duration-200` on inputs/panels | `.transition-smooth` |
428
+ | `transition duration-500` on bars/graphs | `.transition-data` |
429
+
430
+ ---
431
+
432
+ ## PHASE 7 — Dark Mode
433
+
434
+ If the app supports dark mode:
435
+
436
+ 1. Dark mode is triggered by adding `dark` class to the `<html>` element.
437
+ 2. All opsfuse tokens automatically switch to dark values when `html.dark` is present — no extra work needed per component.
438
+ 3. For custom elements, use `dark:` Tailwind prefix: `dark:bg-(--card)` (or `bg-card` when the theme maps it).
439
+ 4. Never hardcode hex colors in dark mode overrides — the tokens already handle it.
440
+
441
+ ---
442
+
443
+ ## PHASE 8 — Verification Checklist
444
+
445
+ After all phases are complete, verify:
446
+
447
+ - [ ] `import "opsfuse-ui/styles.css"` is the **first** import in the app entry
448
+ - [ ] `--font-sans` CSS variable is set (fonts load)
449
+ - [ ] `<OpsfuseThemeProvider theme="...">` wraps the entire app
450
+ - [ ] Chosen brand theme appears on `OpsfuseThemeProvider` and visually matches
451
+ - [ ] Tooltip and toast APIs work if you use them (`TooltipProvider` and `<Toaster />` are inside `OpsfuseThemeProvider`)
452
+ - [ ] No hardcoded hex colors remain in migrated files
453
+ - [ ] No `text-gray-*` or `bg-gray-*` Tailwind palette classes in migrated files
454
+ - [ ] Icon-only buttons all have `aria-label`
455
+ - [ ] Form fields pair inputs with labels
456
+ - [ ] Destructive actions use `confirm()` (works with `<OpsfuseThemeProvider />` / `<OpsfuseRoot />` — no duplicate confirmation provider)
457
+ - [ ] App renders correctly in both light and dark mode (if dark mode is supported)
458
+ - [ ] TypeScript compiles with no errors (`tsc --noEmit`)
459
+
460
+ ---
461
+
462
+ ## Quick Reference — All Four Brand Themes
463
+
464
+ ### 1. RecruitSmartly (default)
465
+
466
+ ```tsx
467
+ <OpsfuseThemeProvider theme="recruitsmartly">
468
+ ```
469
+
470
+ - Personality: Warm Minimal · Deep · Intelligent
471
+ - Primary: Indigo `oklch(0.56 0.19 278)`
472
+ - Surfaces: Cool indigo-tinted whites
473
+ - Best for: AI-powered recruitment, talent intelligence platforms
474
+
475
+ ### 2. SkillReady
476
+
477
+ ```tsx
478
+ <OpsfuseThemeProvider theme="skillready">
479
+ ```
480
+
481
+ - Personality: Warm · Confident · Growth-Oriented
482
+ - Primary: Burnt Orange `#c2561a`
483
+ - Surfaces: Warm earth-toned
484
+ - Best for: Learning platforms, skills assessment, career development
485
+
486
+ ### 3. Verity
487
+
488
+ ```tsx
489
+ <OpsfuseThemeProvider theme="verity">
490
+ ```
491
+
492
+ - Personality: Productive · Organized · Reliable
493
+ - Primary: Emerald `oklch(0.57 0.15 165)`
494
+ - Surfaces: Cool sage-green tinted
495
+ - Best for: Work management, activity logging, productivity tools
496
+
497
+ ### 4. WorkLog
498
+
499
+ ```tsx
500
+ <OpsfuseThemeProvider theme="worklog">
501
+ ```
502
+
503
+ - Personality: Trustworthy · Precise · Authoritative
504
+ - Primary: Cobalt `oklch(0.54 0.2 265)`
505
+ - Surfaces: Cool slate-blue tinted
506
+ - Best for: Compliance tools, verification platforms, precision dashboards
507
+
508
+ ---
509
+
510
+ ## Minimal Setup Snippet (copy-paste start)
511
+
512
+ ```tsx
513
+ // main.tsx or app/layout.tsx
514
+ import "opsfuse-ui/styles.css";
515
+ import { OpsfuseThemeProvider } from "opsfuse-ui";
516
+
517
+ export default function RootLayout({
518
+ children,
519
+ }: {
520
+ children: React.ReactNode;
521
+ }) {
522
+ return (
523
+ <html lang="en">
524
+ <body>
525
+ <OpsfuseThemeProvider theme="recruitsmartly" className="min-h-svh">
526
+ {children}
527
+ </OpsfuseThemeProvider>
528
+ </body>
529
+ </html>
530
+ );
531
+ }
532
+ ```
533
+
534
+ ---
535
+
536
+ ## Do / Don't
537
+
538
+ | ✅ Do | ❌ Don't |
539
+ | ----------------------------------------------------- | --------------------------------------------------- |
540
+ | Import `styles.css` first before any other CSS | Import styles after app CSS (token overrides break) |
541
+ | Wrap the entire app in `OpsfuseThemeProvider` once | Wrap individual components (tokens won't inherit) |
542
+ | Use `cn()` from `opsfuse-ui` for className merging | String-concatenate classNames |
543
+ | Use design tokens `var(--subtle-foreground)` | Use `text-gray-600` or `#6b7280` |
544
+ | Use `data-slot` on custom component parts | Skip `data-slot` on wrappers |
545
+ | Use `confirm()` before destructive actions | Use `window.confirm()` |
546
+ | Import icons from `lucide-react` | Import from other icon libraries |
547
+ | Use `<Field>` for form layout | Raw `div` + `label` + `input` |
548
+ | Test light AND dark mode after migration | Only check light mode |