struxadotcloud/struxa

public

initial commitd4cb9e15 months ago197 lines · 4.8 KB

1	# Component Composition
2
3	## Contents
4
5	- Items always inside their Group component
6	- Callouts use Alert
7	- Empty states use Empty component
8	- Toast notifications use sonner
9	- Choosing between overlay components
10	- Dialog, Sheet, and Drawer always need a Title
11	- Card structure
12	- Button has no isPending or isLoading prop
13	- TabsTrigger must be inside TabsList
14	- Avatar always needs AvatarFallback
15	- Use Separator instead of raw hr or border divs
16	- Use Skeleton for loading placeholders
17	- Use Badge instead of custom styled spans
18
19	---
20
21	## Items always inside their Group component
22
23	Never render items directly inside the content container.
24
25	Incorrect:
26
27	```tsx
28	<SelectContent>
29	<SelectItem value=
30	<SelectItem value=
31	</SelectContent>
32	```
33
34	Correct:
35
36	```tsx
37	<SelectContent>
38	<SelectGroup>
39	<SelectItem value=
40	<SelectItem value=
41	</SelectGroup>
42	</SelectContent>
43	```
44
45	This applies to all group-based components:
46
47	\| Item \| Group \|
48	\| ---------------------------------------------------------- \| ------------------- \|
49	\| `SelectItem`, `SelectLabel`
50	\| `DropdownMenuItem`, `DropdownMenuLabel`,
51	\| `MenubarItem` \| `MenubarGroup
52	\| `ContextMenuItem` \| `ContextMenuGroup
53	\| `CommandItem` \| `CommandGroup
54
55	---
56
57	## Callouts use Alert
58
59	```tsx
60	<Alert>
61	<AlertTitle>Warning</AlertTitle
62	<AlertDescription>Something needs attention.</AlertDescription
63	</Alert>
64	```
65
66	---
67
68	## Empty states use Empty component
69
70	```tsx
71	<Empty>
72	<EmptyHeader>
73	<EmptyMedia variant=
74	<FolderIcon />
75	</EmptyMedia>
76	<EmptyTitle>No projects yet</EmptyTitle
77	<EmptyDescription>Get started by creating a new project.</EmptyDescription
78	</EmptyHeader>
79	<EmptyContent>
80	<Button>Create Project</Button
81	</EmptyContent>
82	</Empty>
83	```
84
85	---
86
87	## Toast notifications use sonner
88
89	```tsx
90	import { toast }
91
92	toast.success("Changes saved."
93	toast.error("Something went wrong."
94	toast("File deleted.", {
95	action: { label: "
96	});
97	```
98
99	---
100
101	## Choosing between overlay components
102
103	\| Use case \| Component \|
104	\| ---------------------------------- \| ------------- \|
105	\| Focused task that requires input \| `Dialog` \|
106	\| Destructive action confirmation \| `AlertDialog` \|
107	\| Side panel with details or filters \| `Sheet` \|
108	\| Mobile-first bottom panel \| `Drawer` \|
109	\| Quick info on hover \| `HoverCard` \|
110	\| Small contextual content on click \| `Popover` \|
111
112	---
113
114	## Dialog, Sheet, and Drawer always need a Title
115
116	`DialogTitle`, `SheetTitle`, `DrawerTitle
117
118	```tsx
119	<DialogContent>
120	<DialogHeader>
121	<DialogTitle>Edit Profile</DialogTitle
122	<DialogDescription>Update your profile.</DialogDescription
123	</DialogHeader>
124	...
125	</DialogContent>
126	```
127
128	---
129
130	## Card structure
131
132	Use full composition — don't dump everything into `CardContent`:
133
134	```tsx
135	<Card>
136	<CardHeader>
137	<CardTitle>Team Members</CardTitle
138	<CardDescription>Manage your team.</CardDescription
139	</CardHeader>
140	<CardContent>...</CardContent
141	<CardFooter>
142	<Button>Invite</Button
143	</CardFooter>
144	</Card>
145	```
146
147	---
148
149	## Button has no isPending or isLoading prop
150
151	Compose with `Spinner` + `data-icon` + `
152
153	```tsx
154	<Button disabled>
155	<Spinner data-icon=
156	Saving...
157	</Button>
158	```
159
160	---
161
162	## TabsTrigger must be inside TabsList
163
164	Never render `TabsTrigger` directly inside `Tabs` — always wrap in `
165
166	```tsx
167	<Tabs defaultValue="
168	<TabsList>
169	<TabsTrigger value=
170	<TabsTrigger value=
171	</TabsList>
172	<TabsContent value=
173	</Tabs>
174	```
175
176	---
177
178	## Avatar always needs AvatarFallback
179
180	Always include `AvatarFallback` for when the image fails to load:
181
182	```tsx
183	<Avatar>
184	<AvatarImage src=
185	<AvatarFallback>JD</AvatarFallback
186	</Avatar>
187	```
188
189	---
190
191	## Use existing components instead of custom markup
192
193	\| Instead of \| Use \|
194	\| -------------------------------------------------- \| ------------------------------------ \|
195	\| `<hr>` or `<div className="border-t">`
196	\| `<div className="animate-pulse">` with styled divs \| `<Skeleton className="h-4 w-3/4" />
197	\| `<span className="rounded-full bg-green-100 ...">` \| `<Badge variant="secondary">