UI components
The main entry @franksauvag/rpg-commons exports shadcn/ui primitives (new-york) and RPG-prefixed shared components.
Storybook
Interactive catalog with props and a11y checks:
Hosted at libs.heritiersdudonjon.com/storybook/.
Setup
ts
import "@franksauvag/rpg-commons/style";
import "@franksauvag/rpg-commons/fonts";Wrap media-aware components with RPGMediaProvider:
tsx
import { RPGMediaProvider, RPGImageOrInitials, Button, Card } from "@franksauvag/rpg-commons";
<RPGMediaProvider apiBaseUrl={apiBaseUrl}>
<Card>
<RPGImageOrInitials label="Barbarian" size="md" />
<Button>Action</Button>
</Card>
</RPGMediaProvider>Families
| Family | Examples |
|---|---|
| shadcn/ui | Button, Card, Dialog, Select, Accordion, Collapsible, Tabs, Sheet, Checkbox … (raw Radix scroll area is exported as ScrollAreaRoot / ScrollBar) |
Shared (no RPG prefix) | ScrollArea, NumberField, CollapsibleCard |
Shared (legacy RPG prefix) | RPGImageOrInitials, RPGSelectionCard, RPGEntryIconCell, RPGMediaProvider, RPGAppShell, RPGVirtualList (RPGScrollArea is a deprecated alias of ScrollArea) |
Design tokens: Design tokens.
Full prop tables and visual states are in Storybook, not duplicated here.
When to use what (agents)
| Need | Use | Avoid |
|---|---|---|
| Scrollable panel / sidebar / virtualized list | ScrollArea variant native (or class rpg-scroll on overflow-*-auto) | Raw browser scrollbar; reinventing .lib-scroll in an app |
| Custom scrollbar without virtualization | ScrollArea variant radix | Nesting Radix viewport as the virtualizer scroll parent |
| Titled card that expands/collapses (collapsed by default) | CollapsibleCard | Hand-rolled card + chevron toggle |
| Numeric input with − / + steppers | NumberField | <input type="number"> with native spinners |
| Expand/collapse sections in a detail view | Accordion / Collapsible | Ad-hoc useState + CSS unless app-specific |
| Tabbed detail (class, species, …) | Tabs | Multiple competing pages for nested SRD relations |
| App chrome header | RPGAppShell + app-injected links (no router in commons) | Hardcoding Journey/CCS URLs inside commons |
CSS utility .rpg-scroll (alias .lib-scroll) lives in @franksauvag/rpg-commons/style.