@reinvented/design 1.0.0 → 1.2.0

package/skills/components/advanced-components.md

@@ -0,0 +1,142 @@
+# Advanced Components
+
+Additional advanced structural and interactive components provided by Shadcn.
+
+```ts
+import { 
+  Accordion, AccordionContent, AccordionItem, AccordionTrigger,
+  Calendar,
+  Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious,
+  Chart, // (And subcomponents like BarChart, LineChart)
+  Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList,
+  Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger,
+  ResizablePanelGroup, ResizablePanel, ResizableHandle,
+  Toggle, ToggleGroup, ToggleGroupItem
+} from '@reinvented/design'
+```
+
+## Accordion
+
+Collapsible content panels.
+
+```tsx
+<Accordion type="single" collapsible>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Is it accessible?</AccordionTrigger>
+    <AccordionContent>Yes. It adheres to the WAI-ARIA design pattern.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Calendar
+
+A date picker calendar component using `v-calendar` under the hood.
+
+```tsx
+<Calendar defaultValue="date" className="rounded-md border shadow" />
+```
+
+## Carousel
+
+A hardware-accelerated carousel (via Embla).
+
+```tsx
+<Carousel className="w-full max-w-xs">
+  <CarouselContent>
+    <CarouselItem v-for="(_, index) in 5" :key="index">
+      <div className="p-1">
+        <Card>
+          <CardContent className="flex aspect-square items-center justify-center p-6">
+            <span className="text-4xl font-semibold">{{ index + 1 }}</span>
+          </CardContent>
+        </Card>
+      </div>
+    </CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## Chart
+
+Data visualization using `recharts` / `@unovis/react`.
+
+```tsx
+<!-- Uses standard Shadcn Chart implementations like BarChart, LineChart via react-echarts or recharts -->
+<!-- See shadcn docs for exact data props structures -->
+```
+
+## Command (Command Palette)
+
+Fast, composable command menu using `cmdk`.
+
+```tsx
+<Command>
+  <CommandInput placeholder="Type a command or search..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Suggestions">
+      <CommandItem value="calendar">Calendar</CommandItem>
+      <CommandItem value="search-emoji">Search Emoji</CommandItem>
+      <CommandItem value="calculator">Calculator</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+## Drawer
+
+A bottom sheet component that acts as a slide-up dialog, especially tailored for mobile layouts where Dialogs might be awkward.
+
+```tsx
+<Drawer>
+  <DrawerTrigger as-child>
+    <Button variant="outline">Open Drawer</Button>
+  </DrawerTrigger>
+  <DrawerContent>
+    <div className="mx-auto w-full max-w-sm">
+      <DrawerHeader>
+        <DrawerTitle>Move Goal</DrawerTitle>
+        <DrawerDescription>Set your daily activity goal.</DrawerDescription>
+      </DrawerHeader>
+      <!-- content -->
+      <DrawerFooter>
+        <Button>Submit</Button>
+        <DrawerClose as-child><Button variant="outline">Cancel</Button></DrawerClose>
+      </DrawerFooter>
+    </div>
+  </DrawerContent>
+</Drawer>
+```
+
+## Resizable
+
+Resizable split panes.
+
+```tsx
+<ResizablePanelGroup direction="horizontal" className="max-w-md rounded-lg border">
+  <ResizablePanel :default-size="50">
+    <div className="flex h-48 items-center justify-center p-6">Sidebar</div>
+  </ResizablePanel>
+  <ResizableHandle with-handle />
+  <ResizablePanel :default-size="50">
+    <div className="flex h-48 items-center justify-center p-6">Content</div>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+
+## Toggle & ToggleGroup
+
+A set of two-state buttons.
+
+```tsx
+<ToggleGroup type="single">
+  <ToggleGroupItem value="bold" aria-label="Toggle bold">
+    <Bold className="h-4 w-4" />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="italic" aria-label="Toggle italic">
+    <Italic className="h-4 w-4" />
+  </ToggleGroupItem>
+</ToggleGroup>
+```

package/skills/components/avatar.md

