@hubbiparts/uikit 0.1.0 → 0.2.0

package/skills/hubbiparts-uikit/rules/usage.md

@@ -0,0 +1,183 @@
+# Usage & Composition
+
+The kit is shadcn/ui on the **Radix** base. Everything in the shadcn Radix docs applies, with these package-specific rules.
+
+## Imports
+
+```tsx
+// Correct
+import { Button, Card, CardContent, cn } from '@hubbiparts/uikit'
+
+// Incorrect — deep import, local copy, or shadcn alias
+import { Button } from '@hubbiparts/uikit/dist/components/ui/button'
+import { Button } from '@/components/ui/button'
+```
+
+Check a component exists in the installed version before importing it: `npx hubbiparts-uikit list`.
+
+## Custom triggers: `asChild`
+
+```tsx
+// Correct
+<DialogTrigger asChild>
+  <Button variant="outline">Open</Button>
+</DialogTrigger>
+
+// Incorrect — nested <button> inside <button>
+<DialogTrigger>
+  <Button variant="outline">Open</Button>
+</DialogTrigger>
+```
+
+`Combobox` is the one Base UI component in the kit: it takes `items` and uses `ComboboxInput` / `ComboboxContent` / `ComboboxList` / `ComboboxItem`, not `asChild`. Check `npx hubbiparts-uikit docs combobox`.
+
+## Groups and items
+
+```tsx
+<Select>
+  <SelectTrigger><SelectValue placeholder="Catalog" /></SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectItem value="oem">OEM</SelectItem>
+      <SelectItem value="partner">Partner</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+
+<Command>
+  <CommandInput placeholder="Search" />
+  <CommandList>
+    <CommandGroup heading="Parts">
+      <CommandItem value="filter">Oil filter</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+## Overlays always have a title
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild><Button variant="outline">Details</Button></SheetTrigger>
+  <SheetContent>
+    <SheetHeader>
+      <SheetTitle>Part details</SheetTitle>
+      <SheetDescription>Review without leaving the catalog.</SheetDescription>
+    </SheetHeader>
+  </SheetContent>
+</Sheet>
+```
+
+Hidden title: `<DialogTitle className="sr-only">Search</DialogTitle>`. Never add `z-index` to overlays.
+
+## Forms
+
+```tsx
+// Correct
+<FieldGroup>
+  <Field data-invalid={!!errors.plate}>
+    <FieldLabel htmlFor="plate">Plate</FieldLabel>
+    <Input id="plate" aria-invalid={!!errors.plate} className="font-mono uppercase" />
+    <FieldDescription>Mercosul or legacy format.</FieldDescription>
+    {errors.plate && <FieldError>{errors.plate}</FieldError>}
+  </Field>
+</FieldGroup>
+
+// Incorrect
+<div className="space-y-2">
+  <label>Plate</label>
+  <input className="border rounded px-2" />
+  <p className="text-red-500">Invalid</p>
+</div>
+```
+
+- Buttons/icons inside inputs: `InputGroup` + `InputGroupInput` + `InputGroupAddon`, never a raw `Input` inside `InputGroup`.
+- 2–7 exclusive options: `ToggleGroup`, not a row of `Button`s with manual active state.
+- Related checkboxes/radios: `FieldSet` + `FieldLegend`.
+- Disabled: `data-disabled` on `Field`, `disabled` on the control.
+
+## Buttons, loading and icons
+
+```tsx
+import { Search } from 'lucide-react'
+
+<Button>
+  <Search data-icon="inline-start" />
+  Search by plate
+</Button>
+
+<Button disabled={pending}>
+  {pending && <Spinner data-icon="inline-start" />}
+  Save
+</Button>
+```
+
+- No `isLoading` prop exists.
+- No `size-4` / `w-4 h-4` on icons inside kit components — the component sizes them.
+- Icon-only buttons: `size="icon"` plus `aria-label`.
+
+## Cards
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Inventory</CardTitle>
+    <CardDescription>Updated 2 min ago</CardDescription>
+  </CardHeader>
+  <CardContent>…</CardContent>
+  <CardFooter><Button variant="outline">Open</Button></CardFooter>
+</Card>
+```
+
+## Feedback
+
+```tsx
+import { toast } from 'sonner'
+
+toast.success('Catalog synchronized')
+```
+
+- Callouts: `Alert` + `AlertTitle` + `AlertDescription`.
+- Empty states: `Empty` + `EmptyHeader` + `EmptyMedia` + `EmptyTitle` + `EmptyDescription`.
+- Loading placeholders: `Skeleton`, not `animate-pulse` divs.
+- Status: `Badge` variants, not colored spans.
+- Dividers: `Separator`, not `<hr>` or `border-t` divs.
+
+## Sidebar layouts
+
+```tsx
+<SidebarProvider>
+  <Sidebar collapsible="icon">
+    <SidebarHeader>…</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>Catalog</SidebarGroupLabel>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton isActive tooltip="Parts">Parts</SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+    <SidebarRail />
+  </Sidebar>
+  <SidebarInset>
+    <header><SidebarTrigger /></header>
+    <main>…</main>
+  </SidebarInset>
+</SidebarProvider>
+```
+
+`useSidebar()` is exported for custom toggles. Needs `TooltipProvider` above it.
+
+## Composition-only patterns
+
+- **Data Table** — `Table` + sorting/filtering/pagination state (e.g. TanStack Table in the project). Keep table state in the feature, not in the kit.
+- **Date Picker** — `Popover` + `PopoverTrigger asChild` (`Button`) + `PopoverContent` + `Calendar`.
+- **Typography** — semantic HTML + `font-display` / `font-sans` / `font-mono` tokens.
+
+## When the kit lacks something
+
+1. Compose it from kit components in a feature folder (e.g. `src/features/parts/PlateSearch.tsx`), not in `components/ui`.
+2. Tell the user it is a kit contribution candidate (see [contributing.md](./contributing.md)).
+3. Never copy a shadcn component into the consumer when the kit already ships it.