@leitware/composables 0.2.1 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +186 -49
  2. package/dist/presets/brutalist.css +53 -39
  3. package/dist/presets/default.css +52 -38
  4. package/dist/presets/signal-pop.css +51 -37
  5. package/dist/styles.css +1 -1
  6. package/dist/tailwind.css +500 -0
  7. package/package.json +9 -31
  8. package/rules/composables.md +80 -84
  9. package/skills/use-composables/SKILL.md +42 -0
  10. package/skills/use-composables/agents/openai.yaml +4 -0
  11. package/skills/use-composables/references/optional-dependencies.md +76 -0
  12. package/skills/use-composables/references/public-api.md +23 -0
  13. package/skills/use-composables/references/semantic-styling.md +134 -0
  14. package/skills/use-composables/references/semantic-utilities.md +131 -0
  15. package/src/_internal/alert.tsx +1 -1
  16. package/src/index.ts +33 -10
  17. package/src/opinionated/accordion.tsx +22 -3
  18. package/src/opinionated/alert.tsx +21 -7
  19. package/src/opinionated/tabs.tsx +16 -3
  20. package/src/styles/composable.css +7 -1
  21. package/src/styles/presets/brutalist.css +53 -39
  22. package/src/styles/presets/default.css +52 -38
  23. package/src/styles/presets/signal-pop.css +51 -37
  24. package/src/styles/presets-data/brutalist.ts +19 -41
  25. package/src/styles/presets-data/default.ts +18 -40
  26. package/src/styles/presets-data/signal-pop.ts +17 -39
  27. package/src/styles/tokens/registry.ts +126 -18
  28. package/src/styles/tokens/semantic-utilities.css +503 -0
  29. package/src/styles/tokens/semantic.css +46 -32
  30. package/src/styles/tokens/tailwind-color-adapter.css +91 -0
  31. package/src/styles/tokens/tailwind-public-utilities.css +500 -0
  32. package/src/styles/tokens/tailwind-theme.css +0 -100
@@ -10,9 +10,9 @@ Generated by `bun scripts/generate-rules.ts`. Do not hand-edit this file.
10
10
  - Import `@leitware/composables/styles.css` once in root/global CSS before using components.
11
11
  - Import at most one preset after the base styles, for example `@leitware/composables/presets/brutalist.css`.
12
12
  - Prefer `Form*` components when building labeled fields with description, validation, or error text.
13
- - Prefer array APIs where provided, such as `Tabs`, `Breadcrumb`, `Pagination`, `Accordion`, `Carousel`, and form selects.
13
+ - Prefer array APIs where provided, such as `Tabs`, `Breadcrumb`, `Pagination`, `Accordion`, and form selects.
14
14
  - Do not import from `src/_internal` or package-internal file paths in downstream apps.
15
- - Use semantic token utilities such as `bg-surface-*`, `text-*`, `border-*`, `stroke-*`, and `icon-*` rather than arbitrary colors.
15
+ - Use only semantic color utilities listed in the generated skill manifest rather than arbitrary colors or inferred token/property combinations.
16
16
  - Use `cn` from the package when composing class names.
17
17
 
18
18
  ## Required CSS
@@ -24,28 +24,24 @@ Generated by `bun scripts/generate-rules.ts`. Do not hand-edit this file.
24
24
  @import '@leitware/composables/presets/brutalist.css';
