Styling guide for Saleor Dashboard React components using macaw-ui design system. Use when creating, refactoring, or modifying React components that need styling - especially layout, spacing, colors, borders, or any visual changes. Triggers on component creation, UI refactors, and style-related tasks.
Two strategies for styling components. Choose based on complexity.
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, , , , , , .
flexGrowflexShrinkflexWrapgridTemplateColumnsgridColumnorderAll 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: display={{ mobile: "none", tablet: "flex", desktop: "grid" }}
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" }} />
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} />;
::placeholder, :hover, :focus, [data-state="open"]@keyframes, complex transition@media (min-width: 960px).row:hover .iconHover 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;
}
}
Always use macaw CSS variables instead of hardcoded values (especially colors, spacing, borders).
Use var(--mu-*) variables. Read the full list from: node_modules/@saleor/macaw-ui/dist/style.css
Common patterns: