Saleor Dashboard Styling

Two strategies for styling components. Choose based on complexity.

Entity detail vs Configuration: Entity detail chrome and in-page settings use the **Detail family (DetailSettingsCard, DetailSectionNav, …). Configuration hubs use Settings** in src/components/Settings/. Do not mix. See [saleor-dashboard-entity-detail](./saleor-dashboard-entity-detail/SKILL.md) for page anatomy, card vs section criteria, primary/secondary headers, channel availability tiers, and Vercel-aligned restraint rules.

Elevation: Use shadows sparingly. When a surface truly floats (modal, popover, menu, setup checklist), follow [saleor-dashboard-smooth-shadow](./saleor-dashboard-smooth-shadow/SKILL.md) — never border + box-shadow on the same elevated node.

Strategy 1: Box Inline Props (Simple Styles)

Use <Box> from @saleor/macaw-ui-next when you need a few CSS properties (layout, spacing, colors).

import { Box, Text } from "@saleor/macaw-ui-next";

<Box display="flex" gap={2} alignItems="center" padding={4} backgroundColor="default1">
  <Text color="default2" size={2}>
    Label
  </Text>
</Box>;

Box supports sprinkle props for: display, flexDirection, alignItems, justifyContent, gap, padding, margin, width, height, borderRadius, backgroundColor, position, cursor, opacity, flexGrow, flexShrink, flexWrap, gridTemplateColumns, gridColumn, order.

All spacing/sizing props accept token numbers: 0 | 0.5 | 1 | 1.5 | 2 | 2.5 | 3 | 3.5 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 14 | 16 | 20 | 24 | 28 | 32 | 36 | 40 | 44 | 48 | 52

Responsive values work for layout props only (display, grid, flex, order, …):

<Box display={{ mobile: "none", tablet: "flex", desktop: "grid" }} />

Do not use responsive objects for spacing (padding, margin, gap). Macaw types allow it, but runtime sprinkles only accept state conditions (default / hover / …) for those props and will throw SprinklesError (breaks Storybook + Jest + the live app). Use a CSS module media query instead:

.root {
  padding-inline: var(--mu-spacing-6);
}
@media (max-width: 768px) {
  .root {
    padding-inline: var(--mu-spacing-3);
  }
}

Escape hatch for arbitrary CSS values via __ prefix:

<Box __width="25%" __transition="background-color 0.2s ease" __minWidth="200px" />

Hover/state-dependent values:

<Box backgroundColor={{ default: "transparent", hover: "default2" }} />

When Box Props Are Enough

• Flex/grid layouts with spacing
• Padding, margin, gap adjustments
• Background and text colors from the design system
• Border radius
• Simple responsive breakpoints

Strategy 2: CSS Modules (Complex Styles)

Use .module.css when you need pseudo-selectors, animations, media queries, complex selectors, or more than ~5 CSS rules.

Create ComponentName.module.css next to ComponentName.tsx. One CSS file per component. Never share CSS module files across components.

/* SearchInput.module.css */
.input {
  flex: 1;
  border: none;
  outline: none;
  background-color: transparent;
  font-size: 14px;
  color: var(--mu-colors-text-default1);
  min-width: 0;
}

.input::placeholder {
  color: var(--mu-colors-text-default2);
}

// SearchInput.tsx
import styles from "./SearchInput.module.css";

<input className={styles.input} />;

When to Use CSS Modules

• Pseudo-selectors: ::placeholder, :hover, :focus, [data-state="open"]
• Animations/transitions: @keyframes, complex transition
• Media queries: @media (min-width: 960px)
• Nested/compound selectors: .row:hover .icon
• More than ~5 CSS rules for a single element

CSS Module Patterns

Hover reveal:

.row .icon {
  opacity: 0;
  transition: opacity 0.15s ease-in-out;
}
.row:hover .icon {
  opacity: 1;
}

Collapsible rotation:

.chevron {
  transition: transform 0.2s ease;
  transform: rotate(-90deg);
}
button[data-state="open"] .chevron {
  transform: rotate(0deg);
}

Responsive layout:

.sidebar {
  display: none;
}
@media (min-width: 1200px) {
  .sidebar {
    display: block;
  }
}

