@mayor_grd/centry-ui 0.1.0 → 0.1.2

package/CLAUDE.md

@@ -0,0 +1,241 @@
+# @mayor_grd/centry-ui — AI Agent Reference
+
+This is the **Basis DS** React UI component library for GRDFI projects.
+When building UI in any project that uses `@mayor_grd/centry-ui`, follow this guide.
+
+## Package
+
+```
+@mayor_grd/centry-ui
+```
+
+## Available Components
+
+All components are imported from the package root:
+
+```tsx
+import { Button, Input, Card, ... } from '@mayor_grd/centry-ui';
+```
+
+### Component List
+
+| Component | Description | Key Props |
+|-----------|-------------|-----------|
+| `Button` | Primary action element | `variant`: default/destructive/outline/secondary/ghost/link · `size`: default/sm/lg/icon/iconSm/iconLg · `loading?: boolean` (spinner + disable) · `asChild` · Pill-shaped (`rounded-full`) |
+| `Input` | Text input field | `state`: default/error. Standard HTML input props |
+| `Card` | Container with sections | Sub-components: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` |
+| `Accordion` | Collapsible panels | `type`: single/multiple, `collapsible`. Sub: `AccordionItem`, `AccordionTrigger`, `AccordionContent` |
+| `Alert` | Feedback banner | `variant`: default/info/success/warning/error. Sub: `AlertTitle`, `AlertDescription` |
+| `AlertDialog` | Confirmation modal | Sub: `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogHeader`, `AlertDialogFooter`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogAction`, `AlertDialogCancel` |
+| `Sidebar` | App navigation | `side`: left/right, `collapsible`: offcanvas/icon/none, `variant`: sidebar/floating/inset |
+| `SidebarProvider` | Sidebar state context | `defaultOpen`, `open`, `onOpenChange`. Hook: `useSidebar()` |
+| `Sheet` | Slide-over panel | Sub: `SheetTrigger`, `SheetContent` (side: top/right/bottom/left), `SheetHeader`, `SheetTitle`, `SheetDescription`, `SheetFooter`, `SheetClose` |
+| `Tooltip` | Hover popup | Wrap with `TooltipProvider`. Sub: `TooltipTrigger`, `TooltipContent` (`variant`: dark/light) |
+| `Separator` | Divider line | `orientation`: horizontal/vertical |
+| `AspectRatio` | Constrain content to a ratio | `ratio`: number (default 1). Re-exports Radix primitive |
+| `Avatar` | User avatar with image + fallback | `size`: 2xs/xs/sm/md/lg/xl. Sub: `AvatarImage`, `AvatarFallback` |
+| `Badge` | Compact status/labeling pill | `variant`: default/secondary/outline/destructive/info/success/warning/error/verified |
+| `Skeleton` | Loading placeholder | Plain div with pulse animation; size via `className` |
+| `Tag` | Rectangular label, optional dismiss | `variant`: default/outline/brand/info/success/warning/error. `onRemove?: () => void` shows close button |
+| `Dialog` | Modal dialog | Sub: `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose` |
+| `Drawer` | Bottom-sheet overlay (vaul) | `shouldScaleBackground`. Sub: `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerFooter`, `DrawerTitle`, `DrawerDescription`, `DrawerClose` |
+| `Popover` | Floating panel | Sub: `PopoverTrigger`, `PopoverContent`, `PopoverAnchor` |
+| `HoverCard` | Hover-triggered popup | Sub: `HoverCardTrigger`, `HoverCardContent` |
+| `Toaster` / `toast` | Sonner toast notifications | Mount `<Toaster />` once; call `toast()` / `toast.success()` / `toast.error()` anywhere |
+| `Label` | Form field label (Radix) | Pair with `htmlFor` / form control id |
+| `Checkbox` | Boolean checkbox | Standard Radix `checked` (true/false/"indeterminate")/`defaultChecked`/`onCheckedChange`/`disabled`. Renders inline check + dash SVG indicators |
+| `Switch` | On/off toggle | Standard Radix props. Boxed-card layout via parent `<Label>` with `has-[[data-state=checked]]:` selector — see Storybook `BoxedCard` story. |
+| `RadioGroup` | Radio set | Sub: `RadioGroupItem`. `value`/`defaultValue`/`onValueChange`. Boxed-card layout via parent `<Label>` with `has-[:checked]:` — see Storybook `BoxedCards` story. |
+| `Toggle` | Single press-toggle button | `variant`: default/outline. `size`: default/sm/lg. `pressed`/`defaultPressed` |
+| `ToggleGroup` | Group of toggles | `type`: single/multiple. `variant`: default/outline/outline-fill/outline-icon/outline-text (bordered group). Sub: `ToggleGroupItem`. |
+| `Slider` | Range slider | `defaultValue` (number[]), `min`/`max`/`step`. Supports single or multi-thumb |
+| `Textarea` | Multi-line text input | `state`: default/error. Standard HTML textarea props |
+| `Select` | Single-select dropdown (Radix) | Sub: `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`, `SelectSeparator`, `SelectScrollUpButton`, `SelectScrollDownButton` |
+| `DropdownMenu` | Menu triggered by a button | Sub: `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem` (`variant`: default/error), `DropdownMenuCheckboxItem`, `DropdownMenuRadioItem`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuGroup`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent`, `DropdownMenuRadioGroup` |
+| `NavigationMenu` | Top-level nav menu | Sub: `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink`, `NavigationMenuIndicator`, `NavigationMenuViewport`. Helper: `navigationMenuTriggerStyle()` |
+| `Breadcrumb` | Path-style nav trail | Sub: `BreadcrumbList` (`size`: sm/md), `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` |
+| `Pagination` | Page navigator | Sub: `PaginationContent`, `PaginationItem`, `PaginationLink` (`isActive`), `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis` |
+| `Collapsible` | Show/hide content (Radix) | Sub: `CollapsibleTrigger`, `CollapsibleContent` |
+| `Progress` | Determinate progress bar | `value`: 0–100 |
+| `Command` | Command palette (cmdk) | Sub: `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandShortcut`, `CommandSeparator`, `CommandDialog` |
+| `Combobox` | Searchable single-select | `options: { value, label, disabled? }[]`, `value`/`defaultValue`/`onValueChange`, `placeholder`, `searchPlaceholder`, `emptyText` |
+| `Calendar` | Date picker grid (react-day-picker) | Passes through all `DayPicker` props (`mode`, `selected`, `onSelect`, etc.) |
+| `DatePicker` | Single-date input | `value`/`defaultValue`/`onValueChange` (Date), `placeholder`, `iconPosition`: left/right |
+| `InputOTP` | OTP code input | `maxLength`. Sub: `InputOTPGroup`, `InputOTPSlot` (`index`), `InputOTPSeparator` |
+| `Carousel` | Slide carousel (embla) | `orientation`: horizontal/vertical, `opts` (Embla options), `plugins`, `setApi`. Sub: `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` |
+| `Table` | Semantic table primitives | `size`: sm/md/lg. Sub: `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption` |
+| `DataTable` | Headless data grid (@tanstack/react-table) | `columns: ColumnDef[]`, `data`, `emptyMessage`, `onTableReady` |
+| `Form` | RHF + zod form helpers | Sub: `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`. Hook: `useFormField()`. Wraps `FormProvider` |
+
+## Color System — Tailwind Classes
+
+Use these Tailwind utility classes. They auto-switch between light and dark mode.
+
+### Backgrounds
+- `bg-bg-canvas` — page background
+- `bg-bg-surface` — card/panel background
+- `bg-bg-popover` — dropdown/popover background
+- `bg-bg-sidebar` — sidebar background
+- `bg-bg-sidebar-accent` — active sidebar item
+- `bg-bg-navbar` — top navbar
+- `bg-bg-brand` — brand/accent background
+- `bg-bg-input` — input field background
+- `bg-bg-secondary` — secondary surfaces
+- `bg-bg-muted` — subtle/muted background
+- `bg-bg-accent` — accent/highlight
+- `bg-bg-strong` — strong emphasis
+- `bg-bg-inverse` — inverse (dark on light, light on dark)
+- `bg-bg-scrim` — overlay/backdrop
+- `bg-bg-transparent` — transparent
+
+### Text
+- `text-text-primary` — primary body text
+- `text-text-secondary` — secondary/supporting text
+- `text-text-muted` — de-emphasized text
+- `text-text-disabled` — disabled state
+- `text-text-inverse` — text on inverse background
+- `text-text-link` — link text
+- `text-text-link-hover` — link hover
+- `text-text-sidebar` — sidebar text
+- `text-text-dialog` — dialog text
+
+### Icons
+- `text-icon-primary`, `text-icon-secondary`, `text-icon-muted`, `text-icon-disabled`
+- `text-icon-inverse`, `text-icon-link`, `text-icon-sidebar`
+
+### Borders
+- `border-border-default` — standard border
+- `border-border-muted` — subtle border
+- `border-border-strong` — emphasis border
+- `border-border-disabled`, `border-border-input`, `border-border-brand`, `border-border-inverse`
+
+### Actions (Buttons)
+| Variant | Background | Hover | Text |
+|---------|-----------|-------|------|
+| Primary | `bg-action-primary-bg` | `hover:bg-action-primary-bg-hover` | `text-action-primary-text` |
+| Secondary | `bg-action-secondary-bg` | `hover:bg-action-secondary-bg-hover` | `text-action-secondary-text` |
+| Ghost | `bg-action-ghost-bg` | `hover:bg-action-ghost-bg-hover` | `text-action-ghost-text` |
+| Outline | `bg-action-outline-bg` | `hover:bg-action-outline-bg-hover` | `text-action-outline-text` |
+| Destructive | `bg-action-destructive-bg` | `hover:bg-action-destructive-bg-hover` | `text-action-destructive-text` |
+| Link | — | — | `text-action-link-text` |
+
+### Status
+| Status | Background | Border | Text | Icon |
+|--------|-----------|--------|------|------|
+| Info | `bg-status-info-bg` | `border-status-info-border` | `text-status-info-text` | `text-status-info-icon` |
+| Success | `bg-status-success-bg` | `border-status-success-border` | `text-status-success-text` | `text-status-success-icon` |
+| Warning | `bg-status-warning-bg` | `border-status-warning-border` | `text-status-warning-text` | `text-status-warning-icon` |
+| Error | `bg-status-error-bg` | `border-status-error-border` | `text-status-error-text` | `text-status-error-icon` |
+
+### Field (Input) Colors
+- `bg-field-bg`, `text-field-text`, `text-field-placeholder`
+- `border-field-border`, `hover:border-field-border-hover`, `focus:border-field-border-focus`
+- `border-field-border-error`, `border-field-border-disabled`
+- `text-field-label`, `text-field-helptext`, `text-field-errortext`
+
+### Focus
+- `ring-focus-ring` — focus ring color
+- `ring-offset-focus-offset` — focus ring offset
+
+### Shadows
+- `shadow-input` — input field shadow
+- `shadow-card` — card elevation
+- `shadow-popover` — dropdown/popover
+- `shadow-modal` — modal dialog
+- `shadow-focus-ring` — focus ring shadow
+
+### Border Radius
+- `rounded-sm` (4px), `rounded-md` (8px), `rounded-lg` (12px), `rounded-xl` (14px), `rounded-full` (9999px)
+
+## Typography CSS Variables
+
+Typography is defined via CSS variables, not Tailwind classes. Use inline styles or custom classes:
+
+| Token | Variables |
+|-------|----------|
+| Display | `--display-font`, `--display-size`, `--display-weight`, `--display-line-height`, `--display-letter-spacing` |
+| H1 | `--h1-font`, `--h1-size`, `--h1-weight`, `--h1-line-height`, `--h1-letter-spacing` |
+| H2 | `--h2-font`, `--h2-size`, `--h2-weight`, `--h2-line-height`, `--h2-letter-spacing` |
+| H3 | `--h3-font`, `--h3-size`, `--h3-weight`, `--h3-line-height`, `--h3-letter-spacing` |
+| H4 | `--h4-font`, `--h4-size`, `--h4-weight`, `--h4-line-height`, `--h4-letter-spacing` |
+| Body SM | `--body-sm-font`, `--body-sm-size`, `--body-sm-weight`, `--body-sm-line-height`, `--body-sm-letter-spacing` |
+| Body MD | `--body-md-font`, `--body-md-size`, `--body-md-weight`, `--body-md-line-height`, `--body-md-letter-spacing` |
+| Label | `--label-font`, `--label-size`, `--label-weight`, `--label-line-height`, `--label-letter-spacing` |
+| Caption | `--caption-font`, `--caption-size`, `--caption-weight`, `--caption-line-height`, `--caption-letter-spacing` |
+
+## Dark Mode
+
+Activate dark mode by adding `dark` class or `data-theme="dark"` to the root element:
+
+```tsx
+<html className="dark">  {/* or data-theme="dark" */}
+```
+
+All color tokens automatically switch values. No code changes needed in components.
+
+## Icon Library
+
+This library uses **iconsax-react** for icons. Import icons like:
+
+```tsx
+import { Home2, Setting2, ArrowDown2 } from 'iconsax-react';
+<Home2 size={16} />
+```
+
+## Component Architecture Pattern
+
+When creating new components for this library, follow this pattern:
+
+```tsx
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const myVariants = cva('base-classes', {
+  variants: { variant: { default: '...', secondary: '...' } },
+  defaultVariants: { variant: 'default' },
+});
+
+interface MyComponentProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof myVariants> {}
+
+const MyComponent = React.forwardRef<HTMLDivElement, MyComponentProps>(
+  ({ className, variant, ...props }, ref) => (
+    <div ref={ref} className={cn(myVariants({ variant }), className)} {...props} />
+  )
+);
+MyComponent.displayName = 'MyComponent';
+
+export { MyComponent, myVariants };
+```
+
+Key conventions:
+- Always use `React.forwardRef`
+- Use `cn()` from `@/lib/utils` for className merging (clsx + tailwind-merge)
+- Use `cva()` for variant definitions
+- Use Radix UI primitives for complex behaviors (dialogs, tooltips, etc.)
+- All colors must use design token Tailwind classes, never hardcoded values
+- Set `displayName` on forwardRef components
+- Support `asChild` prop via Radix `Slot` for composition
+
+## File Structure
+
+```
+src/
+  components/ui/     — All UI components
+  lib/utils.ts       — cn() utility
+  styles/globals.css — Tailwind config + @theme token mappings
+  tokens/generated/  — Auto-generated from Figma tokens
+  docs/              — Storybook documentation pages
+  index.ts           — Library entry point
+scripts/
+  transform-tokens.ts — Token generator (reads design-tokens/ folder)
+design-tokens/       — DTCG token files from Figma
+```
+
+## Token Regeneration
+
+```bash
+pnpm tokens:generate  # Reads design-tokens/ folder → generates CSS, TS, Tailwind theme
+```

package/dist/tokens/generated/primitives.css

@@ -488,8 +488,8 @@
   --letter-spacing-none: 0.15px;
   --letter-spacing-tight: -0.2px;
   --letter-spacing-wide: 0.2px;
-  --letter-spacing-tight-(em): -0.01em;
-  --letter-spacing-wide-(em): 0.02em;
+  --letter-spacing-tight-em: -0.01em;
+  --letter-spacing-wide-em: 0.02em;
 
   /* ── Unit Primitives ── */
   --space-0: 0px;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mayor_grd/centry-ui",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React UI component library built from Basis DS design tokens",
   "type": "module",
   "publishConfig": {
@@ -39,7 +39,8 @@
   ],
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CLAUDE.md"
   ],
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",