@wallarm-org/design-system 4.7.0 → 4.8.0-rc-fix-claude-code.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +4 -2
  2. package/dist/components/BulkBar/index.d.ts +5 -0
  3. package/dist/components/Drawer/classes.js +1 -1
  4. package/dist/components/NotificationCenter/NotificationCenter.d.ts +20 -0
  5. package/dist/components/NotificationCenter/NotificationCenter.js +65 -0
  6. package/dist/components/NotificationCenter/NotificationCenterBody.d.ts +18 -0
  7. package/dist/components/NotificationCenter/NotificationCenterBody.js +202 -0
  8. package/dist/components/NotificationCenter/NotificationCenterContent.d.ts +5 -0
  9. package/dist/components/NotificationCenter/NotificationCenterContent.js +42 -0
  10. package/dist/components/NotificationCenter/NotificationCenterHeader.d.ts +20 -0
  11. package/dist/components/NotificationCenter/NotificationCenterHeader.js +202 -0
  12. package/dist/components/NotificationCenter/NotificationCenterItem.d.ts +26 -0
  13. package/dist/components/NotificationCenter/NotificationCenterItem.js +211 -0
  14. package/dist/components/NotificationCenter/NotificationCenterItemTime.d.ts +9 -0
  15. package/dist/components/NotificationCenter/NotificationCenterItemTime.js +148 -0
  16. package/dist/components/NotificationCenter/NotificationCenterItemTitle.d.ts +14 -0
  17. package/dist/components/NotificationCenter/NotificationCenterItemTitle.js +115 -0
  18. package/dist/components/NotificationCenter/NotificationCenterTabs.d.ts +10 -0
  19. package/dist/components/NotificationCenter/NotificationCenterTabs.js +77 -0
  20. package/dist/components/NotificationCenter/NotificationCenterTrigger.d.ts +13 -0
  21. package/dist/components/NotificationCenter/NotificationCenterTrigger.js +138 -0
  22. package/dist/components/NotificationCenter/index.d.ts +9 -0
  23. package/dist/components/NotificationCenter/index.js +9 -0
  24. package/dist/components/Overlay/Overlay.js +1 -1
  25. package/dist/components/SearchInput/SearchInput.d.ts +7 -5
  26. package/dist/components/SearchInput/SearchInput.js +119 -101
  27. package/dist/components/Select/SelectSearchInput.d.ts +1 -1
  28. package/dist/components/Table/types.d.ts +1 -1
  29. package/dist/components/Tabs/Tabs.d.ts +1 -0
  30. package/dist/components/Tabs/Tabs.js +30 -28
  31. package/dist/components/Tabs/TabsList/index.d.ts +1 -1
  32. package/dist/components/Tabs/index.d.ts +2 -2
  33. package/dist/components/Tour/TourPositioner.d.ts +3 -0
  34. package/dist/components/Tour/TourPositioner.js +4 -4
  35. package/dist/guidelines/foundations/color.md +157 -0
  36. package/dist/guidelines/foundations/focus.md +122 -0
  37. package/dist/guidelines/foundations/layering.md +131 -0
  38. package/dist/guidelines/foundations/radius-elevation.md +111 -0
  39. package/dist/guidelines/foundations/spacing.md +117 -0
  40. package/dist/guidelines/foundations/typography.md +114 -0
  41. package/dist/guidelines/patterns/app-layout.md +1567 -0
  42. package/dist/guidelines/patterns/auth-page.md +668 -0
  43. package/dist/guidelines/patterns/confirmation-dialogs.md +605 -0
  44. package/dist/guidelines/patterns/create-edit-forms.md +768 -0
  45. package/dist/guidelines/patterns/detail-drawer.md +868 -0
  46. package/dist/guidelines/patterns/empty-states.md +461 -0
  47. package/dist/guidelines/patterns/entity-table.md +533 -0
  48. package/dist/guidelines/patterns/feedback-toasts.md +493 -0
  49. package/dist/guidelines/patterns/filtering.md +630 -0
  50. package/dist/guidelines/patterns/resource-list-page.md +558 -0
  51. package/dist/guidelines/patterns/settings-page.md +752 -0
  52. package/dist/guidelines/rules.md +25 -0
  53. package/dist/index.d.ts +2 -1
  54. package/dist/index.js +1 -0
  55. package/dist/metadata/components.json +12641 -9320
  56. package/dist/metadata/guidelines.json +1705 -0
  57. package/dist/theme/typography.css +5 -0
  58. package/dist/utils/formatDateTime.d.ts +6 -0
  59. package/dist/utils/formatDateTime.js +13 -1
  60. package/package.json +6 -1
