@brightlocal/ui-components 1.1.1 → 1.2.0
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.
- package/AI_USAGE.md +390 -0
- package/README.md +45 -10
- package/component-meta.json +1488 -0
- package/dist/blocks/input-list.cjs +2 -0
- package/dist/blocks/input-list.d.ts +93 -0
- package/dist/blocks/input-list.d.ts.map +1 -0
- package/dist/blocks/input-list.js +215 -0
- package/dist/blocks/sidebar.d.ts.map +1 -1
- package/dist/breadcrumb.cjs +1 -1
- package/dist/breadcrumb.d.ts.map +1 -1
- package/dist/breadcrumb.js +17 -14
- package/dist/button.cjs +1 -1
- package/dist/button.d.ts.map +1 -1
- package/dist/button.js +9 -8
- package/dist/calendar.cjs +1 -1
- package/dist/calendar.js +1 -1
- package/dist/checkbox.cjs +1 -1
- package/dist/checkbox.d.ts.map +1 -1
- package/dist/checkbox.js +8 -10
- package/dist/combobox.cjs +1 -1
- package/dist/combobox.d.ts +12 -1
- package/dist/combobox.d.ts.map +1 -1
- package/dist/combobox.js +87 -79
- package/dist/command.cjs +1 -1
- package/dist/command.d.ts.map +1 -1
- package/dist/command.js +60 -50
- package/dist/date-picker.cjs +1 -1
- package/dist/date-picker.d.ts.map +1 -1
- package/dist/date-picker.js +66 -57
- package/dist/field.cjs +1 -1
- package/dist/field.d.ts.map +1 -1
- package/dist/field.js +2 -2
- package/dist/header.cjs +1 -1
- package/dist/header.d.ts +4 -0
- package/dist/header.d.ts.map +1 -1
- package/dist/header.js +33 -13
- package/dist/index.cjs +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +281 -268
- package/dist/input-chip.cjs +1 -1
- package/dist/input-chip.js +2 -2
- package/dist/input-group.cjs +1 -1
- package/dist/input-group.js +17 -17
- package/dist/input-otp.cjs +1 -1
- package/dist/input-otp.d.ts.map +1 -1
- package/dist/input-otp.js +20 -20
- package/dist/input-password.cjs +1 -1
- package/dist/input-password.d.ts.map +1 -1
- package/dist/input-password.js +33 -25
- package/dist/input.cjs +1 -1
- package/dist/input.js +15 -15
- package/dist/label.d.ts.map +1 -1
- package/dist/link.cjs +1 -1
- package/dist/link.d.ts.map +1 -1
- package/dist/link.js +24 -25
- package/dist/list.cjs +1 -0
- package/dist/list.d.ts +104 -0
- package/dist/list.d.ts.map +1 -0
- package/dist/list.js +145 -0
- package/dist/navigation-menu.cjs +1 -1
- package/dist/navigation-menu.d.ts.map +1 -1
- package/dist/navigation-menu.js +6 -5
- package/dist/radio-group.cjs +1 -1
- package/dist/radio-group.js +20 -20
- package/dist/select.cjs +1 -1
- package/dist/select.js +1 -1
- package/dist/sheet.d.ts.map +1 -1
- package/dist/sonner.cjs +1 -1
- package/dist/sonner.d.ts +10 -4
- package/dist/sonner.d.ts.map +1 -1
- package/dist/sonner.js +48 -41
- package/dist/split-layout.cjs +1 -1
- package/dist/split-layout.d.ts +66 -15
- package/dist/split-layout.d.ts.map +1 -1
- package/dist/split-layout.js +100 -96
- package/dist/switch.cjs +1 -1
- package/dist/switch.d.ts.map +1 -1
- package/dist/switch.js +2 -2
- package/dist/textarea.cjs +1 -1
- package/dist/textarea.js +1 -1
- package/dist/tooltip.cjs +1 -1
- package/dist/tooltip.d.ts.map +1 -1
- package/dist/tooltip.js +40 -38
- package/package.json +5 -1
- package/src/blocks/input-list.tsx +366 -0
- package/src/blocks/sidebar.tsx +7 -7
- package/src/components/breadcrumb.tsx +4 -1
- package/src/components/button.tsx +1 -0
- package/src/components/calendar.tsx +1 -1
- package/src/components/checkbox.tsx +2 -4
- package/src/components/combobox.tsx +21 -2
- package/src/components/command.tsx +25 -9
- package/src/components/date-picker.tsx +15 -5
- package/src/components/dropdown-menu.tsx +3 -3
- package/src/components/field.tsx +5 -3
- package/src/components/header.tsx +28 -2
- package/src/components/input-chip.tsx +2 -2
- package/src/components/input-group.tsx +4 -4
- package/src/components/input-otp.tsx +7 -3
- package/src/components/input-password.tsx +8 -2
- package/src/components/input.tsx +1 -1
- package/src/components/label.tsx +1 -4
- package/src/components/link.tsx +3 -4
- package/src/components/list.tsx +290 -0
- package/src/components/navigation-menu.tsx +1 -0
- package/src/components/radio-group.tsx +2 -2
- package/src/components/select.tsx +3 -3
- package/src/components/sheet.tsx +2 -2
- package/src/components/sonner.tsx +30 -12
- package/src/components/split-layout.tsx +200 -79
- package/src/components/switch.tsx +6 -4
- package/src/components/textarea.tsx +1 -1
- package/src/components/tooltip.tsx +4 -2
- package/src/index.ts +2 -0
package/AI_USAGE.md
ADDED
|
@@ -0,0 +1,390 @@
|
|
|
1
|
+
# AI Usage Guide — @brightlocal/ui-components
|
|
2
|
+
|
|
3
|
+
This document provides rules and patterns for AI assistants generating code with the BrightLocal Design System. Following these rules ensures output that is consistent, accessible, and on-system.
|
|
4
|
+
|
|
5
|
+
## Quick Rules
|
|
6
|
+
|
|
7
|
+
1. **Import per-file, never barrel** — `import { Button } from "@brightlocal/ui-components/button"`
|
|
8
|
+
2. **Provide `dataHook` on interactive components** — Required on user-interactive roots (Button, Input, Select, etc.); optional on layout/structural components (Separator, Skeleton, ScrollArea, etc.)
|
|
9
|
+
3. **Use semantic tokens first; fall back to Tailwind utilities, never raw hex** — prefer `text-primary`, use `text-blue-600` when no semantic token fits, never `#000000`
|
|
10
|
+
4. **Use DS components, not raw HTML** — `<Button>` not `<button>`, `<Input>` not `<input>`
|
|
11
|
+
5. **Compose with compound components** — Use the provided sub-component pattern, don't rebuild from primitives
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## The `dataHook` Prop
|
|
16
|
+
|
|
17
|
+
Most components in this library accept a `dataHook` prop, and it is **required** on all user-interactive components. This is the single most important convention to follow.
|
|
18
|
+
|
|
19
|
+
### What is it?
|
|
20
|
+
|
|
21
|
+
`dataHook` renders as a `data-hook` HTML attribute used for automated testing and QA selectors. It is **required** on interactive component roots (Button, Input, Select, Dialog, Tabs, etc.) and **optional** on layout/structural components (Separator, Skeleton, ScrollArea, Collapsible, etc.). Check `component-meta.json` for per-component `dataHookRequired` values.
|
|
22
|
+
|
|
23
|
+
### Naming Convention
|
|
24
|
+
|
|
25
|
+
Use **kebab-case** descriptive names that reflect the component's role in the UI:
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
{context}-{componentType}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**Examples:**
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
<Button dataHook="settings-save-button">Save</Button>
|
|
35
|
+
<Input dataHook="login-email-input" />
|
|
36
|
+
<Dialog>
|
|
37
|
+
<DialogTrigger dataHook="delete-confirm-trigger">Delete</DialogTrigger>
|
|
38
|
+
<DialogContent dataHook="delete-confirm-dialog">
|
|
39
|
+
<DialogTitle>Confirm deletion</DialogTitle>
|
|
40
|
+
</DialogContent>
|
|
41
|
+
</Dialog>
|
|
42
|
+
<Card dataHook="user-profile-card">...</Card>
|
|
43
|
+
<Tabs dataHook="dashboard-tabs">...</Tabs>
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Rules
|
|
47
|
+
|
|
48
|
+
- Use the page/section name as prefix: `login-`, `settings-`, `dashboard-`
|
|
49
|
+
- Use the component type as suffix: `-button`, `-input`, `-dialog`, `-card`
|
|
50
|
+
- For lists, include the item identifier: `user-{id}-row`, `task-{index}-card`
|
|
51
|
+
- Sub-components of compound components inherit context from the parent — only the root or key interactive sub-components need `dataHook`
|
|
52
|
+
- Never use generic names like `hook-1` or `test-button`
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Import Conventions
|
|
57
|
+
|
|
58
|
+
### Correct — Per-file imports
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
import { Button } from "@brightlocal/ui-components/button";
|
|
62
|
+
import { Input } from "@brightlocal/ui-components/input";
|
|
63
|
+
import { Dialog, DialogContent, DialogTrigger, DialogTitle } from "@brightlocal/ui-components/dialog";
|
|
64
|
+
import { Card, CardHeader, CardContent } from "@brightlocal/ui-components/card";
|
|
65
|
+
import { cn } from "@brightlocal/ui-components/lib/utils";
|
|
66
|
+
import { DataTable } from "@brightlocal/ui-components/blocks/data-table";
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Wrong — Barrel imports
|
|
70
|
+
|
|
71
|
+
```tsx
|
|
72
|
+
// NEVER do this — causes large bundle size
|
|
73
|
+
import { Button, Input, Dialog } from "@brightlocal/ui-components";
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Icons
|
|
77
|
+
|
|
78
|
+
Icons come from a separate package:
|
|
79
|
+
|
|
80
|
+
```tsx
|
|
81
|
+
import { SearchIcon, ChevronDownIcon, XIcon } from "@brightlocal/icons";
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Icons render at 16px by default. Do not pass `size` or `strokeWidth` unless you need a different size.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Styling Rules
|
|
89
|
+
|
|
90
|
+
### Color Usage
|
|
91
|
+
|
|
92
|
+
**Priority order:** semantic tokens → Tailwind color utilities → never raw hex values.
|
|
93
|
+
|
|
94
|
+
```tsx
|
|
95
|
+
// BEST — semantic tokens (use whenever a matching token exists)
|
|
96
|
+
<div className="bg-background text-foreground" />
|
|
97
|
+
<div className="bg-primary text-primary-foreground" />
|
|
98
|
+
<div className="bg-muted text-muted-foreground" />
|
|
99
|
+
<div className="border-destructive text-destructive" />
|
|
100
|
+
|
|
101
|
+
// OK — Tailwind color utilities (when no semantic token fits)
|
|
102
|
+
<div className="bg-blue-600 text-white" />
|
|
103
|
+
<div className="bg-gray-100 text-gray-500" />
|
|
104
|
+
|
|
105
|
+
// WRONG — raw hex/rgb values (never use these)
|
|
106
|
+
<div className="bg-[#1e40af] text-[#ffffff]" />
|
|
107
|
+
<div style={{ color: "#000000" }} />
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Available semantic tokens:** `primary`, `secondary`, `destructive`, `muted`, `accent`, `background`, `foreground`, `card`, `popover`, `border`, `input`, `ring`, `warning`, `success`, `info`.
|
|
111
|
+
|
|
112
|
+
### Spacing
|
|
113
|
+
|
|
114
|
+
Use Tailwind spacing utilities. Prefer consistent spacing:
|
|
115
|
+
- Between form fields: `gap-4` or `space-y-4`
|
|
116
|
+
- Card padding: `p-4` or `p-6`
|
|
117
|
+
- Section spacing: `gap-6` or `gap-8`
|
|
118
|
+
|
|
119
|
+
### Transitions
|
|
120
|
+
|
|
121
|
+
Always specify the property — never use `transition-all`:
|
|
122
|
+
|
|
123
|
+
```tsx
|
|
124
|
+
// CORRECT
|
|
125
|
+
<div className="transition-colors duration-200 ease-out" />
|
|
126
|
+
<div className="transition-opacity duration-150 ease-out" />
|
|
127
|
+
|
|
128
|
+
// WRONG
|
|
129
|
+
<div className="transition-all duration-200" />
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Focus States
|
|
133
|
+
|
|
134
|
+
Always use `focus-visible`, never bare `focus`:
|
|
135
|
+
|
|
136
|
+
```tsx
|
|
137
|
+
// CORRECT
|
|
138
|
+
<div className="outline-none focus-visible:shadow-default" />
|
|
139
|
+
|
|
140
|
+
// WRONG
|
|
141
|
+
<div className="focus:ring-2 focus:ring-blue-500" />
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Dark Mode
|
|
145
|
+
|
|
146
|
+
Semantic token classes (e.g., `bg-background`, `text-foreground`, `border-border`) adapt to dark mode automatically via CSS custom properties — no `dark:` prefix needed.
|
|
147
|
+
|
|
148
|
+
Use the `dark:` modifier only for non-token utilities:
|
|
149
|
+
|
|
150
|
+
```tsx
|
|
151
|
+
<div className="bg-white dark:bg-gray-900" />
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Component Patterns
|
|
157
|
+
|
|
158
|
+
### Simple Components
|
|
159
|
+
|
|
160
|
+
```tsx
|
|
161
|
+
<Button dataHook="save-button" variant="default" size="default">
|
|
162
|
+
Save Changes
|
|
163
|
+
</Button>
|
|
164
|
+
|
|
165
|
+
<Input dataHook="search-input" placeholder="Search..." />
|
|
166
|
+
|
|
167
|
+
<Badge dataHook="status-badge" variant="secondary">Active</Badge>
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Compound Components
|
|
171
|
+
|
|
172
|
+
Many components use a compound pattern with multiple sub-components. Always use the provided sub-components:
|
|
173
|
+
|
|
174
|
+
```tsx
|
|
175
|
+
// CORRECT — use compound sub-components
|
|
176
|
+
<Card dataHook="profile-card">
|
|
177
|
+
<CardHeader>
|
|
178
|
+
<CardTitle>Profile</CardTitle>
|
|
179
|
+
<CardDescription>Manage your profile settings</CardDescription>
|
|
180
|
+
</CardHeader>
|
|
181
|
+
<CardContent>
|
|
182
|
+
{/* content */}
|
|
183
|
+
</CardContent>
|
|
184
|
+
<CardFooter>
|
|
185
|
+
<Button dataHook="profile-save-button">Save</Button>
|
|
186
|
+
</CardFooter>
|
|
187
|
+
</Card>
|
|
188
|
+
|
|
189
|
+
// WRONG — reconstructing structure with divs
|
|
190
|
+
<Card dataHook="profile-card">
|
|
191
|
+
<div className="p-4 border-b">
|
|
192
|
+
<h3>Profile</h3>
|
|
193
|
+
</div>
|
|
194
|
+
<div className="p-4">{/* content */}</div>
|
|
195
|
+
</Card>
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Form Fields
|
|
199
|
+
|
|
200
|
+
Always wrap form inputs with `Field` for labels, descriptions, and error states:
|
|
201
|
+
|
|
202
|
+
```tsx
|
|
203
|
+
<Field>
|
|
204
|
+
<FieldLabel htmlFor="email">Email Address</FieldLabel>
|
|
205
|
+
<Input dataHook="email-input" id="email" type="email" />
|
|
206
|
+
<FieldDescription>We'll never share your email.</FieldDescription>
|
|
207
|
+
<FieldError>Please enter a valid email.</FieldError>
|
|
208
|
+
</Field>
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
For groups of related fields:
|
|
212
|
+
|
|
213
|
+
```tsx
|
|
214
|
+
<FieldSet>
|
|
215
|
+
<FieldLegend>Contact Information</FieldLegend>
|
|
216
|
+
<FieldGroup orientation="vertical">
|
|
217
|
+
<Field>
|
|
218
|
+
<FieldLabel htmlFor="name">Name</FieldLabel>
|
|
219
|
+
<Input dataHook="name-input" id="name" />
|
|
220
|
+
</Field>
|
|
221
|
+
<Field>
|
|
222
|
+
<FieldLabel htmlFor="email">Email</FieldLabel>
|
|
223
|
+
<Input dataHook="email-input" id="email" type="email" />
|
|
224
|
+
</Field>
|
|
225
|
+
</FieldGroup>
|
|
226
|
+
</FieldSet>
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
### Overlays (Dialogs, Sheets, Drawers)
|
|
230
|
+
|
|
231
|
+
All overlay components follow the same pattern:
|
|
232
|
+
|
|
233
|
+
```tsx
|
|
234
|
+
<Dialog>
|
|
235
|
+
<DialogTrigger asChild>
|
|
236
|
+
<Button dataHook="open-dialog-button">Open</Button>
|
|
237
|
+
</DialogTrigger>
|
|
238
|
+
<DialogContent dataHook="my-dialog">
|
|
239
|
+
<DialogHeader>
|
|
240
|
+
<DialogTitle>Dialog Title</DialogTitle>
|
|
241
|
+
<DialogDescription>Description of the dialog purpose.</DialogDescription>
|
|
242
|
+
</DialogHeader>
|
|
243
|
+
{/* Dialog body content */}
|
|
244
|
+
<DialogFooter>
|
|
245
|
+
<DialogClose asChild>
|
|
246
|
+
<Button dataHook="dialog-cancel-button" variant="outline">Cancel</Button>
|
|
247
|
+
</DialogClose>
|
|
248
|
+
<Button dataHook="dialog-confirm-button">Confirm</Button>
|
|
249
|
+
</DialogFooter>
|
|
250
|
+
</DialogContent>
|
|
251
|
+
</Dialog>
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
### Select / Combobox
|
|
255
|
+
|
|
256
|
+
For simple selection, use `Select`. For searchable/filterable selection, use `Combobox`:
|
|
257
|
+
|
|
258
|
+
```tsx
|
|
259
|
+
{/* Simple select */}
|
|
260
|
+
<Select value={value} onValueChange={setValue}>
|
|
261
|
+
<SelectTrigger dataHook="country-select">
|
|
262
|
+
<SelectValue placeholder="Select country" />
|
|
263
|
+
</SelectTrigger>
|
|
264
|
+
<SelectContent>
|
|
265
|
+
<SelectItem value="us">United States</SelectItem>
|
|
266
|
+
<SelectItem value="uk">United Kingdom</SelectItem>
|
|
267
|
+
</SelectContent>
|
|
268
|
+
</Select>
|
|
269
|
+
|
|
270
|
+
{/* Searchable combobox */}
|
|
271
|
+
<Combobox value={value} onValueChange={setValue}>
|
|
272
|
+
<ComboboxTrigger dataHook="user-combobox">
|
|
273
|
+
<ComboboxValue placeholder="Select user" />
|
|
274
|
+
</ComboboxTrigger>
|
|
275
|
+
<ComboboxContent>
|
|
276
|
+
<ComboboxInput placeholder="Search users..." />
|
|
277
|
+
<ComboboxEmpty>No users found.</ComboboxEmpty>
|
|
278
|
+
<ComboboxGroup>
|
|
279
|
+
<ComboboxItem value="alice">Alice</ComboboxItem>
|
|
280
|
+
<ComboboxItem value="bob">Bob</ComboboxItem>
|
|
281
|
+
</ComboboxGroup>
|
|
282
|
+
</ComboboxContent>
|
|
283
|
+
</Combobox>
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
### Tables
|
|
287
|
+
|
|
288
|
+
For simple tables, use `Table`. For complex data tables with sorting/filtering/pagination, use the `DataTable` block:
|
|
289
|
+
|
|
290
|
+
```tsx
|
|
291
|
+
{/* Simple table */}
|
|
292
|
+
<Table dataHook="users-table">
|
|
293
|
+
<TableHeader>
|
|
294
|
+
<TableRow>
|
|
295
|
+
<TableHead>Name</TableHead>
|
|
296
|
+
<TableHead>Email</TableHead>
|
|
297
|
+
</TableRow>
|
|
298
|
+
</TableHeader>
|
|
299
|
+
<TableBody>
|
|
300
|
+
<TableRow>
|
|
301
|
+
<TableCell>Alice</TableCell>
|
|
302
|
+
<TableCell>alice@example.com</TableCell>
|
|
303
|
+
</TableRow>
|
|
304
|
+
</TableBody>
|
|
305
|
+
</Table>
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Notifications (Sonner)
|
|
309
|
+
|
|
310
|
+
Mount `<Sonner />` once at the app root, then call `sonner()` anywhere to show toasts:
|
|
311
|
+
|
|
312
|
+
```tsx
|
|
313
|
+
import { sonner, Sonner } from "@brightlocal/ui-components/sonner";
|
|
314
|
+
|
|
315
|
+
// Mount once in your app root (e.g., App.tsx or layout.tsx)
|
|
316
|
+
<Sonner />
|
|
317
|
+
|
|
318
|
+
// Trigger toasts anywhere
|
|
319
|
+
sonner({ title: "Changes saved", icon: "success" });
|
|
320
|
+
sonner({ title: "Error occurred", description: "Please try again.", icon: "error" });
|
|
321
|
+
|
|
322
|
+
// Custom duration (default is 4000ms)
|
|
323
|
+
sonner({ title: "Heads up!", icon: "info" }, { duration: 10000 });
|
|
324
|
+
|
|
325
|
+
// Persistent toast — stays visible until dismissed
|
|
326
|
+
sonner(
|
|
327
|
+
{ title: "Redirecting…", icon: "loading" },
|
|
328
|
+
{ duration: Infinity, id: "redirect-toast" },
|
|
329
|
+
);
|
|
330
|
+
|
|
331
|
+
// Dismiss programmatically
|
|
332
|
+
sonner.dismiss("redirect-toast");
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
- **Icons:** `"info"` | `"success"` | `"warning"` | `"error"` | `"loading"` | `null`
|
|
336
|
+
- **Color schemas:** `"default"` | `"success"`
|
|
337
|
+
- **Duration:** `number` in ms (default 4000). Use `Infinity` to keep the toast visible until the user closes it or you call `sonner.dismiss(id)`
|
|
338
|
+
- **`dataHook` is not required** — Sonner is a global provider, not a per-instance component
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
## Do's and Don'ts
|
|
343
|
+
|
|
344
|
+
### Do
|
|
345
|
+
|
|
346
|
+
- Use `Field` + `FieldLabel` for all form inputs
|
|
347
|
+
- Use `asChild` on triggers to render your own button: `<DialogTrigger asChild><Button>...</Button></DialogTrigger>`
|
|
348
|
+
- Use `cn()` from `@brightlocal/ui-components/lib/utils` to merge classNames
|
|
349
|
+
- Use `variant` and `size` props instead of custom className overrides
|
|
350
|
+
- Provide `aria-label` on icon-only buttons (`iconOnly` prop)
|
|
351
|
+
- Use `Typography` components (`H1`–`H4`, `P`, `Small`, `Muted`, `Lead`) for text
|
|
352
|
+
- Use `Separator` between content sections, not `<hr>` or border utilities
|
|
353
|
+
|
|
354
|
+
### Don't
|
|
355
|
+
|
|
356
|
+
- Don't use raw HTML elements when a DS component exists (`<button>`, `<input>`, `<select>`, `<table>`, `<hr>`)
|
|
357
|
+
- Don't use raw hex/rgb colors (`#000000`, `rgb(0,0,0)`, `bg-[#1e40af]`) — use semantic tokens first (`text-primary`, `bg-muted`), or Tailwind utilities (`text-blue-600`) when no token fits
|
|
358
|
+
- Don't use `transition-all` — always specify the property (`transition-colors`, `transition-opacity`)
|
|
359
|
+
- Don't use bare `focus:` — always use `focus-visible:`
|
|
360
|
+
- Don't import from the barrel `"@brightlocal/ui-components"` — use per-file imports
|
|
361
|
+
- Don't create wrapper `<div>`s for layout when `Card`, `Field`, or layout components exist
|
|
362
|
+
- Don't skip `dataHook` on interactive components — check `component-meta.json` if unsure whether it's required
|
|
363
|
+
- Don't use `size` prop on icons unless overriding the 16px default
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## Accessibility Checklist
|
|
368
|
+
|
|
369
|
+
When composing UI with these components:
|
|
370
|
+
|
|
371
|
+
1. Every form input has a visible `<FieldLabel>` or `aria-label`
|
|
372
|
+
2. Error states use `aria-invalid` (handled by the `error` prop on most inputs)
|
|
373
|
+
3. Dialogs have `DialogTitle` and `DialogDescription`
|
|
374
|
+
4. Icon-only buttons have `aria-label` or `ariaLabel` prop
|
|
375
|
+
5. Images and avatars have `alt` text
|
|
376
|
+
6. Interactive elements are keyboard-navigable (built-in for all DS components)
|
|
377
|
+
7. Color is not the only indicator of state (icons, text, borders supplement color)
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
381
|
+
## Component Reference
|
|
382
|
+
|
|
383
|
+
For a machine-readable registry of all components with their categories, props, variants, and relationships, see [`component-meta.json`](./component-meta.json).
|
|
384
|
+
|
|
385
|
+
For TypeScript prop definitions, use the types exported alongside each component:
|
|
386
|
+
|
|
387
|
+
```tsx
|
|
388
|
+
import type { ButtonProps } from "@brightlocal/ui-components/button";
|
|
389
|
+
import type { InputProps } from "@brightlocal/ui-components/input";
|
|
390
|
+
```
|
package/README.md
CHANGED
|
@@ -5,20 +5,26 @@ BrightLocal Design System UI Components package containing low-level React compo
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
|
|
8
|
+
pnpm add @brightlocal/ui-components
|
|
9
9
|
```
|
|
10
10
|
|
|
11
11
|
## Peer Dependencies
|
|
12
12
|
|
|
13
|
-
This package requires React 18 or 19:
|
|
13
|
+
This package requires React 18 or 19 and Tailwind CSS v4:
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
|
-
|
|
16
|
+
pnpm add react react-dom tailwindcss @tailwindcss/vite
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
You also need the BrightLocal design tokens for theming:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pnpm add @brightlocal/tokens
|
|
17
23
|
```
|
|
18
24
|
|
|
19
25
|
## Components
|
|
20
26
|
|
|
21
|
-
This package includes
|
|
27
|
+
This package includes 61 components built on Radix UI primitives and other React libraries. All components are fully typed with TypeScript and follow BrightLocal's design system patterns.
|
|
22
28
|
|
|
23
29
|
### Layout Components
|
|
24
30
|
|
|
@@ -316,17 +322,46 @@ When using these components:
|
|
|
316
322
|
|
|
317
323
|
## Available Exports
|
|
318
324
|
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
325
|
+
Components are exported per-file (not barrel imports). Use the component name in kebab-case:
|
|
326
|
+
|
|
327
|
+
```tsx
|
|
328
|
+
import { Button } from "@brightlocal/ui-components/button";
|
|
329
|
+
import { Dialog, DialogContent, DialogTrigger } from "@brightlocal/ui-components/dialog";
|
|
330
|
+
import { DataTable } from "@brightlocal/ui-components/blocks/data-table";
|
|
331
|
+
import { useIsMobile } from "@brightlocal/ui-components/hooks/use-mobile";
|
|
332
|
+
import { cn } from "@brightlocal/ui-components/lib/utils";
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
| Path pattern | Example |
|
|
336
|
+
|---|---|
|
|
337
|
+
| `@brightlocal/ui-components/{component}` | `/button`, `/input`, `/dialog`, `/select` |
|
|
338
|
+
| `@brightlocal/ui-components/blocks/{block}` | `/blocks/data-table`, `/blocks/sidebar` |
|
|
339
|
+
| `@brightlocal/ui-components/hooks/{hook}` | `/hooks/use-mobile` |
|
|
340
|
+
| `@brightlocal/ui-components/lib/{util}` | `/lib/utils` |
|
|
323
341
|
|
|
324
342
|
## Dependencies
|
|
325
343
|
|
|
326
344
|
This package builds on:
|
|
327
345
|
|
|
328
|
-
-
|
|
329
|
-
-
|
|
346
|
+
- **Radix UI** - Accessible primitives (Dialog, Select, Tabs, Tooltip, etc.)
|
|
347
|
+
- **Class Variance Authority** - Component variant management
|
|
348
|
+
- **Tailwind Merge** - Intelligent class merging via `cn()` utility
|
|
349
|
+
- **Framer Motion** - Animation and transitions
|
|
350
|
+
- **TanStack Table** - Headless table utilities (DataTable block)
|
|
351
|
+
- **Recharts** - Chart visualizations (Chart component)
|
|
352
|
+
- **react-day-picker** - Calendar and date picking
|
|
353
|
+
- **Embla Carousel** - Carousel functionality
|
|
354
|
+
- **Sonner** - Toast notifications
|
|
355
|
+
- **Vaul** - Drawer component
|
|
356
|
+
|
|
357
|
+
## AI Integration
|
|
358
|
+
|
|
359
|
+
This package ships with AI-friendly documentation:
|
|
360
|
+
|
|
361
|
+
- **[AI_USAGE.md](./AI_USAGE.md)** — Rules, patterns, do's/don'ts, and composition examples for AI code generation
|
|
362
|
+
- **[component-meta.json](./component-meta.json)** — Machine-readable registry of all components with categories, variants, props, and relationships
|
|
363
|
+
|
|
364
|
+
These files help AI assistants generate code that follows BrightLocal Design System conventions out of the box.
|
|
330
365
|
|
|
331
366
|
## Development
|
|
332
367
|
|