@@ -0,0 +1,92 @@
+# Avatar
+
+User/entity representation. Displays an image, initials, or fallback.
+
+```ts
+import { Avatar, AvatarImage, AvatarFallback } from '@reinvented/design'
+```
+
+## Basic Usage
+
+The `Avatar` component handles the rendering logic automatically. It will try to load the `AvatarImage` first, and if it fails or hasn't loaded yet, it displays the `AvatarFallback`.
+
+```tsx
+<Avatar>
+  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+  <AvatarFallback>CN</AvatarFallback>
+</Avatar>
+```
+
+In mockups, explicitly use the `AvatarFallback` without overriding its colors to maintain a clean aesthetic:
+```tsx
+<Avatar>
+  <!-- Generates initials like SC in standard muted Shadcn colors -->
+  <AvatarFallback className="bg-muted text-muted-foreground">
+    {{ user.name.split(' ').map(n => n[0]).join('') }}
+  </AvatarFallback>
+</Avatar>
+```
+
+## Sizes
+
+Add Tailwind sizing classes directly to the `Avatar` wrapper:
+
+| Size | Classes | When to Use |
+|------|---------|-------------|
+| Small | `<Avatar className="w-6 h-6 text-xs">` | Compact lists, inline mentions |
+| Default | `<Avatar className="w-8 h-8 text-xs">` | Table rows, list items, comments |
+| Medium | `<Avatar className="w-10 h-10 text-sm">` | Card headers, conversation items |
+| Large | `<Avatar className="w-12 h-12 text-lg">` | Profile headers, detail views |
+| XL | `<Avatar className="w-16 h-16 text-lg">` | Profile pages, settings |
+
+## Avatar with Name
+
+The standard user display pattern — avatar + name + secondary info:
+
+```tsx
+<div className="flex items-center gap-3">
+  <Avatar className="w-8 h-8">
+    <AvatarImage :src="user.avatarUrl" :alt="user.name" />
+    <AvatarFallback>{{ initials(user.name) }}</AvatarFallback>
+  </Avatar>
+  <div className="min-w-0">
+    <p className="text-sm font-medium truncate">{{ user.name }}</p>
+    <p className="text-xs text-muted-foreground truncate">{{ user.email }}</p>
+  </div>
+</div>
+```
+
+## Avatar Group (Stacked)
+
+```tsx
+<div className="flex -space-x-2">
+  <Avatar v-for="user in users.slice(0, 4)" :key="user.id" className="w-8 h-8 border-2 border-background">
+    <AvatarImage :src="user.avatarUrl" />
+    <AvatarFallback>{{ initials(user.name) }}</AvatarFallback>
+  </Avatar>
+  <Avatar v-if="users.length > 4" className="w-8 h-8 border-2 border-background">
+    <AvatarFallback className="bg-muted text-muted-foreground">+{{ users.length - 4 }}</AvatarFallback>
+  </Avatar>
+</div>
+```
+
+Key: Use `border-2 border-background` on each `<Avatar>` and `-space-x-2` on the container for the overlapping effect.
+
+## Avatar with Status Dot
+
+```tsx
+<div className="relative inline-block">
+  <Avatar className="w-10 h-10">
+    <AvatarImage src="/avatar.jpg" />
+    <AvatarFallback>JD</AvatarFallback>
+  </Avatar>
+  <!-- Top-right overlapping indicator with 'cutout' border effect -->
+  <span className="absolute -top-0.5 -right-0.5 w-3 h-3 rounded-full bg-success ring-2 ring-background z-10" />
+</div>
+```
+
+Use `bg-success` for online status, or `bg-destructive` for unread notifications.
+
+## Rules
+- In flex layouts, `<Avatar>` naturally behaves properly but applying `shrink-0` if it's placed inside a deep flex wrapper might help.
+- In mockups without real images, always rely on `<AvatarFallback>` and DO NOT give it colorful gradients or custom styling. Maintain the strict Shadcn aesthetic using the default `bg-muted` and `text-muted-foreground`.

package/skills/components/badge.md