@@ -0,0 +1,157 @@
1
+ ---
2
+ title: Color
3
+ description: Use when choosing a background, text, icon, border or hover color, so the value switches correctly between light and dark themes.
4
+ components: [Alert, AlertTitle, Badge, Banner, Button, Card, CardContent, Drawer, DropdownMenu, Link, Popover, Radio, SegmentedControl, Slider, Tag, Text, ThemeProvider]
5
+ keywords: [color, colour, token, background, bg, text color, border, surface, elevation, status, danger, warning, success, info, brand, ai, hover, pressed, states, dark mode, theme, palette, opacity]
6
+ order: 20
7
+ ---
8
+
9
+ # Color
10
+
11
+ Use semantic tokens; all but `-fixed` switch with the theme. The prefix repeats: `bg-bg-surface-1`, `text-text-primary`.
12
+
13
+ ## What you use
14
+
15
+ | Need | Use | Not |
16
+ |---|---|---|
17
+ | Body text | `text-text-primary` | `text-slate-900` |
18
+ | Supporting text | `text-text-secondary` | `text-text-primary/60`, `text-muted` |
19
+ | Placeholder or hint | `text-text-hint` | `text-text-tertiary` |
20
+ | Error text | `text-text-danger` | `text-red-600` |
21
+ | Text on a solid fill | `text-text-primary-alt` | `text-white` |
22
+ | Icon ink | `text-icon-secondary` | `text-text-secondary` |
23
+ | Page | `bg-bg-page-bg` | `bg-white` |
24
+ | Card or panel | `bg-bg-surface-1` | `bg-white` |
25
+ | Popover, menu, drawer | `bg-bg-surface-2` | `bg-bg-surface-1` |
26
+ | Neutral tinted area | `bg-bg-light-primary`, `bg-bg-primary` | `bg-slate-50` |
27
+ | Soft status box | `bg-bg-light-danger` + `border-border-danger` | `bg-red-50 border-red-300` |
28
+ | Solid status block | `bg-bg-fill-danger` | `bg-red-600` |
29
+ | Divider | `border-border-primary-light` | `border-gray-200` |
30
+ | Control outline | `border-border-primary` | `border-border-primary-light` |
31
+ | Hover, transparent item | `hover:bg-states-primary-hover` | `hover:bg-slate-100` |
32
+ | Hover, solid fill | `overlay hover:overlay-states-on-fill-hover` | `hover:bg-bg-fill-brand/90`, `hover:brightness-110` |
33
+ | Categorical color | `Badge` `color` | `bg-violet-100` on a `div` |
34
+ | Status notice | `Alert` `color` | A `div` with status classes |
35
+
36
+ ## Rules
37
+
38
+ **Surfaces**
39
+
40
+ - If it sits in page flow (`Card`), use `bg-bg-surface-1`.
41
+ - If it floats over content (`Popover`, `DropdownMenu`, `Drawer`), use `bg-bg-surface-2`.
42
+ - If it is a raised thumb or indicator (`Slider`, `SegmentedControl`, `Radio`), use `bg-bg-surface-3`.
43
+ - If it is a control track, use `bg-bg-primary`, never `bg-bg-surface-3`.
44
+ - Use `bg-bg-surface-5` only for a raised strip like `Banner`.
45
+ - Pick the level by elevation: levels 1–4 are all white in light. Separate them with borders and shadows.
46
+
47
+ **Status**
48
+
49
+ - If the area holds dark text, use `bg-bg-light-<status>` or `bg-bg-<status>` with `border-border-<status>`.
50
+ - If it holds `text-text-primary-alt`, use `bg-bg-fill-<status>`.
51
+ - Use `brand` only for the primary action, `ai` only for assistant content.
52
+ - Pair status color with an icon or word.
53
+ - Use `danger` for errors. `destructive` is only an `Alert`/`Button` prop and `ring-focus-destructive`.
54
+
55
+ **States**
56
+
57
+ - Transparent item: `hover:bg-states-primary-hover`, `active:bg-states-primary-pressed`. Selected: `bg-states-primary-active`.
58
+ - Solid fill: add `overlay`, then `hover:overlay-states-on-fill-hover`, `active:overlay-states-on-fill-pressed`.
59
+ - Brand/danger item: `bg-states-brand-*`, `bg-states-danger-*`. Inverted surface: `bg-states-primary-alt-*`.
60
+ - `states-*` tokens are translucent layers over a resting fill.
61
+ - Prefer components with built-in states, like `Button`.
62
+
63
+ **Theme**
64
+
65
+ - Switch themes with `useTheme().setTheme()`, never by setting `data-theme`.
66
+ - Use `-alt` tokens on inverted surfaces; `-fixed` tokens only on fixed surfaces.
67
+ - **Never** use the `dark:` variant. It follows the OS, not `ThemeProvider`.
68
+ - **Never** use raw palette classes (`bg-red-500`), which ignore the theme, or opacity modifiers (`/90`).
69
+ - **Never** reuse `bg-component-*` outside its component. Exception: an auth page paints `bg-component-app-shell-bg`; see [Auth page](../patterns/auth-page.md).
70
+ - **Never** edit `--color-syntax-*` mappings.
71
+
72
+ **These do not exist**
73
+
74
+ - `bg-primary`, `text-primary`, `border-primary` → `bg-bg-primary`, `text-text-primary`, `border-border-primary`.
75
+ - `text-muted`, `text-subtle`, `text-disabled` → `text-text-secondary`, `text-text-hint`, `text-text-disable-primary`.
76
+ - `bg-surface`, `bg-card`, `bg-background`, `bg-muted` → `bg-bg-surface-1`, `bg-bg-light-primary`.
77
+ - `bg-bg-surface-0`, `bg-bg-surface-6` → levels run 1–5.
78
+ - `error` tokens → `danger`. `bg-bg-fill-primary` → no neutral solid fill. `border-border-secondary` → `border-border-primary-light`.
79
+ - `Badge` `color='purple'` → `violet`. `Tag` has no `color` prop.
80
+
81
+ ## Examples
82
+
83
+ A soft danger box in a card.
84
+
85
+ ```tsx
86
+ import { Card, CardContent, Text } from '@wallarm-org/design-system';
87
+
88
+ export const BlockedRequests = () => (
89
+ <Card>
90
+ <CardContent className='flex flex-col gap-8'>
91
+ <Text size='sm' color='secondary'>Blocked requests</Text>
92
+ <div className='rounded-8 border-1 border-border-danger bg-bg-light-danger px-12 py-8 text-text-danger'>
93
+ 1 204 attacks blocked
94
+ </div>
95
+ </CardContent>
96
+ </Card>
97
+ );
98
+ ```
99
+
100
+ Notices and labels are components.
101
+
102
+ ```tsx
103
+ import { Alert, AlertTitle, Badge } from '@wallarm-org/design-system';
104
+
105
+ export const QuotaNotice = () => (
106
+ <>
107
+ <Alert color='warning'><AlertTitle>Quota at 90%</AlertTitle></Alert>
108
+ <Badge color='violet' type='secondary'>API abuse</Badge>
109
+ </>
110
+ );
111
+ ```
112
+
113
+ A custom solid fill keeps its color on hover.
114
+
115
+ ```tsx
116
+ export const DeployTile = () => (
117
+ <button
118
+ type='button'
119
+ className='overlay bg-bg-fill-brand text-text-primary-alt hover:overlay-states-on-fill-hover active:overlay-states-on-fill-pressed'
120
+ >
121
+ Deploy
122
+ </button>
123
+ );
124
+ ```
125
+
126
+ Switch themes with `useTheme`.
127
+
128
+ ```tsx
129
+ import { Button, useTheme } from '@wallarm-org/design-system';
130
+
131
+ export const DarkModeButton = () => {
132
+ const { setTheme } = useTheme();
133
+ const handleDark = () => setTheme('dark');
134
+
135
+ return <Button onClick={handleDark}>Dark</Button>;
136
+ };
137
+ ```
138
+
139
+ ## Reference
140
+
141
+ `<status>`: `brand`, `danger`, `warning`, `success`, `info`, `ai`.
142
+
143
+ | Family | Classes |
144
+ |---|---|
145
+ | Text | `text-text-` `primary`, `secondary`, `tertiary`, `hint`, `<status>`, `primary-alt`, `secondary-alt`, `tertiary-alt`, `primary-fixed`, `primary-alt-fixed` |
146
+ | Disabled text | `text-text-disable-primary`, `-primary-alt`, `-<status>` (success is spelled `succes`) |
147
+ | Link | `text-text-link-default`, `-hover`, `-default-alt`, `-hover-alt`; prefer `Link` |
148
+ | Icon | `text-icon-` `primary`, `secondary`, `<status>`, `primary-alt`, `secondary-alt`, `primary-fixed`, `primary-alt-fixed`, `primary-disable`, `primary-alt-disable` |
149
+ | Surface | `bg-bg-page-bg`, `bg-bg-surface-1`…`5` |
150
+ | Neutral fill | `bg-bg-light-primary` < `bg-bg-primary` < `bg-bg-strong-primary` |
151
+ | Status fill | `bg-bg-light-<status>` < `bg-bg-<status>` < `bg-bg-strong-<status>`; solid `bg-bg-fill-<status>` |
152
+ | Border | `border-border-primary-light`, `-primary`, `-strong-primary`, `-<status>`, `-strong-<status>` |
153
+ | States | `bg-states-<family>-default-alt`, `-hover`, `-pressed`, `-active`; `bg-states-default-all` |
154
+ | Fill states | `overlay-states-on-fill-hover`, `-pressed`, `-disabled` (need `overlay`) |
155
+ | Focus | `ring-focus-primary`, `-brand`, `-destructive`; see [Focus](./focus.md) |
156
+
157
+ `<family>`: `primary`, `primary-alt`, or a `<status>`. `Text` `color`: `primary`, `primary-alt`, `secondary`, `secondary-alt`, `tertiary-alt`, `danger`, `inherit`. `Badge` `color`: `slate`, `gray`, `zinc`, `neutral`, `stone`, `red`, `w-orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `fuchsia`, `pink`, `rose`.
@@ -0,0 +1,122 @@
1
+ ---
2
+ title: Focus
3
+ description: Use when an element must show keyboard focus, to pick the ring recipe, the focus color token, and where no ring goes.
4
+ components: [Button, Card, CardContent, Input, Textarea, InputGroup, Checkbox, Radio, Switch, DropdownMenu, DropdownMenuItem, Select, SelectOption, NavRail, Slider, Link]
5
+ keywords: [focus, focus-visible, ring, focus ring, outline, keyboard, a11y, accessibility, tab, ring-inset, focus-within]
6
+ order: 60
7
+ ---
8
+
9
+ # Focus
10
+
11
+ Keyboard focus is a 3px ring in a translucent focus color, shown on `:focus-visible`.
12
+ DS components draw it already. Write a ring only on elements your app builds.
13
+
14
+ ## What you use
15
+
16
+ | Need | Use | Not |
17
+ | --- | --- | --- |
18
+ | Ring on an app-built control | `outline-none focus-visible:ring-3 focus-visible:ring-focus-primary` | `focus:ring-*` |
19
+ | Ring on a brand-colored control | `focus-visible:ring-focus-brand` | `ring-focus-primary` |
20
+ | Ring on a destructive control or invalid field | `focus-visible:ring-focus-destructive` | `ring-focus-primary` |
21
+ | Ring inside `overflow-hidden` or flush to a container edge | add `focus-visible:ring-inset` | an outer ring, which gets clipped |
22
+ | Ring on a wrapper around a native input | `has-[input:focus-visible]:ring-3 has-[input:focus-visible]:ring-focus-primary` (or `focus-within:`) | a ring on the inner input |
23
+ | Input with addons | `InputGroup` | a hand-built wrapper ring |
24
+ | Focusable card | `Card` with `onClick` | a `<div tabIndex>` with your own ring |
25
+ | Focus color on a DS button | the `Button` `color` prop (default `brand`) | a `className` override |
26
+
27
+ ## Rules
28
+
29
+ - Use `focus-visible:`, not `focus:`. The ring is for keyboard focus only.
30
+ - Pair the ring with `outline-none`, so the browser outline and the ring never show together.
31
+ - Use `ring-3`. **Never** copy `ring-2` from Card, Resizable, CodeEditor or SimpleCharts: it is known drift.
32
+ - Always set a `ring-focus-*` color. `ring-3` alone draws the default color.
33
+ - Keep the element's radius; the ring follows it.
34
+ - If a parent has `overflow-hidden`, add `ring-inset`.
35
+ - If the control is brand-colored (`Button` with `color='brand'` in any variant, a checked or indeterminate Checkbox, a checked Radio or Switch), use `ring-focus-brand`. Neutral controls (`Button` with `color='neutral'` or `'neutral-alt'`, unchecked Checkbox, Radio or Switch, tabs, tags, inputs) use `ring-focus-primary`.
36
+ - If the control is destructive (`Button` with `color='destructive'`, any variant), use `ring-focus-destructive`.
37
+ - If you build a text field, match `Input`: on focus, `focus-visible:not-disabled:border-border-strong-primary` plus `ring-focus-primary`. Invalid: keep `border-border-strong-danger`, ring `ring-focus-destructive`, hover `ring-focus-destructive-hover`.
38
+ - If an input sits inside a styled wrapper, put the ring on the wrapper.
39
+ - If focus moves by arrow keys (menu, listbox), the highlighted row is the indicator. `DropdownMenuItem` and `SelectOption` use `bg-states-primary-hover`; brand and danger items use `bg-states-brand-hover` and `bg-states-danger-hover`.
40
+ - `NavRail` items show an overlay (`overlay-states-primary-hover`); the `Slider` thumb scales up with a shadow. Neither gets a ring.
41
+ - **Never** add a ring to a menu item or listbox option.
42
+ - **Never** add a ring to a popover, dialog or drawer surface (`DropdownMenu`, `Select` content, `Drawer`).
43
+ - **Never** use `outline-none` on an interactive element without a replacement indicator.
44
+ - **Never** use a border color, `ring-border-*` or a raw palette color as a focus ring.
45
+ - **Never** use `ring-focus-ring-primary`. The token exists but nothing uses it.
46
+ - **Never** add `ring-offset-*`. DS rings sit flush.
47
+ - **Never** override a DS component's ring through `className`. Pick the `color` prop.
48
+
49
+ ### What does not exist
50
+
51
+ - No bare `ring-focus` token; always add a suffix.
52
+ - No `--ring` or ring-width token. Width is the `ring-3` utility.
53
+ - No `focusRing` prop on any component.
54
+ - No exported focus-ring class helper. Write the class string.
55
+ - `Link` has no focus-visible style, only `outline-none`. This is a known gap.
56
+
57
+ ## Examples
58
+
59
+ A DS button picks its ring color from `color`; no class needed.
60
+
61
+ ```tsx
62
+ import { Button } from '@wallarm-org/design-system';
63
+
64
+ export const DeleteButton = ({ onDelete }: { onDelete: () => void }) => (
65
+ <Button variant='primary' color='destructive' onClick={onDelete}>
66
+ Delete
67
+ </Button>
68
+ );
69
+ ```
70
+
71
+ A card becomes focusable and draws its ring once it has a click handler.
72
+
73
+ ```tsx
74
+ import { Card, CardContent } from '@wallarm-org/design-system';
75
+
76
+ export const DetailsCard = ({ onOpen }: { onOpen: () => void }) => (
77
+ <Card onClick={onOpen}>
78
+ <CardContent>Open details</CardContent>
79
+ </Card>
80
+ );
81
+ ```
82
+
83
+ An app-built control uses the standard recipe.
84
+
85
+ ```tsx
86
+ export const CustomTrigger = ({ onOpen }: { onOpen: () => void }) => (
87
+ <button
88
+ type='button'
89
+ className='rounded-8 outline-none focus-visible:ring-3 focus-visible:ring-focus-primary'
90
+ onClick={onOpen}
91
+ >
92
+ Custom trigger
93
+ </button>
94
+ );
95
+ ```
96
+
97
+ A row inside a scroller with `overflow-hidden` uses an inset ring.
98
+
99
+ ```tsx
100
+ export const ClippedRow = ({ onSelect }: { onSelect: () => void }) => (
101
+ <div className='overflow-hidden'>
102
+ <button
103
+ type='button'
104
+ className='w-full outline-none focus-visible:ring-3 focus-visible:ring-inset focus-visible:ring-focus-primary'
105
+ onClick={onSelect}
106
+ >
107
+ Row
108
+ </button>
109
+ </div>
110
+ );
111
+ ```
112
+
113
+ ## Reference
114
+
115
+ `ring-*` widths are px in Tailwind v4 (`ring-3` is 3px) and do not scale with `--spacing`.
116
+
117
+ | Token | Utility | Value |
118
+ | --- | --- | --- |
119
+ | `--color-focus-primary` | `ring-focus-primary` | `slate-400` at 30% |
120
+ | `--color-focus-brand` | `ring-focus-brand` | `w-orange-600` at 30% |
121
+ | `--color-focus-destructive` | `ring-focus-destructive` | `red-600` at 20% |
122
+ | `--color-focus-destructive-hover` | `ring-focus-destructive-hover` | `red-600` at 30% |
@@ -0,0 +1,131 @@
1
+ ---
2
+ title: Layering
3
+ description: Use when an overlay must paint above another one, or when you consider adding a z-index class to app code.
4
+ components: [Drawer, Dialog, DropdownMenu, Select, Popover, Calendar, FilterCascade, Tooltip, Toaster, SearchModal, Tour, SelectionBulkBar, TableActionBar, FeedbackPulse, PageHeader]
5
+ keywords: [z-index, z, stacking, layer, portal, overlay, modal, nested drawer, dialog over drawer, dropdown in dialog, tooltip above, toast above, sticky header, popper]
6
+ order: 50
7
+ ---
8
+
9
+ # Layering
10
+
11
+ Overlays stack themselves by nesting depth. App code never sets z-index on a design-system overlay.
12
+
13
+ ## What you use
14
+
15
+ | Need | Use | Not |
16
+ | --- | --- | --- |
17
+ | A panel over the page | `Drawer` | A `fixed` div with `z-50` |
18
+ | A modal over the page or over a drawer | `Dialog` from `@wallarm-org/design-system/Dialog` | A second `Drawer` styled as a modal |
19
+ | A menu, select, popover or date picker inside a drawer or dialog | `DropdownMenu`, `Select`, `Popover`, `Calendar`, `FilterCascade` as-is | A `z-[100]` class on the content |
20
+ | A hint above everything | `Tooltip` | A `Popover` with a raised z-index |
21
+ | A notification above every drawer and dialog | `useToast()` from `@wallarm-org/design-system/Toast`, plus one `Toaster` | A `Drawer` without overlay |
22
+ | A sticky page header | `PageHeader` with `sticky` | `sticky top-0 z-50` in app code |
23
+ | Bulk actions for a table in a drawer or dialog | Buttons in `DrawerFooter` or `DialogFooter` | `TableActionBar` |
24
+
25
+ What does not exist:
26
+
27
+ - No z-index token scale and no `z-overlay`, `z-modal`, `z-popover` or `z-toast` utility.
28
+ - No `zIndex` prop on any overlay.
29
+ - No `portal={false}` or container prop on `Drawer`, `Dialog`, `DropdownMenu`, `Select`, `Popover` or `Tooltip`.
30
+ - No `Overlay` export. The backdrop comes from `Drawer` and `Dialog` when `overlay` is `true`.
31
+ - No `Dialog` in the package root. Import it from `@wallarm-org/design-system/Dialog`.
32
+
33
+ ## Rules
34
+
35
+ - If an overlay opens from inside another overlay, render it as a React child of the parent's content. Depth comes from the React tree.
36
+ - If you open a `Dialog` from a `Drawer`, put the `Dialog` inside `DrawerContent`. Only a React-ancestor drawer or dialog dismisses the nested one.
37
+ - If you nest a `Drawer` in a `Drawer`, or a `Dialog` in a `Dialog`, expect the parent to scale back. A `Dialog` over a `Drawer` does not scale the drawer.
38
+ - If a dropdown, select, popover, calendar or tooltip sits in any overlay, use it as-is. It already paints above its host.
39
+ - If your app has its own fixed element (chat widget), keep its z-index below 40. At 40 or higher it paints over the drawer backdrop.
40
+ - If your app has its own sticky element inside a scroll area, use `z-10`.
41
+ - **Never** add a `z-*` class or `style={{ zIndex }}` to `DrawerContent`, `DropdownMenuContent`, `SelectPositioner`, `PopoverContent`, `CalendarContent` or `TooltipContent`.
42
+ - If chrome you can't change (a framework or docs-site header) sits at z-index 40 or higher, raise `--drawer-overlay-z-index` and `--drawer-positioner-z-index` together on `:root` above it, positioner 10 higher. Keep both under 900.
43
+ - **Never** override `--tooltip-z-index` or `--toast-z-index`, and never change only one of the two drawer variables.
44
+ - **Never** wrap an overlay trigger in `transform`, `filter` or `isolation: isolate` to fix stacking. Overlay content is portaled to `document.body`.
45
+ - **Never** open `SearchModal` from inside a `Drawer` or `Dialog`. The backdrops cover the search box.
46
+ - **Never** start a `Tour` while a `Drawer` or `Dialog` is open. The drawer ties with or covers the tour.
47
+ - **Never** show `TableActionBar` for a table inside a `Drawer` or `Dialog`. The drawer ties with or covers the bar.
48
+
49
+ ## Examples
50
+
51
+ A menu inside a drawer paints above the drawer with no z-index class.
52
+
53
+ ```tsx
54
+ <DrawerContent>
55
+ <DrawerBody>
56
+ <DropdownMenu>
57
+ <DropdownMenuTrigger asChild>
58
+ <Button variant='outline' color='neutral'>Actions</Button>
59
+ </DropdownMenuTrigger>
60
+ <DropdownMenuContent>
61
+ <DropdownMenuItem>Duplicate</DropdownMenuItem>
62
+ </DropdownMenuContent>
63
+ </DropdownMenu>
64
+ </DrawerBody>
65
+ </DrawerContent>
66
+ ```
67
+
68
+ A confirm dialog opened from a drawer is a React child of `DrawerContent`.
69
+
70
+ ```tsx
71
+ import { Dialog, DialogContent, DialogTitle, DialogTrigger } from '@wallarm-org/design-system/Dialog';
72
+
73
+ <DrawerFooter>
74
+ <Dialog>
75
+ <DialogTrigger asChild>
76
+ <Button variant='primary' color='brand'>Delete</Button>
77
+ </DialogTrigger>
78
+ <DialogContent>
79
+ <DialogTitle>Delete rule?</DialogTitle>
80
+ </DialogContent>
81
+ </Dialog>
82
+ </DrawerFooter>
83
+ ```
84
+
85
+ An app-owned floating widget stays below the drawer backdrop.
86
+
87
+ ```tsx
88
+ <div className='fixed right-16 bottom-16 z-30'>{chat}</div>
89
+ ```
90
+
91
+ ## Reference
92
+
93
+ ### Depth-based overlays
94
+
95
+ `Drawer`, `Dialog`, `DropdownMenu`, `Select`, `Popover`, `Calendar` and `FilterCascade`. Each level adds 20.
96
+
97
+ | Depth | Backdrop | Content |
98
+ | --- | --- | --- |
99
+ | 0 | 40 | 50 |
100
+ | 1 | 60 | 70 |
101
+ | 2 | 80 | 90 |
102
+ | 3 | 100 | 110 |
103
+
104
+ ### Fixed overlays
105
+
106
+ | Component | z-index |
107
+ | --- | --- |
108
+ | `Tooltip` | 1000 |
109
+ | `Toaster` | 900 |
110
+ | `SelectionBulkBar` (`placement='floating'`) | 200 |
111
+ | `TableActionBar`, `Tour`, `FeedbackPulse` | 50 |
112
+ | `SearchModal` | 41 |
113
+ | `Tour` backdrop | 40 |
114
+
115
+ ### Variables
116
+
117
+ | Variable | Value |
118
+ | --- | --- |
119
+ | `--drawer-overlay-z-index` | 40 |
120
+ | `--drawer-positioner-z-index` | 50 |
121
+ | `--toast-z-index` | 900 |
122
+ | `--tooltip-z-index` | 1000 |
123
+
124
+ ### In-flow values
125
+
126
+ In-component only; never competes with overlays.
127
+
128
+ | Value | Where |
129
+ | --- | --- |
130
+ | `z-10` | `PageHeader` `sticky`, sticky menu group labels, pinned table body cells |
131
+ | `z-30` to `z-40` | Table headers |
@@ -0,0 +1,111 @@
1
+ ---
2
+ title: Radius and elevation
3
+ description: Use when choosing a border radius or a shadow for your own element, or when matching the corners and depth of a design-system surface.
4
+ components: [Button, Input, Select, Card, CardContent, Tag, Tooltip, Avatar, DropdownMenu, Popover, PopoverTrigger, PopoverContent, Drawer, Dialog, SearchModal, Alert, Table, Toast, ChatInput, Checkbox, Radio, Switch, Kbd, NavRail, SegmentedControl, Skeleton, InputGroup, SplitButton]
5
+ keywords: [radius, border-radius, rounded, corners, shadow, box-shadow, elevation, depth, drop shadow, raised, floating, dark mode, rounded-8, rounded-12, shadow-md, shadow-xl]
6
+ order: 40
7
+ ---
8
+
9
+ # Radius and elevation
10
+
11
+ Radius utilities are named in pixels. Shadows are named by size and do not change in dark mode.
12
+
13
+ ## What you use
14
+
15
+ | Need | Use | Not |
16
+ | --- | --- | --- |
17
+ | Corners on a control-sized element | `rounded-8` | `rounded-lg`, `rounded-md`, `rounded` |
18
+ | Corners on a menu item or a small inline chip | `rounded-6` | `rounded-md` |
19
+ | Corners on a panel or floating surface | `rounded-12` | `rounded-xl` |
20
+ | A circle or a pill | `rounded-full` | `rounded-[50%]`, `rounded-[999px]` |
21
+ | A bordered tile with a shadow | `Card` | A `div` with `rounded-8 border shadow-sm` |
22
+ | A floating panel anchored to a trigger | `Popover`, `PopoverTrigger`, `PopoverContent` | A positioned `div` with `rounded-12 shadow-md` |
23
+ | A side panel or a modal | `Drawer` or `Dialog` | A `div` with `rounded-12 shadow-xl` |
24
+ | A loading placeholder with matching corners | `<Skeleton rounded={8} />` | `<Skeleton className='rounded-8' />` |
25
+ | Depth on your own floating element | `shadow-md` + `border border-border-primary-light bg-bg-surface-2` | `shadow-md` alone, `drop-shadow-*` |
26
+
27
+ ## Rules
28
+
29
+ - Read `rounded-*` numbers as pixels. If a value is off the scale, round to the nearest step.
30
+ - **Never** use Tailwind's named radii (`rounded-xs` … `rounded-4xl`) or bare `rounded`. They compile to rem defaults off the scale.
31
+ - **Never** write an arbitrary radius or shadow such as `rounded-[15px]` or `shadow-[0_2px_4px_rgba(0,0,0,0.1)]`.
32
+ - If your element sits next to a design-system component, copy that component's radius. A custom button-sized element next to `Button` gets `rounded-8`.
33
+ - If you nest a rounded element inside a padded rounded container, use a smaller inner radius: `rounded-12` outside, 4px padding, `rounded-8` inside.
34
+ - If you round only some corners, use side or corner variants of the same step: `rounded-t-12`, `rounded-tl-12`.
35
+ - If an element stays in the page flow, give it no shadow. `Card` is the one in-flow surface with a shadow (`shadow-sm`).
36
+ - If an element floats, use the shadow for its layer below.
37
+ - If you add a shadow to your own floating element, pair it with `border border-border-primary-light` and a surface fill such as `bg-bg-surface-2`. They carry the depth in dark mode.
38
+ - **Never** add `shadow-*` to `Card`, `Input`, `Button` or another design-system component. They own their shadow.
39
+ - **Never** add a dark-mode shadow (`dark:shadow-lg`) or use `shadow-2xl`.
40
+ - **Never** use a shadow as a focus indicator. See [Focus](./focus.md).
41
+
42
+ There is no `--elevation-*` token, no `shadow-card`/`shadow-popover`/`shadow-modal` utility, and no dark-mode shadow value.
43
+
44
+ ## Examples
45
+
46
+ A placeholder takes its corners from the `rounded` prop.
47
+
48
+ ```tsx
49
+ import { Card, CardContent, Skeleton } from '@wallarm-org/design-system';
50
+
51
+ export const UsageTile = ({ loading }: { loading: boolean }) => (
52
+ <Card>
53
+ <CardContent>
54
+ {loading ? (
55
+ <Skeleton width='100%' height='120px' rounded={8} />
56
+ ) : (
57
+ <div className='h-120 rounded-8 border border-border-primary-light' />
58
+ )}
59
+ </CardContent>
60
+ </Card>
61
+ );
62
+ ```
63
+
64
+ A custom floating element pairs its shadow with a border and fill.
65
+
66
+ ```tsx
67
+ <div className='rounded-12 border border-border-primary-light bg-bg-surface-2 p-12 shadow-md'>
68
+ …
69
+ </div>
70
+ ```
71
+
72
+ A nested item steps the radius down.
73
+
74
+ ```tsx
75
+ <div className='flex rounded-12 bg-bg-surface-2 p-4'>
76
+ <div className='rounded-8 bg-bg-surface-1 px-12 py-6'>Day</div>
77
+ </div>
78
+ ```
79
+
80
+ ## Reference
81
+
82
+ ### Radius scale
83
+
84
+ | Utility | Value | Used by |
85
+ | --- | --- | --- |
86
+ | `rounded-none` | 0 | Joined edges in `InputGroup`, `SplitButton` |
87
+ | `rounded-2` | 2px | Indicators, status dots |
88
+ | `rounded-4` | 4px | `Checkbox` box, `Kbd`, `Switch` thumb |
89
+ | `rounded-6` | 6px | `DropdownMenu` items, small badges, `Skeleton` default |
90
+ | `rounded-8` | 8px | `Button`, `Input`, `Select`, `Tag`, `Tooltip`, `Card`, `Avatar` sm/md |
91
+ | `rounded-10` | 10px | `NavRail` items |
92
+ | `rounded-12` | 12px | `Popover`, `DropdownMenu`, `Dialog`, `Drawer`, `Alert`, `Table` container |
93
+ | `rounded-16` | 16px | `Toast`, `ChatInput`, chat messages |
94
+ | `rounded-24`, `rounded-32` | 24px, 32px | `Skeleton` only |
95
+ | `rounded-full` | 9999px | `Radio`, numeric badges, pills |
96
+
97
+ `Skeleton` `rounded` accepts `'none'`, `'full'`, `2`, `4`, `6`, `8`, `10`, `12`, `16`, `24`, `32`.
98
+
99
+ ### Elevation scale
100
+
101
+ | Utility | Layer | Used by |
102
+ | --- | --- | --- |
103
+ | `shadow-none` | Reset | Fields inside `InputGroup` |
104
+ | `shadow-2xs` | Hairline lift | Bordered filter triggers |
105
+ | `shadow-xs` | Raised control | `Button` primary/outline, `Input`, `Select`, `Checkbox` |
106
+ | `shadow-sm` | In-flow tile, moving thumb | `Card`, `Switch` thumb, `SegmentedControl` indicator |
107
+ | `shadow-md` | Anchored floating surface | `Popover`, `DropdownMenu`, tooltip tour steps |
108
+ | `shadow-lg` | Notification, dragged item | `Toast`, `Table` bulk action bar, dragged rows |
109
+ | `shadow-xl` | Modal layer | `Drawer`, `Dialog`, `SearchModal` |
110
+
111
+ See [Spacing](./spacing.md) for padding inside rounded surfaces.
@@ -0,0 +1,117 @@
1
+ ---
2
+ title: Spacing
3
+ description: Use when choosing a gap, padding or margin value, a Stack or Flex gap prop, or the inner spacing of a page, card, drawer or dialog.
4
+ components: [Stack, HStack, VStack, Flex, Page, PageHeader, PageToolbar, PageContent, PageTitle, PageActions, Card, CardHeader, CardTitle, CardContent, CardFooter, Drawer, DrawerHeader, DrawerBody, DrawerFooter, Dialog, DialogBody, DialogFooter]
5
+ keywords: [spacing, gap, padding, margin, space, px, scale, inset, gutter, Stack, HStack, VStack, Flex, layout, whitespace]
6
+ order: 10
7
+ ---
8
+
9
+ # Spacing
10
+
11
+ Every numeric spacing and sizing utility counts in pixels. `p-16` is 16px; `p-4` is 4px.
12
+
13
+ ## What you use
14
+
15
+ | Need | Use | Not |
16
+ | --- | --- | --- |
17
+ | Children in a column | `<VStack gap={16}>` | `space-y-4`, `flex flex-col gap-4` |
18
+ | Children in a row | `<HStack gap={8}>` | `space-x-2`, per-child margins |
19
+ | A row or column with `basis`, `grow` or `shrink` | `<Flex gap={12} basis='1/2'>` | A raw `div` with `flex basis-1/2` |
20
+ | Padding on your own element | `p-16`, `px-24`, `py-8` | `p-4` meaning 16px |
21
+ | Page gutters | `PageHeader`, `PageToolbar`, `PageContent` | Your own `px-*` on the page wrapper |
22
+ | A bordered tile | `Card` with `CardHeader`, `CardContent`, `CardFooter` | A `div` with `p-16 rounded-8 border` |
23
+ | Side panel or modal body | `DrawerBody`, `DialogBody` | Padding classes inside header, body or footer |
24
+
25
+ ## Rules
26
+
27
+ - Read every number in a spacing or sizing class (`p-*`, `m-*`, `gap-*`, `w-*`, `h-*`, `size-*`, `inset-*`, `top-*`) as pixels.
28
+ - **Never** copy a Tailwind docs value as-is. Multiply it by 4: Tailwind `p-4` is `p-16` here, `mt-8` is `mt-32`, `h-8` is `h-32`.
29
+ - Stay on the scale. If a value is off it, round to the nearest step. Off-scale classes such as `p-10` still compile; the rule stops you, not the build.
30
+ - If children sit in a line, use `Stack`, `HStack` or `VStack` with `gap`. **Never** use per-child margins or `space-*`.
31
+ - Pass `gap` as a scale-number prop, not a `gap-*` class. Off-scale numbers fail type-checking.
32
+ - If you omit `gap` on `Stack`, `HStack` or `VStack`, you get 4px. If you omit it on `Flex`, you get none.
33
+ - If you want no gap on `Stack`, pass `gap={0}`. `Flex` has no `gap={0}`; omit the prop.
34
+ - If you need `className` on the flex container, use `Stack`. `Flex` does not accept `className`.
35
+ - `PageHeader`, `PageToolbar` and `PageContent` own the 24px side gutter. **Never** wrap `Page` in a padded container.
36
+ - `Card` owns its 16px padding. **Never** add `p-*` to `Card` or its parts.
37
+ - Put drawer and dialog content straight into `DrawerBody` or `DialogBody`. Their 24px gutter is fixed.
38
+ - **Never** pass `className` to `DrawerHeader`, `DrawerBody` or `DrawerFooter`. They accept only `children` and `ref`.
39
+ - Import `Dialog` parts from `@wallarm-org/design-system/Dialog`. `Dialog` is not exported from the package root.
40
+ - **Never** reach for a `--spacing-10` token, a `space-*` component prop, or a `padding` prop on `Stack`, `Flex`, `Card` or `Page`. None exist.
41
+
42
+ ## Examples
43
+
44
+ A column of sections uses `VStack`, not per-child margins.
45
+
46
+ ```tsx
47
+ import { Text, VStack } from '@wallarm-org/design-system';
48
+
49
+ <VStack gap={24}>
50
+ <Text>Profile</Text>
51
+ <Text>Security</Text>
52
+ </VStack>;
53
+ ```
54
+
55
+ Padding on your own element uses the pixel number, not the Tailwind docs number.
56
+
57
+ ```tsx
58
+ <div className='px-24 py-12'>Content</div>; // not 'px-6 py-3'
59
+ ```
60
+
61
+ A page puts cards straight into `PageContent`, with no padding of its own.
62
+
63
+ ```tsx
64
+ import {
65
+ Card, CardContent, CardHeader, CardTitle, HStack,
66
+ Page, PageContent, PageHeader, PageTitle,
67
+ } from '@wallarm-org/design-system';
68
+
69
+ <Page name='overview' fullSize fixedHeight>
70
+ <PageHeader>
71
+ <PageTitle>Overview</PageTitle>
72
+ </PageHeader>
73
+ <PageContent>
74
+ <HStack gap={16} align='stretch'>
75
+ <Card>
76
+ <CardHeader><CardTitle>Requests</CardTitle></CardHeader>
77
+ <CardContent>1,204</CardContent>
78
+ </Card>
79
+ </HStack>
80
+ </PageContent>
81
+ </Page>;
82
+ ```
83
+
84
+ ## Reference
85
+
86
+ ### Scale
87
+
88
+ Each step is a `--spacing-N` token and a utility suffix (`p-N`, `gap-N`, `w-N`), N in pixels. Zero is `--spacing-none` (`p-0`).
89
+
90
+ | Range | Steps (px) |
91
+ | --- | --- |
92
+ | Tight | 1, 2, 4, 6, 8, 12 |
93
+ | Component | 16, 20, 24, 28, 32, 36, 40, 44, 48 |
94
+ | Layout | 56, 64, 80, 96, 112, 128, 144 |
95
+
96
+ ### Layout components
97
+
98
+ | Component | `gap` values | Default `gap` | Direction | `className` |
99
+ | --- | --- | --- | --- | --- |
100
+ | `Stack` | `0` and every step `1`–`144` | `4` | `column` | Yes |
101
+ | `VStack` | Same as `Stack` | `4` | `column` (fixed) | Yes |
102
+ | `HStack` | Same as `Stack` | `4` | `row` (fixed), `align='center'` | Yes |
103
+ | `Flex` | Every step `1`–`144`, no `0` | none | `row` | No |
104
+
105
+ ### Built into components
106
+
107
+ Do not repeat these.
108
+
109
+ | Component | Side gutter | Gap between items |
110
+ | --- | --- | --- |
111
+ | `PageHeader`, `PageToolbar`, `PageContent` | 24px | 12px (header, toolbar) |
112
+ | `PageActions` | — | 8px |
113
+ | `Card` | 16px all round | 8px between parts; 12px in `CardFooter` |
114
+ | `DrawerHeader`, `DialogHeader` | 24px left | 12px |
115
+ | `DrawerBody`, `DialogBody` | 24px | — |
116
+ | `DrawerFooter`, `DialogFooter` | 24px, 16px vertical | 8px |
117
+ | Drawer / Dialog inset from viewport | 8px / 32px | — |