6.3 KiB
@collabry/components
React 19 + Tailwind CSS component library for the Collabry UI, built on shadcn/ui (Radix UI, cmdk, Sonner), with a Storybook catalogue.
npm install
npm run storybook # http://localhost:6006
npm run build # library → dist/ (ESM, types, collabry.css)
npm run build-storybook # static Storybook → storybook-static/
npm run typecheck
Use in an app
import { ThemeProvider, Button, Toaster } from '@collabry/components';
import '@collabry/components/styles.css';
import '@fontsource/lato/400.css';
import '@fontsource/lato/700.css';
import '@fontsource/lato/900.css';
<ThemeProvider theme="dark" accent="#6A5FCB" tint="off" className="min-h-screen bg-app">
<Button variant="primary">Neue Aufgabe</Button>
<Toaster /> {/* once, if you use toast() */}
</ThemeProvider>;
react and react-dom (19) are peer dependencies; radix-ui, cmdk, sonner, class-variance-authority, lucide-react, clsx and tailwind-merge come with the package.
Dialogs, menus and popovers portal into the nearest ThemeProvider element, so they keep its theme, accent and tint.
Composition
Components are small parts you assemble, like shadcn/ui. They don't take data objects or config props; each part renders one element, takes className and ref, and has a data-slot (card-title, nav-item, …) to target it from outside. Parts that are often links or headings accept asChild. The design (spacing, colors, states) lives in the parts; structure and data live in your code.
<CardFrame>
<Card asChild>
<section aria-labelledby="h-tasks">
<CardHeader>
<CardTitle id="h-tasks">
Meine Aufgaben <CountBadge>6</CountBadge>
</CardTitle>
<CardAction>…</CardAction>
</CardHeader>
<TaskTable aria-label="Meine Aufgaben">
<TaskRow done={task.status === 'done'}>
<TaskCell>
<TaskCheckbox checked={…} onCheckedChange={…} aria-label="…" />
</TaskCell>
<TaskCell>
<TaskTitle>{task.title}</TaskTitle>
<TaskMeta>…</TaskMeta>
</TaskCell>
…
</TaskRow>
</TaskTable>
</section>
</Card>
</CardFrame>
Conventions:
- State flows down through context where it's shared:
Fieldwires label, control and messages (id,aria-describedby,aria-invalid);Sidebartells its parts whether it's collapsed;TaskTablesets the column grid of its rows. - Overlays use the Radix pattern:
Dialog+DialogTrigger+DialogContent,Menu+MenuTrigger+MenuContent,Popover+PopoverTrigger+PopoverContent. Controlled (open/onOpenChange) or not. - Text the user sees is German by default (labels like "Schließen"); pass your own children or
aria-labelto change it. - The stories are the reference compositions;
src/stories/examples.tsxholds the bigger ones (notification panel, account menu).
Structure
src/styles/tokens.css: design tokens (--cl-*) for dark and light, with accent and tint derived viacolor-mixsrc/styles/index.css: Tailwind v4 theme mapping tokens to utilities (bg-surface,text-fg-muted,border-line, …) and to shadcn's token namessrc/components/ui/: shadcn/ui primitives (components.json), restyled to the Collabry tokenssrc/components/<Name>/<Name>.tsx+<Name>.stories.tsx: Collabry parts built fromui/
Components
| Area | Parts |
|---|---|
| Foundations | ThemeProvider, Button, CardFrame, Card, CardHeader, CardHeading, CardTitle, CardDescription, CardAction, CardFooter, PageHeader, PageHeading, PageEyebrow, PageTitle, PageDescription, PageActions, Empty*, SectionLabel, MetaSeparator, Spinner, Logo |
| Forms | Field, FieldHeader, FieldLabel, FieldNote, FieldDescription, FieldError, Input, InputGroup, InputGroupAddon, InputGroupButton, PasswordInput, Textarea, Select, SelectOption, Checkbox, TaskCheckbox, SegmentedControl, SegmentedControlItem, SegmentedControlCount |
| Display | StatusBadge, CountBadge, RoleBadge, Swatch, Kbd, KbdGroup, IndicatorDot, Avatar, AvatarImage, AvatarFallback, PersonAvatar, AvatarGroup, ProgressBar, StatusProgress, StatusBar, StatusLegend |
| Overlays | Dialog*, AlertDialog*, Drawer*, Menu*, Popover*, Command*, SearchTrigger, Toast, ToastAction, ToastClose, Toaster, toast(), Notification* |
| Navigation | Sidebar, SidebarHeader, SidebarLogo, SidebarActions, SidebarButton, SidebarToggle, SidebarNav, NavItem, NavItemLabel, SidebarFooter, SidebarUserButton, SidebarUserName, MobileHeader*, MobileTabBar, MobileTab |
| Tasks | TaskTable, TaskTableHeader, TaskTableHead, TaskRow, TaskCell, TaskOpenButton, TaskTitle, TaskMeta, TaskCommentCount, TaskAssignee, TaskDue, TaskTableEmpty, TaskSection*, PriorityLabel, Deadline*, DateTile, Comment* |
| Groups | GroupRow*, GroupCard*, NewGroupTile*, InviteBanner* |
| Calendar | CalendarGrid, CalendarWeekday, CalendarDay*, CalendarChip, CalendarMarker, CalendarLegend*, CalendarToolbar, CalendarNav, CalendarRangeLabel, FilterChip, FilterChipSwatch, DayEvent* |
| Settings | SettingsNav*, SettingsSection*, SettingsRow*, ThemePicker, ThemeOption, ThemePreview, ThemeOptionLabel, ColorSchemePicker, ColorSchemeOption, SaveStatus |
| Auth | AuthBrandPanel, AuthBrandContent, AuthHeadline, Feature*, PasswordRules, PasswordRule, passwordRules() |
Adding shadcn/ui components
npx shadcn@latest add <component>
npm uninstall cn
Then, in the new src/components/ui/<component>.tsx:
- change
import { cn } from "cn"toimport { cn } from "@/lib/cn"(the registry now imports shadcn'scnpackage; ours knows the custom text and shadow scales) - pass
container={usePortalContainer()}(from@/lib/portal) to every*.Portal - shadcn token names (
bg-popover,text-muted-foreground,border-border, …) map to Collabry colors, exceptaccent, which is the brand color here: replacefocus:bg-accent/hover:bg-accentwithbg-hover-menu - the
animate-in/fade-in-0/zoom-in-95classes needtw-animate-css, which is not installed; usedata-[state=open]:animate-panel-ininstead