Design Tokens

Always use macaw CSS variables instead of hardcoded values (especially colors, spacing, borders).

In CSS Modules

Use var(--mu-*) variables. Read the full list from: node_modules/@saleor/macaw-ui/dist/style.css

Common patterns:

color: var(--mu-colors-text-default1);
background-color: var(--mu-colors-background-default2);
border: 1px solid var(--mu-colors-border-default1);

In TypeScript

Import vars from @saleor/macaw-ui-next for JS-accessible tokens:

import { vars } from "@saleor/macaw-ui-next";

vars.spacing[2]; // spacing token
vars.colors.border.default1; // border color
vars.colors.text.default2; // text color

Full TypeScript token structure: node_modules/@saleor/macaw-ui/dist/theme/contract.css.d.ts

Foldable sections (DetailGroupBox)

For expandable/collapsible sections on detail and create pages, use DetailGroupBox — not the legacy @dashboard/components/Accordion wrapper and not a one-off Macaw Accordion with custom chrome.

Component: [src/components/DetailGroupBox/DetailGroupBox.tsx](../../src/components/DetailGroupBox/DetailGroupBox.tsx)

Reference usages:

• Shipping zone rates: src/shipping/components/ShippingZoneRates/ShippingZoneRateItem.tsx
• Shipping postal codes: src/shipping/components/ShippingZonePostalCodes/ShippingZonePostalCodes.tsx
• Countries list, metadata editors, translation groups

import { DetailGroupBox } from "@dashboard/components/DetailGroupBox/DetailGroupBox";
import { Title2 } from "@dashboard/components/Title2/Title2";
import { Box } from "@saleor/macaw-ui-next";

<DetailGroupBox
  groupId="unique-section-id"
  dataTestId="my-section"
  triggerButtonTestId="my-section-expand"
  defaultExpanded={false}
  marginTop={4}
  headerStart={<Title2>{title}</Title2>}
  headerEnd={optionalMetaOrActions}
>
  <Box padding={5}>{/* section body */}</Box>
</DetailGroupBox>;

Rules

• Header title: prefer Title2 for the foldable label (same as shipping rates)
• groupId: stable unique string (or entity id when listing many foldables)
• defaultExpanded: false for optional/advanced content; true only when the section is primary
• Do not full-bleed: nest DetailGroupBox inside DashboardCard.Content (or another padded container). Shipping zone rates/postal codes do this — a bare DetailGroupBox as a page sibling of cards spans the content column edge-to-edge and looks wrong
• Body padding: content area has no built-in padding — wrap children in <Box padding={5}> (or match the surrounding list/table pattern)
• Actions in the header: put icon buttons in headerEnd and call event.stopPropagation() so they don’t toggle expand/collapse
• Do not use @dashboard/components/Accordion for new UI — that is the older bordered accordion pattern

When to use what

Typography & semantics (shared)

• Prefer macaw Text tokens (size, fontWeight, color) over browser defaults or ad-hoc CSS font-size.
• Section card titles on entity detail: always Text size={5} fontWeight="bold" as="h2" — owned by DetailSettingsCard (and matching secondary cards). Pass title content only.
• Foldable nested rows: Title2 inside DetailGroupBox — do not invent a third heading style.
• Column / table headers (datagrid, list headers) stay secondary (size={2}–3, regular/medium) — they are not section titles.
• One visual system for the same role across collections, categories, channels, shipping — if a title looks “off”, fix the shared primitive, not a one-off page style.

Interactive affordances (hover / focus)

Every clickable control must show a hover (and focus-visible) state. Prefer one of:

Do not ship interactive elements that only change the cursor. Focus-visible outlines stay required for keyboard users (outline / macaw focus rings).

Links in UI components — prefer normal text color

Inside cards, sidebars, provenance, tooltips, and other product UI chrome, prefer normal text colors over accent blue:

// ✅ Preferred in entity detail / sidebar chrome
<Link href={orderUrl} color="secondary">
  <Text size={3} as="span">#{orderNumber}</Text>
</Link>

// ✅ Channel with globe icon
<ChannelDetailsLink channel={channel} size={3} color="default1" fontWeight="regular" />

