From 6e836d42f85fce12f5ee7de5ba2bf2e5b63e1ad2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89mile=20R=C3=A9?= <emile@getprobo.com>
Date: Mon, 6 Apr 2026 17:41:03 +0400
Subject: [PATCH] Add UI rules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Émile Ré <emile@getprobo.com>
---
 AGENTS.md            |   1 +
 contrib/claude/ui.md | 259 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 260 insertions(+)
 create mode 100644 contrib/claude/ui.md

diff --git a/AGENTS.md b/AGENTS.md
index 1e575a234..8a61343bc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,6 +38,7 @@ Detailed guides for specific subsystems live in `contrib/claude/`:
 - [`contrib/claude/license.md`](contrib/claude/license.md) — ISC license header (all file types)
 - [`contrib/claude/mcp.md`](contrib/claude/mcp.md) — MCP API patterns (specification.yaml, mcpgen, resolvers, type helpers)
 - [`contrib/claude/relay.md`](contrib/claude/relay.md) — Frontend Relay client (queries, fragments, mutations, pagination)
+- [`contrib/claude/ui.md`](contrib/claude/ui.md) — `@probo/ui`, Tailwind, tailwind-variants, folders, skeletons, compound components
 - [`contrib/claude/release.md`](contrib/claude/release.md) — Release process (version bump, changelog, tag, push)
 - [`contrib/claude/sandbox.md`](contrib/claude/sandbox.md) — Lima sandbox environments (create, manage, access services)
 - [`contrib/claude/validation.md`](contrib/claude/validation.md) — Validation framework (fluent API, validators, error codes, propagation)
