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.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
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.mdindex 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 openworkspace — 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 workIdentify 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 itPick the archetype (`page-archetypes.md` §15) and open its exemplar files. Also find theclosest 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, lockedrows, mixed selections, multi-currency) and how each renders — reuse the domain's ownpredicates (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 wicomponent 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 isan 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 newshared 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 driftdiff --git a/.claude/skills/carbon-design/references/anti-patterns.md b/.claude/skills/carbon-design/references/anti-patterns.mdindex 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'sconstants 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.mdindex 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 clean3. **Walk the checklist below.** For every item answer PASS / FIX / N/A. Every FIX gets changednow, 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 adifferent 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 titlgrep -nE 'size="sm"' $FILES # MES files: every operator action is lggrep -nE '<div[^>]*(divide-y|grid-cols-\[)' $FILES # record list as divs? → TableBasegrep -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.mdnew file mode 100644index 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.mdindex 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; childrenread them via `useRouteData(path.to.x(id))`.diff --git a/.claude/skills/carbon-design/references/principles.md b/.claude/skills/carbon-design/references/principles.mdindex 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.## Contents1. Who Carbon is for (the premise)-2. The 19 principles+2. The 20 principles3. Carbon vs generic SaaS — the contrast table4. 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 |