// ❌ Avoid for body/meta links in cards
<Link href={orderUrl}>#{orderNumber}</Link> // accent blue

Channel display primitives live in src/components/Channel/Channel.tsx:

• ChannelDisplay — read-only name + globe icon (optional inactive suffix)
• ChannelDetailsLink — same chrome, links to channel details
• ClickableChannel — same chrome, links to orders filtered by channel (permission-gated)

Do not hand-roll Globe + blue Link for channel names.

Price inputs (PriceFieldV2) — preferred

Use [PriceFieldV2](../../src/components/PriceFieldV2/PriceFieldV2.tsx) for all new money/amount fields (channel prices, voucher fixed amounts, cost prices, etc.). Do not add new type="number" money inputs or revive legacy PriceField.

Canonical references:

• Bulk publish review: BulkPublishReviewRow.tsx (PriceFieldV2 + TSV paste)
• Voucher fixed amount per channel: VoucherFixedAmountChannelList.tsx

import { PriceFieldV2 } from "@dashboard/components/PriceFieldV2/PriceFieldV2";

<PriceFieldV2
  currencySymbol={channel.currencyCode}
  value={price}
  onChange={setPrice}
  aria-label={…}
/>

Default (medium) input size for channel amount lists — size="small" feels cramped next to currency adornments. Use small only in dense dialogs (e.g. bulk publish).

Row-list UIs with aligned amount columns should support spreadsheet paste (onPasteCapture + src/utils/spreadsheetPaste/). See also docs/follow-ups/spreadsheet-paste-reuse.md.

Channel amount lists (Pricing / Order value / voucher amounts)

Canonical references: VoucherFixedAmountChannelList, OrderValue (shipping method), PricingCard (shipping method).

Anti-patterns:

• One CSS rule for .headerRow, .row { min-height: 3.25rem; padding: … } — labels inherit a tall input row.
• Skipping the label row on single-amount channel lists (“obvious” Price column) — keep Channel name / Price so Pricing matches Order value. Prefer the same on voucher amount lists when you touch them.
• Material-UI Table / TableCell for channel amount or breakdown lists — prefer macaw Box + CSS grid like OrderValue / PricingCard / ShippingZoneRateChannelTable. Fighting MUI head padding is a losing battle.

Entity detail settings card (DetailSettingsCard)

Primary bordered settings surface on entity detail pages. Full rules (primary vs secondary header, card vs section, Vercel restraint) live in [saleor-dashboard-entity-detail](./saleor-dashboard-entity-detail/SKILL.md).

Secondary sidebar ops cards (AssignListCard, ChannelInventoryCard) use white headers with meta on the right — not DetailSettingsCard.

In-card assignable lists (AssignableList*)

Flush lists inside DetailSettingsCard (products in a collection, attribute values, voucher codes, product-type attributes). The primitive owns padding, heading height, hover-reveal delete, and pagination. Feature views pass columns, rows, and the assign action.

Layout numbers: src/components/AssignableListTable/assignableListTableLayout.ts. Full composition and anti-patterns: [saleor-dashboard-entity-detail](./saleor-dashboard-entity-detail/SKILL.md) → In-card assignable lists.

Do not add a one-off .listHeader / .pagination { border-top } in a feature module.css.

Anti-patterns

• No inline style={{}} - Use Box props or CSS Modules instead
• No plain .css files for components - Use .module.css to scope styles
• No hardcoded colors - Use var(--mu-colors-*) or Box color props
• No shared CSS modules - Each component gets its own .module.css file
• Combining Box + CSS Modules is OK - Use Box for layout, CSS Module for complex styling within the same component
• No legacy @dashboard/components/Accordion for new foldable sections - Use DetailGroupBox (see above)
• No border + box-shadow on elevated surfaces - See [saleor-dashboard-smooth-shadow](./saleor-dashboard-smooth-shadow/SKILL.md)
• No bare browser heading styles for card titles - Do not style only string titles; the primitive must style all title nodes
• No new type="number" money fields - Use PriceFieldV2 (see above)
• No tall column-label bands in channel amount lists - Label rows stay compact (spacing-1 Y); do not reuse value-row min-height (see Channel amount lists above)