diff --git a/contrib/claude/ui.md b/contrib/claude/ui.md
new file mode 100644
index 000000000..eba63d62d
--- /dev/null
+++ b/contrib/claude/ui.md
@@ -0,0 +1,259 @@
+# UI system (`@probo/ui`)
+
+Shared React UI for Probo apps lives in the **`@probo/ui`** workspace package ([`packages/ui`](../../packages/ui)). This document describes **target** conventions for building and styling those components.
+
+**Today’s codebase does not fully match these rules.** The tree still uses layouts like `Atoms/`, `Molecules/`, and `Layouts/`, and many files mix ad-hoc Tailwind on `className` with `tailwind-variants`. Treat this guide as the direction for new work and refactors, not as a description of the current tree.
+
+For data loading and GraphQL on the console, see [`contrib/claude/relay.md`](relay.md).
+
+## Package and tooling
+
+| Item | Convention |
+|------|------------|
+| Package | **`@probo/ui`** — import shared components from this package in apps. |
+| Styling | **Tailwind** (project uses Tailwind v4 in `packages/ui`). |
+| Variants API | **`tailwind-variants`** — `import { tv } from "tailwind-variants"` to define component styles and slot class names. |
+
+Preview components with Storybook from `packages/ui`: `npm run dev` (Storybook on port 6006 per `package.json`).
+
+## `tailwind-variants` and `className`
+
+In a **single component file**, do **not** mix arbitrary Tailwind utility strings on `className` with `tailwind-variants` for the same styling concerns. Put layout and look in **`tv` variants and `slots`** (and the APIs `tv` exposes for overrides). If consumers need extensibility, expose it through variant props or documented slot/class hooks—not by sprinkling raw utilities beside `tv()` output in the same file.
+
+For **compound / multi-slot** components, define `tv` in a **dedicated module** (see [Variants file](#variants-file)) so loading-only code paths can import styles without pulling the full interactive implementation.
+
+### Do / don’t: `tv` vs raw `className`
+
+```tsx
+// Bad — same file mixes tv() output with ad-hoc Tailwind on className (clsx shown for the anti-pattern)
+import { clsx } from "clsx";
+import { tv } from "tailwind-variants";
+
+const row = tv({ base: "flex items-center gap-2" });
+export function Row({ children }: { children: React.ReactNode }) {
+  return <div className={clsx(row(), "rounded-md border border-border-low")}>{children}</div>;
+}
+```
+
+```tsx
+// Good — layout and look live in tv
+import { tv } from "tailwind-variants";
+
+const row = tv({
+  base: "flex items-center gap-2 rounded-md border border-border-low",
+});
+export function Row({ children }: { children: React.ReactNode }) {
+  return <div className={row()}>{children}</div>;
+}
+```
+
+```tsx
+// Good — optional styling toggles use tv variants, not extra className strings in this file
+import { tv } from "tailwind-variants";
+
+const row = tv({
+  base: "flex items-center gap-2",
+  variants: {
+    bordered: { true: "rounded-md border border-border-low", false: "" },
+  },
+  defaultVariants: { bordered: true },
+});
+export function Row(props: { bordered?: boolean; children: React.ReactNode }) {
+  return <div className={row({ bordered: props.bordered })}>{props.children}</div>;
+}
+```
+
+## Folder layout
+
+**Simple and layout primitives** belong in **usage-oriented** folders:
+
+- `typography/`
+- `form/`
+- `layouts/`
+
+**Other components** live in a folder **named after the component** (e.g. `ImageCard/`), with optional split files for subparts.
+
+### Do / don’t: folder placement
+
+```text
+// Good — target layout (usage folders for primitives, component folder for composites)
+packages/ui/src/
+  media/Image.tsx
+  media/ImageSkeleton.tsx
+  typography/Text.tsx
+  typography/TextSkeleton.tsx
+  form/Field.tsx
+  layouts/CenteredLayout.tsx
+  ImageCard/variants.ts
+  ImageCard/ImageCard.tsx
+  ImageCard/ImageCardSkeleton.tsx
+
+// Bad — ad-hoc placement for a simple primitive (should live under typography / form / layouts)
+packages/ui/src/RandomFolder/Text.tsx
+```
+
+## Skeletons
+
+For each meaningful component, provide a paired loading UI:
+
+- Naming: **`ComponentName`** and **`ComponentNameSkeleton`** (e.g. `Text` / `TextSkeleton`).
+
+A partial precedent today: [`CenteredLayoutSkeleton`](../../packages/ui/src/Layouts/CenteredLayout.tsx) alongside the layout component.
+
+### Do / don’t: skeleton naming
+
+```tsx
+// Good — paired names
+export function Text(props: TextProps) { /* … */ }
+export function TextSkeleton() { /* … */ }
+
+// Bad — unrelated name or missing pair
+export function Text(props: TextProps) { /* … */ }
+export function LoadingText() { /* … */ } // use TextSkeleton instead
+```
+
+## Compound modules (e.g. `ImageCard`)
+
+Multi-region UI (card shell, media, text column, etc.) is exported as a **compound module** with static properties on one object.
+
+### Folder and exports
+
+- One directory per feature component (e.g. `ImageCard/`). Heavy logic may live in **separate files**; the public surface remains **`ImageCard`** with attached properties.
+- **`ImageCard`** — the compound module (named/default export as established in the package).
+- **`ImageCard.Root`** — top-level container **when it may hold business logic** (state, effects, data wiring, etc.).
+- **`ImageCard.Shell`** — **pure layout shell**: takes **`image`** and **`text`** (and other region) **props**—each a `ReactNode`—and places them in the matching **`tv` slots**. **No children** for layout regions on `Shell`; **no state or logic** in `Shell`. If the outer wrapper is layout-only, expose it as **`Shell`**, not **`Root`**.
+- **`Image`** and **`Text`** — **shared primitives** from **`@probo/ui`** (e.g. typography / media folders), not namespaced under **`ImageCard`**. **`Root`** composes them into **`Shell`**’s **`image`** / **`text`** props; apps import the same **`Image`** / **`Text`** everywhere.
+
+**`Root` vs `Shell`:** use **`Root`** when the container owns logic; use **`Shell`** for a presentational outer frame. **`Root` may render `Shell`** inside when logic sits outside the styled layout.
+
+### `tailwind-variants` slots
+
+For this pattern, model regions with **`tv` `slots`** named consistently with the layout—for the example above:
+
+- `shell`
+- `image`
+- `text`
+
+Add or rename slots when the layout has more or different regions. **`Shell`** applies the matching slot output on its wrappers; **`Image`** / **`Text`** stay free of **`ImageCard`**-specific layout—keep the [no-mixing rule](#tailwind-variants-and-classname) in each file.
+
+### Do / don’t: compound API and slots
+
+`variants.ts` holds `tv`; **`Shell`** applies slot class names on its wrapping tags only (no duplicate Tailwind strings for those regions in the same file).
+
+```ts
+// ImageCard/variants.ts — Good
+import { tv } from "tailwind-variants";
+
+export const imageCard = tv({
+  slots: {
+    shell: "flex gap-4 rounded-lg border border-border-low p-4",
+    image: "shrink-0 overflow-hidden rounded-md",
+    text: "min-w-0 flex-1 flex flex-col gap-1",
+  },
+});
+```
+
+`Shell` calls **`imageCard()`** (or **`imageCard({ … })`** when the layout has variants), destructures **`shell`**, **`image`**, and **`text`**, and mounts each slot’s class name on a **wrapper element** around the prop node. **`Image`** and **`Text`** supply semantics and styling for media and copy; **`Shell`** only owns the **card layout slot wrappers**.
+
+```tsx
+// ImageCard/ImageCardShell.tsx — Good — slot class names on wrapping tags
+import { imageCard } from "./variants";
+
+export function ImageCardShell(props: { image: React.ReactNode; text: React.ReactNode }) {
+  const { shell, image, text } = imageCard();
+  return (
+    <div className={shell()}>
+      <div className={image()}>{props.image}</div>
+      <div className={text()}>{props.text}</div>
+    </div>
+  );
+}
+```
+
+```tsx
+// ImageCard/ImageCard.tsx — Good — Root owns logic; Shell receives region nodes as props
+import { Image, Text } from "@probo/ui";
+
+function ImageCardRoot(props: { image: React.ReactNode; text: React.ReactNode }) {
+  const id = useId();
+  // state, effects, data wiring …
+  return (
+    <ImageCard.Shell
+      image={<Image>{props.image}</Image>}
+      text={<Text>{props.text}</Text>}
+    />
+  );
+}
+
+// Bad — Shell takes regions as children instead of image / text props
+// <ImageCard.Shell>
+//   <Image>…</Image>
+//   <Text>…</Text>
+// </ImageCard.Shell>
+
+// Bad — data hooks or state live on Shell
+function ImageCardShellWithData(props: { image: React.ReactNode; text: React.ReactNode }) {
+  const data = useQuery(/* … */); // move to Root (or above)
+  return (
+    <div>
+      {props.image}
+      {props.text}
+    </div>
+  );
+}
+```
+
+(The snippets above are illustrative; names and props should match the real component.)
+
+## Skeleton placement and composition
+
+For compound components, the **card-level skeleton is not nested** on the module as `ImageCard.Skeleton`. Export **`ImageCardSkeleton`** as a **separate top-level symbol** (e.g. `ImageCardSkeleton.tsx` or the folder barrel) so routes can depend on **loading UI + shell layout** without importing the full `ImageCard` graph—smaller initial bundles for skeleton-first views. That also avoids pulling in **Radix UI** and other dependencies that are **not needed at load time** for the skeleton-only path.
+
+**Implementation:** `ImageCardSkeleton` should **reuse the same layout as the real card** by rendering **`ImageCard.Shell`** with the same **`image` / `text` props** as **`ImageCard.Root`**, but passing **skeleton primitives** instead of **`Image`** / **`Text`**:
+
+- **`image`** → **`ImageSkeleton`**
+- **`text`** → **`TextSkeleton`**
+
+`Root` composes real content with **`Image`** and **`Text`** (same imports as elsewhere in the app). The skeleton passes **`ImageSkeleton`** and **`TextSkeleton`** directly into **`Shell`** so loading views avoid **`Image`** / **`Text`** when that keeps bundles or behavior simpler.
+
+Reuse existing **`ImageSkeleton`** / **`TextSkeleton`** from typography or media primitives when available; avoid duplicate one-off pulse blocks.
+
+### Do / don’t: skeleton imports and composition
+
+```tsx
+// Bad — skeleton nested on the compound object (pulls full card module into the route)
+import { ImageCard } from "@probo/ui";
+<ImageCard.Skeleton />
+
+// Good — top-level skeleton export; reuse Shell + ImageSkeleton / TextSkeleton
+import { ImageCard, ImageCardSkeleton } from "@probo/ui";
+
+// Inside ImageCardSkeleton.tsx (conceptually):
+export function ImageCardSkeleton() {
+  return (
+    <ImageCard.Shell
+      image={<ImageSkeleton />}
+      text={<TextSkeleton />}
+    />
+  );
+}
+```
+
+The important part is **separate `ImageCardSkeleton` export**, **one `Shell` API** (`image` / `text` props), **shared shell layout**, and **reused `ImageSkeleton` / `TextSkeleton`**.
+
+## Variants file
+
+Keep the **`tv({ slots: { … } })` definition** (and derived slot functions) in a **standalone file**, conventionally **`variants.ts`** next to the component folder. Import it from **`Shell`** and **skeleton** modules so skeleton entry points can pull **variants + shell** without the rest of the compound module’s business logic.
+
+### Do / don’t: colocating `tv` with the heavy module
+
+```tsx
+// Bad — variants defined only inside ImageCard.tsx; ImageCardSkeleton imports ImageCard and drags Root / hooks
+// ImageCard.tsx
+const imageCard = tv({ slots: { shell: "...", image: "...", text: "..." } });
+
+// Good — shared variants module imported by Shell and ImageCardSkeleton only
+// variants.ts — export imageCard (or slot helpers)
+// ImageCardShell.tsx — import { imageCard } from "./variants"
+// ImageCardSkeleton.tsx — import { imageCard } from "./variants"
+```