`s so spacing stays on the system's scale. Use design tokens for every value (`var(--color-*)`, spacing tokens), never raw hex or px. Reserve Badge for counts and enumerated states; status belongs on a status indicator. **The house-system bridge (resolve the tension):** the CSS mechanics in Sections 5-10 (scroll ownership, `position:sticky` headers, frozen-column offsets, z-index tiers, `min-width:0`) are the **contract a mature system's hooks already satisfy** under the hood. Inside such a system, reach for the hook or plugin first, because a real sticky-column hook gives you the offset, the solid background, and the shadow divider correctly. Drop to the raw CSS contract only (a) to verify the system did it right when something bleeds through, or (b) when you are outside a design system entirely. Never hand-roll a sticky column with inline styles inside a system Table when the hook exists. ### 2.B External systems (match the host, or pick by archetype) | Archetype / brief | Reach for | Why | |---|---|---| | IBM-style enterprise analytics, dense grids | `@carbon/react` + `@carbon/styles` | Most mature data-density + 2x-grid + empty/loading patterns [carbon] | | Microsoft / enterprise SaaS, DataGrid | `@fluentui/react-components` (v9) | Official Fluent 2, Overflow primitives, tokens [fluent] | | Atlassian / Jira-style product | `@atlaskit/*` + `@atlaskit/tokens` | Semantic spacing tokens chosen by meaning [atlaskit] | | Merchant/admin, resource lists | Polaris (`@shopify/polaris` or web components) | IndexTable, four-states philosophy, error content [polaris] | | GitHub-style devtool chrome | `@primer/react` / `@primer/css` | PageLayout landmarks, Blankslate, Truncate [primer] | | Adaptive/canonical layouts, consumer-ish | `@material/web` + Material 3 tokens | Window-size classes, list-detail/supporting-pane [material3] | | Own-the-code lean internal tool | Radix Primitives + shadcn/ui + TanStack Table | Headless a11y primitives, you own styling [radix, tanstack] | | Enterprise React data-dense fast | Ant Design or Mantine + Mantine React Table | Batteries-included Table/Form [ant, mantine] | | Lean keyboard-first (Linear/Vercel vibe) | Radix/shadcn + custom tokens | Density + command palette + restraint [linear, vercel] | **Honesty rule:** if the app is one of these, use the official package and its Table/Form/Dialog. Do not recreate Carbon's data table in raw CSS. Do not import a system's tokens then override 90% of them. --- ## 3. FRAME-FIRST APP-SHELL ARCHITECTURE **Budget the frame in pixels before writing one line of content.** Real applications are built top-down: pick the shell, name its regions, give each an explicit px budget, decide its container policy and responsive behavior, then fill. Content-first layout (write sections, wrap each in a Card) produces a padded scroll column that reads as a prototype. [most systems' layout docs] ### 3.A Pick the shell - **AppShell** (header and/or side nav) - the default full-page product frame. - **Layout + LayoutContent + LayoutPanel** - multi-pane tools: explorers, consoles, master-detail with an inspector. - **Plain content column** - a single form, a settings section, a wizard. ### 3.B Region px budgets (memorize these) | Region | Budget | |---|---| | Side nav | 240-280px | | Icon rail (collapsed nav) | 64-72px | | Detail / inspector panel | 340-420px (resizable 320-480) | | Filter / facet rail | 220-260px | | Row height | 32px compact / 40px standard / 48px comfortable [dense systems budget 32-40; Carbon ships 5 relative tiers, no fixed px] | | Header / top nav | 48-64px (common app-bar convention) | ### 3.C Landmark regions (do not conflate them) Name every region with a real landmark and know the difference [primer PageLayout]: - **Header** - full width, top, app chrome. - **Content** - the primary region, flexes to fill. - **Pane** - a secondary region **beside** Content, content-height only. Use for an inspector or supporting info. - **Sidebar** - **full-height** navigation, distinct from Pane. Never build a "sidebar" that is really a content-height pane, or a "pane" that is really full-height nav. - **Footer** - full width, bottom (status bar, pagination context). ### 3.D Canonical layouts (recognize and scaffold) [material3] - **List-detail** - list on the left, selected record on the right. Below ~1024px, detail overlays or becomes a separate route. - **Supporting-pane** - primary content ~2/3, supporting pane ~1/3. - **Feed** - a single scrolling stream (rows/bubbles, no cards in the stream). - **Master-detail with inspector** (the tool backbone) - selecting a row opens a **fixed-width LayoutPanel inspector**, it does not navigate away. Add `resizable`. Overlay it below ~1024px instead of compressing Content. ### 3.E App-shell chrome that marketing UI never has - **Workspace / org switcher** - almost every SaaS shell needs one, anchored top of the side nav or header-left, showing the current tenant's name/avatar. On click, a dropdown (not a modal) lists workspaces with a search field once there are 8+, a "recent workspaces" group, and a "create/join" action at the bottom. It switches context (data scope), it is not a nav destination. Keep it one element; never scatter tenant choice into the nav list. Persist the last-active workspace per user. - **Global command palette** (Cmd/Ctrl-K) - for DATA_COMPLEXITY >= 2 keyboard-first tools, this is the fastest navigation. Recognize it as a first-class shell affordance, not a nice-to-have. - **Background-job / async status tray** - when the app kicks off concurrent long-running operations (imports, exports, deploys), a persistent notification tray (a header icon with a count badge opening a dropdown of jobs) beats a modal per job. Each job row shows a determinate progress bar, a cancel affordance, and terminal success/error with a result link. Carbon's rule: for waits over a few minutes, let the user leave and notify on completion. Never block the whole UI on one background job. [carbon loading] ### 3.F Container policy per region (Cards vs Rows, decided per archetype) | Archetype | Container policy | |---|---| | Tracker / work tool (issues, tickets, CRM) | Rows only. Grouped edge-to-edge lists, zero cards. | | Console / observability | Card grid for dashboard widgets; Table for everything else. | | Messaging / feed | Rows and bubbles. No cards in the stream. | | Media / gallery | Card grid (ClickableCard) + dense metadata rows in detail. | | Settings / forms | FormLayout sections; Card only to group dangerous/billing actions. | Banned: a Card per list item (card soup), stacked full-width Cards as page structure, nested Cards, Badge as decoration. --- ## 4. LAYOUT HARD RULES (Failing any of these ships broken work) * **SCROLL OWNERSHIP (the #1 product-UI layout bug).** Exactly **one** wrapper owns each scroll axis (`overflow:auto`). The page `` must **never** scroll horizontally. A wide table scrolls inside its own container, not by pushing the whole app sideways. Sticky headers use `position:sticky` scoped to that scroll wrapper, **never** `position:fixed` to the viewport. [carbon, ant table-scroll, tanstack] If two nested elements both scroll the same axis, you have a bug. * **Every sticky element needs a bounded-height ancestor.** `position:sticky` silently does nothing if no ancestor establishes a scroll boundary. A sticky table header requires the table's scroll container to have a real max-height. [css mechanics] * **min-width:0 on flex children that hold text.** A flex/grid child defaults to `min-width:auto`, which refuses to shrink below content size, so `text-overflow:ellipsis` silently no-ops and the child pushes the layout wider instead. Any truncating text inside a flex row needs `min-width:0` on the text-holding child. This is the most common reason "my ellipsis isn't working." [overflow-truncation] * **Responsive contract declared up front, per region.** Before filling, write which regions collapse, overlay, or drop at which breakpoints. No "Tailwind will handle it" assumptions. Nav collapses to an icon rail or off-canvas MobileNav; the inspector overlays below ~1024px; a wide table keeps horizontal scroll rather than reflowing columns. * **Breakpoints: use size classes, not device names.** Compact / medium / expanded (Material 3) or Carbon's exact 2x-grid breakpoints (320 / 672 / 1056 / 1312 / 1584, 8px mini-unit, 16px padding, 32px gutter) as a fallback grid. [material3, carbon 2x-grid] * **Container queries for reusable components.** A card or panel that appears in a wide Content region and a narrow Pane must respond to **its own** width, not the viewport. Use `container-type` + `@container`, not viewport media queries, for anything that renders in more than one region width. [joshwcomeau, responsive-layout] * **Sidebar collapse = off-canvas or icon-rail, not in-place shrink.** Collapsing a 260px nav to 180px just cramps it. Collapse to a 64-72px icon rail (with tooltips) or slide it off-canvas with a persistent reopen strip. Persist which panes were shown across a resize/fold so the user does not lose context. * **Density is a layout MODE, not a CSS zoom.** Offer at least the density presets the DENSITY dial calls for as a real switch (row height + padding token swap), not a browser-zoom hack. [i18n-a11y-density, carbon 5 row heights] * **Never hardcode a fixed width on a text container.** Badges, buttons, table headers, chips, tags must be auto-layout (flex/grid, hug-contents) so text can reflow or expand. A fixed-width text container clips under real data and under translation (Section 10.B). * **Tabular numbers for compared numbers.** Any column or list of numbers the user compares vertically uses `font-variant-numeric: tabular-nums` so digits align. Proportional digits in a metrics column is a Tell. --- ## 5. OVERFLOW & TRUNCATION CATALOG (Deep-Dive) Product UI is where real strings arrive: a 90-character file path, a German button label, a customer name that is one word or forty. Truncation is a scalpel, not a default. ### 5.A The never-truncate list (mandatory) **Never truncate primary/identifying content**: titles, entity names, unique IDs, error and validation messages, page headers, button labels. Truncation is for **secondary/supplementary** content only (descriptions, secondary metadata, breadcrumb middles). [carbon overflow, primer truncate] If an identifying string is too long, wrap it, give it more space, or use middle-truncation that preserves both ends (for paths/IDs) - never a trailing ellipsis that hides the part that distinguishes two records. ### 5.B Every truncated string needs a real full-text fallback A hover-only `title` tooltip is **not** an accessible fallback: it fails keyboard-only users, touch users, and speech-recognition users. Provide the full text on focus as well as hover, or expandable inline, or in the detail view. [carbon, primer] ### 5.C Long button labels (mandatory, a signature product-UI Tell) **Never truncate a button label.** Size the button to its content ("hug contents") with a `min-width` floor for tap-target accessibility. If the label is long (or translated), wrap to at most 2 lines before you ever truncate, and re-evaluate the label copy. A button reading "Save chang..." is broken work. Icon-only buttons need an `aria-label` and a tooltip. [overflow-truncation, i18n] ### 5.D Single-line ellipsis recipe `overflow:hidden; text-overflow:ellipsis; white-space:nowrap;` **plus** `min-width:0` on every flex ancestor between the text and the scroll/row container (Section 4). Without the `min-width:0` chain, the CSS is inert. ### 5.E Multi-line clamp recipe (`-webkit-line-clamp`) All four properties together or none work: `display:-webkit-box; -webkit-line-clamp:N; -webkit-box-orient:vertical; overflow:hidden;`. **Never put padding on the clamped element itself** - the clamp math ignores padding and text bleeds. If you need padding, wrap the clamp in a padded parent, or use a fixed-height fallback (`line-height * N`). [css-tricks line-clampin] ### 5.F Content edge cases: counts, big numbers, missing data (mandatory) Real data is 0, 1, or 1,000,000 - design all three, not just the demo's "3." - **Zero / one / many (pluralization):** every count string handles 0, 1, and N with correct grammar - "0 items," "1 item," "24 items," never "1 items" or "24 item." Use an ICU/plural-aware formatter, never string concatenation; some languages have up to 6 plural forms. The zero case usually routes to an empty state (Section 6.C), not "0 items" sitting in a full layout. - **Very large / very precise numbers:** abbreviate for scannability in dense contexts (1.2k, 3.4M, 1.1B) but keep the exact value reachable on hover/focus and in the detail view; **never abbreviate a number the user must act on precisely** (an invoice total, an account balance). Locale-aware grouping (1,234.56 vs 1.234,56), tabular-nums for compared columns (Section 4), and a consistent threshold before switching to abbreviation. - **Missing / null / not-applicable (general rule, not just table cells):** a null field renders a consistent, quiet placeholder ("Not set," "-," "Unknown") that is visually distinct from an empty string and from zero. Decide per field whether null means "not set yet" (invite input), "not applicable" (explain briefly), or "hidden by permission" (Section 6.G) - three different placeholders, never one blank that reads as a render bug. - **Long unbroken tokens** (URLs, hashes, file paths, IDs with no spaces): use middle-truncation that keeps both ends, or `overflow-wrap:anywhere`, never a trailing ellipsis that hides the distinguishing tail, and never let the token blow out its column width. ### 5.G Column-header and chrome overflow - **Column headers**: wrap to 2 lines, then truncate with a tooltip carrying the full header. [carbon] - **Breadcrumbs**: collapse the middle to an ellipsis/overflow-menu, keep first and last. [carbon overflow] - **Toolbars / action bars / tabs**: use priority-plus overflow (Fluent Overflow): declare a visible-priority order and a `minimumVisible` floor, move the rest into a "More" menu, render in reverse DOM order so the first item wins. [fluent] - **Long free content blocks**: "Show more / Show less" for expandable prose, "Load more" for lists (Section 7.D). --- ## 6. STATE MATRIX (Deep-Dive) Every data surface has more than a happy path. Design the full matrix at **three granularities**: page, component/region, and field. The slop failure is reusing one grey box for every non-happy state. ### 6.A The four base states, always designed together For any region that loads data, design **ideal / loading / empty / error** before you ship the ideal. [polaris four-states, nngroup] ### 6.B Loading timing thresholds (mandatory) - **< 1s**: show nothing. A flash-and-vanish skeleton is worse than a beat of stillness. - **1-10s, full-page/region load**: a **skeleton that mirrors the real layout shape** (the actual rows/fields it will become), never a frame-only grey box, never a spinner for structured content. [nngroup skeleton, carbon loading] - **> 10s, or unknown-length work** (uploads, downloads, conversions, deploys): a **determinate progress bar**, never an indeterminate spinner or skeleton. For multi-minute work, let the user leave and notify on done. [carbon] - **Background refresh of already-shown data**: keep the old content visible with a subtle inline indicator. **Never re-blank** cached content to a spinner/skeleton on refresh. ### 6.C Empty states are three distinct states (mandatory) Never reuse one empty component/message across these: 1. **Never-used-yet (first run)** - onboarding tone: what this is + a primary CTA to create the first record. [primer empty-states, pencilandpaper] 2. **Filtered/searched to nothing** - "no results for X," with a clear-filters action. The data exists; the filter is the cause. 3. **Zero-as-a-win** - "inbox zero," "no alerts." Positive tone, no guilt CTA. [carbon empty-states, atlaskit empty-state] For tiny tiles/side-panels, a centered text-only empty state is the exception to "mirror the layout." ### 6.D Error states are never empty states A load failure is **always** an ErrorState, never an EmptyState. Error copy is specific, plain-language, actionable (what to do next), and carries an error code/id for support. Route all of them through one shared ErrorState component so tone and layout stay consistent; never ship a bare "An error occurred." [polaris error-messages, nngroup] ### 6.E Field and inline states Fields have their own micro-states: pending async validation (Section 8.D), inline error, success confirmation, saving/saved (autosave, Section 8.E). Do not let a field-level failure silently no-op. ### 6.F Partial, stale, and offline states (mandatory to consider) Between "loaded" and "failed" live the states real networks produce: - **Partial load / partial failure:** when a composite view loads and one widget fails, fail **that widget in place** (its own inline ErrorState + retry), never blank the whole page for one failed panel. A dashboard where one broken tile kills every tile is a bug. - **Stale / cached / refreshing:** show last-known-good data with a subtle "updating" indicator and a "last updated " stamp; never re-blank to a skeleton on a background refresh (Section 6.B). On refresh failure, keep the stale data and surface a non-blocking "couldn't refresh, showing data from " notice. - **Offline / disconnected:** detect connection loss, show a persistent non-modal banner, disable or **queue** mutations, and reconcile on reconnect. Never let a user type into a form that silently cannot save. - **Optimistic update contract:** if you render a mutation before the server confirms, you MUST have a rollback path - restore the prior value and show a clear error if the write fails. An optimistic update with no rollback is a data-integrity Tell. ### 6.G Permission and plan states (product-UI-only, mandatory to consider) Marketing UI has no concept of these; product UI lives on them: - **Permission-denied / role-gated**: decide **disabled vs. hidden** deliberately. Hide an action the user can never have; disable (with a reason on hover/focus) an action they could have with a role change. Never show a dead control with no explanation. - **Read-only mode**: present the same layout with inputs rendered as static values and a clear "read-only" affordance, not greyed-out inputs that look broken. - **Plan/license-locked**: a locked-feature affordance ("Upgrade to unlock") is a distinct state with its own component - visible, explained, with an upgrade path - not a disabled button. [Keep it consistent with whatever precedent the host app already sets.] --- ## 7. DATA TABLE DEEP-DIVE (The Hardest Product Surface) Gate depth by DATA_COMPLEXITY. A simple list needs 7.A-7.B; an enterprise grid needs all of it. **Inside a design system, use its `Table` plus the system's plugins/hooks; the mechanics below are the contract those hooks satisfy, and your guide when you are outside one.** ### 7.A Scroll ownership and sticky header (mandatory) One wrapper owns both axes (`overflow:auto`) with a bounded height; the page never scrolls sideways (Section 4). Sticky header via `position:sticky; top:0` **scoped to that wrapper**. [carbon, ant table-scroll] ### 7.B Frozen / pinned columns (mandatory recipe) `position:sticky` + explicit `left:0` (or `right:0`) offset + `z-index >= 10` (above the scrolling body) + a **solid, non-transparent background that also covers hover and selected-row states** + an **inset `box-shadow` divider, never a CSS `border`** (borders disappear or double-render under sticky scroll). Miss the solid background and the scrolling content bleeds through the frozen column. [ant, mantine-react-table column-pinning, tanstack] ### 7.C Virtualization (DATA_COMPLEXITY 3) Virtualize past ~100-200 rows. Required DOM shape: **two wrappers** - outer = viewport-height scrollable, inner = full virtual-content height (a spacer). **Never size the `

` for layout, tokens only, Badge for counts only, status via a status indicator? - [ ] **No product-UI Tells** from Section 15; **zero em-dashes** anywhere visible? - [ ] **One design system** per app (no Carbon + Fluent mixed)? If a single box cannot be honestly ticked, fix it before delivering. --- # APPENDICES - Source-Backed Reference Material ## Appendix A - Install / CLI per system ```bash # House design system - resolve the real API before writing UI. # Most systems ship a CLI or a docs site; use whichever exists. # 1. find the closest shipped page/block template # 2. study its layout skeleton # 3. read real props for every component (never invent props) # IBM Carbon npm install @carbon/react @carbon/styles # Microsoft Fluent UI React v9 npm install @fluentui/react-components # Atlassian Atlaskit (per-component + tokens) npm install @atlaskit/tokens @atlaskit/dynamic-table # Shopify Polaris npm install @shopify/polaris # GitHub Primer React npm install @primer/react styled-components # Radix Primitives + shadcn/ui + TanStack Table npm install @radix-ui/react-dialog @radix-ui/react-toast @tanstack/react-table npx shadcn@latest add table dialog # Material Web (Material 3) npm install @material/web # Ant Design / Mantine + Mantine React Table npm install antd npm install @mantine/core @mantine/form mantine-react-table ``` ## Appendix B - Canonical sources (real URLs, gsearch-verified) Consolidated primary sources: **Frame / layout** - Carbon 2x grid: https://carbondesignsystem.com/elements/2x-grid/usage/ - Primer PageLayout: https://primer.style/product/components/page-layout - Material 3 canonical layouts: https://m3.material.io/foundations/adaptive-design/canonical-layouts - Material 3 list-detail: https://m3.material.io/foundations/layout/canonical-examples/list-detail - Material 3 supporting-pane: https://m3.material.io/foundations/layout/canonical-examples/supporting-pane - Container queries: https://www.joshwcomeau.com/css/container-queries-unleashed/ **Overflow / truncation** - Carbon overflow content: https://carbondesignsystem.com/patterns/overflow-content/ - Primer Truncate: https://primer.style/product/components/truncate/ - CSS line-clamp: https://css-tricks.com/line-clampin/ **State matrix** - Polaris EmptyState: https://polaris-react.shopify.com/components/layout-and-structure/empty-state - Carbon empty states: https://carbondesignsystem.com/patterns/empty-states-pattern/ - Carbon loading: https://carbondesignsystem.com/patterns/loading-pattern/ - Primer empty states: https://primer.style/product/ui-patterns/empty-states/ - NN/g skeleton screens: https://www.nngroup.com/articles/skeleton-screens/ - NN/g empty-state design: https://www.nngroup.com/articles/empty-state-interface-design/ - Pencil&Paper empty states: https://www.pencilandpaper.io/articles/empty-states - Polaris error messages: https://polaris-react.shopify.com/content/error-messages **Data table** - Carbon data table: https://carbondesignsystem.com/components/data-table/usage/ - Polaris IndexTable: https://polaris-react.shopify.com/components/tables/index-table - Ant table scroll: https://ant.design/docs/blog/table-scroll-ghost/ - Ant virtual table: https://ant.design/docs/blog/virtual-table/ - TanStack column sizing: https://tanstack.com/table/latest/docs/guide/column-sizing - Mantine React Table column pinning: https://www.mantine-react-table.com/docs/guides/column-pinning - NN/g infinite scroll: https://www.nngroup.com/articles/infinite-scrolling-tips/ - Baymard checkout linear / pagination context: https://baymard.com/blog/checkout-process-should-be-linear - Pagination vs infinite vs load-more: https://www.smashingmagazine.com/2016/03/pagination-infinite-scrolling-load-more-buttons/ **Forms / flows** - LukeW web form design: https://www.lukew.com/ff/entry.asp?504 - NN/g web form design: https://www.nngroup.com/articles/web-form-design/ - NN/g form errors: https://www.nngroup.com/articles/errors-forms-design-guidelines/ - Polaris inline error: https://polaris-react.shopify.com/components/selection-and-input/inline-error - Ant / 2x form pattern: https://2x.ant.design/docs/pattern/form - Mantine form validation: https://mantine.dev/form/validation/ **Overlays / layering / a11y** - Radix Dialog: https://www.radix-ui.com/primitives/docs/components/dialog - Radix Toast: https://www.radix-ui.com/primitives/docs/components/toast - W3C ARIA alertdialog: https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/ - W3C ARIA dialog-modal: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ - W3C ARIA grid data-grids: https://www.w3.org/WAI/ARIA/apg/patterns/grid/examples/data-grids/ - MDN stacking context: https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Positioned_layout/Stacking_context **Tokens / density / i18n** - Atlaskit design tokens: https://atlassian.design/foundations/design-tokens - Atlaskit spacing: https://atlassian.design/foundations/spacing - Crowdin UI localization: https://crowdin.com/blog/best-practices-for-ui-localization - Material 3 accessibility (targets): https://m3.material.io/components/buttons/accessibility **Modern minimal** - Linear method: https://linear.app/method/introduction - Vercel design guidelines: https://vercel.com/design/guidelines