Zipstack · hari-kuriakose · Jul 26, 2026 · Jul 26, 2026 · Jul 26, 2026 · Jul 26, 2026
diff --git a/.gitignore b/.gitignore
@@ -40,6 +40,9 @@ eggs/
 .eggs/
 lib/
 lib64/
+# The Python `lib/` rule above also matches the frontend's shadcn/ui helper
+# directory (`@/lib/utils` per components.json). Keep that tracked.
+!frontend/src/lib/
 parts/
 sdist/
 var/

diff --git a/frontend/biome.json b/frontend/biome.json
@@ -4,6 +4,11 @@
   "files": {
     "ignoreUnknown": false
   },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  },
   "formatter": {
     "enabled": true,
     "indentStyle": "space",

diff --git a/frontend/bun.lock b/frontend/bun.lock
diff --git a/frontend/bun.lockb b/frontend/bun.lockb
diff --git a/frontend/components.json b/frontend/components.json
@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": false,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}
diff --git a/frontend/docs/P0-FOUNDATION.md b/frontend/docs/P0-FOUNDATION.md
@@ -0,0 +1,102 @@
+# P0 — shadcn/ui Foundation
+
+Implements **P0-01 … P0-16** of `UN_SHADCN_IMPL_PLAN.md`
+(spec: `UN_SHADCN_SPEC.md`, palette decision **D8** = Midnight Bloom).
+
+**Zero visual change is the goal of this phase.** antd still renders every
+screen; this PR only installs the shadcn stack alongside it (§7 coexistence).
+
+---
+
+## What landed
+
+| Task | Change |
+|---|---|
+| P0-03/04 | shadcn stack + Radix + RHF/zod + self-hosted `@fontsource` Inter / Geist Mono |
+| P0-05 | `components.json` (`style: new-york`, `tsx: false`, lucide) |
+| P0-06 | `tailwind.config.js`, `postcss.config.js` |
+| P0-07 | `@tailwindcss/vite` added **after** `optionalPluginImports()` |
+| P0-08 | `src/lib/utils.js` — `cn()` |
+| P0-09 | Legacy CSS vars → `--legacy-*` (D6) |
+| P0-10/11/12 | `src/index.css`: Tailwind first, Midnight Bloom tokens, `@theme inline` |
+| P0-13 | 32 primitives in `src/components/ui/` |
+| P0-14 | `vitest.config.mjs`: `@` alias + `css: false` |
+| P0-15 | `next-themes` `ThemeProvider` driven by the existing session theme |
+| P0-16 | `sonner` `<Toaster />` + shared `useAppToast` helper |
+
+## Gate results
+
+| Gate | Result |
+|---|---|
+| **P0-G1** build w/o plugins | **PASS** — `src/plugins/` is absent in an OSS checkout by design (copy overlay, gitignored), so every build here exercises the `optionalPluginImports` path |
+| **P0-G3** dark mode | **PASS** — see below |
+| **P0-G4** lint | **PASS** (see "Pre-existing" note) |
+| **P0-G5** tests | **PASS** — 4 files / 16 tests green |
+| **P0-G6** no visual regression | **PASS** — see below |
+
+### P0-G3 — `@theme inline` verified
+
+Measured in headless Chromium by toggling `.dark` on `<html>`:
+
+| | light | dark |
+|---|---|---|
+| `--background` | `#fafafa` | `#1a1a1a` |
+| `--foreground` | `#1a1a1a` | `#fafafa` |
+| **`bg-background` utility** | `rgb(250,250,250)` | `rgb(26,26,26)` |
+| **`text-foreground` utility** | `rgb(26,26,26)` | `rgb(250,250,250)` |
+
+The last two rows are the ones that matter: the **Tailwind utilities** flip, not
+just the CSS variables. A plain `@theme` would have frozen them at the light
+value — this is the trap called out in §2.5.3a.
+
+`--primary` is `#6f5cef` in both modes (correct — Midnight Bloom keeps the
+brand violet constant across themes).
+
+### P0-G6 — no visual regression
+
+Same page measured before and after P0:
+
+| Metric | Before | After |
+|---|---|---|
+| antd elements | 33 | 33 |
+| antd buttons | 5 | 5 |
+| button height | 50px | 50px |
+| button background | `rgb(47,147,246)` | `rgb(47,147,246)` |
+| button radius | 6px | 6px |
+| body background | `rgb(233,233,233)` | `rgb(233,233,233)` |
+| body font | system | **Inter** |
+
+Only the font changed — that is P0-12's intended effect. Tailwind Preflight does
+not disturb antd, consistent with the coexistence test in §7.
+
+---
+
+## Notes for review
+
+**Two deviations from the plan, both necessary and neither changing intent:**
+
+1. **`jsconfig.json` added** (not in the plan). The shadcn CLI refuses to run
+   without it: *"Failed to load jsconfig.json. Couldn't find tsconfig.json"*. It
+   declares the same `@/*` → `./src/*` alias that `vite.config.js` already has,
+   so it also fixes editor/IDE resolution.
+
+2. **`biome.json` — `css.parser.tailwindDirectives: true`** (not in the plan).
+   Without it Biome cannot parse `@theme` / `@plugin` / `@custom-variant` and
+   **fails CI with 4 CSS parse errors**. This is a required companion to
+   adopting Tailwind v4; the plan's P0-G4 gate missed it.
+
+**Pre-existing lint findings (NOT introduced here):** `biome ci src/` reports 4
+errors and 26 warnings. All 4 errors are in `src/assets/export-tool.svg` and
+`src/assets/login-onboard-message.svg`; both files are byte-identical to `main`,
+and running the same Biome binary against a pristine `main` checkout reproduces
+them. The 26 warnings (`noEmptyBlockStatements`, `useBlockStatements`) are in
+files this PR never touched.
+
+**Deferred deliberately:**
+- `body { overflow: hidden }` is left as-is. It interacts with Radix's
+  scroll-lock; P0-12 says re-test at the first P2 dialog conversion.
+- `ALERT_SURFACE = "antd"` in `App.jsx` keeps antd as the single notification
+  surface. The sonner bridge is mounted and wired but dormant, so alerts are not
+  double-rendered. P2-06 flips the constant and deletes the antd branch.
+
+**Not started:** P1–P4 and the cloud plugin phase, per the 🛑 STOP gate after P0.
diff --git a/frontend/docs/form-pattern.md b/frontend/docs/form-pattern.md
@@ -0,0 +1,98 @@
+# Form conversion pattern (P3-01)
+
+The reviewed pattern that P3-02 applies to the remaining call-sites.
+
+## The problem
+
+antd's `Form` bundles validation, layout and state into one component, and this
+codebase drives it **imperatively** through a form instance:
+
+```jsx
+const [form] = Form.useForm();
+form.setFieldsValue({ name: group?.name });          // populate on edit
+const values = await form.validateFields().catch(() => null);
+if (!values) return;                                  // bail out when invalid
+form.resetFields();
+```
+
+14 `useForm()` sites and 102 `Form.Item`s depend on that API. Rewriting each by
+hand onto raw react-hook-form would mean 102 independent chances to change
+submit or validation behaviour — and one wrong `.catch()` silently lets an
+invalid form submit.
+
+## The pattern: keep antd's API, swap the engine
+
+`@/components/ui/antd-form` implements antd's `Form` surface on top of
+react-hook-form. Call-sites convert **by import only**:
+
+```diff
+-import { Form, Input } from "antd";
++import { Form } from "@/components/ui/antd-form";
++import { Input } from "@/components/ui/input";
+```
+
+The JSX is untouched:
+
+```jsx
+<Form form={form} layout="vertical">
+  <Form.Item
+    label="Name"
+    name="name"
+    rules={[{ required: true, message: "Group name is required" }]}
+  >
+    <Input maxLength={255} />
+  </Form.Item>
+</Form>
+```
+
+## What the shim guarantees
+
+| antd API | Behaviour preserved |
+|---|---|
+| `Form.useForm()` | Returns `[form]` with the imperative methods below |
+| `form.setFieldsValue(obj)` | Populates fields — edit-mode modals depend on this |
+| `form.getFieldsValue()` / `getFieldValue(n)` | Reads current values |
+| `form.validateFields()` | **Rejects** when invalid, resolves with values when valid |
+| `form.resetFields()` | Clears back to empty |
+| `<Form.Item rules>` | `required`, `min`, `max`, `pattern`, and custom `validator` |
+| `<Form.Item>` without `name` | Renders as plain layout |
+| `onFinish` | Fires only when validation passes |
+
+**The rejection semantics are the load-bearing part.** Call-sites are written as
+`await form.validateFields().catch(() => null)` and bail on `null`. If
+`validateFields` resolved on invalid input instead of rejecting, every one of
+those guards would silently pass and submit bad data. Two unit tests pin this:
+one asserts the rejection, one asserts `onFinish` does not fire while a required
+field is empty.
+
+## Rules translation
+
+antd rule objects map onto RHF options:
+
+| antd | RHF |
+|---|---|
+| `{ required: true, message }` | `required: message` |
+| `{ max: n, message }` | `maxLength: { value: n, message }` |
+| `{ min: n, message }` | `minLength: { value: n, message }` |
+| `{ pattern: re, message }` | `pattern: { value: re, message }` |
+| `{ validator: async fn }` | `validate: { customN: … }` — a thrown error's message becomes the inline message |
+
+## Controlled-child injection
+
+`Form.Item` clones its single child and injects `value`/`onChange`/`onBlur`,
+which is how antd wires inputs too. `valuePropName="checked"` is honoured for
+`Checkbox`/`Switch`. The child's own `onChange` still fires, so call-sites that
+react to changes keep working.
+
+## Reference conversion
+
+`src/components/groups/GroupCreateEditModal.jsx` — a small modal exercising
+`setFieldsValue` (edit mode), `validateFields().catch()` (submit guard),
+`resetFields()` (cancel), and a `required` rule. Converted with an import change
+only.
+
+## When NOT to use the shim
+
+New forms should use `react-hook-form` + `@/components/ui/form` directly. The
+`antd-form` module exists to carry the existing 102 call-sites across without
+behaviour drift, and should not grow new antd-only props.
-Original file line number
+Diff line change
@@ Expand Up / @@ -40,6 +40,9 @@ eggs/ @@
     .eggs/
     lib/
     lib64/
+    # The Python `lib/` rule above also matches the frontend's shadcn/ui helper
+    # directory (`@/lib/utils` per components.json). Keep that tracked.
+    !frontend/src/lib/
     parts/
     sdist/
     var/
@@ Expand Down @@