25
25
  ```
26
26
 
27
+ Tailwind v4 consumers that need state or responsive variants of exact public semantic classes must import `@leitware/composables/tailwind.css` after Tailwind and before `@leitware/composables/styles.css`.
28
+
27
29
  ## Entrypoints
28
30
 
29
- | Import | Source |
30
- | ---------------------------------- | ------------------------------- |
31
- | `@leitware/composables` | `./src/index.ts` |
32
- | `@leitware/composables/ai` | `./src/opinionated/ai/index.ts` |
33
- | `@leitware/composables/styles.css` | `./dist/styles.css` |
34
- | `@leitware/composables/presets/*` | `./dist/presets/*` |
31
+ | Import | Source |
32
+ | ------------------------------------ | ------------------------------- |
33
+ | `@leitware/composables` | `./src/index.ts` |
34
+ | `@leitware/composables/ai` | `./src/opinionated/ai/index.ts` |
35
+ | `@leitware/composables/styles.css` | `./dist/styles.css` |
36
+ | `@leitware/composables/tailwind.css` | `./dist/tailwind.css` |
37
+ | `@leitware/composables/presets/*` | `./dist/presets/*` |
35
38
 
36
39
  ## Optional Dependencies
37
40
 
38
- | Install when using… | Package |
39
- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40
- | `Calendar`, `FormCalendarPopover` | `react-day-picker` |
41
- | `Carousel` | `embla-carousel-react` |
42
- | `Dropzone`, `FormDropzone`, `FormMultiDropzone` | `react-dropzone` |
43
- | `ResizablePanels` | `react-resizable-panels` |
44
- | `Sonner` (toasts) | `sonner` |
45
- | AI elements from `@leitware/composables/ai` | `ai`, `shiki`, `streamdown`, `@streamdown/cjk`, `@streamdown/code`, `@streamdown/math`, `@streamdown/mermaid`, `use-stick-to-bottom`, `nanoid`, `@radix-ui/react-use-controllable-state` |
46
- | `ThemeInjector` / `TokenConfigPanel` | `react-colorful` |
47
- | Default preset fonts | `@fontsource-variable/inter` |
48
- | Brutalist preset fonts | `@fontsource-variable/space-grotesk`, `@fontsource-variable/jetbrains-mono` |
41
+ | Install when using… | Import from | Optional packages |
42
+ | ------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
43
+ | AI elements | `@leitware/composables/ai` | `ai`, `shiki`, `streamdown`, `@streamdown/cjk`, `@streamdown/code`, `@streamdown/math`, `@streamdown/mermaid`, `use-stick-to-bottom`, `nanoid`, `@radix-ui/react-use-controllable-state`, `cmdk`, `motion` |
44
+ | Preset typography | CSS or application entrypoint | The Fontsource packages listed below |
49
45
 
50
46
  ## Component Catalog
51
47
 
@@ -61,57 +57,57 @@ Use this catalog to choose public exports. The `Source module` column is for mai
61
57
 
62
58
  ### Hooks
63
59
 
64
- | Module | Source module | Import from | Public values | Public types | Description |
65
- | -------------------- | ---------------------------------- | ----------------------- | ----------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
66
- | `use-mobile` | `./hooks/use-mobile` | `@leitware/composables` | `useIsMobile` | - | Hook to detect mobile viewport breakpoint |
67
- | `use-numeric-input` | `./hooks/use-numeric-input` | `@leitware/composables` | `useNumericInput` | `NumericInputOptions`, `UseNumericInputOptions`, `UseNumericInputReturn` | Hook for numeric input handling with sanitization and parsing |
68
- | `direction-provider` | `./opinionated/direction-provider` | `@leitware/composables` | - | - | Base UI reading-direction provider with `useDirection` |
60
+ | Module | Source module | Import from | Public values | Public types | Description |
61
+ | -------------------- | ----------------------------------- | ----------------------- | ----------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
62
+ | `use-mobile` | `./hooks/use-mobile` | `@leitware/composables` | `useIsMobile` | - | Hook to detect mobile viewport breakpoint |
63
+ | `use-numeric-input` | `./hooks/use-numeric-input` | `@leitware/composables` | `useNumericInput` | `NumericInputOptions`, `UseNumericInputOptions`, `UseNumericInputReturn` | Hook for numeric input handling with sanitization and parsing |
64
+ | `direction-provider` | `@base-ui/react/direction-provider` | `@leitware/composables` | - | - | Base UI reading-direction provider with `useDirection` |
69
65
 
70
66
  ### Layout
71
67
 
72
- | Module | Source module | Import from | Public values | Public types | Description |
73
- | -------------- | ---------------------------- | ----------------------- | ---------------------------------------------------------- | ----------------- | ----------------------------------------------------------- |
74
- | `stack` | `./opinionated/stack` | `@leitware/composables` | `Stack` | - | Flex-based vertical or horizontal stack layout |
75
- | `grid` | `./opinionated/grid` | `@leitware/composables` | `Grid` | - | Responsive CSS grid layout component |
76
- | `container` | `./opinionated/container` | `@leitware/composables` | `Container` | - | Centered max-width content wrapper |
77
- | `spacer` | `./opinionated/spacer` | `@leitware/composables` | `Spacer` | - | Flexible whitespace component for spacing |
78
- | `separator` | `./opinionated/separator` | `@leitware/composables` | `Separator` | - | Visual divider line between content sections |
79
- | `layout` | `./opinionated/layout` | `@leitware/composables` | `NewspaperCell`, `NewspaperGrid`, `Section` | - | Rigid layout primitives: Section, FlexSpacer, NewspaperGrid |
80
- | `layout-bento` | `./opinionated/layout-bento` | `@leitware/composables` | `BentoCell`, `BentoGrid` | - | Bento grid layout with BentoGrid, BentoCell, and composites |
81
- | `resizable` | `./opinionated/resizable` | `@leitware/composables` | `ResizableHandle`, `ResizablePanel`, `ResizablePanelGroup` | - | Resizable split pane panels |
82
- | `scroll-area` | `./opinionated/scroll-area` | `@leitware/composables` | `ScrollArea`, `ScrollBar` | `ScrollAreaProps` | Custom scrollbar container with overflow handling |
68
+ | Module | Source module | Import from | Public values | Public types | Description |
69
+ | -------------- | ---------------------------- | ----------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------- |
70
+ | `stack` | `./opinionated/stack` | `@leitware/composables` | `Stack` | `StackProps` | Flex-based vertical or horizontal stack layout |
71
+ | `grid` | `./opinionated/grid` | `@leitware/composables` | `Grid` | `GridProps` | Responsive CSS grid layout component |
72
+ | `container` | `./opinionated/container` | `@leitware/composables` | `Container` | `ContainerProps` | Centered max-width content wrapper |
73
+ | `spacer` | `./opinionated/spacer` | `@leitware/composables` | `Spacer` | `SpacerProps` | Flexible whitespace component for spacing |
74
+ | `separator` | `./opinionated/separator` | `@leitware/composables` | `Separator` | - | Visual divider line between content sections |
75
+ | `layout` | `./opinionated/layout` | `@leitware/composables` | `NewspaperCell`, `NewspaperGrid`, `Section` | `NewspaperCellProps`, `NewspaperGridProps`, `SectionProps` | Rigid layout primitives: Section, FlexSpacer, NewspaperGrid |
76
+ | `layout-bento` | `./opinionated/layout-bento` | `@leitware/composables` | `BentoCell`, `BentoGrid` | - | Bento grid layout with BentoGrid, BentoCell, and composites |
77
+ | `resizable` | `./opinionated/resizable` | `@leitware/composables` | `ResizableHandle`, `ResizablePanel`, `ResizablePanelGroup` | - | Resizable split pane panels |
78
+ | `scroll-area` | `./opinionated/scroll-area` | `@leitware/composables` | `ScrollArea`, `ScrollBar` | `ScrollAreaProps` | Custom scrollbar container with overflow handling |
83
79
 
84
80
  ### Typography & Display
85
81
 
86
- | Module | Source module | Import from | Public values | Public types | Description |
87
- | ------------ | -------------------------- | ----------------------- | ---------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------- |
88
- | `typography` | `./opinionated/typography` | `@leitware/composables` | `Typography` | - | Polymorphic text component with typographic scale variants |
89
- | `badge` | `./opinionated/badge` | `@leitware/composables` | `Badge` | `BadgeProps` | Small status label with color variants |
90
- | `avatar` | `./opinionated/avatar` | `@leitware/composables` | `Avatar`, `AvatarFallback`, `AvatarImage` | `AvatarProps` | Circular image element with automatic initials fallback |
91
- | `icon` | `./opinionated/icon` | `@leitware/composables` | `Icon` | - | Icon wrapper with size and color variants |
92
- | `kbd` | `./opinionated/kbd` | `@leitware/composables` | `Kbd`, `KbdGroup` | `KbdGroupProps`, `KbdProps` | Keyboard shortcut key and key group display |
93
- | `skeleton` | `./opinionated/skeleton` | `@leitware/composables` | `Skeleton`, `SkeletonAvatar`, `SkeletonButton`, `SkeletonInput`, `SkeletonText` | `SkeletonProps` | Animated placeholder for loading content |
94
- | `progress` | `./opinionated/progress` | `@leitware/composables` | `Progress`, `ProgressIndicator`, `ProgressLabel`, `ProgressTrack`, `ProgressValue` | `ProgressProps` | Horizontal progress bar indicator |
95
- | `divider` | `./opinionated/divider` | `@leitware/composables` | `Divider` | - | Horizontal or vertical divider with solid, dots, and pills variants |
82
+ | Module | Source module | Import from | Public values | Public types | Description |
83
+ | ------------ | -------------------------- | ----------------------- | ---------------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- |
84
+ | `typography` | `./opinionated/typography` | `@leitware/composables` | `Typography` | `TypographyProps`, `TypographyVariant` | Polymorphic text component with typographic scale variants |
85
+ | `badge` | `./opinionated/badge` | `@leitware/composables` | `Badge` | `BadgeProps` | Small status label with color variants |
86
+ | `avatar` | `./opinionated/avatar` | `@leitware/composables` | `Avatar`, `AvatarFallback`, `AvatarImage` | `AvatarProps` | Circular image element with automatic initials fallback |
87
+ | `icon` | `./opinionated/icon` | `@leitware/composables` | `Icon` | - | Icon wrapper with size and color variants |
88
+ | `kbd` | `./opinionated/kbd` | `@leitware/composables` | `Kbd`, `KbdGroup` | `KbdGroupProps`, `KbdProps` | Keyboard shortcut key and key group display |
89
+ | `skeleton` | `./opinionated/skeleton` | `@leitware/composables` | `Skeleton`, `SkeletonAvatar`, `SkeletonButton`, `SkeletonInput`, `SkeletonText` | `SkeletonProps` | Animated placeholder for loading content |
90
+ | `progress` | `./opinionated/progress` | `@leitware/composables` | `Progress`, `ProgressIndicator`, `ProgressLabel`, `ProgressTrack`, `ProgressValue` | `ProgressProps` | Horizontal progress bar indicator |
91
+ | `divider` | `./opinionated/divider` | `@leitware/composables` | `Divider` | `DividerProps` | Horizontal or vertical divider with solid, dots, and pills variants |
96
92
 
97
93
  ### Feedback & Overlay
98
94
 
99
- | Module | Source module | Import from | Public values | Public types | Description |
100
- | -------------- | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------- |
101
- | `alert` | `./opinionated/alert` | `@leitware/composables` | `Alert`, `AlertAction`, `AlertDescription`, `AlertTitle` | `AlertProps`, `AlertType` | Contextual feedback messages with type-based icon mapping |
102
- | `dialog` | `./opinionated/dialog` | `@leitware/composables` | `Dialog`, `DialogClose`, `DialogContent`, `DialogDescription`, `DialogFooter`, `DialogHeader`, `DialogTitle`, `DialogTrigger` | `DialogProps` | Modal dialog overlay with trigger, title, and footer props |
103
- | `alert-dialog` | `./opinionated/alert-dialog` | `@leitware/composables` | `AlertDialog`, `AlertDialogAction`, `AlertDialogCancel`, `AlertDialogContent`, `AlertDialogDescription`, `AlertDialogTitle`, `AlertDialogTrigger` | `AlertDialogProps` | Modal dialog for important confirmations |
104
- | `sheet` | `./opinionated/sheet` | `@leitware/composables` | `Sheet`, `SheetClose`, `SheetContent`, `SheetDescription`, `SheetFooter`, `SheetHeader`, `SheetTitle`, `SheetTrigger` | `SheetProps` | Slide-out panel from screen edge |
105
- | `popover` | `./opinionated/popover` | `@leitware/composables` | `Popover`, `PopoverContent`, `PopoverDescription`, `PopoverHeader`, `PopoverTitle`, `PopoverTrigger` | `PopoverProps` | Floating content panel anchored to a trigger |
106
- | `tooltip` | `./opinionated/tooltip` | `@leitware/composables` | `Tooltip`, `TooltipContent`, `TooltipTrigger` | `TooltipProps` | Informational popup on hover or focus |
107
- | `hover-card` | `./opinionated/hover-card` | `@leitware/composables` | `HoverCard`, `HoverCardContent`, `HoverCardTrigger` | `HoverCardProps` | Preview card shown on hover |
108
- | `sonner` | `./opinionated/sonner` | `@leitware/composables` | `Toaster` | - | Toast notification system powered by Sonner |
95
+ | Module | Source module | Import from | Public values | Public types | Description |
96
+ | -------------- | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- |
97
+ | `alert` | `./opinionated/alert` | `@leitware/composables` | `Alert`, `AlertAction`, `AlertDescription`, `AlertTitle` | `AlertProps`, `AlertType`, `AlertVariant` | Contextual feedback messages with type-based icon mapping |
98
+ | `dialog` | `./opinionated/dialog` | `@leitware/composables` | `Dialog`, `DialogClose`, `DialogContent`, `DialogDescription`, `DialogFooter`, `DialogHeader`, `DialogTitle`, `DialogTrigger` | `DialogProps` | Modal dialog overlay with trigger, title, and footer props |
99
+ | `alert-dialog` | `./opinionated/alert-dialog` | `@leitware/composables` | `AlertDialog`, `AlertDialogAction`, `AlertDialogCancel`, `AlertDialogContent`, `AlertDialogDescription`, `AlertDialogTitle`, `AlertDialogTrigger` | `AlertDialogProps` | Modal dialog for important confirmations |
100
+ | `sheet` | `./opinionated/sheet` | `@leitware/composables` | `Sheet`, `SheetClose`, `SheetContent`, `SheetDescription`, `SheetFooter`, `SheetHeader`, `SheetTitle`, `SheetTrigger` | `SheetProps` | Slide-out panel from screen edge |
101
+ | `popover` | `./opinionated/popover` | `@leitware/composables` | `Popover`, `PopoverContent`, `PopoverDescription`, `PopoverHeader`, `PopoverTitle`, `PopoverTrigger` | `PopoverProps` | Floating content panel anchored to a trigger |
102
+ | `tooltip` | `./opinionated/tooltip` | `@leitware/composables` | `Tooltip`, `TooltipContent`, `TooltipTrigger` | `TooltipProps` | Informational popup on hover or focus |
103
+ | `hover-card` | `./opinionated/hover-card` | `@leitware/composables` | `HoverCard`, `HoverCardContent`, `HoverCardTrigger` | `HoverCardProps` | Preview card shown on hover |
104
+ | `sonner` | `./opinionated/sonner` | `@leitware/composables` | `Toaster` | - | Toast notification system powered by Sonner |
109
105
 
110
106
  ### Navigation
111
107
 
112
108
  | Module | Source module | Import from | Public values | Public types | Description |
113
109
  | --------------- | ----------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------ |
114
- | `tabs` | `./opinionated/tabs` | `@leitware/composables` | `Tabs`, `TabsContent` | `TabItem` | Tabbed content navigation with items array API |
110
+ | `tabs` | `./opinionated/tabs` | `@leitware/composables` | `Tabs`, `TabsContent` | `TabItem`, `TabsProps`, `TabsVariant` | Tabbed content navigation with items array API |
115
111
  | `breadcrumb` | `./opinionated/breadcrumb` | `@leitware/composables` | `Breadcrumb`, `BreadcrumbEllipsis`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbList`, `BreadcrumbPage`, `BreadcrumbSeparator` | `BreadcrumbItemData`, `BreadcrumbProps` | Navigation trail with items array API |
116
112
  | `pagination` | `./opinionated/pagination` | `@leitware/composables` | `Pagination`, `PaginationContent`, `PaginationEllipsis`, `PaginationItem`, `PaginationLink`, `PaginationNext`, `PaginationPrevious` | `PaginationProps` | Page navigation with currentPage and totalPages API |
117
113
  | `sidebar` | `./opinionated/sidebar` | `@leitware/composables` | `Sidebar`, `SidebarContent`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupAction`, `SidebarGroupContent`, `SidebarGroupLabel`, `SidebarHeader`, `SidebarInput`, `SidebarInset`, `SidebarMenu`, `SidebarMenuAction`, `SidebarMenuBadge`, `SidebarMenuButton`, `SidebarMenuItem`, `SidebarMenuSkeleton`, `SidebarMenuSub`, `SidebarMenuSubButton`, `SidebarMenuSubItem`, `SidebarProvider`, `SidebarRail`, `SidebarSeparator`, `SidebarTrigger`, `useSidebar` | - | Application sidebar with collapsible navigation groups |
@@ -119,20 +115,20 @@ Use this catalog to choose public exports. The `Source module` column is for mai
119
115
 
120
116
  ### Data Display
121
117
 
122
- | Module | Source module | Import from | Public values | Public types | Description |
123
- | ------------- | --------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------- |
124
- | `table` | `./opinionated/table` | `@leitware/composables` | `Table`, `TableBody`, `TableCaption`, `TableCell`, `TableFooter`, `TableHead`, `TableHeader`, `TableRow` | - | Semantic HTML table with styled rows and cells |
125
- | `card` | `./opinionated/card` | `@leitware/composables` | `Card`, `CardAction`, `CardContent`, `CardDescription`, `CardFooter`, `CardHeader`, `CardTitle` | `CardProps` | Bordered content container with title, description, action, and footer props |
126
- | `accordion` | `./opinionated/accordion` | `@leitware/composables` | `Accordion`, `AccordionContent`, `AccordionItem`, `AccordionTrigger` | `AccordionItemData`, `AccordionProps` | Vertically collapsible content sections with items array API |
127
- | `collapsible` | `./opinionated/collapsible` | `@leitware/composables` | `Collapsible`, `CollapsibleContent`, `CollapsibleTrigger` | `CollapsibleProps` | Expandable and collapsible content panel with trigger prop |
128
- | `item` | `./opinionated/item` | `@leitware/composables` | `Item`, `ItemActions`, `ItemContent`, `ItemDescription`, `ItemFooter`, `ItemGroup`, `ItemHeader`, `ItemMedia`, `ItemSeparator`, `ItemTitle` | `ItemProps` | Flexible list item with title, description, icon, and actions |
129
- | `message` | `./opinionated/message` | `@leitware/composables` | `Message`, `MessageAvatar`, `MessageContent`, `MessageFooter`, `MessageGroup`, `MessageHeader` | - | Message row primitives for chat, activity, and assistant UIs |
130
- | `bubble` | `./opinionated/bubble` | `@leitware/composables` | `Bubble`, `BubbleContent`, `BubbleGroup`, `BubbleReactions` | `BubbleProps` | Message bubble primitives with semantic variants |
131
- | `marker` | `./opinionated/marker` | `@leitware/composables` | `Marker`, `MarkerContent`, `MarkerIcon` | `MarkerProps` | Inline metadata marker with icon, separator, and border variants |
132
- | `empty` | `./opinionated/empty` | `@leitware/composables` | `Empty`, `EmptyContent`, `EmptyDescription`, `EmptyHeader`, `EmptyMedia`, `EmptyTableState`, `EmptyTitle` | `EmptyProps`, `EmptyTableStateProps` | Empty state placeholder with icon, title, and description |
133
- | `carousel` | `./opinionated/carousel` | `@leitware/composables` | `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselNext`, `CarouselPrevious` | `CarouselProps` | Horizontally scrollable content slider with items array API |
134
- | `code-block` | `./opinionated/code-block` | `@leitware/composables` | `CodeBlock` | - | Monospace code display with line numbers |
135
- | `list` | `./opinionated/list` | `@leitware/composables` | `List`, `ListArrowItem`, `ListBulletItem` | `ListItemData`, `ListProps`, `ListVariant` | Variant list renderer: arrow, bullet |
118
+ | Module | Source module | Import from | Public values | Public types | Description |
119
+ | ------------- | --------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- |
120
+ | `table` | `./opinionated/table` | `@leitware/composables` | `Table`, `TableBody`, `TableCaption`, `TableCell`, `TableFooter`, `TableHead`, `TableHeader`, `TableRow` | - | Semantic HTML table with styled rows and cells |
121
+ | `card` | `./opinionated/card` | `@leitware/composables` | `Card`, `CardAction`, `CardContent`, `CardDescription`, `CardFooter`, `CardHeader`, `CardTitle` | `CardProps` | Bordered content container with title, description, action, and footer props |
122
+ | `accordion` | `./opinionated/accordion` | `@leitware/composables` | `Accordion`, `AccordionContent`, `AccordionItem`, `AccordionTrigger` | `AccordionItemData`, `AccordionProps`, `AccordionVariant` | Vertically collapsible content sections with items array API |
123
+ | `collapsible` | `./opinionated/collapsible` | `@leitware/composables` | `Collapsible`, `CollapsibleContent`, `CollapsibleTrigger` | `CollapsibleProps` | Expandable and collapsible content panel with trigger prop |
124
+ | `item` | `./opinionated/item` | `@leitware/composables` | `Item`, `ItemActions`, `ItemContent`, `ItemDescription`, `ItemFooter`, `ItemGroup`, `ItemHeader`, `ItemMedia`, `ItemSeparator`, `ItemTitle` | `ItemProps`, `ItemVariants` | Flexible list item with title, description, icon, and actions |
125
+ | `message` | `./opinionated/message` | `@leitware/composables` | `Message`, `MessageAvatar`, `MessageContent`, `MessageFooter`, `MessageGroup`, `MessageHeader` | - | Message row primitives for chat, activity, and assistant UIs |
126
+ | `bubble` | `./opinionated/bubble` | `@leitware/composables` | `Bubble`, `BubbleContent`, `BubbleGroup`, `BubbleReactions` | `BubbleProps` | Message bubble primitives with semantic variants |
127
+ | `marker` | `./opinionated/marker` | `@leitware/composables` | `Marker`, `MarkerContent`, `MarkerIcon` | `MarkerProps` | Inline metadata marker with icon, separator, and border variants |
128
+ | `empty` | `./opinionated/empty` | `@leitware/composables` | `Empty`, `EmptyContent`, `EmptyDescription`, `EmptyHeader`, `EmptyMedia`, `EmptyTableState`, `EmptyTitle` | `EmptyProps`, `EmptyTableStateProps` | Empty state placeholder with icon, title, and description |
129
+ | `carousel` | `./opinionated/carousel` | `@leitware/composables` | `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselNext`, `CarouselPrevious` | `CarouselProps` | Horizontally scrollable content slider with items array API |
130
+ | `code-block` | `./opinionated/code-block` | `@leitware/composables` | `CodeBlock` | `CodeBlockProps` | Monospace code display with line numbers |
131
+ | `list` | `./opinionated/list` | `@leitware/composables` | `List`, `ListArrowItem`, `ListBulletItem` | `ListItemData`, `ListProps`, `ListVariant` | Variant list renderer: arrow, bullet |
136
132
 
137
133
  ### Form Components
138
134
 
@@ -152,23 +148,23 @@ Use this catalog to choose public exports. The `Source module` column is for mai
152
148
  | `form-calendar-popover` | `./opinionated/form-calendar-popover` | `@leitware/composables` | `FormCalendarPopover` | `FormCalendarPopoverProps` | Date picker field with calendar popover |
153
149
  | `form-date-of-birth` | `./opinionated/form-date-of-birth` | `@leitware/composables` | `FormDateOfBirth` | `DateOfBirthValue`, `FormDateOfBirthProps` | Three-field date of birth input with auto-advance |
154
150
  | `form-dropzone` | `./opinionated/form-dropzone` | `@leitware/composables` | `ACCEPT_PRESETS`, `FormDropZone` | `FormDropZoneProps` | Single file upload field with drag-and-drop |
155
- | `form-multi-dropzone` | `./opinionated/form-multi-dropzone` | `@leitware/composables` | `FormMultiDropZone` | `FormMultiDropZoneProps` | Multi-file upload field with drag-and-drop |
151
+ | `form-multi-dropzone` | `./opinionated/form-multi-dropzone` | `@leitware/composables` | `ACCEPT_PRESETS`, `FormMultiDropZone` | `FormMultiDropZoneProps` | Multi-file upload field with drag-and-drop |
156
152
 
157
153
  ### Interactive
158
154
 
159
- | Module | Source module | Import from | Public values | Public types | Description |
160
- | -------------- | ---------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------- |
161
- | `button` | `./opinionated/button` | `@leitware/composables` | `Button` | `ButtonProps` | Clickable button with loading spinner support |
162
- | `toggle` | `./opinionated/toggle` | `@leitware/composables` | `Toggle` | `ToggleProps` | Pressable toggle button with left and right icon slots |
163
- | `toggle-group` | `./opinionated/toggle-group` | `@leitware/composables` | `ToggleGroup`, `ToggleGroupItem` | `ToggleGroupOption`, `ToggleGroupProps` | Grouped toggle buttons for single or multiple selection |
164
- | `switch` | `./opinionated/switch` | `@leitware/composables` | `Switch` | - | Toggle switch for on/off states |
165
- | `slider` | `./opinionated/slider` | `@leitware/composables` | `Slider` | - | Draggable range slider input |
166
- | `checkbox` | `./opinionated/checkbox` | `@leitware/composables` | `Checkbox` | - | Toggle checkbox input with checked state |
167
- | `radio-group` | `./opinionated/radio-group` | `@leitware/composables` | `RadioGroup`, `RadioGroupItem` | - | Group of mutually exclusive radio options |
168
- | `combobox` | `./opinionated/combobox` | `@leitware/composables` | `Combobox`, `ComboboxChip`, `ComboboxChips`, `ComboboxChipsInput`, `ComboboxCollection`, `ComboboxContent`, `ComboboxEmpty`, `ComboboxGroup`, `ComboboxInput`, `ComboboxItem`, `ComboboxLabel`, `ComboboxList`, `ComboboxSeparator`, `ComboboxTrigger`, `ComboboxValue` | `ComboboxOption`, `ComboboxProps` | Searchable select dropdown with autocomplete |
169
- | `select` | `./opinionated/select` | `@leitware/composables` | `Select`, `SelectContent`, `SelectGroup`, `SelectItem`, `SelectLabel`, `SelectTrigger`, `SelectValue` | `SelectOption`, `SelectProps` | Dropdown select menu with scrollable options |
170
- | `calendar` | `./opinionated/calendar` | `@leitware/composables` | `Calendar`, `CalendarDayButton` | - | Date picker calendar powered by react-day-picker |
171
- | `dropzone` | `./opinionated/dropzone` | `@leitware/composables` | `DropZone`, `DropZoneFile` | - | Drag-and-drop file upload area |
155
+ | Module | Source module | Import from | Public values | Public types | Description |
156
+ | -------------- | ---------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------- |
157
+ | `button` | `./opinionated/button` | `@leitware/composables` | `Button` | `ButtonProps` | Clickable button with loading spinner support |
158
+ | `toggle` | `./opinionated/toggle` | `@leitware/composables` | `Toggle` | `ToggleProps` | Pressable toggle button with left and right icon slots |
159
+ | `toggle-group` | `./opinionated/toggle-group` | `@leitware/composables` | `ToggleGroup`, `ToggleGroupItem` | `ToggleGroupOption`, `ToggleGroupProps` | Grouped toggle buttons for single or multiple selection |
160
+ | `switch` | `./opinionated/switch` | `@leitware/composables` | `Switch` | - | Toggle switch for on/off states |
161
+ | `slider` | `./opinionated/slider` | `@leitware/composables` | `Slider` | - | Draggable range slider input |
162
+ | `checkbox` | `./opinionated/checkbox` | `@leitware/composables` | `Checkbox` | - | Toggle checkbox input with checked state |
163
+ | `radio-group` | `./opinionated/radio-group` | `@leitware/composables` | `RadioGroup`, `RadioGroupItem` | - | Group of mutually exclusive radio options |
164
+ | `combobox` | `./opinionated/combobox` | `@leitware/composables` | `Combobox`, `ComboboxChip`, `ComboboxChips`, `ComboboxChipsInput`, `ComboboxCollection`, `ComboboxContent`, `ComboboxEmpty`, `ComboboxGroup`, `ComboboxInput`, `ComboboxItem`, `ComboboxLabel`, `ComboboxList`, `ComboboxSeparator`, `ComboboxTrigger`, `ComboboxValue` | `ComboboxOption`, `ComboboxProps` | Searchable select dropdown with autocomplete |
165
+ | `select` | `./opinionated/select` | `@leitware/composables` | `Select`, `SelectContent`, `SelectGroup`, `SelectItem`, `SelectLabel`, `SelectTrigger`, `SelectValue` | `SelectOption`, `SelectProps` | Dropdown select menu with scrollable options |
166
+ | `calendar` | `./opinionated/calendar` | `@leitware/composables` | `Calendar`, `CalendarDayButton` | - | Date picker calendar powered by react-day-picker |
167
+ | `dropzone` | `./opinionated/dropzone` | `@leitware/composables` | `ACCEPT_PRESETS`, `DropZone`, `DropZoneFile` | `Accept`, `DropZoneFileProps`, `DropZoneProps`, `FileRejection` | Drag-and-drop file upload area |
172
168
 
173
169
  ### Tooling Components
174
170
 
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: use-composables
3
+ description: Build, style, theme, or review React interfaces that consume @leitware/composables. Use when adding Composables components, configuring styles or presets, overriding semantic tokens for light and dark modes, choosing semantic utility classes, resolving optional peer dependencies, or checking consumer code for design-system code smells.
4
+ ---
5
+
6
+ # Use Composables
7
+
8
+ Treat the package's public components, semantic CSS variables, documented semantic classes, and presets as the design-system API. Keep palette primitives, Tailwind adapter variables, and internal components behind that boundary.
9
+
10
+ ## Follow the consumer workflow
11
+
12
+ 1. Inspect the installed package version and the consuming application's existing root CSS, theme selector, package manager, and verification scripts.
13
+ 2. Import `@leitware/composables/styles.css` once in the root CSS entrypoint.
14
+ 3. Import at most one `@leitware/composables/presets/<name>.css` after `styles.css` when selecting a non-default preset.
15
+ 4. Read the generated [public API manifest](references/public-api.md) before importing components. Import normal components, values, and types from `@leitware/composables`; import AI components only from `/ai`. Never import from `src/`, `_internal/`, or unpublished paths.
16
+ 5. Prefer a public component's props and variants before adding consumer styling. The manifest proves that a name is public, but it does not document props; inspect the installed package source or TypeScript declarations before using an unfamiliar component API.
17
+ 6. Use documented semantic classes for colour roles. Read [semantic-styling.md](references/semantic-styling.md) before adding or changing theme values, colour classes, token overrides, or Tailwind variants. Consult the generated [semantic utility manifest](references/semantic-utilities.md) as the exact base-class allowlist.
18
+ 7. Add application-specific token overrides after all package imports in the designated root theme CSS. Define light values in `:root` and dark values in `.dark`, or preserve the application's established equivalent selector.
19
+ 8. Read [optional-dependencies.md](references/optional-dependencies.md) before using the AI entrypoint, preset fonts, or when resolving a missing-module error.
20
+ 9. Run the consuming repository's relevant lint, typecheck, test, and build scripts. Run any package-provided Composables or semantic-token verification command when available. Report commands that could not be found or run.
21
+
22
+ ## Enforce the design-system boundary
23
+
24
+ - Keep raw colour literals inside explicitly designated theme CSS only, where they assign semantic custom properties.
25
+ - Reject raw colours in components, CSS modules, inline styles, and arbitrary utility values.
26
+ - Reject primitive palette classes and variables such as `bg-blue-500` and `var(--blue-800)`.
27
+ - Reject direct use of internal Tailwind adapter variables such as `--color-*`.
28
+ - Reject direct semantic-variable utility syntax when a documented class exists, such as `bg-[var(--bg-surface-success)]`.
29
+ - Preserve semantic intent: use a surface role for backgrounds, a text role for text, an icon role for icons, and a stroke role for border colour. Do not infer public ring or outline colour utilities.
30
+ - Do not invent a raw value, primitive class, direct-variable class, or misleading existing role when the system lacks the needed semantic role. Report the missing role and propose a reusable semantic token instead.
31
+
32
+ ## Review changes
33
+
34
+ Check that the result:
35
+
36
+ - imports styles once and no more than one preset;
37
+ - imports normal values and types from the root entrypoint and AI components from `/ai`;
38
+ - keeps light and dark overrides together at the theme boundary;
39
+ - uses documented semantic roles consistently across states;
40
+ - installs optional peers only for AI features or preset fonts that require them;
41
+ - introduces no design-system escape hatch outside an intentional theme override;
42
+ - passes the consuming repository's available verification commands.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: 'Use Composables'
3
+ short_description: 'Build interfaces with Composables correctly'
4
+ default_prompt: 'Use $use-composables to build this interface with public components and semantic styling.'
@@ -0,0 +1,76 @@
1
+ # Optional dependencies reference
2
+
3
+ Use this reference before adding AI components, loading preset fonts, or resolving a missing-module error. Install only the peers needed by the selected optional surface, using the consuming repository's package manager.
4
+
5
+ ## Component dependencies
6
+
7
+ All non-AI components—including Calendar, Carousel, DropZone, Resizable, Toaster, ThemeInjector, and TokenConfigPanel—are imported from `@leitware/composables`. Their runtime integrations are installed with the package and require no feature subpath or separate peer installation.
8
+
9
+ AI components are the deliberate exception. Import them from `@leitware/composables/ai` and install the optional peers required by that entrypoint: `ai`, `shiki`, `streamdown`, `@streamdown/cjk`, `@streamdown/code`, `@streamdown/math`, `@streamdown/mermaid`, `use-stick-to-bottom`, `nanoid`, `@radix-ui/react-use-controllable-state`, `cmdk`, and `motion`. Do not install this dependency set in applications that do not import AI components.
10
+
11
+ ## Preset fonts
12
+
13
+ Core styles render with system fallbacks when optional fonts are not installed or loaded. To reproduce a preset's intended typography, install only its packages and load the listed entrypoints before the package styles. In a CSS entrypoint use `@import`; in a JavaScript or TypeScript application entrypoint use the same package paths with side-effect `import` statements.
14
+
15
+ | Preset | Font packages |
16
+ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
17
+ | Default | `@fontsource-variable/inter`, `@fontsource-variable/bricolage-grotesque` |
18
+ | Brutalist | `@fontsource-variable/space-grotesk`, `@fontsource-variable/jetbrains-mono` |
19
+ | Signal Pop | `@fontsource/ibm-plex-sans`, `@fontsource-variable/space-grotesk`, `@fontsource-variable/jetbrains-mono`, `@fontsource/ibm-plex-mono` |
20
+
21
+ Inspect the selected preset and current package documentation for its exact font requirements before installing. Do not install every optional font package pre-emptively.
22
+
23
+ ### Default font loading
24
+
25
+ ```css
26
+ @import '@fontsource-variable/inter';
27
+ @import '@fontsource-variable/bricolage-grotesque';
28
+ @import '@leitware/composables/styles.css';
29
+ ```
30
+
31
+ The variable entrypoints contain the weight ranges used by the preset.
32
+
33
+ ### Brutalist font loading
34
+
35
+ ```css
36
+ @import '@fontsource-variable/space-grotesk';
37
+ @import '@fontsource-variable/jetbrains-mono';
38
+ @import '@leitware/composables/styles.css';
39
+ @import '@leitware/composables/presets/brutalist.css';
40
+ ```
41
+
42
+ ### Signal Pop font loading
43
+
44
+ ```css
45
+ @import '@fontsource/ibm-plex-sans/400.css';
46
+ @import '@fontsource/ibm-plex-sans/500.css';
47
+ @import '@fontsource/ibm-plex-sans/600.css';
48
+ @import '@fontsource/ibm-plex-sans/700.css';
49
+ @import '@fontsource-variable/space-grotesk';
50
+ @import '@fontsource-variable/jetbrains-mono';
51
+ @import '@fontsource/ibm-plex-mono/400.css';
52
+ @import '@fontsource/ibm-plex-mono/500.css';
53
+ @import '@fontsource/ibm-plex-mono/600.css';
54
+ @import '@fontsource/ibm-plex-mono/700.css';
55
+ @import '@leitware/composables/styles.css';
56
+ @import '@leitware/composables/presets/signal-pop.css';
57
+ ```
58
+
59
+ The explicit IBM Plex imports load the normal weights used by common body, control, and brand text. The Space Grotesk and JetBrains Mono variable entrypoints cover their preset weight ranges. Load italic entrypoints separately only when the consuming interface actually uses italics.
60
+
61
+ Equivalent application-entry imports are valid:
62
+
63
+ ```ts
64
+ import '@fontsource/ibm-plex-sans/400.css'
65
+ import '@fontsource-variable/space-grotesk'
66
+ ```
67
+
68
+ ## Resolve missing modules
69
+
70
+ 1. Identify the imported public component or subpath that reaches the missing package.
71
+ 2. Confirm that the feature is actually used and cannot be removed or replaced by a core component.
72
+ 3. Check the installed `@leitware/composables` version's peer dependency range.
73
+ 4. Install a compatible version with the application's existing package manager.
74
+ 5. Re-run typecheck and the relevant build or test command.
75
+
76
+ Do not import unpublished source paths to bypass an optional dependency. Do not move an optional package into application production dependencies unless the application actually ships the corresponding feature.
@@ -0,0 +1,23 @@
1
+ # Public API manifest
2
+
3
+ <!-- This file is generated by scripts/generate-rules.ts. Do not edit it directly. -->
4
+
5
+ This is the exact installed-package entrypoint and export-name contract. Import values and types only from the entrypoint where they are listed. This manifest identifies names, not component props; inspect the installed package source or TypeScript declarations before using an unfamiliar API.
6
+
7
+ ## `@leitware/composables`
8
+
9
+ - Values (275): `ACCEPT_PRESETS`, `Accordion`, `AccordionContent`, `AccordionItem`, `AccordionTrigger`, `Alert`, `AlertAction`, `AlertDescription`, `AlertDialog`, `AlertDialogAction`, `AlertDialogCancel`, `AlertDialogContent`, `AlertDialogDescription`, `AlertDialogTitle`, `AlertDialogTrigger`, `AlertTitle`, `AspectRatio`, `Avatar`, `AvatarFallback`, `AvatarImage`, `Badge`, `BentoCell`, `BentoGrid`, `Breadcrumb`, `BreadcrumbEllipsis`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbList`, `BreadcrumbPage`, `BreadcrumbSeparator`, `Bubble`, `BubbleContent`, `BubbleGroup`, `BubbleReactions`, `Button`, `Calendar`, `CalendarDayButton`, `Card`, `CardAction`, `CardContent`, `CardDescription`, `CardFooter`, `CardHeader`, `CardTitle`, `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselNext`, `CarouselPrevious`, `Checkbox`, `cn`, `CodeBlock`, `Collapsible`, `CollapsibleContent`, `CollapsibleTrigger`, `Combobox`, `ComboboxChip`, `ComboboxChips`, `ComboboxChipsInput`, `ComboboxCollection`, `ComboboxContent`, `ComboboxEmpty`, `ComboboxGroup`, `ComboboxInput`, `ComboboxItem`, `ComboboxLabel`, `ComboboxList`, `ComboboxSeparator`, `ComboboxTrigger`, `ComboboxValue`, `Container`, `Dialog`, `DialogClose`, `DialogContent`, `DialogDescription`, `DialogFooter`, `DialogHeader`, `DialogTitle`, `DialogTrigger`, `DirectionProvider`, `DISABLED_OPACITY`, `Divider`, `DropdownMenu`, `DropdownMenuCheckboxItem`, `DropdownMenuContent`, `DropdownMenuGroup`, `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuSeparator`, `DropdownMenuSub`, `DropdownMenuSubContent`, `DropdownMenuSubTrigger`, `DropdownMenuTrigger`, `DropZone`, `DropZoneFile`, `Empty`, `EmptyContent`, `EmptyDescription`, `EmptyHeader`, `EmptyMedia`, `EmptyTableState`, `EmptyTitle`, `Field`, `FieldContent`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldLabel`, `FieldLegend`, `FieldSeparator`, `FieldSet`, `FieldTitle`, `FOCUS_RING`, `FOCUS_RING_DESTRUCTIVE`, `formatNumericValue`, `FormCalendarPopover`, `FormCheckbox`, `FormCombobox`, `FormDateOfBirth`, `FormDropZone`, `FormInput`, `FormInputGroup`, `FormMultiCombobox`, `FormMultiDropZone`, `FormRadioGroup`, `FormSelect`, `FormSlider`, `FormSwitch`, `FormTextarea`, `Grid`, `GridOverlay`, `HoverCard`, `HoverCardContent`, `HoverCardTrigger`, `Icon`, `Input`, `InputGroup`, `InputGroupAddon`, `InputGroupButton`, `InputGroupInput`, `InputGroupTextarea`, `Item`, `ItemActions`, `ItemContent`, `ItemDescription`, `ItemFooter`, `ItemGroup`, `ItemHeader`, `ItemMedia`, `ItemSeparator`, `ItemTitle`, `Kbd`, `KbdGroup`, `Label`, `leftPad`, `List`, `ListArrowItem`, `ListBulletItem`, `Marker`, `MarkerContent`, `MarkerIcon`, `Message`, `MessageAvatar`, `MessageContent`, `MessageFooter`, `MessageGroup`, `MessageHeader`, `NativeSelect`, `NativeSelectOptGroup`, `NativeSelectOption`, `NewspaperCell`, `NewspaperGrid`, `Pagination`, `PaginationContent`, `PaginationEllipsis`, `PaginationItem`, `PaginationLink`, `PaginationNext`, `PaginationPrevious`, `parseNumericValue`, `Popover`, `PopoverContent`, `PopoverDescription`, `PopoverHeader`, `PopoverTitle`, `PopoverTrigger`, `Progress`, `ProgressIndicator`, `ProgressLabel`, `ProgressTrack`, `ProgressValue`, `RadioGroup`, `RadioGroupItem`, `ResizableHandle`, `ResizablePanel`, `ResizablePanelGroup`, `sanitizeNumericInput`, `ScrollArea`, `ScrollBar`, `Section`, `Select`, `SelectContent`, `SelectGroup`, `SelectItem`, `SelectLabel`, `SelectTrigger`, `SelectValue`, `Separator`, `Sheet`, `SheetClose`, `SheetContent`, `SheetDescription`, `SheetFooter`, `SheetHeader`, `SheetTitle`, `SheetTrigger`, `Sidebar`, `SidebarContent`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupAction`, `SidebarGroupContent`, `SidebarGroupLabel`, `SidebarHeader`, `SidebarInput`, `SidebarInset`, `SidebarMenu`, `SidebarMenuAction`, `SidebarMenuBadge`, `SidebarMenuButton`, `SidebarMenuItem`, `SidebarMenuSkeleton`, `SidebarMenuSub`, `SidebarMenuSubButton`, `SidebarMenuSubItem`, `SidebarProvider`, `SidebarRail`, `SidebarSeparator`, `SidebarTrigger`, `Skeleton`, `SkeletonAvatar`, `SkeletonButton`, `SkeletonInput`, `SkeletonText`, `Slider`, `Spacer`, `Stack`, `Switch`, `Table`, `TableBody`, `TableCaption`, `TableCell`, `TableFooter`, `TableHead`, `TableHeader`, `TableRow`, `Tabs`, `TabsContent`, `Textarea`, `ThemeInjector`, `Toaster`, `Toggle`, `ToggleGroup`, `ToggleGroupItem`, `TokenConfigPanel`, `Tooltip`, `TooltipContent`, `TooltipTrigger`, `Typography`, `useDirection`, `useIsMobile`, `useNumericInput`, `useSidebar`
10
+ - Types (91): `Accept`, `AccordionItemData`, `AccordionProps`, `AccordionVariant`, `AlertDialogProps`, `AlertProps`, `AlertType`, `AlertVariant`, `AvatarProps`, `BadgeProps`, `BreadcrumbItemData`, `BreadcrumbProps`, `BubbleProps`, `ButtonProps`, `CardProps`, `CarouselProps`, `CodeBlockProps`, `CollapsibleProps`, `ComboboxOption`, `ComboboxProps`, `ContainerProps`, `DateOfBirthValue`, `DialogProps`, `DirectionProviderProps`, `DividerProps`, `DropdownMenuItemData`, `DropdownMenuProps`, `DropZoneFileProps`, `DropZoneProps`, `EmptyProps`, `EmptyTableStateProps`, `FileRejection`, `FormCalendarPopoverProps`, `FormCheckboxProps`, `FormComboboxOption`, `FormComboboxProps`, `FormDateOfBirthProps`, `FormDropZoneProps`, `FormInputGroupInputProps`, `FormInputGroupProps`, `FormInputProps`, `FormMultiComboboxOption`, `FormMultiComboboxProps`, `FormMultiDropZoneProps`, `FormRadioGroupOption`, `FormRadioGroupProps`, `FormSelectOption`, `FormSelectProps`, `FormSliderProps`, `FormSwitchProps`, `FormTextareaProps`, `GridOverlayProps`, `GridProps`, `HoverCardProps`, `ItemProps`, `ItemVariants`, `KbdGroupProps`, `KbdProps`, `ListItemData`, `ListProps`, `ListVariant`, `MarkerProps`, `NativeSelectOptionData`, `NativeSelectProps`, `NewspaperCellProps`, `NewspaperGridProps`, `NumericInputOptions`, `NumericMode`, `PaginationProps`, `PopoverProps`, `ProgressProps`, `ScrollAreaProps`, `SectionProps`, `SelectOption`, `SelectProps`, `SheetProps`, `SkeletonProps`, `SpacerProps`, `StackProps`, `TabItem`, `TabsProps`, `TabsVariant`, `TextDirection`, `ToggleGroupOption`, `ToggleGroupProps`, `ToggleProps`, `TooltipProps`, `TypographyProps`, `TypographyVariant`, `UseNumericInputOptions`, `UseNumericInputReturn`
11
+
12
+ ## `@leitware/composables/ai`
13
+
14
+ - Values (127): `AIAttachment`, `AIAttachmentEmpty`, `AIAttachmentHoverCard`, `AIAttachmentHoverCardContent`, `AIAttachmentHoverCardTrigger`, `AIAttachmentInfo`, `AIAttachmentPreview`, `AIAttachmentRemove`, `AIAttachments`, `AIChainOfThought`, `AIChainOfThoughtContent`, `AIChainOfThoughtHeader`, `AIChainOfThoughtImage`, `AIChainOfThoughtSearchResult`, `AIChainOfThoughtSearchResults`, `AIChainOfThoughtStep`, `AICodeBlock`, `AICodeBlockActions`, `AICodeBlockContainer`, `AICodeBlockContent`, `AICodeBlockCopyButton`, `AICodeBlockFilename`, `AICodeBlockHeader`, `AICodeBlockLanguageSelector`, `AICodeBlockLanguageSelectorContent`, `AICodeBlockLanguageSelectorItem`, `AICodeBlockLanguageSelectorTrigger`, `AICodeBlockLanguageSelectorValue`, `AICodeBlockTitle`, `AIConfirmation`, `AIConfirmationAccepted`, `AIConfirmationAction`, `AIConfirmationActions`, `AIConfirmationRejected`, `AIConfirmationRequest`, `AIConfirmationTitle`, `AIConversation`, `AIConversationContent`, `AIConversationDownload`, `AIConversationEmptyState`, `AIConversationScrollButton`, `AIInlineCitation`, `AIInlineCitationCard`, `AIInlineCitationCardBody`, `AIInlineCitationCardTrigger`, `AIInlineCitationCarousel`, `AIInlineCitationCarouselContent`, `AIInlineCitationCarouselHeader`, `AIInlineCitationCarouselIndex`, `AIInlineCitationCarouselItem`, `AIInlineCitationCarouselNext`, `AIInlineCitationCarouselPrev`, `AIInlineCitationQuote`, `AIInlineCitationSource`, `AIInlineCitationText`, `AIMessage`, `AIMessageAction`, `AIMessageActions`, `AIMessageBranch`, `AIMessageBranchContent`, `AIMessageBranchNext`, `AIMessageBranchPage`, `AIMessageBranchPrevious`, `AIMessageBranchSelector`, `AIMessageContent`, `AIMessageResponse`, `AIMessageToolbar`, `AIPlan`, `AIPlanAction`, `AIPlanContent`, `AIPlanDescription`, `AIPlanFooter`, `AIPlanHeader`, `AIPlanTitle`, `AIPlanTrigger`, `AIPromptInput`, `AIPromptInputActionAddAttachments`, `AIPromptInputActionAddScreenshot`, `AIPromptInputActionMenu`, `AIPromptInputActionMenuContent`, `AIPromptInputActionMenuItem`, `AIPromptInputActionMenuTrigger`, `AIPromptInputBody`, `AIPromptInputButton`, `AIPromptInputFooter`, `AIPromptInputHeader`, `AIPromptInputProvider`, `AIPromptInputSelect`, `AIPromptInputSelectContent`, `AIPromptInputSelectItem`, `AIPromptInputSelectTrigger`, `AIPromptInputSelectValue`, `AIPromptInputSubmit`, `AIPromptInputTextarea`, `AIPromptInputTools`, `AIReasoning`, `AIReasoningContent`, `AIReasoningTrigger`, `AIShimmer`, `AISource`, `AISources`, `AISourcesContent`, `AISourcesTrigger`, `AISuggestion`, `AISuggestions`, `AITask`, `AITaskContent`, `AITaskItem`, `AITaskItemFile`, `AITaskTrigger`, `AITool`, `AIToolContent`, `AIToolHeader`, `AIToolInput`, `AIToolOutput`, `getAttachmentLabel`, `getMediaCategory`, `getStatusBadge`, `highlightCode`, `messagesToMarkdown`, `useAttachmentContext`, `useAttachmentsContext`, `usePromptInputAttachments`, `usePromptInputController`, `usePromptInputReferencedSources`, `useProviderAttachments`, `useReasoning`
15
+ - Types (95): `AIAttachmentEmptyProps`, `AIAttachmentHoverCardContentProps`, `AIAttachmentHoverCardProps`, `AIAttachmentHoverCardTriggerProps`, `AIAttachmentInfoProps`, `AIAttachmentPreviewProps`, `AIAttachmentProps`, `AIAttachmentRemoveProps`, `AIAttachmentsProps`, `AIChainOfThoughtContentProps`, `AIChainOfThoughtHeaderProps`, `AIChainOfThoughtImageProps`, `AIChainOfThoughtProps`, `AIChainOfThoughtSearchResultProps`, `AIChainOfThoughtSearchResultsProps`, `AIChainOfThoughtStepProps`, `AICodeBlockCopyButtonProps`, `AICodeBlockLanguageSelectorContentProps`, `AICodeBlockLanguageSelectorItemProps`, `AICodeBlockLanguageSelectorProps`, `AICodeBlockLanguageSelectorTriggerProps`, `AICodeBlockLanguageSelectorValueProps`, `AIConfirmationAcceptedProps`, `AIConfirmationActionProps`, `AIConfirmationActionsProps`, `AIConfirmationProps`, `AIConfirmationRejectedProps`, `AIConfirmationRequestProps`, `AIConfirmationTitleProps`, `AIConversationContentProps`, `AIConversationDownloadProps`, `AIConversationEmptyStateProps`, `AIConversationProps`, `AIConversationScrollButtonProps`, `AIInlineCitationCardBodyProps`, `AIInlineCitationCardProps`, `AIInlineCitationCardTriggerProps`, `AIInlineCitationCarouselContentProps`, `AIInlineCitationCarouselHeaderProps`, `AIInlineCitationCarouselIndexProps`, `AIInlineCitationCarouselItemProps`, `AIInlineCitationCarouselNextProps`, `AIInlineCitationCarouselPrevProps`, `AIInlineCitationCarouselProps`, `AIInlineCitationProps`, `AIInlineCitationQuoteProps`, `AIInlineCitationSourceProps`, `AIInlineCitationTextProps`, `AIMessageActionProps`, `AIMessageActionsProps`, `AIMessageBranchContentProps`, `AIMessageBranchNextProps`, `AIMessageBranchPageProps`, `AIMessageBranchPreviousProps`, `AIMessageBranchProps`, `AIMessageBranchSelectorProps`, `AIMessageContentProps`, `AIMessageProps`, `AIMessageResponseProps`, `AIMessageToolbarProps`, `AIPlanActionProps`, `AIPlanContentProps`, `AIPlanDescriptionProps`, `AIPlanFooterProps`, `AIPlanHeaderProps`, `AIPlanProps`, `AIPlanTitleProps`, `AIPlanTriggerProps`, `AIPromptInputProps`, `AIPromptInputSubmitProps`, `AIReasoningContentProps`, `AIReasoningProps`, `AIReasoningTriggerProps`, `AIShimmerProps`, `AISourceProps`, `AISourcesContentProps`, `AISourcesProps`, `AISourcesTriggerProps`, `AISuggestionProps`, `AISuggestionsProps`, `AITaskContentProps`, `AITaskItemFileProps`, `AITaskItemProps`, `AITaskProps`, `AITaskTriggerProps`, `AIToolContentProps`, `AIToolHeaderProps`, `AIToolInputProps`, `AIToolOutputProps`, `AIToolProps`, `AttachmentData`, `AttachmentMediaCategory`, `AttachmentVariant`, `PromptInputMessage`, `ToolPart`
16
+
17
+ ## CSS entrypoints
18
+
19
+ | Import | Package target |
20
+ | ------------------------------------ | --------------------- |
21
+ | `@leitware/composables/styles.css` | `./dist/styles.css` |
22
+ | `@leitware/composables/tailwind.css` | `./dist/tailwind.css` |
23
+ | `@leitware/composables/presets/*` | `./dist/presets/*` |
@@ -0,0 +1,134 @@
1
+ # Semantic styling reference
2
+
3
+ Use this reference when choosing semantic classes, applying a preset, overriding tokens, or reviewing styling.
4
+
5
+ ## Import order
6
+
7
+ Import the base stylesheet once from the application's root CSS:
8
+
9
+ ```css
10
+ @import '@leitware/composables/styles.css';
11
+ ```
12
+
13
+ Select no more than one optional preset and place it immediately after the base import:
14
+
15
+ ```css
16
+ @import '@leitware/composables/styles.css';
17
+ @import '@leitware/composables/presets/brutalist.css';
18
+ ```
19
+
20
+ Place application overrides after both imports. Do not copy package CSS into the application and do not require downstream Tailwind configuration merely to render package components.
21
+
22
+ ## Use semantic variants with Tailwind v4
23
+
24
+ Base classes in the generated utility manifest work without Tailwind. A Tailwind v4 application that needs state, responsive, group, or other variants of those exact classes must use this import order:
25
+
26
+ ```css
27
+ @import 'tailwindcss';
28
+ @import '@leitware/composables/tailwind.css';
29
+ @import '@leitware/composables/styles.css';
30
+ @import '@leitware/composables/presets/signal-pop.css'; /* Optional */
31
+ ```
32
+
33
+ With `tailwind.css` present, variant-prefixed forms of an exact manifest class are permitted:
34
+
35
+ ```tsx
36
+ <div className="bg-surface-success hover:bg-surface-hover md:text-success" />
37
+ ```
38
+
39
+ The suffix after all variants must exactly match a manifest class. The adapter does not make inferred combinations such as `ring-stroke-focus`, `outline-stroke-focus`, or `bg-icon-success` public. Without `tailwind.css`, use only the shipped unprefixed classes; do not assume Tailwind can generate their variants.
40
+
41
+ ## Override semantic roles
42
+
43
+ Treat the root theme stylesheet as the only raw-value boundary. Assign application values to public semantic variables in both modes when the value should change with the theme:
44
+
45
+ ```css
46
+ @import '@leitware/composables/styles.css';
47
+ @import '@leitware/composables/presets/brutalist.css';
48
+
49
+ :root {
50
+ --bg-fill-brand: #4f46e5;
51
+ --border-focus: #3730a3;
52
+ }
53
+
54
+ .dark {
55
+ --bg-fill-brand: #818cf8;
56
+ --border-focus: #a5b4fc;
57
+ }
58
+ ```
59
+
60
+ Preserve an established dark-mode selector when the application intentionally uses an equivalent such as `[data-theme='dark']`. Keep overrides after package imports so normal CSS cascade order applies.
61
+
62
+ Override semantic roles, not primitive palette values or Tailwind adapter aliases:
63
+
64
+ ```css
65
+ /* Correct theme-boundary override */
66
+ :root {
67
+ --bg-surface-brand: oklch(0.95 0.04 280);
68
+ }
69
+
70
+ /* Incorrect: modifies a palette primitive */
71
+ :root {
72
+ --violet-200: oklch(0.95 0.04 280);
73
+ }
74
+
75
+ /* Incorrect: targets the Tailwind adapter */
76
+ :root {
77
+ --color-surface-brand: oklch(0.95 0.04 280);
78
+ }
79
+ ```
80
+
81
+ ## Choose a semantic class
82
+
83
+ Use the package's generated [semantic utility manifest](semantic-utilities.md) as the exact class allowlist. Do not infer that every token supports every CSS property. A class name can be syntactically plausible while still being outside the public contract.
84
+
85
+ Choose by role:
86
+
87
+ | Intent | Prefer | Avoid |
88
+ | ------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------- |
89
+ | Page or component surface | documented `bg-*` or `bg-surface-*` class | `bg-white`, `bg-neutral-100`, `bg-[#fff]` |
90
+ | Text content or status | documented `text-*` class | `text-red-600`, `text-[var(--text-critical)]` |
91
+ | Icon colour | documented `text-icon-*`, `fill-icon-*`, or `stroke-icon-*` class | a palette class or raw SVG colour |
92
+ | Border colour | documented `border-stroke-*` class plus consumer-owned border width/style | `border-gray-300`, raw colour, unrelated text token |
93
+ | Ring or outline colour | report a missing public utility; prefer an existing component focus treatment | inferred `ring-stroke-*` or `outline-stroke-*` class |
94
+ | Chart series | documented `fill-chart-*` or `stroke-chart-*` class | inferred `text-chart-*` or an arbitrary palette sequence |
95
+
96
+ Common semantic families include:
97
+
98
+ - surfaces and fills: default, muted, inverse, transparent, status, emphasis, and brand roles;
99
+ - content: default, secondary, muted, disabled, inverse, link, status, emphasis, and brand roles;
100
+ - icons: default, secondary, disabled, inverse, status, emphasis, and brand roles;
101
+ - border colours: `border-stroke-*` roles for default, secondary, input, tertiary, disabled, inverse, focus, status, emphasis, and brand;
102
+ - charts: numbered `fill-chart-*` and `stroke-chart-*` roles.
103
+
104
+ The current public manifest does not expose ring-colour or outline-colour classes. Treat that as a design-system gap when a component's existing focus treatment is insufficient; do not translate `--border-focus` into an invented ring or outline utility.
105
+
106
+ Use status roles only for their meaning. Do not use `critical` merely because it happens to be red or `success` merely because it happens to be green. Use brand roles for branded emphasis rather than as general-purpose decoration.
107
+
108
+ ## Distinguish semantic classes from Tailwind internals
109
+
110
+ Write the concise semantic class exposed by the package:
111
+
112
+ ```tsx
113
+ <div className="bg-surface-success text-success border-stroke-success" />
114
+ ```
115
+
116
+ Do not spell the same intent through an arbitrary value or adapter variable:
117
+
118
+ ```tsx
119
+ <div className="bg-[var(--bg-surface-success)] text-[--text-success]" />
120
+ ```
121
+
122
+ The consuming application may use its own layout, responsive, and non-colour utilities. Treat `--color-*` aliases and incidental Tailwind output found in package CSS as implementation details, not public tokens.
123
+
124
+ ## Handle missing roles
125
+
126
+ Stop and report a design-system gap when no documented role accurately expresses the intent. Include:
127
+
128
+ 1. the UI purpose and interaction state;
129
+ 2. why existing roles are semantically wrong;
130
+ 3. a proposed reusable role name and affected CSS property;
131
+ 4. whether both light and dark values are needed;
132
+ 5. components or consumers likely to share the role.
133
+
134
+ Do not hide the gap with a one-off literal, a primitive palette class, or a misleading semantic token.