@tap-payments/os-micro-frontend-shared 0.3.253 → 0.3.255

package/src/components/primitives/README.md

@@ -0,0 +1,507 @@
+# `primitives` — Tier 1 Contract
+
+The **smallest buildable UI blocks** in the library — leaf atoms that Tier 2 components and MFEs compose on top of. This file is the single source of truth for creating, modifying, naming, and styling a primitive. PRs that violate it fail `eslint-plugin-boundaries` or get caught in review.
+
+## Table of Contents
+
+1. [Purpose & philosophy](#1-purpose--philosophy)
+2. [How to import a primitive](#2-how-to-import-a-primitive)
+3. [The file contract](#3-the-file-contract)
+4. [How to create a new primitive](#4-how-to-create-a-new-primitive)
+5. [How to modify an existing primitive](#5-how-to-modify-an-existing-primitive)
+6. [Naming conventions](#6-naming-conventions)
+7. [Styling conventions](#7-styling-conventions) — includes [7.3 Required theme access](#73-required-theme-access), [7.3.1 V2 palette tokens](#731-v2-palette-tokens), [7.3.2 V2 elevation tokens](#732-v2-elevation-tokens), [7.3.3 V2 spacing tokens](#733-v2-spacing-tokens), [7.3.4 V2 radius tokens](#734-v2-radius-tokens), [7.3.5 V2 blur tokens](#735-v2-blur-tokens), [7.3.6 V2 typography tokens](#736-v2-typography-tokens), [7.3.7 Frozen hex](#737-frozen-hex-no-matching-v2-token)
+8. [Structural patterns](#8-structural-patterns)
+9. [Documented restyling exceptions](#9-documented-restyling-exceptions)
+10. [Dependency isolation & enforcement](#10-dependency-isolation--enforcement)
+11. [What does not belong in a primitive](#11-what-does-not-belong-in-a-primitive)
+12. [Reference — current primitives](#12-reference--current-primitives)
+13. [Storybook](#13-storybook)
+14. [PR checklist](#14-pr-checklist)
+
+---
+
+## 1. Purpose & philosophy
+
+A primitive is a **leaf atom**: the smallest component you can build anything on top of — one visual/interactive concept, no composition of other primitives, no domain knowledge, no shared hook modules, no data fetching.
+
+**Litmus test:** if you remove a piece and what remains is still a complete, usable UI atom on its own, that piece either stays (it's part of the same concept) or moves to Tier 2 (it's a second concept). If Tier 2 would have to reimplement behavior because the primitive bundled too much or imported a sibling, the boundary is wrong.
+
+Three properties every rule below protects:
+
+| Property               | Meaning                                                                                                   |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| **Predictable weight** | Importing a primitive never pulls in another primitive, a shared hook module, or domain logic.            |
+| **Always restyleable** | Consumers reshape it with `styled()` or `sx` — never fork it. See [7.1](#71-the-restyling-contract).      |
+| **Stable names**       | Twelve MFEs share these names. One convention beats a locally clever one. See [6](#6-naming-conventions). |
+
+This folder is **isolated** from other `src/components` composites. MFEs import it via `@components/primitives`; Tier 2 components compose these primitives later.
+
+**Legacy is discovery only.** `src/components` shows _which_ atoms to extract, not _how_ to structure them. Match legacy _behavior_; discard legacy _structure_ (`Wrapper`, `Styled*` prefixes, `Base` suffixes, bare boolean names).
+
+---
+
+## 2. How to import a primitive
+
+`primitives/index.ts` is the **only** public entry point for this folder. No per-primitive paths.
+
+```tsx
+import { Button, Input, Icon, buttonClassNames, type ButtonProps, type ButtonClassNames } from '@components/primitives'
+```
+
+| Import                                    | Allowed                                                           |
+| ----------------------------------------- | ----------------------------------------------------------------- |
+| `@components/primitives`                  | Yes — default export, types, and `{name}ClassNames`               |
+| `@components`                             | Yes — when the name is re-exported from `src/components/index.ts` |
+| `@components/primitives/Button`           | No — use the barrel; enforced by `no-restricted-imports`          |
+| `@components/primitives/Button/style`     | No — deep import                                                  |
+| `@components/primitives/Button/constants` | No — deep import                                                  |
+| `@components/primitives/Button/Button`    | No — bypasses public API                                          |
+| `@v2/components/primitives`               | No — this folder moved; use `@components/primitives`              |
+
+Barrel rules:
+
+- Each primitive's `index.ts`: `export { default }` + explicit `export type { … }` + `export { <name>ClassNames }` (internal wiring — consumers use the barrel only).
+- `primitives/index.ts`: explicit named re-exports only — **never `export *`**.
+
+---
+
+## 3. The file contract
+
+**Five required files per primitive** (+ optional `icons.tsx`).
+
+```
+primitives/Button/
+├── Button.tsx     # implementation
+├── constants.ts   # classNames, lookup maps, values imported from more than one file
+├── style.ts       # styled Parts only; imports maps from ./constants
+├── type.ts        # props + public types
+└── index.ts       # public API — export { buttonClassNames }
+```
+
+| File                          | Contains                                                                                                                        | Does NOT contain                             |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| **`constants.ts`**            | `<name>ClassNamePrefix`, `<name>ClassNames`, `<Primitive>ClassNames` type, lookup maps, values imported from more than one file | `styled()` components, React nodes           |
+| **`type.ts`**                 | Props and component-specific public types                                                                                       | const values, classNames                     |
+| **`style.ts`**                | `styled()` Parts/shells, `get<What>()` helpers importing from `./constants`                                                     | `as const` lookup tables                     |
+| **`<Name>.tsx`**              | Component logic, JSX, private handlers                                                                                          | lookup maps — those stay in `./constants`    |
+| **`icons.tsx`** (when needed) | Inline `<svg>` exports only                                                                                                     | components, hooks, styled parts, lookup maps |
+
+A named export in `constants.ts` must be **imported from more than one file**. A value imported by a single module is inlined there (with a freeze comment when it is a hex that has no v2 token — [7.3.7](#737-frozen-hex-no-matching-v2-token)). Repeated references inside that one file still count as a single import.
+
+| Forbidden                                    | Goes instead                                                  |
+| -------------------------------------------- | ------------------------------------------------------------- |
+| `hooks/`                                     | Tier 2 — or private logic inline in `.tsx`                    |
+| `utils.ts`                                   | Private function in `.tsx`, or global `utils/` if shared      |
+| lookup maps in `style.ts` / `.tsx`           | **`constants.ts`**                                            |
+| a `constants.ts` export imported by one file | inline the value in that file                                 |
+| sub-`components/`                            | Styled Parts in `style.ts`                                    |
+| `types.ts`                                   | `type.ts` — singular, always                                  |
+| story/test files                             | `.storybook/stories/components/primitives/<Name>.stories.tsx` |
+| inline `<svg>` in `.tsx`                     | **`icons.tsx`** on the owning primitive                       |
+| `@constants` icon URL maps / asset refs      | **`constants.ts`**                                            |
+
+**`icons.tsx` (SVG only):** when a primitive renders its own inline SVG markup, add `icons.tsx` (e.g. `Checkbox/icons.tsx`, `MenuItem/icons.tsx`). Export `<svg>` React nodes only — no lookup maps, no `@constants` URL maps, no styled Parts. Asset URL maps belong in **`constants.ts`**. **Internal only** — do not re-export from `primitives/index.ts`.
+
+**Promotion to Tier 2** when a folder needs any of: a dedicated hook/util file, composition of two concepts (field + helper text, input + form wiring), or imports from another primitive. Tier 2 lives outside this folder, same five required files plus optional `hooks/` and `utils.ts`. Tier 2 imports primitives via `@components/primitives` only.
+
+---
+
+## 4. How to create a new primitive
+
+1. **Discover** — find legacy usages; list what varies (sizes, variants, states). Ignore legacy structure.
+2. **Confirm scope** — one concept, no sibling primitive needed, no shared hook module, no domain meaning. Otherwise build Tier 2.
+3. **Scaffold** five files under `src/components/primitives/<Name>/` (+ optional `icons.tsx`).
+4. **`type.ts`** — extend a base type that carries `className` (HTML attributes or MUI props); declare `sx` explicitly; JSDoc non-obvious props.
+5. **`constants.ts`** — `<name>ClassNamePrefix`, `<name>ClassNames` (built from prefix + slot), lookup maps, and values imported from more than one file. Inline a value that is imported by only one module.
+6. **`style.ts`** — one bare `<Name>Styled` (interactive/`ref` target), optional shell/Parts; import maps from `./constants`. Tokens come from required `theme.v2` ([7.3](#73-required-theme-access)).
+7. **`<Name>.tsx`** — `forwardRef` + `memo`, wire slot classNames via `joinClassNames` from `@utils`, JSDoc with restyling note, `data-testid="<Name>"`.
+8. **`index.ts`** — default export + types from `./type` + `export { <name>ClassNames, type <Primitive>ClassNames }` from `./constants`.
+9. **Register** in `primitives/index.ts` (append, explicit named exports).
+10. **Storybook** — see [13](#13-storybook); include `{Name}Styled` and `{Name}StyledSlots`.
+11. **Verify** — `yarn lint && yarn build:types`.
+
+`Button/` is the reference implementation for all five files.
+
+---
+
+## 5. How to modify an existing primitive
+
+| Change            | Where                                                                                                                         |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| New prop          | `type.ts` (+ JSDoc); style-only props as `$`-prefixed transient props in `style.ts`                                           |
+| Visuals           | `style.ts` only — never inline `sx` in `.tsx` as the source of truth. Required theme access: [7.3](#73-required-theme-access) |
+| New variant/size  | Extend union in `type.ts`; add lookup-map entry in **`constants.ts`**; consume in `style.ts`                                  |
+| New slot / Part   | Add to `<name>ClassNames` in **`constants.ts`**; wire in `.tsx` via `joinClassNames`                                          |
+| Const value       | **`constants.ts` only** — never add consts to `style.ts` or `.tsx`                                                            |
+| Behavior          | Private handler/function in `.tsx`; if it outgrows the file → Tier 2                                                          |
+| Breaking change   | Update call sites, stories, [reference table](#12-reference--current-primitives), call out in PR — 12 MFEs consume this       |
+| Structural change | Re-verify restyling — shell changes move where `className`/`sx` land                                                          |
+
+---
+
+## 6. Naming conventions
+
+### Quick reference
+
+| What                       | Convention                                                                      | Example                                            |
+| -------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Folder / component file    | `PascalCase`, match exactly                                                     | `Button/` · `Button.tsx`                           |
+| Props file                 | `type.ts` — never `types.ts`                                                    | `type.ts`                                          |
+| Constants file             | `constants.ts` — all const values + slot classNames                             | `constants.ts`                                     |
+| Slot classNames object     | `<name>ClassNames` — camelCase, `as const`                                      | `buttonClassNames`                                 |
+| Slot className prefix      | `<name>ClassNamePrefix` in **`constants.ts`** — `os-shared-<Primitive>`         | `buttonClassNamePrefix`                            |
+| Slot className string      | `` `${prefix}-<slot>` `` — never repeat the prefix per slot                     | `` `${buttonClassNamePrefix}-startIcon` ``         |
+| Slot classNames type       | `<Primitive>ClassNames` in **`constants.ts`** — `(typeof xClassNames)[keyof …]` | `ButtonClassNames` in `constants.ts`               |
+| Lookup map in constants    | `camelCase` `as const` — e.g. `sizeStyles`, `variantStyles`                     | `sizeStyles` in `Button/constants.ts`              |
+| Class composition          | `joinClassNames(...)` from `@utils`                                             | `joinClassNames(buttonClassNames.root, className)` |
+| Props interface            | `<Name>Props`                                                                   | `ButtonProps`                                      |
+| Public sub-type            | `<Name><Concept>`                                                               | `ButtonVariant`, `InputSize`                       |
+| Story file                 | `<Name>.stories.tsx` under `.storybook/stories/components/primitives/`          | `Button.stories.tsx`                               |
+| Component name             | `PascalCase`, no `Base` suffix                                                  | `Input` not `InputBase`                            |
+| Boolean prop               | `is` / `has` / `can` / `should` — unless native HTML or established MUI prop    | `isLoading`; inherited `disabled`, `fullWidth`     |
+| Event prop / handler       | `on` / `handle`                                                                 | `onChange` · `handleKeyDown`                       |
+| Interactive styled element | `<Name>Styled` — bare, one per primitive, `ref` target                          | `ButtonStyled`                                     |
+| Outer shell                | `<Name><Purpose>Styled` — gets `className`/`sx` when rendered                   | `CheckboxLabelStyled`, `InputFieldStyled`          |
+| Inner Part                 | `<Name><Role>Styled` — no consumer `className`/`sx`/`ref`                       | `ChipTextStyled`, `ProgressBarFillStyled`          |
+| Style transient prop       | `$` prefix + `shouldForwardProp`                                                | `$variant`, `$size`                                |
+| Style lookup / helper      | `get<What>()` in `style.ts` · lookup maps in **`constants.ts`**                 | `getFieldHeight` · `sizeStyles`                    |
+| Value sets                 | string union or `as const` object — never TS `enum`                             | `'sm' \| 'md'`                                     |
+
+### Styled-export decision rule
+
+1. Interactive/measurable DOM node? → bare `<Name>Styled`.
+2. Outer shell grouping the interactive node with something else? → `<Name><Purpose>Styled`.
+3. Everything else → Part: `<Name><Role>Styled`.
+
+### Banned
+
+- `Styled<Name>` prefix · `<Name>Component` · `<Name>Root` · bare `Wrapper`/`Container`
+- Trailing `export { X }` re-exports in `style.ts` — use `export const`
+- `export *` in any `index.ts`
+- Plain MUI `Box`/`span` with inline `sx` in `.tsx` need no `Styled` name (e.g. Button loading overlay)
+
+Prefer full words (`Button`, not `Btn`). Callback props describe events (`onSave`), not instructions (`save`). Internal-only props use `@internal` JSDoc, not `_` prefixes.
+
+---
+
+## 7. Styling conventions
+
+MUI + Emotion. Reusable styles in `style.ts` via `styled()`; one-off overrides via `sx`.
+
+### 7.1 The restyling contract
+
+Every primitive must work with all three:
+
+```typescript
+const Compact = styled(Button)({ height: 24, padding: '0 8px' })
+```
+
+```tsx
+<Button sx={{ marginTop: 1 }} />
+```
+
+```tsx
+import { buttonClassNames, Button } from '@components/primitives'
+
+const ButtonStyled = styled(Button)({
+  [`& .${buttonClassNames.startIcon}`]: { marginRight: 4 },
+})
+```
+
+Requirements:
+
+1. Props type includes `className` (HTML or MUI base type).
+2. Explicit `sx?: SxProps<Theme>`, forwarded to the correct node.
+3. `forwardRef` on the interactive/measurable node — bare `<Name>Styled` — unless listed in [9](#9-documented-restyling-exceptions).
+4. Never destructure away `className` and drop it.
+5. **With a shell:** `className`/`sx` → shell (perceived box); `ref` → bare `<Name>Styled`.
+6. **Slot classNames:** every rendered DOM node gets its slot class from `<name>ClassNames` in `constants.ts`. Root/shell merges with consumer `className` via `joinClassNames(slotClass, className)`.
+
+Verify in Storybook:
+
+- `styled(YourPrimitive)({ border: '2px solid red' })` — border on perceived root ([13](#13-storybook)).
+- `styled(YourPrimitive)({ [\`& .\${classNames.slot}\`]: { … } })` — targets inner Part.
+
+### 7.2 `styled()` vs `sx` vs inline `style`
+
+| Tool         | Use for                                                                     |
+| ------------ | --------------------------------------------------------------------------- |
+| `styled()`   | Reusable variant styles in `style.ts`                                       |
+| `sx`         | Per-instance / consumer overrides — every primitive accepts and forwards it |
+| `style={{}}` | **Never** — bypasses theme, breaks CSP nonces, wins specificity over `sx`   |
+
+### 7.3 Required theme access
+
+Primitives depend on the **custom app theme** created by `appTheme` in `src/theme`. The MUI module augmentation declares `v2: ThemeV2` on both `Theme` and `ThemeOptions`, and `appTheme` always mounts the complete v2 token set. Read `theme.v2` directly. Tests, Storybook, and any other primitive renderer must provide `appTheme`. If a required design token is missing, add it to the v2 theme contract before consuming it.
+
+### 7.3.1 V2 palette tokens
+
+V2 colors live on `theme.v2.palette` (mounted by `appTheme`), not `theme.palette`. `theme.palette.foreground` is a type error. Non-primitive code must not import `@v2/theme` (enforced by `no-restricted-imports`).
+
+Destructure the slot once at the top of the `styled()` callback — do not sprinkle `theme.v2.palette…` through `style.ts`.
+
+Prefer the **original color scales** (`base`, `grey`, `brand`, `success`, `error`, `warning`) over semantic aliases that point at the same hex (`foreground`, `background`, `border`, `interactive`, `status`). Use a semantic group only when no scale key matches. `brand` lives at `palette.brand`, not under `interactive`.
+
+```ts
+export const ButtonStyled = styled(ButtonBase)(({ theme }) => {
+  const { base, grey, brand } = theme.v2.palette
+  return {
+    color: grey[500],
+    backgroundColor: base.white,
+    border: `1px solid ${grey[100]}`,
+    // brand[500], not interactive.primary.default or foreground.brand
+    '&:hover': { color: brand[500] },
+  }
+})
+```
+
+### 7.3.2 V2 elevation tokens
+
+V2 shadows live on the required `theme.v2.elevation` slot, not `theme.shadows`. Keys and CSS values live in `src/theme/_v2/elevation.ts`. The v2 slot is built in `src/theme/_v2/theme.ts` and mounted by `appTheme`.
+
+```ts
+boxShadow: theme.v2.elevation[300],
+```
+
+### 7.3.3 V2 spacing tokens
+
+V2 spacing lives on the required `theme.v2.spacing` slot, not `theme.spacing`. The function is pixel-in, pixel-out (`src/theme/_v2/utils.ts`): `spacing(8)` returns `'8px'`. It is **not** MUI's 8px multiplier — `theme.v2.spacing(1)` is `1px`, not `8px`.
+
+Call the function directly at the use site. Do not extract a `(factor) => \`${factor}px\`` stand-in.
+
+```ts
+export const ButtonStyled = styled(ButtonBase)(({ theme }) => ({
+  gap: theme.v2.spacing(8),
+  padding: `${theme.v2.spacing(8)} ${theme.v2.spacing(18)}`,
+}))
+```
+
+### 7.3.4 V2 radius tokens
+
+V2 radii live on the required `theme.v2.radius` slot, not `theme.shape.borderRadius`. Same pixel-in, pixel-out helper as spacing: `radius(4)` returns `'4px'`. Call it directly at the use site.
+
+```ts
+export const ButtonStyled = styled(ButtonBase)(({ theme }) => ({
+  borderRadius: theme.v2.radius(4),
+}))
+```
+
+Leave `borderRadius: '50%'` and other non-pixel radii as-is — `radius()` only produces `px` strings.
+
+### 7.3.5 V2 blur tokens
+
+V2 blur lives on the required `theme.v2.blur` slot as an object (same shape as elevation), not a pixel-in function. Keys and CSS values live in `src/theme/_v2/blur.ts`. Values are CSS `filter` / `backdrop-filter` strings. The v2 slot is built in `src/theme/_v2/theme.ts` and mounted by `appTheme`. Do not invent keys outside that map.
+
+```ts
+backdropFilter: theme.v2.blur[12],
+```
+
+### 7.3.6 V2 typography tokens
+
+V2 type lives on the required `theme.v2.typography` slot, not `theme.typography`. Families, weights, and the Tap DS type scale (Heading–Micro) live in `src/theme/_v2/typography.ts`. Each role is a CSS style object (`fontFamily`, `fontSize`, `lineHeight`, `fontWeight`, `letterSpacing`). Spread a role at the use site, or pass its path to the Typography primitive as `textVariant`. The primitive resolves text variants and named `weight` values against the active `theme.v2.typography`; an omitted or invalid `textVariant` uses `body.default.regular`. MUI's `variant` defaults to `subtitle2`. Do not invent roles or weights the scale does not define.
+
+```ts
+<Typography textVariant="body.large.semibold" />
+<Typography textVariant="body.large.semibold" weight="bold" sx={{ fontSize: 18 }} />
+
+export const LabelStyled = styled('span')(({ theme }) => ({
+  ...theme.v2.typography.textVariants.body.default.medium,
+  color: theme.v2.palette.grey[900],
+}))
+```
+
+Standalone weight: `theme.v2.typography.fontWeightBold` (600). Do not use legacy `theme.typography`.
+
+### 7.3.7 Frozen hex (no matching v2 token)
+
+Same-hex v1 colours map to `theme.v2.palette` scale tokens (`base`, `grey`, `brand`, `success`, `error`, `warning`). When a spec hex has **no equal** v2 scale value, freeze the literal — do not keep the v1 theme key, and do not pick a nearby token as a silent substitute.
+
+If the hex is **imported from more than one file**, name it in `constants.ts` and comment the source plus why it is not a v2 token. Exception by explicit decision: `FieldFeedback` feedback colours resolve from v2 scale tokens (`error[500]`, `warning[500]`, `success[700]`, `brand[500]`) instead of frozen hexes.
+
+If the hex is imported by **one file only**, leave it at the call site with the same comment — even when that file references it more than once:
+
+```ts
+// Off-track grey — no equal v2 scale hex (`grey[200]` is `#E4E6E9`).
+backgroundColor: '#D9D9D9',
+```
+
+If Figma already names a missing scale step the primitive needs, add that token to the v2 theme contract ([7.3](#73-required-theme-access)) instead of freezing.
+
+### 7.4–7.7 Other rules
+
+- **`$` props** — style-only, filtered via `shouldForwardProp` (see `ChipStyled` in `Chip/style.ts`).
+- **Theme tokens** — primitives use `theme.v2.palette` / `theme.v2.typography` / `theme.v2.spacing` / `theme.v2.radius` / `theme.v2.elevation` / `theme.v2.blur`; otherwise `theme.breakpoints` over raw `@media`. See [7.3](#73-required-theme-access).
+- **`style.ts` contents** — styled Parts and `get<What>()` helpers only. Import lookup maps from `./constants`. No lookup tables, and no named constants that are imported by only one file. No MUI `name`/`slot` or slot-class maps. No business logic.
+- **Variants** — lookup object in **`constants.ts`**, not `if`/`else` chains. Responsive via `theme.breakpoints.*` in `style.ts`.
+- **Icons / decorative affordances** — no inline `<svg>` in `<Name>.tsx`. Put inline SVG in `icons.tsx` ([3](#3-the-file-contract)). Asset URLs and icon src maps go in **`constants.ts`**. For a standalone icon atom, use the **`Icon`** primitive (`src` + `alt`). Do not import `Icon` from another primitive — rebuild a local Part instead.
+
+---
+
+## 8. Structural patterns
+
+Three shapes cover every primitive:
+
+**Simple leaf** — `className`/`sx`/`ref` on one node:
+
+`Button`, `Icon`, `Switch`, `Skeleton`, `Avatar`, `Divider`, `Collapse`, `Badge`, `Slider`, `CopyButton`, `Typography`, `RadioButton`, `Backdrop`, `ProgressBar`, `Chip`, `Accordion`, `Dialog`, `MenuItem`, `ToggleButtons`, `LazyImage`, `FieldFeedback`, `ScrollLoader`.
+
+**Shell + interactive** — `className`/`sx` on shell, `ref` on inner node:
+
+`Checkbox`, `CircularProgress`, `Input`, `Textarea`, `Menu` (see [9](#9-documented-restyling-exceptions) for `Input` / `Textarea` / `Menu` `ref`).
+
+**Inner Parts** — styled pieces with no public restyling surface:
+
+`ProgressBarFillStyled`, `ChipTextStyled`, `ChipCopyButtonStyled`, `MenuItemIndicatorSlotStyled`, `ToggleButtonsButtonStyled`, `FieldFeedbackMessageStyled`, `FieldFeedbackIconStyled`, `CircularProgressLabelTextStyled`, etc.
+
+Add a shell only when the interactive node cannot carry the perceived bounding box (label beside checkbox, border around field chrome).
+
+---
+
+## 9. Documented restyling exceptions
+
+Intentional deviations from [7.1](#71-the-restyling-contract). Do not "fix" without updating this table and the component JSDoc.
+
+| Primitive                      | Exception                                                                            | Why                                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `Tooltip`                      | No `forwardRef`; `className`/`sx` → popper bubble                                    | MUI clones child and owns positioning — no owned interactive node                        |
+| `Checkbox`, `CircularProgress` | With label shell: `ref` on bare `<Name>Styled`; `className`/`sx` on shell            | Shell is perceived box; inner node stays interactive                                     |
+| `Input`                        | `ref` → native `<input>` via `inputRef`; `className`/`sx` → `InputFieldStyled`       | MUI `Input` root is a `<div>` — ref there breaks `.focus()` / form libs                  |
+| `Textarea`                     | `ref` → native `<textarea>` via `inputRef`; `className`/`sx` → `TextareaFieldStyled` | Same MUI `InputBase` root issue as `Input`                                               |
+| `Menu`                         | `ref` / `className` → `MenuStyled` (Popper); `sx` → `MenuPanelStyled`                | `className` lands on Popper with the `popper` slot; panel chrome via `sx` / `panelProps` |
+| `LazyImage`                    | `ref` → `<img>`; `className`/`sx` → lazy-load wrapper                                | Library owns the wrapper node — restyle the perceived box, ref the image                 |
+
+---
+
+## 10. Dependency isolation & enforcement
+
+```mermaid
+flowchart LR
+  tier2["Tier 2 components"] --> primitives
+  primitives --> foundation["shared utils, constants, theme, MUI"]
+```
+
+| From                      | May import                                                              | May not import                                                                                   |
+| ------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `components/primitives/*` | `@utils`, `@constants`, global `src/types`, `@v2/theme`, MUI, `./icons` | another primitive's component/`index.ts`/other files; Tier 2; shared hook module (`src/hooks/*`) |
+
+**React hooks inside a primitive are fine** (`useState`, `useEffect`). The ban is on importing **shared hook modules** that carry app/domain state.
+
+**No primitive imports another primitive** — not via `index.ts`, not wrapped in `styled()`. When two primitives share an affordance (e.g. `Chip` copy icon vs `CopyButton`), each owns local asset refs in **`constants.ts`** + a local styled Part, promote pure logic to `@utils`, or compose both in Tier 2.
+
+Enforced by `eslint-plugin-boundaries` and `no-restricted-imports` in [`eslint.config.js`](../../../eslint.config.js):
+
+- Files classified by path (`primitive` before `component` — first match wins).
+- Primitives may only depend on `type` / `util` / `constant` elements (plus same-folder `./style`, `./type`).
+- Tier 2 `component` elements may import primitives via their `index.ts`.
+- Naming and styling rules are review-only — see [14](#14-pr-checklist).
+
+---
+
+## 11. What does not belong in a primitive
+
+Promote to Tier 2 (outside `src/components/primitives/`) instead:
+
+| Does not belong                     | Example                                                                            |
+| ----------------------------------- | ---------------------------------------------------------------------------------- |
+| Helper / error / hint **text**      | `Input` has `error` boolean (border only); message text is Tier 2                  |
+| Form-library wiring                 | `react-hook-form` `Controller` → `RHF*` Tier 2 component                           |
+| Domain formatting / validation      | Currency, IBAN, merchant lookups                                                   |
+| Data fetching / shared domain hooks | API calls, global store                                                            |
+| Two independent concepts composed   | Field + helper + clear button                                                      |
+| Import of another primitive         | Rebuild locally or compose in Tier 2 ([10](#10-dependency-isolation--enforcement)) |
+| Auto-generated `id`                 | Caller passes `id` for label/`aria-*` wiring                                       |
+| Outer layout margins                | Consumers position with `sx`                                                       |
+
+**Known boundary — `Input` floating label:** the optional `label` prop renders floating-label chrome (`FormControl` shell) inside the primitive today. The agreed direction is to shrink `Input` to the bare bordered field and move floating-label layout to Tier 2 when that component is built. Until then, document any change here and in the reference table.
+
+---
+
+## 12. Reference — current primitives
+
+28 primitives exported from [`index.ts`](./index.ts).
+
+| Primitive          | Interactive (`ref`)        | Shell                         | Parts / inline                                                                                 | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ------------------ | -------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Button`           | `ButtonStyled`             | —                             | `content`, `startIcon`, `endIcon`, `loading`, `loadingSpinner`                                 | `constants.ts`; export `buttonClassNames`; `$variant`, `$size`, `$fullWidth`, `$isLoading`                                                                                                                                                                                                                                                                                                                                                                                         |
+| `Icon`             | `IconStyled`               | —                             | —                                                                                              | `constants.ts`; `root`; single `<img>`                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `Checkbox`         | `CheckboxStyled`           | `CheckboxLabelStyled`         | `control`, `label`                                                                             | `constants.ts`; `root` (label shell), `control`, `label`; `icons.tsx`                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `Switch`           | `SwitchStyled`             | —                             | —                                                                                              | `constants.ts`; `root`; MUI `Switch`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `Typography`       | `TypographyStyled`         | —                             | —                                                                                              | `constants.ts`; `root`; `$textVariant`, `$weight`; MUI `variant` defaults to `subtitle2`; MUI `noWrap` for single-line ellipsis; omitted/invalid `textVariant` → `body.default.regular`                                                                                                                                                                                                                                                                                            |
+| `RadioButton`      | `RadioButtonStyled`        | —                             | —                                                                                              | `constants.ts`; `root`; `icons.tsx`                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `CircularProgress` | `CircularProgressStyled`   | `CircularProgressLabelStyled` | `progress`, `labelOverlay`, `labelText`                                                        | `constants.ts`; `root`, `progress`, `labelOverlay`, `labelText`; `hasLabel` when determinate                                                                                                                                                                                                                                                                                                                                                                                       |
+| `Tooltip`          | —                          | —                             | `popper`, `tooltip`, `arrow`, `content`, `title`, `supportingText`, `wrapper`                  | `constants.ts`; optional `supportingText`; `className` → popper ([9](#9-documented-restyling-exceptions))                                                                                                                                                                                                                                                                                                                                                                          |
+| `Skeleton`         | `SkeletonStyled`           | —                             | —                                                                                              | `constants.ts`; `root`; defaults `rounded` / `16`                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `Avatar`           | `AvatarStyled`             | —                             | —                                                                                              | `constants.ts`; `root`; `avatarSizeConfig`; `$size`; `$color`; always circular                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `Divider`          | `DividerStyled`            | —                             | —                                                                                              | `constants.ts`; `root`; `$type` (`default` Gray/100, `subtle` `border.subtle`); 1px; default `horizontal`                                                                                                                                                                                                                                                                                                                                                                          |
+| `Collapse`         | `CollapseStyled`           | —                             | —                                                                                              | `constants.ts`; `root`; defaults `unmountOnExit` / `300` ms                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `Badge`            | `BadgeStyled`              | —                             | —                                                                                              | `constants.ts`; `root`; `$color` (legacy colours + Figma `active` / `inactive` / `highlight`); `$compact` / `$round` / `$pointer`; Micro/Bold; Space/2×Space/4; Radius/48                                                                                                                                                                                                                                                                                                          |
+| `Backdrop`         | `BackdropStyled`           | —                             | portal in `.tsx`                                                                               | `constants.ts`; `root`; `invisible` default `true` (popover/dropdown click-catcher, no fill/no blur, `zIndex` 999); `invisible={false}` → `#000` at 30% + `hasBlur` → `theme.v2.blur[6]`, `zIndex` 1; `open` optional (default `true`) + `onClose`                                                                                                                                                                                                                                 |
+| `CopyButton`       | `CopyButtonStyled`         | —                             | —                                                                                              | `constants.ts`; `root`; default `feedbackMs` 2000; `$copied`                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `ProgressBar`      | `ProgressBarStyled`        | —                             | `fill`, `text`                                                                                 | `constants.ts`; `root`, `fill`, `text`; `$value`, `$isDecimal`                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `Chip`             | `ChipStyled`               | —                             | `text`, `copyButton`, `icon`                                                                   | `constants.ts`; `chipVariantStyles`; own copy Part — not `CopyButton` ([10](#10-dependency-isolation--enforcement))                                                                                                                                                                                                                                                                                                                                                                |
+| `Slider`           | `SliderStyled`             | —                             | —                                                                                              | `constants.ts`; `root`; `onChange: (value: number) => void`                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `Input`            | native `<input>`           | `InputFieldStyled`            | `label`, `input`, `loadingIcon`, `validatedIcon`                                               | `constants.ts`; `root`, `label`, `input`, `loadingIcon`, `validatedIcon`; `inputFieldHeights`, Safari/number guards; `required` asterisk via MUI, `loading` needs label, `validated` works with/without label (`disabled` > `loading` > `validated`); `disableFocusRing` kills normal focus ring, `Mui-error`/`Mui-warning` rings always apply, error wins ties; `inputStateClasses` merged into `inputClassNames` (slots + states, separated by comment), selected via `:where()` |
+| `Textarea`         | native `<textarea>`        | `TextareaFieldStyled`         | `label`, `textarea`                                                                            | `constants.ts`; `root`, `label`, `textarea`; static in-field label (no shrink); labelled min-height 96; Space/32 top + Space/8 sides; `required` asterisk                                                                                                                                                                                                                                                                                                                          |
+| `Accordion`        | `AccordionStyled`          | —                             | `summary`, `content`, `labelStartAdornment`, `labelContent`, `labelEndAdornment`, `expandIcon` | `constants.ts`; `icons.tsx`; optional `expanded`/`onChange` (controlled) or `defaultExpanded` (uncontrolled); chevron separate from label adornments                                                                                                                                                                                                                                                                                                                               |
+| `Menu`             | `MenuStyled`               | `MenuPanelStyled`             | `popper`, `panel`                                                                              | `constants.ts`; `popper`, `panel`; scroll-shadow after 12 items; see §9                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `Dialog`           | `DialogStyled`             | —                             | `title`, `divider`, `content`, `actions`                                                       | `constants.ts`; `root`, `title`, `divider`, `content`, `actions`; heading draws a local divider Part — not `Divider` ([10](#10-dependency-isolation--enforcement)); paper 394px unless `fullWidth`                                                                                                                                                                                                                                                                                 |
+| `MenuItem`         | `MenuItemStyled`           | —                             | `indicator`, `content`, `disabled`                                                             | `constants.ts`; `menuItemIndicatorVariants`; `icons.tsx`; `startAdornment` overrides indicator                                                                                                                                                                                                                                                                                                                                                                                     |
+| `ToggleButtons`    | `ToggleButtonsStyled`      | —                             | `button`                                                                                       | `constants.ts`; `root`, `button`; `$isActive`; `$type` (`text` / `icon`); `$size` (`md` 32px / `sm` 24px); Elevation/100                                                                                                                                                                                                                                                                                                                                                           |
+| `LazyImage`        | native `<img>` via library | —                             | `root` (wrapper)                                                                               | `constants.ts`; `lazyImageEffectAssets`                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `FieldFeedback`    | `FieldFeedbackStyled`      | —                             | `icon`, `message`                                                                              | `constants.ts`; `style.ts` `getFieldFeedbackColors` (v2 tokens `error[500]`, `warning[500]`, `success[700]`, `brand[500]`); `$feedbackType`                                                                                                                                                                                                                                                                                                                                        |
+| `ScrollLoader`     | `ScrollLoaderStyled`       | —                             | —                                                                                              | `constants.ts`; `root`; near-bottom offset 50; `loadMoreItems` + pagination props                                                                                                                                                                                                                                                                                                                                                                                                  |
+
+---
+
+## 13. Storybook
+
+Path: `.storybook/stories/components/primitives/<Name>.stories.tsx`
+
+```tsx
+import { Avatar } from '@components/primitives'
+
+const meta: Meta<typeof Avatar> = {
+  title: 'Primitives/Avatar',
+  component: Avatar,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded', controls: { expanded: true } },
+}
+```
+
+Required stories:
+
+- **`Default`** — driven by `args`
+- **Variant/size matrix** — use `Story*` helpers from `@storybook-utils`
+- **`{Name}Styled`** — `const ButtonStyled = styled(Button)({ border: '2px solid red' })` proof on the perceived root
+- **`{Name}StyledSlots`** — `const ButtonStyledSlots = styled(Button)({ [\`& .\${buttonClassNames.startIcon}\`]: { … } })` proof
+- **Meaningful states** — disabled, error, loading, indeterminate, etc.
+
+---
+
+## 14. PR checklist
+
+**Structure**
+
+- [ ] One concept, no shared hook module, no domain logic — otherwise Tier 2
+- [ ] Five files (`constants.ts` required); optional `icons.tsx`; no `hooks/`, `utils.ts`, sub-`components/`
+- [ ] Lookup maps and values imported from more than one file live in `constants.ts`; a value imported by one file is inlined there
+- [ ] `<name>ClassNames` exported from `index.ts` + barrel
+- [ ] Registered in [`index.ts`](./index.ts) with explicit exports (no `export *`)
+- [ ] Zero imports from another primitive folder
+- [ ] Consumers import via `@components/primitives` or `@components` (no per-primitive paths, no `@v2/components/primitives`)
+
+**Naming & styling**
+
+- [ ] Names match [6](#6-naming-conventions) — `PascalCase`, `<Name>Props`, `$` transient props, `os-shared-*` slot classes
+- [ ] Slot classNames wired on every DOM node; root uses `joinClassNames`
+- [ ] `ref` / `className` / `sx` routed correctly; red-border `styled()` test passes
+- [ ] No inline `style={{}}`; theme tokens where available; lookup maps in `constants.ts`
+- [ ] Tokens come from required `theme.v2` slots ([7.3](#73-required-theme-access)). Palette: `theme.v2.palette` ([7.3.1](#731-v2-palette-tokens)). Typography: `theme.v2.typography` ([7.3.6](#736-v2-typography-tokens)). Spacing: `theme.v2.spacing(n)` — `n` is pixels, not MUI units ([7.3.3](#733-v2-spacing-tokens)). Radius: `theme.v2.radius(n)` ([7.3.4](#734-v2-radius-tokens)). Blur: `theme.v2.blur[n]` ([7.3.5](#735-v2-blur-tokens))
+- [ ] No MUI `name`/`slot` or slot-class maps
+
+**Verification**
+
+- [ ] Storybook updated (`Default`, `{Name}Styled`, `{Name}StyledSlots`, states)
+- [ ] [Reference table](#12-reference--current-primitives) updated if roles changed
+- [ ] `yarn lint && yarn build:types` pass