@@ -0,0 +1,105 @@
+# Badge
+
+Small status indicators and labels.
+
+```ts
+import { Badge } from '@reinvented/design'
+```
+
+## Variants
+
+The standard Baseline Shadcn Badge includes:
+| Variant | Appearance | When to Use |
+|---------|-----------|-------------|
+| `default` | `bg-primary text-primary-foreground` | Active status, primary category, count |
+| `secondary` | `bg-secondary text-secondary-foreground` | Neutral tags, metadata labels |
+| `destructive` | `bg-destructive text-destructive-foreground` | Error status, failed, expired |
+| `outline` | `border` | Low-emphasis tags, filter chips |
+
+| `success` | `bg-success text-success-foreground` | Success status, confirmed |
+| `warning` | `bg-warning text-warning-foreground` | Warning status, pending review |
+| `info` | `bg-info text-info-foreground` | Informational status |
+
+## Usage
+
+```tsx
+<Badge>Active</Badge>
+<Badge variant="secondary">Draft</Badge>
+<Badge variant="destructive">Overdue</Badge>
+<Badge variant="outline">v2.0.1</Badge>
+```
+
+## Status Badge Pattern
+
+Map data states to badge variants:
+
+```tsx
+<Badge :variant="getStatusVariant(item.status)">
+  {{ item.status }}
+</Badge>
+```
+
+```ts
+import type { BadgeVariants } from '@reinvented/design/components/ui/badge'
+
+function getStatusVariant(status: string): BadgeVariants['variant'] {
+  const map: Record<string, BadgeVariants['variant']> = {
+    active: 'default',
+    completed: 'success',
+    success: 'success',
+    warning: 'warning',
+    pending: 'secondary',
+    draft: 'secondary',
+    failed: 'destructive',
+    archived: 'outline',
+  }
+  return map[status] || 'secondary'
+}
+```
+
+## Badge with Dot Indicator
+
+For status badges that need a colored dot:
+
+```tsx
+<Badge variant="outline" className="gap-1.5">
+  <span className="w-1.5 h-1.5 rounded-full bg-success" />
+  Online
+</Badge>
+```
+
+## Composition with Other Components
+
+### In Table Cells
+```tsx
+<TableCell>
+  <Badge variant="secondary">{{ item.status }}</Badge>
+</TableCell>
+```
+
+### In Card Headers
+```tsx
+<CardHeader className="flex flex-row items-center justify-between">
+  <CardTitle>Project Alpha</CardTitle>
+  <Badge>Active</Badge>
+</CardHeader>
+```
+
+### As Count Indicator
+```tsx
+<Button variant="ghost">
+  Notifications
+  <Badge className="ml-1.5 px-1.5 py-0.5 text-xs">3</Badge>
+</Button>
+```
+
+## Rules
+- Badge text should be **short** — 1-2 words max
+- **Constrained-width contexts (table cells, narrow columns):** Add `whitespace-nowrap` to the Badge's `className` to prevent line breaks. Badges should never wrap to two lines — if text is wrapping, either the label is too long or the column is too narrow.
+- Use `variant="secondary"` as the default when unsure
+- **Always use built-in status variants**: For status badges, use `variant="warning"` for pending/caution states, `variant="success"` for confirmed/approved, `variant="destructive"` for errors/failures. Do **not** override colors manually (e.g., `className="bg-amber-500"`) — this bypasses dark mode handling and breaks visual consistency.
+- Don't use badges for actions — they're display-only
+- In tables, badges go in their own column (not inline with other text)
+- **NEVER over-style badges**: Do not stack arbitrary Tailwind utilities (`bg-warning/5`, `text-warning/80`, `border-warning/30`) on top of a Badge to invent custom variations. This breaks dark/light mode contrast. Always rely on the built-in variants (`variant="secondary"`, `variant="warning"`, etc.).
+- **NEVER invent new semantic solid colors**: Do not create your own badge variants by forcibly applying saturated background utility classes (e.g. `bg-emerald-500` or `bg-green-600/20 text-green-700`). Shadcn UI thrives on restraint. Use `default`, `secondary`, `outline`, or `destructive` exclusively.
+- **NEVER override internal typography**: Do not apply font-weight (`font-normal`), text-sizes, or custom paddings (unless scaling down) to `<Badge>`. It should strictly use its native styles to maintain proportion with the rest of the Shadcn system.

package/skills/components/button.md

