Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

feat(skills): carbon-design requires a functionality contract, real wiring and browser verification

aashu8aa81f095aa5
diff --git a/.claude/skills/carbon-design/SKILL.md b/.claude/skills/carbon-design/SKILL.md
index c992eb010a..206d5c6920 100644
--- a/.claude/skills/carbon-design/SKILL.md
+++ b/.claude/skills/carbon-design/SKILL.md
@@ -35,10 +35,13 @@ sits next to the ID and the next step is the one primary button. Documents open
workspace — header strip, structure on the left, work in the middle, metadata on the right.
State lives in the URL. Secondary things hide in known places (⋯ menu, Properties panel,
hidden columns, row menus), never behind modes. Permissions and locks disable in place.
-Everything is keyboard-reachable, translated, and honest about its state. On the shop floor
-the same language gets bigger, simpler and touch-first.
+Everything is keyboard-reachable, translated, and honest about its state. And it is **worked
+on**, not looked at: every value a user may need to change is changeable right where it is
+shown (a line opens into its editable form, a header fact autosaves in Properties, the next
+status is one click), guarded by the record's lock. On the shop floor the same language gets
+bigger, simpler and touch-first.
-## The 12 laws (short form — the reasoning is in `references/principles.md`)
+## The 13 laws (short form — the reasoning is in `references/principles.md`)
1. **Quiet chrome, loud data.** Tokens only; hue only for meaning; ink primary; no colored prose.
2. **Identity first.** Readable IDs / thumbnails / avatars — visible, copyable, linked. No raw ids.
@@ -52,6 +55,7 @@ the same language gets bigger, simpler and touch-first.
10. **Dense, not cramped.** `text-sm` body, `text-xs` muted labels, h-8 buttons, 4/8/16 spacing, `font-medium`.
11. **Primitives own the surface.** `Card > CardContent`, no double edges, `rounded-lg` inner boxes, no big shadows.
12. **Honest, grounded, translated, keyboard-first.** Real states only; real APIs and domain rules (verified in source); every string in Lingui; named shortcuts.
+13. **Usable end to end.** The screen provides its archetype's full capability contract (`references/functionality.md`) wired to the record's real endpoints. A read-only mock or a disabled placeholder is not a design.
## Workflow
@@ -59,7 +63,8 @@ Follow these steps for any UI work. Steps 1–4 happen **before** writing code.
### Step 1 — Classify the work
Identify every surface the feature touches and read the matching references. Always read
-`references/principles.md` and `references/anti-patterns.md` once per task.
+`references/principles.md`, `references/functionality.md` and `references/anti-patterns.md`
+once per task.
| The feature involves… | Read |
|---|---|
@@ -73,12 +78,15 @@ Identify every surface the feature touches and read the matching references. Alw
| Keyboard, drag & drop, motion, accessibility, responsive | `references/interaction-motion-a11y.md` |
| Anything operators use on the shop floor (`apps/mes`) | `references/shop-floor-mes.md` |
| Any user-facing words | `references/content-and-copy.md` |
+| What users must be able to do; wiring edits, lines, statuses, locks | `references/functionality.md` |
| Unsure how far to reuse vs invent | `references/worked-examples.md` |
### Step 2 — Find the sibling and read it
Pick the archetype (`page-archetypes.md` §15) and open its exemplar files. Also find the
closest existing screen *in the same module*. Read their actual code — the exemplar is the
-spec. Canonical starting points:
+spec. Read its **routes** too (`$id.new`, `$id.$lineId.details`, `update.tsx`, `status`,
+`confirm`, `delete`): that is where the functionality and the domain rules live, and your
+screen will post to them. Canonical starting points:
| Need | Exemplar (paths from `apps/erp/app/`) |
|---|---|
@@ -118,6 +126,9 @@ Design brief — <feature>
- Data cases: <nulls and special values the domain already models (e.g. deadline types, locked
rows, mixed selections, multi-currency) and how each renders — reuse the domain's own
predicates (e.g. `deadlineRequiresDueDate`) instead of approximating>
+- Capabilities: <one line per user job: job → surface → component → endpoint it posts to
+ (`path.to.*`, verified) → what locks it. Every row of the archetype contract in
+ `functionality.md` is either here or skipped with a reason>
- Copy: <titles, buttons, toasts, empty text — in Carbon patterns>
- Reuse / extend / create: <list, with the reason for each extend/create and what was rejected>
```
@@ -125,7 +136,23 @@ If the user asked only for a design (no code), the brief plus annotated ASCII wi
component choices is the deliverable.
### Step 5 — Build
-Follow the brief and the exemplar.
+Follow the brief and the exemplar. **Wire every capability for real** — post to the record's
+existing routes, reuse its validated form components where they fit, respect its lock
+helpers. If a job has no endpoint, stop and say so rather than rendering a dead control.
+
+**Build for real data.** Names are long, descriptions are missing, quantities have five
+decimals, lists have 40 rows. In every flex row the text column is `flex-1 min-w-0` with
+`truncate`/`line-clamp-1` on `w-full` children, fixed parts (thumbnails, badges, amounts,
+trailing actions) are `shrink-0`, trailing hover actions are absolutely positioned over a
+`pr-10` reserve, IDs are `whitespace-nowrap`, and tables inside cards use the `Table`
+primitive (it scrolls horizontally itself) with no content forcing a card wider than its
+column. Exemplar comment: `modules/sales/ui/SalesOrder/SalesOrderSummary.tsx:409-413`.
+Content inside the 3-pane workspace lives in **resizable panes**, so its width has little to
+do with the viewport: at a 1024 px screen with Explorer and Properties open, the content pane
+is ~470 px. Size grids and row layouts inside panes with **container queries** (`@container`
+on the card/row, then `@md:` / `@xl:` / `@3xl:` — Tailwind v4 built-in, precedent
+`components/Gantt/Gantt.tsx`), not `md:`/`lg:` viewport breakpoints. Let status pills and
+badges wrap (`flex-wrap`) rather than clip.
**Verify before you use — every time.** The most common way a Carbon-looking design breaks is
an invented API. Before writing any of these, open the source and confirm it:
@@ -154,10 +181,16 @@ Also obey the mechanics rules:
`.claude/rules/numeric-precision.md`, `.claude/rules/table-csv-export.md`, `packages/react/AGENTS.md`.
Where those files disagree with the code (e.g. Card radius), the code wins — note it.
-### Step 6 — Design-language review (mandatory)
+### Step 6 — Design-language review and browser verification (mandatory)
Run `references/design-review.md`: the seven questions, the checklist, the grep for red flags,
-and the state walk-through. **Fix every FIX and re-run** until clean. Work is not done until the
-review summary is written. If something can't be made to fit without a system change (a new
+the state walk-through, **and §4 — render it in a real browser and use it**. Typecheck and
+lint passing says nothing about layout or usability. Check whether the dev server is up
+(`grep ^ERP_URL .env.local`, then load it); if it is, log in with the `auth` skill and
+screenshot every screen at 1440, 1024 and 390 px wide, perform each capability from the brief
+once (edit a quantity, change a date, add and delete a line, transition status), and look at
+the screenshots before claiming anything. If no server can run, say explicitly that the UI is
+unverified — never present it as done. **Fix every FIX and re-run** until clean. Work is not
+done until the review summary is written. If something can't be made to fit without a system change (a new
shared component, a new token), stop and ask rather than improvising a one-off.
## When Carbon itself is inconsistent
@@ -181,7 +214,9 @@ mention any drift you touched in your summary.
## Done when
-- [ ] Design brief written (Step 4) and followed
+- [ ] Design brief written (Step 4) and followed, including the capability table
+- [ ] Every capability wired to a real endpoint and exercised once in the browser
+- [ ] Screenshots at 1440 / 1024 / 390 px reviewed; no overflow, clipping or wrapping IDs
- [ ] Every reuse/extend/create decision recorded with its reason
- [ ] `references/design-review.md` checklist all PASS or justified N/A; red-flag grep clean or justified
- [ ] Review summary written in the final message, including open questions about drift
diff --git a/.claude/skills/carbon-design/references/anti-patterns.md b/.claude/skills/carbon-design/references/anti-patterns.md
index 8bc66012a8..cd5bc1a055 100644
--- a/.claude/skills/carbon-design/references/anti-patterns.md
+++ b/.claude/skills/carbon-design/references/anti-patterns.md
@@ -69,6 +69,20 @@ Three kinds:
- Designing against invented APIs (props, route helpers, columns) or restating a sibling's
constants from memory. → open the source; import the constant.
+### Usability and robustness
+- A page that only displays: values the sibling lets users change (quantity, price, dates,
+ customer, terms) shown as text. → line form card, Properties autosave, form cards
+ (`functionality.md`).
+- Disabled "not available" placeholders for actions you didn't wire. → wire the real route,
+ or leave the capability out and say why.
+- Re-implementing a mutation (price resolution, lock checks, status derivation) the record's
+ existing route already does. → post to that route.
+- Text in flex rows without `min-w-0` + `truncate`: names run under trailing quantities and
+ off the panel edge. IDs that wrap ("MTR-" / "9000"). Tables whose last column is clipped
+ inside a card. Tooltip wrappers that break a `w-full` button.
+- Declaring UI done after typecheck/lint without rendering it at desk and phone widths and
+ using it once.
+
### Copy
- "Oops!", "Successfully saved! 🎉", exclamation marks, marketing voice.
- Sentence-case buttons/headers in ERP; Title Case toasts.
diff --git a/.claude/skills/carbon-design/references/design-review.md b/.claude/skills/carbon-design/references/design-review.md
index 54f3e4e75f..c5314ef7f4 100644
--- a/.claude/skills/carbon-design/references/design-review.md
+++ b/.claude/skills/carbon-design/references/design-review.md
@@ -12,13 +12,16 @@ self-critique loop, not a formality: find the gaps, fix them, re-run until clean
3. **Walk the checklist below.** For every item answer PASS / FIX / N/A. Every FIX gets changed
now, not listed as a follow-up.
4. **Grep your diff** for the mechanical red flags (§3).
-5. **Render the states** mentally (or in the browser via the `test` / `agent-browser` skills if
- the app is running): empty, loading, one row, many rows, long text, locked, no permission,
- error, dark mode, mobile (ERP < 768px) or tablet (MES).
-6. Repeat 3–5 until everything is PASS or a justified N/A. Then write the review summary (§4).
+5. **Render it and use it in a real browser (§4).** Not optional when a dev server can run.
+ Walk the states: empty, one row, many rows, long text, locked, no permission, error, dark
+ mode, 1440 / 1024 / 390 px (ERP) or tablet (MES). Perform every capability in the brief.
+6. Repeat 3–5 until everything is PASS or a justified N/A. Then write the review summary (§5).
-## 1. The seven questions (answer in one line each)
+## 1. The eight questions (answer in one line each)
+0. **Can a user do their job here?** Walk the capability table from the brief: can each job
+ be done on this screen, the way the sibling page lets them? Anything read-only that the
+ sibling lets them change is a FIX.
1. **Does this feel like Carbon?** Put it next to the sibling screen: would a user notice a
different hand?
2. **Is the information hierarchy consistent?** Identity first; one primary; metadata recedes;
@@ -34,6 +37,25 @@ self-critique loop, not a formality: find the gaps, fix them, re-run until clean
## 2. Checklist
+### Functionality
+- [ ] Every row of the archetype contract in `functionality.md` is implemented or skipped with a reason
+- [ ] Values users change (qty, price, dates, customer, terms) are editable where shown — line form card, Properties autosave, or form card
+- [ ] Every control posts to a real, verified endpoint; no disabled placeholders or dead buttons
+- [ ] Locks use the domain helper on the client and the route's guard on the server
+- [ ] After each mutation the screen reflects it (revalidation or optimistic state) and errors toast
+- [ ] Each capability was exercised once in the browser
+
+### Layout robustness
+- [ ] Flex rows: text column `flex-1 min-w-0`, text `truncate`/`line-clamp-1` on `w-full` children, fixed parts `shrink-0`
+- [ ] Trailing hover actions absolutely positioned over a `pr-*` reserve; nothing overlaps text
+- [ ] IDs and money never wrap (`whitespace-nowrap`); long descriptions truncate with `TruncatedTooltipText`
+- [ ] Tables in cards don't clip columns; the card never grows wider than its pane
+- [ ] Full-width buttons stay full width (wrappers like Tooltip triggers don't break `w-full`)
+- [ ] No `Hyperlink` inside a tight flex row or card header — it reserves width for its hidden hover "Open" button; use a plain `Link` there, `Hyperlink` in table cells
+- [ ] Wide tables inside narrow panes get a `min-w-[…]` so the `Table` primitive scrolls horizontally instead of squashing columns into each other
+- [ ] Grids/rows inside workspace panes use container queries (`@container` + `@md:`…), not viewport `md:`/`lg:` — panes resize independently of the screen
+- [ ] Screenshots at 1440 / 1024 / 390 px checked, with the longest real names in the data
+
### Structure
- [ ] Correct archetype (`page-archetypes.md`) and matches its exemplar's shape
- [ ] Identity (readable ID / thumbnail / avatar) visible, copyable where the sibling allows, linked
@@ -114,11 +136,31 @@ grep -nE ' title=\{?["`t]' $FILES # native titl
grep -nE 'size="sm"' $FILES # MES files: every operator action is lg
grep -nE '<div[^>]*(divide-y|grid-cols-\[)' $FILES # record list as divs? → TableBase
grep -nE 'font-headline|size="h[123]"' $FILES # serif only for the page title
+grep -nE 'isDisabled(\s|>|$)|isDisabled=\{true\}' $FILES # hard-disabled controls → wired action or a real lock condition
```
(`grep -P` may be needed for the lookahead on some systems; if unavailable, grep
`react-icons/` and inspect.) Every hit is either fixed or justified in the summary.
-## 4. Review summary (write this at the end)
+## 4. Browser verification (how)
+
+```bash
+grep '^ERP_URL' .env.local # per-worktree URL; never assume
+agent-browser open "$ERP_URL/login" # then follow the `auth` skill (DEV_BYPASS_EMAIL)
+agent-browser set viewport 1440 900
+agent-browser open "$ERP_URL/x/<your route>" && sleep 4
+agent-browser screenshot <scratchpad>/1440.png # then Read the png and look at it
+agent-browser set viewport 1024 800 && agent-browser screenshot <scratchpad>/1024.png
+agent-browser set viewport 390 844 && agent-browser screenshot <scratchpad>/390.png
+agent-browser snapshot -i # refs for clicking/filling to exercise capabilities
+```
+To change a number in a react-aria field, `click` it, `press Meta+a`, then `type` — `fill`
+can append to the existing value (3 → "34"). Re-read the field from `snapshot -i` before saving,
+and confirm the saved value in the database or the reloaded page. Revert every test edit.
+Pick records with the longest names, the most lines and a locked status. After each
+capability (edit qty, change a date, add/delete a line, transition), re-screenshot and confirm
+the page reflects it. Fix, re-render, re-look. Include what you exercised in the summary.
+
+## 5. Review summary (write this at the end)
```
Design-language review
@@ -127,6 +169,8 @@ Design-language review
- Extended: <what + why> (or none)
- New: <component/pattern + why no existing one fits + how it follows Carbon's language> (or none)
- Deviations from the exemplar: <each with a reason> (or none)
+- Capabilities exercised in the browser: <job → result> (one line each)
+- Screenshots reviewed: <widths + records used>
- States covered: empty / loading / error / locked / no-permission / dark / mobile|tablet
- Open questions for the team: <e.g. drift items touched> (or none)
- Props audit: <Component — props used — file:line of its props type> (one line each)
diff --git a/.claude/skills/carbon-design/references/functionality.md b/.claude/skills/carbon-design/references/functionality.md
new file mode 100644
index 0000000000..9972c7b3a6
--- /dev/null
+++ b/.claude/skills/carbon-design/references/functionality.md
@@ -0,0 +1,120 @@
+# Functionality — what a Carbon screen must let people DO
+
+A screen that looks like Carbon but can't be worked on is a mock-up, not a Carbon screen.
+Users live in these pages all day: they change a quantity, fix a price, move a date, add a
+line, confirm the order, ship it. **Design the capabilities first, then the look.** Every
+archetype below has a capability contract — the things users expect because every sibling
+page gives them. Read the exemplar's *routes*, not just its components: the functionality
+lives in the route actions, the fetcher contracts and the lock helpers.
+
+Paths are relative to `apps/erp/app/`.
+
+## Contents
+1. How to use this file (the capability pass)
+2. Document workspace contract (Archetype B)
+3. Item / master record contract (Archetypes C and D)
+4. The wiring patterns (how Carbon implements edits)
+5. Locks — how "can I edit this?" is decided and enforced
+6. Things that are never acceptable
+
+---
+
+## 1. The capability pass (do this before layout)
+
+1. **List the user's jobs** on this screen as verbs: "change the quantity of a line",
+ "add a line", "confirm the order", "see what has shipped", "attach the customer PO".
+2. **Take the archetype contract below** and tick every row that applies. A row you skip
+ needs a reason in the brief ("RMA has no notes — sibling has none").
+3. **For each job, name where it happens and what it calls**: the surface (explorer row menu,
+ line card, Properties field, header button), the component, and the *existing* route
+ action / service it posts to (`path.to.*` helper, verified). If no endpoint exists, the
+ job needs one — say so in the brief; don't render a control that goes nowhere.
+4. **Mark what locks it** (`is{Entity}Locked(status)`, permission, revision release lock).
+
+A new screen built on an existing record type reuses that record's real endpoints —
+`update.tsx` bulk routes, `$id.new`, `$lineId.details` actions, status/confirm routes. A new
+UI calling the old actions is how Carbon evolves a page without forking its domain rules
+(sales rules, lock guards, MRP triggers, exchange-rate derivation all live in those actions).
+
+## 2. Document workspace (Archetype B) — users must be able to…
+
+| # | Capability | Canonical pattern | Exemplar |
+|---|---|---|---|
+| 1 | Add a line | Explorer footer "Add Line Item" (+ `EXPLORER_SHORTCUTS.addLine`) opens `<XLineForm type="modal">` (a `ModalCard` in modal mode) posting to `$id.new` | `modules/sales/ui/SalesOrder/SalesOrderExplorer.tsx:259-302`, `routes/x+/sales-order+/$orderId.new.tsx` |
+| 2 | Open a line and **edit it in place** — item, quantity, price, dates, tax/shipping/add-ons | Explorer row navigates to `$id.$lineId.details`; the SAME line form renders as a collapsible Card (`ModalCard type="card"`), explicit Save, followed by the line's related cards | `routes/x+/sales-order+/$orderId.$lineId.details.tsx:285-373`, `SalesOrderLineForm.tsx:587-845` |
+| 3 | Delete a line | Explorer row ⋮ → confirm modal → `$lineId.delete` guarded by `requireUnlocked` | `SalesOrderExplorer.tsx:430-440`, `$orderId.$lineId.delete.tsx:48-54` |
+| 4 | Reorder lines | explicit edit mode: `useLineOrderEditMode` + `ReorderableLineList` → `$id.line-order` | `components/LineReorder/useLineOrderEditMode.ts`, `SalesOrderExplorer.tsx:193-254` |
+| 5 | Change header facts (customer, dates, location, contacts, currency, reference) | Properties panel: one tiny `ValidatedForm` per field, inline field, `onUpdate(field, value)` → fetcher posts `ids`,`field`,`value` to the entity's bulk `update.tsx` (switch on field, `requireUnlockedBulk`) | `SalesOrderProperties.tsx:63-83`, `routes/x+/sales-order+/update.tsx` |
+| 6 | Assign an owner | `<Assignee variant="inline">` + `useOptimisticAssignment` | `SalesOrderProperties.tsx:104-178` |
+| 7 | Custom fields | `CustomFormInlineFields` → `path.to.customFields` | `SalesReturnOrderProperties.tsx` (end of panel) |
+| 8 | Move through the lifecycle | status-gated header buttons; the next step is the single primary; confirm modal (`Confirm` or a custom Modal when it needs inputs) → `$id.confirm` / `$id.status`; Reopen in ⋯ posts `status=Draft` | `SalesOrderHeader.tsx:333-445`, `$orderId.status.tsx`, `$orderId.confirm.tsx` |
+| 9 | Create / reach downstream documents | header button before any exist, `Receipts ▾` dropdown listing them after | `SalesOrderHeader.tsx:463-647`, `useSalesOrder.ts` |
+| 10 | Shipping and payment terms | Cards in the details pane, `ValidatedForm isDisabled={isLocked}` + Save | `SalesOrderShipmentForm.tsx:111`, `SalesOrderPaymentForm.tsx:59` |
+| 11 | Notes | Internal / External tabs with the rich `Editor`, debounced autosave | `modules/sales/ui/Opportunity/OpportunityNotes.tsx:55-149` |
+| 12 | Attachments | Documents card: dropzone + table (download, delete), deferred load | `OpportunityDocuments.tsx:65-197` |
+| 13 | See totals | Summary card computed from the loader's lines | `SalesOrderSummary.tsx:108-303` |
+| 14 | Preview / export / email | PDF preview, CSV export of lines, email option in the confirm modal | `SalesOrderHeader.tsx:319-407`, `$orderId.confirm.tsx:145-190` |
+| 15 | See history | `useAuditLog` item in ⋯ + drawer | `SalesOrderHeader.tsx:237-242` |
+| 16 | Delete the document | ⋯ last item, destructive, `ConfirmDelete`, disabled when locked | `SalesOrderHeader.tsx:348-359` |
+| 17 | Get rule feedback | `useRuleViolations` wraps the line form fetcher | `SalesOrderLineForm.tsx:113-120` |
+
+The details pane (no line selected) is a stack of **working** cards: state → Summary →
+Notes → Documents → the header's form cards (shipping, payment). The line pane is: line form
+card → line notes → line-specific cards (jobs, shipments, method, costing) → documents.
+
+## 3. Item / master record (Archetypes C, D) — users must be able to…
+
+| # | Capability | Canonical pattern | Exemplar |
+|---|---|---|---|
+| 1 | Switch facets by URL | route tabs from a `use{Entity}Navigation` hook into `DetailsTopbar` (gated by role/permission/record state, ⌘⇧ shortcuts) | `modules/items/ui/Parts/usePartNavigation.tsx:35-97`, `components/Layout/Navigation/DetailsTopbar.tsx` |
+| 2 | Edit attributes inline | Properties autosave → `path.to.bulkUpdateItems` (`{items, field, value}`), toast on error | `PartProperties.tsx:173-202`, `routes/x+/items+/update.tsx` |
+| 3 | Edit grouped settings | a Card per concern with `ValidatedForm` + explicit Save; one action routed by `intent` | `ItemManufacturingForm.tsx`, `routes/x+/part+/$itemId.details.tsx:179-238` |
+| 4 | Edit the structure (BoM / operations) | cards with Add, per-line Save, delete, drag-reorder, optimistic pending rows | `modules/items/ui/Item/BillOfMaterial.tsx:279-365`, `BillOfProcess.tsx` |
+| 5 | Navigate structure | explorer tree with URL selection (`?materialId=`) that swaps Properties to the node | `components/BoMExplorer/BoMExplorer.tsx:179-195` |
+| 6 | See and adjust stock | per-location (`?location`, user default fallback) quantities + an adjustment modal | `routes/x+/part+/$itemId.inventory.tsx:46-77`, `InventoryStorageUnits.tsx:362-559` |
+| 7 | See supply & demand over time | planning chart + Supply & Demand card with document links | `ItemPlanningChart.tsx` |
+| 8 | Versions and revisions | New / Duplicate / Set Active in method tools; revisions from Used In | `MakeMethodTools.tsx:311-380` |
+| 9 | Where used | Used In tree grouped by module | `routes/x+/part+/$itemId.tsx:294-408` |
+| 10 | Notes, files, tags, custom fields | `ItemNotes` (debounced), `ItemDocuments`, tags + custom fields in Properties | `$itemId.details.tsx:336, 392`, `PartProperties.tsx:205-240` |
+| 11 | Delete / change notice / audit | header ⋯ | `PartHeader.tsx:82-133` |
+
+## 4. Wiring patterns (reuse them exactly)
+
+- **Autosave a field**: per-field `ValidatedForm` (validator = one zod field) around an
+ `inline` form field; `onChange`/`onBlur` → `onUpdate(field, value)` → `useFetcher().submit`
+ to the bulk update route; `useEffect` toasts `fetcher.data.error`. Skip the post when the
+ value didn't change.
+- **Explicit-save card**: `ValidatedForm` + zod validator from `{module}.models.ts` +
+ `Card` + `CardFooter <Submit>`; the route action validates with
+ `validator(schema).validate(formData)`, calls the service, `throw redirect(...)` with
+ flash on success (`.claude/rules/conventions-forms.md`).
+- **Line form, two containers**: one component, `type="modal" | "card"`, wrapped by
+ `ModalCardProvider`; create in a modal from the explorer, edit as a card in the content
+ pane (`packages/react/src/ModalCard.tsx`).
+- **Status transition**: `useFetcher` or `Confirm action={path.to.xStatus(id)}` with a hidden
+ `status` input; the route checks permissions and the transition.
+- **Optimistic state**: read `fetcher.formData` / `useFetchers()` for pending values rather
+ than local state (`BillOfMaterial.tsx:1366-1389`).
+- **Where a real page's form component can be reused, reuse it** (the line form, the notes,
+ the documents card). Redesigning a page means rearranging and improving the experience —
+ it does not mean re-implementing validated forms and domain rules from scratch.
+
+## 5. Locks
+
+- The client asks the model helper: `isSalesOrderLocked`, `isQuoteLocked`,
+ `isPurchaseOrderLocked`, `isSalesReturnOrderLocked` (`modules/sales/sales.models.ts:1094`,
+ `modules/purchasing/purchasing.models.ts`), plus `permissions.can("update", module)`.
+ Locked forms get `isDisabled`; explorers disable Add/Delete.
+- The server enforces it: `requireUnlocked` (redirect + flash) and `requireUnlockedBulk`
+ (error object for bulk updates) in `utils/lockedGuard.server.ts:23-67`.
+- Items: revision release lock and change-notice draft lock (`BillOfMaterial.tsx:194-198`,
+ `ReleaseLockAlert.tsx`, `items.server.ts:202-230`); a lock icon tooltip explains why.
+- A locked control stays visible and says why (tooltip or the status pill itself).
+
+## 6. Never acceptable
+
+- A read-only rendition of a page whose sibling is editable ("sample", "preview", "v1").
+- Disabled placeholder buttons standing in for actions you didn't wire.
+- New UI that re-implements a mutation the record's existing route already performs.
+- Dropping a capability the sibling has (notes, documents, reorder, audit log) without
+ saying why in the brief.
diff --git a/.claude/skills/carbon-design/references/page-archetypes.md b/.claude/skills/carbon-design/references/page-archetypes.md
index 0416d6e088..e16d45df58 100644
--- a/.claude/skills/carbon-design/references/page-archetypes.md
+++ b/.claude/skills/carbon-design/references/page-archetypes.md
@@ -100,6 +100,9 @@ RFQs, invoices, RMA, Job, Issue, Change Notice, Maintenance, Procedure, Training
`modules/purchasing/ui/PurchaseOrder/PurchaseOrderHeader.tsx` (downstream-doc dropdowns),
`modules/production/ui/Jobs/JobHeader.tsx` (derived badges, view switcher),
`modules/quality/ui/Issue/IssueProperties.tsx` (autosave properties).
+- **Capabilities** (add/edit/delete/reorder lines, autosave Properties, lifecycle routes,
+ notes, documents, downstream docs, audit log) — the full contract with exemplars is in
+ `functionality.md` §2. The shape above is only half the archetype.
- `$id._index.tsx` redirects to `$id.details`. Parent loader loads the record + lines; children
read them via `useRouteData(path.to.x(id))`.
diff --git a/.claude/skills/carbon-design/references/principles.md b/.claude/skills/carbon-design/references/principles.md
index 77459a3587..e28c82b923 100644
--- a/.claude/skills/carbon-design/references/principles.md
+++ b/.claude/skills/carbon-design/references/principles.md
@@ -8,7 +8,7 @@ you can ask of your own design.
## Contents
1. Who Carbon is for (the premise)
-2. The 19 principles
+2. The 20 principles
3. Carbon vs generic SaaS — the contrast table
4. How to decide when principles pull in different directions
@@ -223,6 +223,19 @@ helper) rather than building a parallel system that answers the same question di
- **Test:** *Did I open the source for every component, prop, path helper and column I used?
Does every special value the domain models have a designed rendering?*
+### P20. Worked on, not looked at
+Every Carbon screen is a place where work happens. The value a user reads is the value they
+can change, in the same place: a line opens into its editable form card, a header fact
+autosaves in Properties, a status moves with one primary click, a stock figure has its
+adjustment modal. All of it runs through the record's existing route actions, so the domain
+rules (sales rules, lock guards, price resolution, MRP) come along for free.
+- **Why:** users open a sales order to *change* it — the customer called about quantity,
+ price, a date. A beautiful read-only page sends them hunting for "the real one".
+- **Shows up as:** `ModalCard` line forms, per-field autosave Properties, status routes,
+ `is{Entity}Locked` + `requireUnlocked` (`references/functionality.md`).
+- **Test:** *Pick the three most common reasons a user opens this screen. Can they finish
+ each one here without leaving? Did I click through each one in a browser?*
+
---
## 3. Carbon vs generic SaaS
@@ -248,6 +261,7 @@ Use this table when a design "works" but feels generic.
| Numbers right-aligned with bold totals | Left-aligned list cells with `tabular-nums`; right alignment only in label→amount summaries; totals `font-semibold` |
| Undo snackbars | Confirm first; soft delete where reversible ("Deactivate", "Move to Trash") |
| Floating "+" action button | "Add X" primary in the table title bar (desk); FAB only in MES operation dock |
+| Read-only "view" pages with an Edit button elsewhere | The page you read is the page you edit; locks disable in place |
| Hover-scale animations, bouncy springs | Press `active:scale-[0.96]`, 150–200ms ease-out, property-scoped transitions |
| Wide-screen dashboards with many widgets | Content capped (`max-w-4xl` create, `max-w-5xl` posting docs, `max-w-[60rem]` settings); dashboards only on module landing pages |