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
@carbon/react
Shared UI component library — primitives, layout, data display, and overlays built on Radix, React Aria, and Tailwind.
Always
- Use existing components first. Grep
packages/react/src/before writing custom UI. Prefer built-invariantprops over ad-hocbg-*/text-*classes. - Use
cn()for class merging (import { cn } from "@carbon/react"— it'stwMerge(clsx(...))). Never raw string concatenation for conditional classes. - Components live flat in
src/(e.g.src/Button.tsx), not under acomponents/subdirectory. Follow this convention for new components. - Concentric border radius: outer radius = inner radius + padding. Card shell is
rounded-lg; don't re-add borders/radius on CardContent. - Popover inside Drawer/Dialog:
stopPropagationononWheel/onTouchMoveofPopoverContentto prevent scroll-lock from swallowing events. - Drawer closing animation: the panel slides out only when the
Drawerstays mounted and itsopenprop goes false.{item && <Drawer open />}removes it in the same render, so nothing animates — keep the record while it closes (useDrawerItemin the ERP,~/hooks). The positioning div inDrawerPortalruns a no-op exit animation matched to the panel's closing duration; Radix unmounts the portal as soon as that div stops animating, so change the two durations together.
Ask First
- Adding a new Radix/React Aria primitive dependency
- Changing the public API of
Button,Card,ModalDrawer, or other widely-used components - Modifying the barrel export in
src/index.tsx
Never
- Use
transition-allwhen a scoped transition (transition-transform,transition-colors) works - Create icon-only buttons without
aria-label— useIconButtoncomponent instead - Import from deep paths (
@carbon/react/src/Button) — always use the package barrel or named sub-exports (@carbon/react/Editor,@carbon/react/Chart)
Validation Commands
pnpm --filter @carbon/react typecheck
pnpm --filter @carbon/react test
pnpm --filter @carbon/react lint
Key Patterns
import { Button, Card, HStack, VStack, IconButton, cn } from "@carbon/react";
- Button variants:
primary | secondary | solid | active | destructive | ghost | outline | link; sizes:sm | md | lg;shortcut/hideShortcutKey/shortcutGuardbind a hotkey with a keycap badge (topmost-dialog guarded) - Shortcuts: combos are named constants — shared
SHORTCUTSinsrc/shortcuts.ts, never string literals at call sites.useShortcutKeys(one binding) anduseShortcutKeyMap(entries array, dev-warns on duplicates) both delegate to react-hotkeys-hook — never add a hand-rolled keydown listener;useShortcutSequence(g-then-letter) is the lone exception (no library sequence support).isEditableTarget(the one editable-target check;isTextEntryTargetis its fields-only half, for menu keys); menu items takeshortcut={MENU_ITEM_SHORTCUTS.x}, live only while their menu is open,ShortcutHelpOverlay(the?overlay; apps declare entries). Enter vs ⌘Enter and badge visibility are design decisions — see.claude/rules/conventions-ui.md§ Keyboard shortcuts - Choice screens:
ChoiceCardGroup(card radios,autoFocusfocuses the selected card) andRadioGroupButton(radio styled as a secondary Button) give one tab stop + arrow-key select; Enter stays free for the screen's continue action - Layout:
VStack/HStackwith numericspacingprop (maps tospace-y-*/space-x-*) - Overlays:
Drawer,Modal,ModalDrawer(unified drawer/modal),BottomSheet,Popover. A controlledModal/Drawerwith noonOpenChangecannot be dismissed and shows no close button; never pass a handler that does nothing (no-noop-open-changecheck). A route rendered as a modal or drawer closes withuseCloseRoute()(back when this tab has history, else the parent route), notnavigate(-1) - Status: a pill shows a tooltip only when given
tooltip(extra detail) oriconOnly— never one repeating its label.iconOnlyrenders just the coloured icon, with the label in an always-on tooltip and as thearia-label(string children only) — for dense rows and narrow drawers.TooltipContenttakesanchorto position against a different element than the trigger, when one tooltip serves many small hover targets (a strip of bars) - App nav:
NavRailis the primary left nav of both the ERP and MES shells (56px icon rail, grows to 240px after a 150ms mouse hover or when pinned, left drawer below md that closes itself on navigation). The rail renders a pin toggle beside itsheaderwhile expanded (it callsSidebarProvider'stoggleSidebar; ⌘B also pins, unless the provider getskeyboardShortcut={false}). Unpinning (the toggle, ⌘B or a page'sSidebarTrigger) collapses the rail at once, also under the mouse; hover cannot reopen it until the pointer leaves the rail. The pin is not persisted: both apps passdefaultOpen={false}, and the provider writes no cookie (see.ai/lessons.md, "A cookie that was only ever written"). Optionalheaderandfooterslots; the header is aNavRailSwitcher— the company's logo (logoLight/logoDark, falling back to an initialsAvatar) in the icon column with its name fading in, a menu trigger or, withasChild, a link, and a full-width row on phones;NavRailGroupadds a titled section that shows as a divider while collapsed. Entries areNavRailItem(a button, orasChildfor a trigger/link) andNavRailLink;labelis a string and doubles as the accessible name. A Radix menu/popover opened from aNavRailItemorNavRailSwitcherkeeps the rail as it was (open or collapsed) until it closes. Render insideSidebarProvider; the shadcn-styleSidebar*primitives remain for other layouts - Links that prefetch:
PrefetchLinkis a React RouterLinkthat prefetches its destination when the pointer goes down on it. Use it instead of<Link prefetch="intent">, which prefetches on a 100 ms hover and so runs a page's loaders for every row the mouse passes over. The click reuses the prefetch only becauseprefetchCacheMiddleware(@carbon/utils, in each app's rootmiddleware) gives a prefetch response a few seconds of private cache; without it both requests reach the server and the click waits behind the prefetch.NavRailLinkand both apps'Hyperlinkalready use it - Record outlet:
RecordOutletis the<Outlet>of every route under/x. It remounts the page inside it when that page is shown for a different record (the params of the route in the outlet, not of a drawer below it), so nothing seeded from the previous record survives. A plain<Outlet>there fails theno-bare-outletcheck - Data:
Table(TanStack), chart components via sub-exports (@carbon/react/Chart) - Rich text:
@carbon/react/Editorand@carbon/react/RichText(wraps@carbon/tiptap). Read-only rich text isRichTextView.generateHTMLreturns""on the server and hydration keeps a serverdangerouslySetInnerHTMLas it is, so__html: generateHTML(…)on a page's first load stays empty;RichTextViewsets the HTML once the page has hydrated - Error boundary:
@carbon/react/ErrorBoundary—RouteErrorBoundary(exported asErrorBoundaryfrom a module layout so a failed loader shows inside the app shell; it shows the status code and, for a 4xx, the message the server threw —routeErrorCopy— so throw aResponsewhose body says what was wrong. A 5xx or thrownErrorgets generic copy) andRootErrorBoundary(drop-in rootErrorBoundaryfor RR v7 that maps 404 / 503 (the maintenance screen) / other HTTP / thrownErrorto a styled screen) plus its parts (ErrorScreen,GlitchHeading,StatusReadout,MagneticLink,NoiseOverlay). Both read a request that got no response (isNetworkError: aTypeErrorwith one of the browsers' fetch-failure messages) as a lost connection, not a fault, anduseNetworkRetryrevalidates when the browser is back online or the tab is shown again, which clears the error. Wrap it in the app'sDocumentand passenvsowindow.envis set (the client crashes hydration otherwise). Copy is intentionally hardcoded English, not i18n. - Avatar:
srcmay be a URL or a generated-avatar value fromuser.avatarUrl(dicebear:<style>:<seed>[:<rrggbb>]; the styles and value helpers are in@carbon/utilsavatar.ts). A generated value renders as a plain<img>ofgeneratedAvatarUrl(value)(utils/generatedAvatarImage.ts, whichAvatarimports instead of the renderer so no bundle that shows an avatar carries DiceBear) —/file/avatar/:value?v=<GENERATED_AVATAR_RENDER_VERSION>— so it is in the server-rendered HTML and needs no client JavaScript. Every app (ERP, MES, academy) serves that path with a one-line route re-exportinggeneratedAvatarLoaderfrom@carbon/react/GeneratedAvatar: it draws the SVG on the server with DiceBear 10 and answersCache-Control: public, max-age=31536000, immutable, so a refresh reads it from the browser cache. BumpGENERATED_AVATAR_RENDER_VERSIONwhenever the same value would draw differently (a DiceBear upgrade, a change to the rendering options), or browsers keep the old image. The avatar picker draws in the browser instead (GeneratedAvatarPreview,useGeneratedAvatar), because a color drag makes a new value per step; there the DiceBear core and each style's JSON load withimport()(STYLE_LOADERS, typedRecord<GeneratedAvatarStyle, …>), never with awith: { type: "json" }attribute (Vite passes it to the browser, which rejects the JSON Vite serves as JavaScript, and the picker stays grey); the server side instead bundles@dicebear/stylesthroughssrNoExternalin each app'svite.config.ts, because Node refuses a package's JSON without the attribute.generatedAvatarClassName(style)picks the image classes: line-art styles on white (bg-white) in both themes, color styles onbg-muted. A value's optional background goes to DiceBear asbackgroundColor; on a dark one (isDarkBackground, WCAG contrast) the styles that draw lines straight onto the background (INK_OPTIONS) get white ink. The appAvatarwrappers turn a stored value intosrcwithavatarSrc(@carbon/utils); a new user has no avatar (initials) until they choose one - Announcement:
AnnouncementBaris the one-line bar both shells render above their page area for the deployment's announcement. It remembers a dismissal in localStorage per user and announcement id, and while shown sets--announcement-heighton<html>; the ERP's--content-insetincludes it, and a page sized from100dvhoutside that variable must subtract it - Seasonal decorations:
@carbon/react/HalloweenexportsHalloweenLayer(mounted once in each app shell). It renders nothing unless the root loader's theme ishalloween, and everything but that entry file loads in its own chunk. Keep everything seasonal inside that folder: the removal checklist is the header ofsrc/Halloween/HalloweenLayer.tsx. - Polish: shadows over borders,
tabular-numsfor dynamic numbers,active:scale-[0.98]on pressables,text-balance/text-prettyfor text wrapping
Cross-References
.claude/rules/conventions-ui.md— full UI conventions, polish principles, review checklist@carbon/tiptap— editor extensions used byEditor/andRichText/@carbon/content/glossary— term definitions used byLabelWithHelp@carbon/form— form field components (import from~/components/Formin apps, not directly)