@@ -0,0 +1,87 @@
+# Button
+
+Primary interactive element. Always use `<Button>` — never raw `<button>`.
+
+```ts
+import { Button } from '@reinvented/design'
+```
+
+## Variants
+
+| Variant | Classes | When to Use |
+|---------|---------|-------------|
+| `default` | `bg-primary text-primary-foreground` | **Primary actions**: Save, Create, Submit, Send. One per section max. |
+| `secondary` | `bg-secondary text-secondary-foreground` | **Secondary actions**: Cancel, Back, Reset. Alongside a primary button. |
+| `destructive` | `bg-destructive text-destructive-foreground` | **Dangerous actions**: Delete, Remove. Always pair with confirmation. |
+| `outline` | `border bg-background` | **Tertiary actions**: Export, Filter, Share. Less visual weight than secondary. |
+| `ghost` | `hover:bg-accent` | **Subtle actions**: Icon-only buttons, toolbar actions, table row actions. |
+| `link` | `text-primary underline-offset-4` | **Inline links**: Text-level actions that look like links. |
+| `success` | `bg-success text-success-foreground` | **Positive confirmations**: Approve, Accept, Confirm. |
+| `warning` | `bg-warning text-warning-foreground` | **Warning actions**: Suspend, Delay, Acknowledge Risk. |
+| `info` | `bg-info text-info-foreground` | **Informational actions**: View Details, Learn More. |
+
+### Variant Decision Tree
+```
+Is this the main CTA?
+├─ Yes → default
+├─ No
+│  ├─ Is it destructive? → destructive
+│  ├─ Is it paired with a primary button? → secondary or outline
+│  ├─ Is it an icon-only action? → ghost (size="icon")
+│  ├─ Is it inline with text? → link
+│  └─ Is it a positive confirmation? → success
+```
+
+## Sizes
+
+| Size | Classes | When to Use |
+|------|---------|-------------|
+| `xs` | `h-7 px-2 text-xs` | Compact UI: table row actions, inline tags |
+| `sm` | `h-8 px-3 text-xs` | Secondary area buttons, compact toolbars |
+| `default` | `h-9 px-4 py-2` | **Standard** — use this for most buttons |
+| `lg` | `h-10 px-8` | Emphasized CTAs, empty state actions |
+| `xl` | `h-12 px-10 text-base` | Hero/marketing CTAs only |
+| `icon` | `h-9 w-9` | Icon-only square buttons |
+
+## Common Compositions
+
+### Button with Icon
+```tsx
+<Button>
+  <Plus className="w-4 h-4" />
+  New Project
+</Button>
+```
+
+### Icon-Only Button
+```tsx
+<Button variant="ghost" size="icon" aria-label="Settings">
+  <Settings className="w-4 h-4" />
+</Button>
+```
+
+### Loading Button
+```tsx
+<Button :disabled="saving">
+  <Loader2 v-if="saving" className="w-4 h-4 animate-spin" />
+  {{ saving ? 'Saving...' : 'Save Changes' }}
+</Button>
+```
+
+### Button Group (primary + secondary)
+```tsx
+<div className="flex items-center gap-2">
+  <Button variant="outline">Cancel</Button>
+  <Button>Save Changes</Button>
+</div>
+```
+Note: Primary action is always **last** (rightmost) in a button group.
+
+### Destructive with Confirmation
+Always pair destructive buttons with `<AlertDialog>` — never delete on single click.
+
+## Rules
+- One `default` variant button per logical section (the "primary CTA rule")
+- Always add `aria-label` to icon-only buttons
+- Loading state: show `<Loader2 className="w-4 h-4 animate-spin" />` and `:disabled="true"`
+- In forms, use `type="submit"` on the primary button, `type="button"` on others

package/skills/components/card.md

