@leitware/composables 0.2.0 → 1.0.0

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.
@@ -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 (71): `AccordionItemData`, `AccordionProps`, `AlertDialogProps`, `AlertProps`, `AlertType`, `AvatarProps`, `BadgeProps`, `BreadcrumbItemData`, `BreadcrumbProps`, `BubbleProps`, `ButtonProps`, `CardProps`, `CarouselProps`, `CollapsibleProps`, `ComboboxOption`, `ComboboxProps`, `DateOfBirthValue`, `DialogProps`, `DirectionProviderProps`, `DropdownMenuItemData`, `DropdownMenuProps`, `EmptyProps`, `EmptyTableStateProps`, `FormCalendarPopoverProps`, `FormCheckboxProps`, `FormComboboxOption`, `FormComboboxProps`, `FormDateOfBirthProps`, `FormDropZoneProps`, `FormInputGroupInputProps`, `FormInputGroupProps`, `FormInputProps`, `FormMultiComboboxOption`, `FormMultiComboboxProps`, `FormMultiDropZoneProps`, `FormRadioGroupOption`, `FormRadioGroupProps`, `FormSelectOption`, `FormSelectProps`, `FormSliderProps`, `FormSwitchProps`, `FormTextareaProps`, `GridOverlayProps`, `HoverCardProps`, `ItemProps`, `KbdGroupProps`, `KbdProps`, `ListItemData`, `ListProps`, `ListVariant`, `MarkerProps`, `NativeSelectOptionData`, `NativeSelectProps`, `NumericInputOptions`, `NumericMode`, `PaginationProps`, `PopoverProps`, `ProgressProps`, `ScrollAreaProps`, `SelectOption`, `SelectProps`, `SheetProps`, `SkeletonProps`, `TabItem`, `TextDirection`, `ToggleGroupOption`, `ToggleGroupProps`, `ToggleProps`, `TooltipProps`, `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.
@@ -0,0 +1,131 @@
1
+ # Public semantic utility manifest
2
+
3
+ <!-- This file is generated by scripts/generate-css.ts. Do not edit it directly. -->
4
+
5
+ This is the exact allowlist of framework-independent semantic colour classes shipped by Composables. It is generated from `publicSemanticUtilities` in `src/styles/tokens/registry.ts`; do not infer additional token/property combinations.
6
+
7
+ | Class | Category | Semantic token | Declaration |
8
+ | --------------------------- | -------- | ----------------------------- | ---------------------------------------------------- |
9
+ | `bg-default` | bg | `--bg-default` | `background-color: var(--bg-default)` |
10
+ | `bg-inverse` | bg | `--bg-inverse` | `background-color: var(--bg-inverse)` |
11
+ | `bg-muted` | bg | `--bg-muted` | `background-color: var(--bg-muted)` |
12
+ | `bg-surface-default` | bg | `--bg-surface-default` | `background-color: var(--bg-surface-default)` |
13
+ | `bg-surface-popover` | bg | `--bg-surface-popover` | `background-color: var(--bg-surface-popover)` |
14
+ | `bg-surface-accent` | bg | `--bg-surface-accent` | `background-color: var(--bg-surface-accent)` |
15
+ | `bg-surface-info` | bg | `--bg-surface-info` | `background-color: var(--bg-surface-info)` |
16
+ | `bg-surface-success` | bg | `--bg-surface-success` | `background-color: var(--bg-surface-success)` |
17
+ | `bg-surface-warning` | bg | `--bg-surface-warning` | `background-color: var(--bg-surface-warning)` |
18
+ | `bg-surface-critical` | bg | `--bg-surface-critical` | `background-color: var(--bg-surface-critical)` |
19
+ | `bg-surface-emphasis` | bg | `--bg-surface-emphasis` | `background-color: var(--bg-surface-emphasis)` |
20
+ | `bg-surface-inverse` | bg | `--bg-surface-inverse` | `background-color: var(--bg-surface-inverse)` |
21
+ | `bg-surface-transparent` | bg | `--bg-surface-transparent` | `background-color: var(--bg-surface-transparent)` |
22
+ | `bg-overlay` | bg | `--bg-overlay` | `background-color: var(--bg-overlay)` |
23
+ | `bg-surface-brand` | bg | `--bg-surface-brand` | `background-color: var(--bg-surface-brand)` |
24
+ | `bg-surface-brand-2` | bg | `--bg-surface-brand-2` | `background-color: var(--bg-surface-brand-2)` |
25
+ | `bg-surface-brand-3` | bg | `--bg-surface-brand-3` | `background-color: var(--bg-surface-brand-3)` |
26
+ | `bg-surface-brand-4` | bg | `--bg-surface-brand-4` | `background-color: var(--bg-surface-brand-4)` |
27
+ | `bg-surface-brand-5` | bg | `--bg-surface-brand-5` | `background-color: var(--bg-surface-brand-5)` |
28
+ | `bg-surface-hover` | bg | `--bg-surface-hover` | `background-color: var(--bg-surface-hover)` |
29
+ | `bg-fill-default` | bg | `--bg-fill-default` | `background-color: var(--bg-fill-default)` |
30
+ | `bg-fill-primary` | bg | `--bg-fill-primary` | `background-color: var(--bg-fill-primary)` |
31
+ | `bg-fill-brand` | bg | `--bg-fill-brand` | `background-color: var(--bg-fill-brand)` |
32
+ | `bg-fill-brand-2` | bg | `--bg-fill-brand-2` | `background-color: var(--bg-fill-brand-2)` |
33
+ | `bg-fill-brand-3` | bg | `--bg-fill-brand-3` | `background-color: var(--bg-fill-brand-3)` |
34
+ | `bg-fill-brand-4` | bg | `--bg-fill-brand-4` | `background-color: var(--bg-fill-brand-4)` |
35
+ | `bg-fill-brand-5` | bg | `--bg-fill-brand-5` | `background-color: var(--bg-fill-brand-5)` |
36
+ | `bg-fill-info` | bg | `--bg-fill-info` | `background-color: var(--bg-fill-info)` |
37
+ | `bg-fill-success` | bg | `--bg-fill-success` | `background-color: var(--bg-fill-success)` |
38
+ | `bg-fill-warning` | bg | `--bg-fill-warning` | `background-color: var(--bg-fill-warning)` |
39
+ | `bg-fill-critical` | bg | `--bg-fill-critical` | `background-color: var(--bg-fill-critical)` |
40
+ | `bg-fill-emphasis` | bg | `--bg-fill-emphasis` | `background-color: var(--bg-fill-emphasis)` |
41
+ | `bg-fill-transparent` | bg | `--bg-fill-transparent` | `background-color: var(--bg-fill-transparent)` |
42
+ | `bg-fill-secondary` | bg | `--bg-fill-secondary` | `background-color: var(--bg-fill-secondary)` |
43
+ | `bg-fill-secondary-inverse` | bg | `--bg-fill-secondary-inverse` | `background-color: var(--bg-fill-secondary-inverse)` |
44
+ | `text-default` | text | `--text-default` | `color: var(--text-default)` |
45
+ | `text-content-secondary` | text | `--text-secondary` | `color: var(--text-secondary)` |
46
+ | `text-content-muted` | text | `--text-muted` | `color: var(--text-muted)` |
47
+ | `text-disabled` | text | `--text-disabled` | `color: var(--text-disabled)` |
48
+ | `text-inverse` | text | `--text-inverse` | `color: var(--text-inverse)` |
49
+ | `text-on-fill-primary` | text | `--text-on-fill-primary` | `color: var(--text-on-fill-primary)` |
50
+ | `text-on-fill-secondary` | text | `--text-on-fill-secondary` | `color: var(--text-on-fill-secondary)` |
51
+ | `text-on-surface-accent` | text | `--text-on-surface-accent` | `color: var(--text-on-surface-accent)` |
52
+ | `text-info` | text | `--text-info` | `color: var(--text-info)` |
53
+ | `text-success` | text | `--text-success` | `color: var(--text-success)` |
54
+ | `text-warning` | text | `--text-warning` | `color: var(--text-warning)` |
55
+ | `text-critical` | text | `--text-critical` | `color: var(--text-critical)` |
56
+ | `text-emphasis` | text | `--text-emphasis` | `color: var(--text-emphasis)` |
57
+ | `text-brand` | text | `--text-brand` | `color: var(--text-brand)` |
58
+ | `text-brand-2` | text | `--text-brand-2` | `color: var(--text-brand-2)` |
59
+ | `text-brand-3` | text | `--text-brand-3` | `color: var(--text-brand-3)` |
60
+ | `text-brand-4` | text | `--text-brand-4` | `color: var(--text-brand-4)` |
61
+ | `text-brand-5` | text | `--text-brand-5` | `color: var(--text-brand-5)` |
62
+ | `text-link` | text | `--text-link` | `color: var(--text-link)` |
63
+ | `text-icon-default` | icon | `--icon-default` | `color: var(--icon-default)` |
64
+ | `fill-icon-default` | icon | `--icon-default` | `fill: var(--icon-default)` |
65
+ | `stroke-icon-default` | icon | `--icon-default` | `stroke: var(--icon-default)` |
66
+ | `text-icon-secondary` | icon | `--icon-secondary` | `color: var(--icon-secondary)` |
67
+ | `fill-icon-secondary` | icon | `--icon-secondary` | `fill: var(--icon-secondary)` |
68
+ | `stroke-icon-secondary` | icon | `--icon-secondary` | `stroke: var(--icon-secondary)` |
69
+ | `text-icon-disabled` | icon | `--icon-disabled` | `color: var(--icon-disabled)` |
70
+ | `fill-icon-disabled` | icon | `--icon-disabled` | `fill: var(--icon-disabled)` |
71
+ | `stroke-icon-disabled` | icon | `--icon-disabled` | `stroke: var(--icon-disabled)` |
72
+ | `text-icon-inverse` | icon | `--icon-inverse` | `color: var(--icon-inverse)` |
73
+ | `fill-icon-inverse` | icon | `--icon-inverse` | `fill: var(--icon-inverse)` |
74
+ | `stroke-icon-inverse` | icon | `--icon-inverse` | `stroke: var(--icon-inverse)` |
75
+ | `text-icon-info` | icon | `--icon-info` | `color: var(--icon-info)` |
76
+ | `fill-icon-info` | icon | `--icon-info` | `fill: var(--icon-info)` |
77
+ | `stroke-icon-info` | icon | `--icon-info` | `stroke: var(--icon-info)` |
78
+ | `text-icon-success` | icon | `--icon-success` | `color: var(--icon-success)` |
79
+ | `fill-icon-success` | icon | `--icon-success` | `fill: var(--icon-success)` |
80
+ | `stroke-icon-success` | icon | `--icon-success` | `stroke: var(--icon-success)` |
81
+ | `text-icon-warning` | icon | `--icon-warning` | `color: var(--icon-warning)` |
82
+ | `fill-icon-warning` | icon | `--icon-warning` | `fill: var(--icon-warning)` |
83
+ | `stroke-icon-warning` | icon | `--icon-warning` | `stroke: var(--icon-warning)` |
84
+ | `text-icon-critical` | icon | `--icon-critical` | `color: var(--icon-critical)` |
85
+ | `fill-icon-critical` | icon | `--icon-critical` | `fill: var(--icon-critical)` |
86
+ | `stroke-icon-critical` | icon | `--icon-critical` | `stroke: var(--icon-critical)` |
87
+ | `text-icon-emphasis` | icon | `--icon-emphasis` | `color: var(--icon-emphasis)` |
88
+ | `fill-icon-emphasis` | icon | `--icon-emphasis` | `fill: var(--icon-emphasis)` |
89
+ | `stroke-icon-emphasis` | icon | `--icon-emphasis` | `stroke: var(--icon-emphasis)` |
90
+ | `text-icon-brand` | icon | `--icon-brand` | `color: var(--icon-brand)` |
91
+ | `fill-icon-brand` | icon | `--icon-brand` | `fill: var(--icon-brand)` |
92
+ | `stroke-icon-brand` | icon | `--icon-brand` | `stroke: var(--icon-brand)` |
93
+ | `text-icon-brand-2` | icon | `--icon-brand-2` | `color: var(--icon-brand-2)` |
94
+ | `fill-icon-brand-2` | icon | `--icon-brand-2` | `fill: var(--icon-brand-2)` |
95
+ | `stroke-icon-brand-2` | icon | `--icon-brand-2` | `stroke: var(--icon-brand-2)` |
96
+ | `text-icon-brand-3` | icon | `--icon-brand-3` | `color: var(--icon-brand-3)` |
97
+ | `fill-icon-brand-3` | icon | `--icon-brand-3` | `fill: var(--icon-brand-3)` |
98
+ | `stroke-icon-brand-3` | icon | `--icon-brand-3` | `stroke: var(--icon-brand-3)` |
99
+ | `text-icon-brand-4` | icon | `--icon-brand-4` | `color: var(--icon-brand-4)` |
100
+ | `fill-icon-brand-4` | icon | `--icon-brand-4` | `fill: var(--icon-brand-4)` |
101
+ | `stroke-icon-brand-4` | icon | `--icon-brand-4` | `stroke: var(--icon-brand-4)` |
102
+ | `text-icon-brand-5` | icon | `--icon-brand-5` | `color: var(--icon-brand-5)` |
103
+ | `fill-icon-brand-5` | icon | `--icon-brand-5` | `fill: var(--icon-brand-5)` |
104
+ | `stroke-icon-brand-5` | icon | `--icon-brand-5` | `stroke: var(--icon-brand-5)` |
105
+ | `border-stroke-default` | border | `--border-default` | `border-color: var(--border-default)` |
106
+ | `border-stroke-secondary` | border | `--border-secondary` | `border-color: var(--border-secondary)` |
107
+ | `border-stroke-input` | border | `--border-input` | `border-color: var(--border-input)` |
108
+ | `border-stroke-tertiary` | border | `--border-tertiary` | `border-color: var(--border-tertiary)` |
109
+ | `border-stroke-disabled` | border | `--border-disabled` | `border-color: var(--border-disabled)` |
110
+ | `border-stroke-inverse` | border | `--border-inverse` | `border-color: var(--border-inverse)` |
111
+ | `border-stroke-focus` | border | `--border-focus` | `border-color: var(--border-focus)` |
112
+ | `border-stroke-brand` | border | `--border-brand` | `border-color: var(--border-brand)` |
113
+ | `border-stroke-brand-2` | border | `--border-brand-2` | `border-color: var(--border-brand-2)` |
114
+ | `border-stroke-brand-3` | border | `--border-brand-3` | `border-color: var(--border-brand-3)` |
115
+ | `border-stroke-brand-4` | border | `--border-brand-4` | `border-color: var(--border-brand-4)` |
116
+ | `border-stroke-brand-5` | border | `--border-brand-5` | `border-color: var(--border-brand-5)` |
117
+ | `border-stroke-info` | border | `--border-info` | `border-color: var(--border-info)` |
118
+ | `border-stroke-success` | border | `--border-success` | `border-color: var(--border-success)` |
119
+ | `border-stroke-warning` | border | `--border-warning` | `border-color: var(--border-warning)` |
120
+ | `border-stroke-critical` | border | `--border-critical` | `border-color: var(--border-critical)` |
121
+ | `border-stroke-emphasis` | border | `--border-emphasis` | `border-color: var(--border-emphasis)` |
122
+ | `fill-chart-1` | chart | `--chart-1` | `fill: var(--chart-1)` |
123
+ | `stroke-chart-1` | chart | `--chart-1` | `stroke: var(--chart-1)` |
124
+ | `fill-chart-2` | chart | `--chart-2` | `fill: var(--chart-2)` |
125
+ | `stroke-chart-2` | chart | `--chart-2` | `stroke: var(--chart-2)` |
126
+ | `fill-chart-3` | chart | `--chart-3` | `fill: var(--chart-3)` |
127
+ | `stroke-chart-3` | chart | `--chart-3` | `stroke: var(--chart-3)` |
128
+ | `fill-chart-4` | chart | `--chart-4` | `fill: var(--chart-4)` |
129
+ | `stroke-chart-4` | chart | `--chart-4` | `stroke: var(--chart-4)` |
130
+ | `fill-chart-5` | chart | `--chart-5` | `fill: var(--chart-5)` |
131
+ | `stroke-chart-5` | chart | `--chart-5` | `stroke: var(--chart-5)` |
@@ -7,9 +7,12 @@
7
7
 
8
8
  File structure:
9
9
  tokens/palette.css — Primitive color scales (build-time + runtime)
10
- tokens/tailwind-theme.css — Tailwind utility registrations (@theme)
10
+ tokens/tailwind-color-adapter.css — Generated Tailwind color aliases
11
+ tokens/tailwind-theme.css — Non-color Tailwind theme registrations
11
12
  tokens/semantic.css — Semantic role tokens (:root + .dark)
12
13
  tokens/components.css — Component-level tunables
14
+ presets/default.css — The canonical default light/dark preset
15
+ tokens/semantic-utilities.css — Generated public semantic classes
13
16
  tokens/base.css — Global base styles (@layer base)
14
17
  ============================================================================ */
15
18
 
@@ -62,7 +65,10 @@
62
65
 
63
66
  /* ── Token layers ─────────────────────────────────────────────────────── */
64
67
  @import './tokens/palette.css';
68
+ @import './tokens/tailwind-color-adapter.css';
65
69
  @import './tokens/tailwind-theme.css';
66
70
  @import './tokens/semantic.css';
67
71
  @import './tokens/components.css';
72
+ @import './presets/default.css';
73
+ @import './tokens/semantic-utilities.css';
68
74
  @import './tokens/base.css';