@scalepad/ui 0.1.0

package/.ai/rules/date-handling.md

@@ -0,0 +1,39 @@
+<!-- Auto-generated from apps/lm-web/.ai/rules/ at publish time. Do not edit here; edit the canonical source. -->
+
+> **Applies to:** any consumer of `@scalepad/ui`. Originally authored inside the ScalePad lm-web app; lm-web-specific app architecture rules (architecture, mutations, data-fetching, error-handling, routing, sort-types, testing, feature-conventions) are deliberately not shipped.
+
+
+# Date Handling
+
+Never call `new Date()` directly in feature or shared code. Use helpers from `@scalepad/ui-utils/date`:
+
+| Situation | Use | Import |
+|---|---|---|
+| Non-nullable DTO date string (`created_at`, `updated_at`, `enrolled_at`) | `toDate(dto.field)` | `@scalepad/ui-utils/date` |
+| Nullable DTO date string | `parseApiDate(dto.field)` | `@/shared/utils` |
+| Current wall-clock time | `getCurrentDate()` | `@scalepad/ui-utils/date` |
+| Date string → formatted display | `formatDate(toDate(str), DateFormat.X)` | `@scalepad/ui-utils/date` |
+
+```ts
+// ✅ Correct
+import { toDate, getCurrentDate, formatDate, DateFormat } from '@scalepad/ui-utils/date';
+import { parseApiDate } from '@/shared/utils';
+
+createdAt: toDate(dto.created_at),           // non-nullable DTO field
+lastSeenAt: parseApiDate(dto.last_seen_at),  // nullable DTO field
+const now = getCurrentDate();                // wall-clock time
+formatDate(toDate(str), DateFormat.MONTH_SHORT) // formatted display
+
+// ❌ Wrong
+createdAt: new Date(dto.created_at),
+const now = new Date(),
+d.toLocaleString('en-US', { month: 'short' })
+```
+
+**Why:** `toDate` and `getCurrentDate` are mockable in tests; bare `new Date()` calls are not. `parseApiDate` centralises the nullable-string guard. `formatDate` + `DateFormat` keeps display formatting consistent with the design system.
+
+**Exceptions** — `new Date()` is acceptable in:
+- `src/mocks/` — test fixture and seed data
+- Runtime type-guard coercions for external/unknown inputs (e.g. `x instanceof Date ? x : new Date(x)`)
+- `packages/utils/src/date/` — the helpers themselves
+- Storybook stories and test files

package/.ai/rules/figma-design-system.md