@@ -0,0 +1,144 @@
+# Card
+
+The primary content container. Use Cards to group related content into visually distinct blocks.
+
+```ts
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@reinvented/design'
+```
+
+## Subcomponents
+
+| Component | Default Classes | Purpose |
+|-----------|----------------|---------|
+| `Card` | `rounded-lg border bg-card shadow-sm` | Outer container |
+| `CardHeader` | `flex flex-col gap-1.5 p-6` | Title + description area |
+| `CardTitle` | `font-semibold leading-none tracking-tight` | Card heading |
+| `CardDescription` | `text-sm text-muted-foreground` | Subtitle / helper text |
+| `CardContent` | `p-6 pt-0` | Body content area |
+| `CardFooter` | `flex items-center p-6 pt-0` | Action buttons area |
+
+## Standard Card
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Team Members</CardTitle>
+    <CardDescription>Manage your team and their roles.</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <!-- Content here -->
+  </CardContent>
+  <CardFooter className="justify-end gap-2">
+    <Button variant="outline">Cancel</Button>
+    <Button>Save</Button>
+  </CardFooter>
+</Card>
+```
+
+## Stat Card (Dashboard KPI)
+
+Used in dashboard stat grids. Compact layout with metric + label + optional trend.
+
+```tsx
+<Card>
+  <CardHeader className="flex flex-row items-center justify-between pb-2">
+    <CardTitle className="text-sm font-medium">Total Revenue</CardTitle>
+    <DollarSign className="h-4 w-4 text-muted-foreground" />
+  </CardHeader>
+  <CardContent>
+    <div className="text-2xl font-bold">$45,231.89</div>
+    <p className="text-xs text-muted-foreground">+20.1% from last month</p>
+  </CardContent>
+</Card>
+```
+
+Key details:
+- `CardHeader` uses `flex flex-row items-center justify-between pb-2` to place icon on the right
+- `CardTitle` is downsized to `text-sm font-medium` (not the default heading size)
+- Metric value is `text-2xl font-bold`
+- Trend text is `text-xs text-muted-foreground`
+- **NEVER wrap the icon in a colored background element** (like `bg-primary/20 p-2 rounded-full`). Stat card icons should remain minimal and transparent, using `text-muted-foreground` directly.
+
+## Clickable Card (List Item)
+
+```tsx
+<Card className="cursor-pointer transition-colors hover:bg-accent/50">
+  <CardContent className="flex items-center gap-4 p-4">
+    <div className="w-10 h-10 rounded-full shrink-0 bg-gradient-to-br from-primary/20 to-primary/40" />
+    <div className="flex-1 min-w-0">
+      <p className="text-sm font-medium truncate">Project Alpha</p>
+      <p className="text-xs text-muted-foreground">Updated 2 hours ago</p>
+    </div>
+    <ChevronRight className="w-4 h-4 text-muted-foreground shrink-0" />
+  </CardContent>
+</Card>
+```
+
+Key details:
+- Use `hover:bg-accent/50` for subtle hover (not `hover:shadow-md` which can look jarring)
+- `min-w-0` on the text container enables `truncate` to work in flex layouts
+- `shrink-0` on fixed-size elements prevents them from collapsing
+
+## Card with Sections (Divided Content)
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Account Settings</CardTitle>
+  </CardHeader>
+  <CardContent className="space-y-4">
+    <div className="flex items-center justify-between">
+      <div>
+        <p className="text-sm font-medium">Email Notifications</p>
+        <p className="text-xs text-muted-foreground">Receive emails about your account activity.</p>
+      </div>
+      <Switch />
+    </div>
+    <Separator />
+    <div className="flex items-center justify-between">
+      <div>
+        <p className="text-sm font-medium">Marketing Emails</p>
+        <p className="text-xs text-muted-foreground">Receive emails about new features and updates.</p>
+      </div>
+      <Switch />
+    </div>
+  </CardContent>
+</Card>
+```
+
+## Card with Footer Link ("View All" Pattern)
+
+When a card shows a preview of a longer list (e.g., recent activity, top items), use a footer link to navigate to the full view. This is a very common pattern — always implement it consistently:
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Recent Activity</CardTitle>
+    <CardDescription>Latest updates in this project</CardDescription>
+  </CardHeader>
+  <CardContent>
+    {/* Preview list items */}
+  </CardContent>
+  <CardFooter className="border-t px-6 py-3">
+    <Button variant="ghost" size="sm" className="w-full text-muted-foreground">
+      View all activity <ArrowRight className="ml-2 w-4 h-4" />
+    </Button>
+  </CardFooter>
+</Card>
+```
+
+Key details:
+- `CardFooter` gets `border-t px-6 py-3` — the border separates the link from content, and `py-3` keeps it compact (default `p-6` is too spacious for a single text link)
+- Button uses `variant="ghost" size="sm"` — visually lightweight, clearly interactive on hover
+- Button uses `w-full` so the entire footer row is clickable
+- Text color is `text-muted-foreground` — secondary emphasis, not primary (this is navigation, not a CTA)
+- Arrow icon (`ArrowRight`) signals navigation
+- **Never** use a full-height default button or `variant="link"` here — ghost sm is the standard
+
+## Rules
+
+- **Padding**: Cards use `p-6` by default. Use `p-4` for compact cards (list items, stat cards).
+- **List Items Alignment**: When rendering lists or `ScrollArea` items inside a card, avoid "double-padding" (the card's padding + the item's padding making items intuitively disconnected from the title). Manually offset the `<CardContent>` padding (e.g., `<CardContent className="flex-1 min-h-0 px-3 pb-3 pt-0">`).
+- **Never hardcode backgrounds** — `bg-card` is automatic. Add custom backgrounds only for special cases.
+- **Don't nest cards** — if you need sections within a card, use `<Separator>` or spacing.
+- **Card grid gap**: Use `gap-4` for stat card grids, `gap-6` for content card grids.

package/skills/components/chart.md

@@ -0,0 +1,88 @@
+# Charts
+
+Visual data representations. Supports `<AreaChart>`, `<BarChart>`, `<DonutChart>`, and `<LineChart>`.
+
+```ts
+import { AreaChart, BarChart, DonutChart, LineChart } from '@reinvented/design'
+```
+
+## Basic Structure
+
+Charts require `data`, an `index` (the x-axis or category key), and `categories` (the data keys to plot). Note that `DonutChart` uses the `category` prop instead of `categories`.
+
+### Area Chart
+
+```tsx
+<AreaChart
+  :data="[
+    { month: 'Jan', revenue: 1200, profit: 800 },
+    { month: 'Feb', revenue: 2100, profit: 1200 }
+  ]"
+  index="month"
+  :categories="['revenue', 'profit']"
+  className="h-72"
+/>
+```
+
+### Bar Chart
+
+```tsx
+<BarChart
+  :data="chartData"
+  index="name"
+  :categories="['total', 'predicted']"
+  :rounded-corners="4"
+  className="h-72"
+/>
+```
+
+### Line Chart
+
+```tsx
+<LineChart
+  :data="chartData"
+  index="date"
+  :categories="['activeUsers']"
+  className="h-64"
+/>
+```
+
+### Donut Chart
+
+Used for single-dimension distribution.
+
+```tsx
+<DonutChart
+  :data="[
+    { name: 'Direct', value: 400 },
+    { name: 'Organic', value: 300 },
+    { name: 'Referral', value: 300 },
+  ]"
+  index="name"
+  category="value"
+  className="h-48"
+/>
+```
+
+## Key Props
+
+| Prop | Description | Applies To |
+|------|-------------|------------|
+| `data` | Array of objects representing the dataset. | All |
+| `index` | The key used for labels (X-axis) (e.g., 'month', 'name'). | All |
+| `categories` | Array of keys to plot (e.g., `['revenue', 'profit']`). | Area, Bar, Line |
+| `category` | Single key to plot for distributions. | Donut |
+| `valueFormatter` | Function to format tooltip/axis values `(tick: number) => string`. | All |
+| `colors` | Array of CSS color variables or raw values. Default colors apply automatically. | All |
+| `showLegend` | Boolean to show/hide the legend (default true). | All |
+
+## Rules
+
+- Always set an explicit height (e.g., `className="h-72"`) on charts.
+- Place charts inside a `<CardContent>` with a `<CardTitle>` describing the data.
+- Ensure `index` matches a string field in the data (like a date or name).
+- Provide plausible dummy data in mockup mode.
+- **Formatting Currency**: When dealing with financial numbers, use `valueFormatter` and configure `toLocaleString` to show 2 decimal places: `:value-formatter="(tick) => tick.toLocaleString('en-US', { style: 'currency', currency: 'USD' })"`
+- **Colors**: Shadcn charts (Unovis) expect valid CSS color strings (hex `#10b981`, standard color names like `red`, or css vars like `var(--theme-primary)`). Do NOT pass raw Tailwind semantic names (like `emerald` or `primary`) to the `colors` array as they will fail to resolve and render black. Instead, use their hex equivalents (e.g., `#10b981` for emerald).
+- **Legends**: If building a custom legend beneath a chart, make sure to add `:show-legend="false"` to the chart so it doesn't render duplicate keys!
+- **Donut Chart Key Clash**: When using `<DonutChart>`, do NOT use `'value'` as the `category` key in your data, because it clashes with Unovis internal segment variables and causes `[object Object]` tooltip rendering errors. Always use a semantic key like `revenue`, `amount`, `users`, etc. (e.g. `<DonutChart category="revenue" />`).