@@ -0,0 +1,372 @@
+<!-- Auto-generated from .cursor/rules/ at publish time. Do not edit here; edit the canonical source. -->
+
+> **Path-context note:** Paths in this rule that begin with `src/frontend/ClientApps/packages/ui/src/...` refer to the ScalePad UI source tree as authored. In your consumer project, that source lives at `node_modules/@scalepad/ui/src/...`. Treat the two paths as interchangeable when you're reading examples.
+
+
+# LM Design System — Figma Mockup Rules
+
+These rules are MANDATORY for every Figma-related task: building or updating mockups, screens, modals, drawers, or panels in Figma; reading a Figma frame to implement in code; or writing Code Connect mappings. They override generic Figma-MCP guidance whenever there is conflict. If a rule cannot be satisfied (e.g. the design system genuinely lacks a primitive), STOP and tell the user — do not silently substitute a hardcoded value.
+
+## 1. Canonical Design System
+
+**The ONLY design system to draw from is the `LM Design System` library.**
+
+| Field | Value |
+|---|---|
+| File name | `LM Design System` |
+| Figma file URL | `https://www.figma.com/design/VCLfybgU3OaUUPrQdBaVmP/LM-Design-System` |
+| `fileKey` | `VCLfybgU3OaUUPrQdBaVmP` |
+| Library key | `lk-5ca1dcd26f40f0d14e872ac95ebdb56292e1c16c64d9157f837dc2ae6441e3d4a025a1dbcaadcb677883d963c16f12bdaefe8caf762f8b9f9c10f6dbf68d2c8e` |
+| Library short name (in MCP) | `LM Design System` |
+| Variable collections | `Tokens` (colors, spacing, radius), `typography` (paragraph spacing), `border radii` (raw absolute) |
+
+**IMPORTANT — library precedence (when `search_design_system` returns duplicates):**
+
+1. Always pick `LM Design System` (`lk-5ca1...2c8e`).
+2. NEVER use `Basic Design System` (`lk-60d6...dafb`) — it is the upstream parent. `LM Design System` overrides and re-exports everything you need.
+3. NEVER use `ControlMap Library` (`lk-d7e3...f23c`), `Simple Design System`, `Material 3 Design Kit`, `iOS / iPadOS / watchOS / visionOS` libraries — they are different products or stale.
+
+When `search_design_system` returns the same asset name under both `LM Design System` and `Basic Design System`, ALWAYS use the `LM Design System` entry — not the first result.
+
+## 2. Sample Mockup For Pattern Reference
+
+When you need a reference for "what good looks like" assembled from this library:
+
+- File: `LM-Vision`, `fileKey` `AE4ZLZoEgdJList3S4eJ7q`
+- Sample frame node id: `5228:40665`
+
+Use it via `get_design_context` to inspect spacing, component variants, and token bindings BEFORE composing a new mockup. Match its conventions. If it disagrees with these rules, these rules win.
+
+## 3. Mandatory Pre-Flight Before Any Figma Write
+
+A persistent cache of LM Design System keys lives in [`figma-lm-design-system-keys.mdc`](mdc:.cursor/rules/figma-lm-design-system-keys.mdc) — read it BEFORE running any `search_design_system` query. Most components, variables, text styles, and effect styles you need are already cached there with the canonical role-based recipes from §6 / §7 / §8 below.
+
+Before the FIRST `use_figma` mutation in a task that produces a mockup:
+
+1. **Read `figma-lm-design-system-keys.mdc`** and pick keys by role.
+2. **For anything missing from the cache**, run `search_design_system` (with `fileKey` set to the target file), then **add the resolved key back into `figma-lm-design-system-keys.mdc` in the same change.** When `search_design_system` returns matches from multiple libraries, pick the row whose `libraryKey` starts with `lk-5ca1dcd2...` (LM Design System) per §1 precedence.
+3. **Open the LM Vision reference frame** (`5787:30996` foundation list-page, `5555:14` UC11 share-modal chrome, `5680:13` UC15 drawer chrome, `5722:13` UC22 public branded chrome) via `get_design_context` to confirm visual conventions for the surface you're building.
+4. Only AFTER cached keys are loaded, write the wrapper frame, then build sections one `use_figma` call at a time.
+
+If a needed token/component/style is genuinely missing from `LM Design System` (verified by both the cache AND a follow-up `search_design_system`), STOP and ask the user — do NOT fall back to `Basic Design System`, `ControlMap Library`, hex codes, or raw pixel values.
+
+Always pass `skillNames: "figma-generate-design"` (or the actual skill stack you loaded, e.g. `"figma-use,figma-generate-design"`) to `use_figma` for logging.
+
+## 4. Spacing — Strict Token-Only
+
+**Figma `LM Design System` spacing tokens (collection `Tokens`, scope `GAP`, ALL of these and ONLY these):**
+
+| Figma variable name | Approx px | When to use |
+|---|---:|---|
+| `Spacing/spacing-none` | 0 | Eliminate gap, flush layout |
+| `Spacing/spacing-xxs` | 4 | Icon ↔ adjacent label, dense badge interior |
+| `Spacing/spacing-xs` | 8 | Tight inline groups, compact button padding |
+| `Spacing/spacing-sm` | 12 | Default field-row gap, card content-to-content |
+| `Spacing/spacing-md` | 16 | Section padding interior, card padding |
+| `Spacing/spacing-lg` | 20 | Section ↔ section in a card or panel |
+| `Spacing/spacing-xl` | 24 | Page section padding |
+| `Spacing/spacing-xxl` | 32 | Major page-level gaps, column gutter |
+
+Bind via `figma.variables.importVariableByKeyAsync(key)` then `frame.setBoundVariable("itemSpacing"|"paddingTop"|"paddingBottom"|"paddingLeft"|"paddingRight", spacingVar)`.
+
+**FORBIDDEN spacing patterns:**
+
+- Setting `itemSpacing`, `paddingLeft`, `paddingRight`, `paddingTop`, `paddingBottom`, `paddingVertical`, or `paddingHorizontal` to a numeric literal (e.g. `frame.itemSpacing = 12`). ALWAYS bind to a variable.
+- Using a variable from `Basic Design System` even when it has the same name.
+- Using the `border radii` or `typography` collections for layout spacing — those scopes are wrong.
+- "Eyeballing" gaps that fall between tokens. Round to the nearest valid token. The token ladder is intentionally coarse to enforce rhythm.
+
+**Reading the LM-Vision reference (`5228:40665`):** if you see a gap that does not match one of the eight tokens, you are reading the wrong number — re-inspect with `get_design_context` and use the bound variable, not the resolved px value.
+
+**Code-side spacing (when implementing in `apps/lm-web/`):** the `@scalepad/ui` props mostly mirror the Figma names but differ at the extremes:
+
+| Figma token | `@scalepad/ui` Mantine prop value |
+|---|---|
+| `Spacing/spacing-none` | `"0"` (or omit) |
+| `Spacing/spacing-xxs` | `"2xs"` (4px) |
+| `Spacing/spacing-xs` | `"xs"` (8px) |
+| `Spacing/spacing-sm` | `"sm"` (12px) |
+| `Spacing/spacing-md` | `"md"` (16px) |
+| `Spacing/spacing-lg` | `"lg"` (20px) |
+| `Spacing/spacing-xl` | `"xl"` (24px) |
+| `Spacing/spacing-xxl` | `"2xl"` (32px) |
+
+The codebase exposes additional `3xs` (2 px), `3xl` (40 px), `4xl` (48 px), `5xl` (64 px) values that DO NOT exist in Figma. When porting from a Figma frame, you must NOT use those — if a code mockup needs them, the design must be updated in Figma first. When generating a mockup from code that uses them, round to the nearest Figma token and call out the rounding to the user.
+
+## 5. Radius — Strict Token-Only
+
+Use only these variables from collection `Tokens` (scope `CORNER_RADIUS`):
+
+| Figma variable name | Approx px | Use |
+|---|---:|---|
+| `Radius/radius-none` | 0 | Hard edges (table cells, full-bleed) |
+| `Radius/radius-xs` | 2 | Tiny tags, small chips |
+| `Radius/radius-sm` | 4 | Inputs, dense controls |
+| `Radius/radius-md` | 6 | Default for buttons, badges |
+| `Radius/radius-lg` | 8 | Cards, popovers, modals interior |
+| `Radius/radius-xl` | 12 | Large surfaces, prominent cards |
+| `Radius/radius-xxl` | 16 | Hero / marketing surfaces |
+
+Pill / circular shapes use Mantine prop `radius="full"` in code; in Figma there is no token for that — set `cornerRadius` to half the height for pills, full for circles, and document why a token wasn't bound.
+
+The `border radii / absolute/radius-*` collection exists for primitives the system itself is built from. **Do not use it in mockups.**
+
+## 6. Colors — Bind Variables, Never Set Hex
+
+**Categories** (collection `Tokens`):
+
+- `Background/*` — frame and shape fills (scopes `FRAME_FILL`, `SHAPE_FILL`, `EFFECT_COLOR`)
+- `Text/*` — text fills (scope `TEXT_FILL`)
+- `Stroke/*` — borders and dividers
+- `Icon/*` — icon fills inside `Icon /` components
+
+**Sub-categories**: `default` (neutral), `Subdued`, `Primary` (brand green), `Information` (indigo), `Success` (teal), `Warning` (yellow), `Danger` (red), `Inverse`, `disabled`, `transparent`, `body`, `backdrop`, `input`.
+
+**Variants**: `default`, `light`, `filled`, `strong`, `disabled`, `inverse`, `default-hover`, `light-hover`, `filled-hover`.
+
+**Common token recipe** — pick by *role*, not by hue:
+
+| Need | Variable to bind |
+|---|---|
+| Primary CTA fill | `Background/Primary/filled` |
+| Primary CTA hover | `Background/Primary/filled-hover` |
+| Primary CTA label | `Text/inverse` |
+| Soft brand surface (selected pill, info card) | `Background/Primary/light` |
+| Brand-tinted text on soft surface | `Text/Primary/light` (or `Text/link` for links) |
+| Page background | `Background/body` |
+| Card / sheet background | `Background/default` |
+| Subtle striping or subdued chip | `Background/Subdued/light` |
+| Filled neutral chip | `Background/Subdued/filled` |
+| Default body copy | `Text/default` |
+| Subdued body copy / helper text | `Text/Subdued/strong` (NOT `light`) |
+| Lightest helper / placeholder | `Text/Subdued/light` |
+| Disabled label | `Text/disabled/default` |
+| Danger label | `Text/Danger/default` (or `Text/Danger/strong` on light bg) |
+| Success label | `Text/Success/strong` |
+| Warning label | `Text/Warning/strong` |
+| Information label | `Text/Information/strong` |
+| Default border | `Stroke/default` |
+| Hairline border | `Stroke/Subdued/default` |
+| Focus ring (outer) | `Stroke/focus/strong` |
+| Modal backdrop overlay | `Background/backdrop` |
+| Input field background | `Background/input` |
+
+Bind colors via:
+
+```js
+const bgVar = await figma.variables.importVariableByKeyAsync(BG_KEY);
+const fill = figma.variables.setBoundVariableForPaint(
+  { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', bgVar
+);
+node.fills = [fill];
+```
+
+**FORBIDDEN color patterns:**
+
+- `node.fills = [{ type: 'SOLID', color: { r: ..., g: ..., b: ... } }]` without a bound variable.
+- Hex codes anywhere in mockup data, including inside `iconBg` / `iconFg` props (this is a real recurring failure — see `apps/lm-web/src/features/global-search/components/QuickCreateRail.tsx`'s pre-rules pattern).
+- Picking a hue family (e.g. `green`, `red`) directly from primitives like `colors.ts` instead of a semantic role (`Primary`, `Danger`).
+- "Per-entity" accent colors invented for a single mockup. If the design needs five distinct accent surfaces (e.g. task / initiative / goal / meeting / deliverable), use the five available semantic tinted backgrounds — `Primary/light`, `Information/light`, `Success/light`, `Warning/light`, `Danger/light` — paired with their matching `Text/<role>/strong`. If you genuinely need more than the five semantic roles, STOP and ask the user — don't invent a sixth.
+
+## 7. Text Styles — Apply, Don't Reinvent
+
+Available text styles in `LM Design System`:
+
+| Figma style name | Use |
+|---|---|
+| `heading 1` | Page title (rare; reserved for marketing / empty states) |
+| `heading 2` | Major section title |
+| `heading 3` | Card title, drawer title |
+| `heading 4` | Subsection title |
+| `heading 5` | Inline group title, dense panel title |
+| `Body/Body 1` | Default body copy (14 px regular) |
+| `Body/Body 1 Strong` | Body copy with emphasis (14 px medium 500) |
+| `Body/Body 1 Stronger` | Body copy with stronger emphasis (14 px semibold 600) |
+
+The library also exposes `caption1`, `caption1.strong`, `caption1.stronger`, `caption2`, `caption2.strong`, `caption2.stronger`, `caption3`, `caption3.strong`, `caption3.stronger`, `smallCaps`, `monospaced`. Search for the exact name with `search_design_system` (`includeStyles: true`) before binding — case and slash placement matter.
+
+Apply via:
+
+```js
+const textStyle = await figma.importStyleByKeyAsync(STYLE_KEY);
+textNode.textStyleId = textStyle.id;
+```
+
+**FORBIDDEN typography patterns:**
+
+- Setting `fontSize`, `fontName`, `lineHeight`, `letterSpacing`, or `textCase` directly on a text node when a matching style exists. Apply the style.
+- Choosing a heading level by *visual weight* rather than *semantic role* (e.g. using `heading 2` because it "looks the right size" for a card title — use `heading 3` for cards).
+- Applying `smallCaps` to anything outside its intended use (eyebrow labels above sections / cards). It is opinionated and breaks easily.
+
+**Code-side**: in `apps/lm-web/`, use `<Text variant="...">` from `@scalepad/ui`. Variant names mirror Figma: `body1`, `body1.strong`, `body1.stronger`, `caption1`, `caption2`, `caption3`, `smallCaps`, `monospaced`. Heading variants live on `<Heading>` (`heading1`–`heading5`).
+
+## 8. Effects (Shadows) — Apply, Don't Build
+
+Use these `EFFECT` styles from `LM Design System`:
+
+| Figma style name | Use |
+|---|---|
+| `shadow-2xs` | Pressed / inset hint |
+| `shadow-xs` | Subtle separator (1 px stack hint) |
+| `shadow-sm` | Inline cards, popover tip |
+| `shadow-md` | Default elevated card |
+| `shadow-lg` | Drawer, popover floating layer |
+| `shadow-xl` | Modal, command palette |
+| `shadow-2xl` | High-emphasis floating UI (rare) |
+
+Apply with `node.effectStyleId = (await figma.importStyleByKeyAsync(SHADOW_KEY)).id`. Never construct a `DROP_SHADOW` effect manually; the colors and offsets in the system are tuned for both light and dark modes.
+
+## 9. Components — Instances Only, From `LM Design System`
+
+When the system has the component, use a component INSTANCE — never re-build with primitives. Confirmed components in `LM Design System` (this is not exhaustive — verify with `search_design_system` first):
+
+| Need | Component name |
+|---|---|
+| Action / submit button | `Button` (component_set) |
+| Icon-only button | `Icon Button` |
+| Toolbar / segmented buttons | `Button Group`, `Button Group Icon Button` |
+| Text-style link with icon | `Link Button` |
+| Toggle (single state) | `Toggle Button`, `Toggle Icon Button` |
+| Pagination control | `Pagination Button` |
+| Tab strip | `Tabs` (container component_set) wrapping one `Tab` (single tab component_set) per panel |
+| Surface / panel container | `Card` (component_set), `Hover Card` |
+| Image carousel | `Carousel with Image` |
+| **Confirmation / alert modal** (single yes-or-no question — "Are you sure?", "Delete this?", "Discard changes?", validation prompt) | **`Alert Dialog`** (component_set, key `9b2fb3dcc9a991615d1119cb0638f5a01682700f`). Set `Type` = `Desktop` or `Mobile`. Toggle `ShowError` for destructive / failure states. **Sample assembled instance**: node `4141:5746` — open it, copy it, override the title/body/buttons. Do NOT recompose from `Dialog` + `Dialog Header` + `Dialog Footer` + buttons. |
+| Full-content modal (forms, multi-step flows, dense panels) | `Dialog` (component_set) composed with `Dialog Header` + `Dialog Footer`. Use this only when the body content is too rich for `Alert Dialog` (more than a sentence or two of body copy, embedded forms, lists, etc.). |
+| **Labeled form control** (label + optional hint + error + the control itself) | **`Vertical Field`** (default, label above) or **`Horizontal Field`** (label-on-the-side, settings-style). Set the `Type` variant to one of `Text Value` / `Select` / `Radio` / `Textarea` / `Checkbox` / `Slider`. **One component covers all six control shapes** — never compose a labeled form control by hand from primitives. |
+| Bare text input (no label, e.g. inline search, table cell editor, card-embedded value) | `Input` |
+| OTP input | `Input OTP` |
+| File upload | `Input File` |
+| Date input | `Date Picker Input` |
+| Table cell wrapper | `Table Cell` |
+| Filter dropdown | `Filter Menu` |
+| Inline iconography | `Icon / <name>` (e.g. `Icon / circle-check-big`, `Icon / rocket`) |
+
+For each instance:
+
+1. Import via `figma.importComponentSetByKeyAsync(KEY)` (or `importComponentByKeyAsync` for non-variant components).
+2. **Discover keys at runtime — never copy keys from this file.** Read `componentPropertyDefinitions` on the imported component_set/component and inspect every entry: `VARIANT` keys are bare names (`Variant`, `Size`, `State`, `Content`, `Slot No.`); `BOOLEAN`, `INSTANCE_SWAP`, and `TEXT` keys carry an unstable `#nnn:m` suffix (e.g. `Show left icon#11:0`). The suffix changes when the component is restructured upstream.
+3. Override text via the component's TEXT property keys (e.g. `"Label#2:0": "Save changes"` — but read the actual key from `componentPropertyDefinitions`), not by writing `node.characters`.
+4. For nested instances that expose their own TEXT properties, call `setProperties()` on the nested instance.
+5. Never detach an instance to "tweak" it. If a variant is missing, STOP and ask.
+
+### Conditional Icon / Slot Properties — Set BOTH The Gate AND The Swap
+
+This is THE most common slip when authoring instances of `LM Design System` components programmatically. Many components hide an icon-instance or content-slot behind a *gate* — either a `BOOLEAN` toggle or a `VARIANT` value. Setting the swap without flipping the gate ⇒ the icon never renders. Flipping the gate without setting the swap ⇒ the placeholder icon (`circle-help`-shaped) renders.
+
+There are three gating patterns in `LM Design System`:
+
+| Pattern | Gate | Paired swap | Example components |
+|---|---|---|---|
+| **A. Boolean-gated swap** | `BOOLEAN` named `Show <something>` | `INSTANCE_SWAP` with `⮑` prefix on a sibling property | `Button` (`Show left icon` → `⮑ Left Content`, plus `Show right icon` → `⮑ Right Content`); `Badge` (`Show icon left` → `⮑ Icon left`; note the word order differs from `Button`) |
+| **B. Variant-gated swap** | `VARIANT` value reveals the swap | `INSTANCE_SWAP` (no `⮑` prefix) | `Tab` (`Content` = `Icon` or `Icon + Label` reveals `Icon`); `Card` (`Slot No.` = `1 Slot` … `6 Slots` reveals `Main Slot` / `Header Slot` / `Footer Slot`) |
+| **C. Always-visible swap** | none | `INSTANCE_SWAP` always present | `Icon Button` (the whole component IS the icon — just set `⮑ Left icon`) |
+
+There is **also** a fourth shape worth knowing: components like `Input` expose `Show decoration left` / `Show decoration right` booleans **without** a sibling instance-swap. The decoration content is a nested instance you reach by traversing `instance.children` and calling `setProperties()` on the inner decoration node. Don't assume a paired swap exists just because a `Show <x>` boolean exists — check the `componentPropertyDefinitions` first.
+
+**Recipe — boolean-gated icon (the Button shape):**
+
+```js
+// 1. Discover keys at runtime.
+const buttonSet = await figma.importComponentSetByKeyAsync(BUTTON_KEY);
+const defs = buttonSet.componentPropertyDefinitions;
+const showLeftKey = Object.keys(defs).find(k => k.startsWith('Show left icon#'));
+const leftSwapKey = Object.keys(defs).find(k => k.startsWith('⮑ Left Content#'));
+if (!showLeftKey || !leftSwapKey) throw new Error('Button shape changed — re-discover.');
+
+// 2. Resolve the icon to a NODE ID. INSTANCE_SWAP values are node ids, NOT component keys.
+const plusIcon = await figma.importComponentByKeyAsync(ICON_PLUS_KEY);
+
+// 3. Set BOTH the gate AND the swap in a single setProperties() call.
+const instance = buttonSet.defaultVariant.createInstance();
+instance.setProperties({
+  Variant: 'Primary',
+  Size: 'md',
+  [showLeftKey]: true,
+  [leftSwapKey]: plusIcon.id,
+});
+```
+
+**Recipe — variant-gated icon (the Tab shape):** flip the variant first, then set the swap.
+
+```js
+const tabSet = await figma.importComponentSetByKeyAsync(TAB_KEY);
+const defs = tabSet.componentPropertyDefinitions;
+const iconKey = Object.keys(defs).find(k => k.startsWith('Icon#'));
+const icon = await figma.importComponentByKeyAsync(ICON_KEY);
+
+const instance = tabSet.defaultVariant.createInstance();
+instance.setProperties({
+  Content: 'Icon + Label',  // VARIANT — gates the Icon swap
+  Size: 'Regular',
+  [iconKey]: icon.id,
+});
+```
+
+**Rules of thumb:**
+
+- INSTANCE_SWAP values are **node ids** (e.g. `"123:45"`), not component keys. Pattern: `(await figma.importComponentByKeyAsync(KEY)).id`.
+- VARIANT keys are bare strings; everything else has a `#nnn:m` suffix you must read at runtime.
+- The `⮑` arrow prefix in property names (`⮑ Left Content`, `⮑ Icon right`, `⮑ Left icon`) is part of the actual key — preserve it exactly. It's the literal Unicode character U+2BAD.
+- Property names are **inconsistent across components** by design — `Button` says `"Show left icon"` while `Badge` says `"Show icon left"`. Never copy a key from another component; always re-discover.
+
+**Icons specifically:** prefer `Icon / <lucide-name>` components from `LM Design System`. The codebase ships `lucide-react` icons in code, but in Figma mockups always use the design-system icon component so the icon stays linked. If the icon you need does not exist in `Icon / *`, STOP and ask before creating a new vector.
+
+**FORBIDDEN component patterns:**
+
+- Drawing a button with a `RECTANGLE` + `TEXT`. Use `Button`.
+- Placing a Lucide SVG asset inline instead of `Icon / *`.
+- Picking a button variant by visual size match — match the *role*: `Primary` for the single dominant CTA, `Secondary` for normal actions, `Outline` / `Ghost` for tertiary, `Destructive` for delete-class actions, `Outline Inverse` only on dark surfaces.
+- Composing a labeled form control by hand — `Input` + a separate `Text` for the label + another `Text` for the helper/hint + manual red styling for errors. `Vertical Field` / `Horizontal Field` already wraps all of that and renders the label, hint, error, and control with consistent spacing. Pick `Type` = `Text Value` / `Select` / `Radio` / `Textarea` / `Checkbox` / `Slider` for the inner control. Reserve bare `Input` (and bare `Radio` / `Checkbox` / `Switch` / `Textarea`) for cases where the design intentionally has no label — inline search, value cells in a `Table`, embedded controls in a `Card` body where the label lives elsewhere.
+- Reaching for the bare primitive component (`Radio`, `Checkbox`, `Switch`, `Textarea`, `Input`) when the design shows a label or helper next to it. The label/helper is part of the `Field`, not next to it.
+- Composing a confirmation / alert modal from `Dialog` + `Dialog Header` + `Dialog Footer` + two `Button`s + a custom layout. Use `Alert Dialog` (sample at node `4141:5746`) and override the inner text and buttons. `Dialog` is for content-rich modals — forms, multi-step flows, dense panels — not for "Are you sure?" prompts.
+- Setting an `INSTANCE_SWAP` property (icon slot, content slot) **without** also flipping its boolean gate or setting the variant value that reveals it. The icon will not render.
+- Flipping a `Show <something>` boolean **without** also setting the paired `INSTANCE_SWAP`. The default placeholder icon (`circle-help`-shaped) will render and the mockup will look broken.
+- Hardcoding `#nnn:m` property suffixes from this rule file, a sample script, or another component into a script. Always re-discover from `componentPropertyDefinitions` on the live component.
+- Passing a component **key** as an `INSTANCE_SWAP` value. It must be the node `.id` returned by `importComponentByKeyAsync(...)`.
+
+## 10. Layout Discipline
+
+- Every container that has more than one child MUST be auto-layout. No absolute positioning except for floating overlays (tooltips, popovers).
+- `counterAxisAlignItems` and `primaryAxisAlignItems` must be set explicitly — don't rely on defaults.
+- After `appendChild`, set `layoutSizingHorizontal` / `layoutSizingVertical` on the appended node — `FILL` for stretch children, `HUG` for content-sized, `FIXED` only when the parent is `HUG` and a child needs a hard width.
+- One section per `use_figma` call. Build wrapper first, return its id, then build each section into the wrapper.
+- Validate each section with `get_screenshot` (by node id, not the whole frame) before moving on.
+
+## 11. Translating Mockups Back To Code (lm-web)
+
+When implementing a Figma frame in `apps/lm-web/src/features/<name>/...`:
+
+- UI imports come from `@scalepad/ui`, never `@mantine/core` directly. (See `.ai/rules/styling.md`.)
+- Spacing uses Mantine props `gap` / `p` / `px` / `py` / `mt` / etc., with the token names from §4 above (`"3xs"` is FORBIDDEN unless the corresponding Figma frame is updated to add the missing token first).
+- Colors use `bg="background.<role>"` / `c="text.<role>"` / `style={{ borderColor: toCssVar(tokens.color.stroke.default) }}` etc. — see `packages/ui/src/theme/themeContract.css.ts` for the full contract. NEVER inline hex / rgba.
+- Text uses `<Text variant="...">` / `<Heading variant="...">` from `@scalepad/ui`. Don't set `fz`, `fw`, `lh`, `lts`, or `ff` directly.
+- Icons: use `lucide-react` components in code (this is the only place Lucide is allowed); name should match the Figma icon name `Icon / <kebab-name>` → React `<KebabName />`.
+
+When you find an existing file using hardcoded hex / rgba on accent bubbles, badges, or icon tints (the recurring symptom), fix it back to tokens at the same time you ship the mockup. The accent palette for "per-entity" tints is the five semantic roles in §6 — not invented hex codes.
+
+## 12. Forbidden Shortcuts (Hard Stop List)
+
+Every one of these is a stop-and-ask, not a substitute-and-continue:
+
+- ✗ Hex code or `rgba(...)` literal in a mockup, in CSS-in-TS, in a component prop, or in a variable definition.
+- ✗ Numeric literal as `itemSpacing`, padding, gap, cornerRadius, fontSize, lineHeight.
+- ✗ Component drawn from primitives when the named component exists in `LM Design System`.
+- ✗ Pulling assets from `Basic Design System` or `ControlMap Library` files when the same name exists in `LM Design System`.
+- ✗ Detaching an instance to override style.
+- ✗ Inventing a new accent color outside the five semantic roles.
+- ✗ Setting `node.characters` on a text inside an instance whose containing component exposes a TEXT property — use `setProperties()`.
+- ✗ Setting an `INSTANCE_SWAP` icon/slot property without also flipping its gate (the paired `Show <…>` boolean, or the `Content` / `Slot No.` variant value). See §9 "Conditional Icon / Slot Properties".
+- ✗ Hardcoding `#nnn:m` property suffixes from this file or any prior script. Read from `componentPropertyDefinitions` at runtime, every time.
+- ✗ Composing a labeled form control by hand from `Input` + label `Text` + helper `Text`. Use `Vertical Field` / `Horizontal Field` with the appropriate `Type` variant. See §9 component table.
+- ✗ Composing a confirmation / alert modal from `Dialog` + `Dialog Header` + `Dialog Footer` + buttons. Use `Alert Dialog` (sample assembled instance: node `4141:5746` in `LM Design System`). See §9 component table.
+- ✗ Skipping the §3 pre-flight before the first mutating `use_figma` call.
+
+## 13. Reference Anchors (do not edit by hand)
+
+- Code source of truth for tokens: `src/frontend/ClientApps/packages/ui/src/tokens/` and `src/frontend/ClientApps/packages/ui/src/theme/themeContract.css.ts`.
+- Token JSON exports the codebase generates from: `packages/figma-tokens/source/*.json` (Figma-side export of `LM Design System`).
+- Code Connect mappings: `src/frontend/ClientApps/packages/ui/src/components/**/*.figma.tsx`. They point at `LM Design System` (`VCLfybgU3OaUUPrQdBaVmP`). Safe to use as a starting reference for component URLs, but always verify the target node still exists with `search_design_system` before linking from a new mockup.
+- New-frontend styling rules (lm-web): `src/frontend/ClientApps/.ai/rules/styling.md`.
+
+If any rule above conflicts with `.ai/rules/styling.md`, the lm-web rule wins for code; this file wins for Figma writes.