@uselets/ui 0.6.0 → 1.0.0

package/dist/skills/uselets-ui/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: uselets-ui
+description: Use @uselets/ui in apps: install it, configure themes, choose public imports/components, and inspect the installed package API.
+---
+
+# @uselets/ui
+
+## Overview
+
+Use this skill as portable documentation for projects that consume `@uselets/ui` from npm.
+It should help with installation, styling setup, public imports, component selection, and implementation using the package API that exists in the current app.
+
+To set up a consumer project after installing `@uselets/ui`, run `bun uselets init` from that project root. To install or update only this skill, run `bun uselets skill`. The skill command replaces the Codex and Claude Code copies with the version bundled in the installed package.
+
+## Workflow
+
+1. Start with the bundled package references.
+   - Read `references/package-guide.md` for setup, entrypoints, wrappers, and usage rules.
+   - Read `references/component-catalog.md` for the module list and exported symbols snapshot.
+2. If `@uselets/ui` is installed in the current project, inspect the installed package for exact local-version details.
+   - Run `node .agents/skills/uselets-ui/scripts/print-public-api.mjs` in Codex projects.
+   - Run `node .claude/skills/uselets-ui/scripts/print-public-api.mjs` in Claude Code projects.
+3. When exact props or type signatures matter, inspect the installed declaration files directly:
+   - `node_modules/@uselets/ui/dist/index.d.ts`
+   - `node_modules/@uselets/ui/dist/components/*.d.ts`
+   - `node_modules/@uselets/ui/dist/hooks/*.d.ts`
+   - `node_modules/@uselets/ui/dist/lib/*.d.ts`
+
+## Answering Rules
+
+- Do not invent components, props, variants, hooks, or helper exports.
+- Prefer the installed package in `node_modules` over the bundled snapshot whenever it exists.
+- Make it explicit when an answer is based on the bundled snapshot rather than the installed package.
+- Recommend only public entrypoints:
+  - `@uselets/ui`
+  - `@uselets/ui/<module>`
+  - `@uselets/ui/hooks/<hook-module>`
+  - `@uselets/ui/utils`
+  - `@uselets/ui/styles.css`
+  - `@uselets/ui/themes/max.css`
+  - `@uselets/ui/themes/gomax.css`
+  - `@uselets/ui/postcss.config`
+- Do not rely on package internals or unpublished source paths.
+
+## Implementation Rules
+
+- Prefer barrel imports for common app usage and readability.
+- Use module subpaths when you want a single module or when the user asks for the exact import path.
+- Use `@uselets/ui/hooks/<hook-module>` for dedicated hook subpaths, not legacy `@uselets/ui/use-*` paths.
+- Recommend importing one theme stylesheet once in the app entrypoint: `@uselets/ui/themes/max.css` for Max apps or `@uselets/ui/themes/gomax.css` for Gomax apps.
+- Treat `@uselets/ui/themes/gomax.css` as the GoMax Figma-backed palette, exposed through the same public color families as the Max theme.
+- Treat `@uselets/ui/styles.css` as a legacy compatibility alias for the Max theme.
+- Recommend `@fontsource-variable/inter` when matching the package typography setup.
+- Recommend `@uselets/ui/postcss.config` when the app needs the package PostCSS preset for Tailwind v4.
+- For tooltip-heavy apps, wrap the app with `TooltipProvider`.
+- For toast usage, mount `Toaster` near the app root before calling `toast(...)`.
+- For package theme helpers, use `ThemeProvider`, `useTheme`, and `ModeToggle` from `@uselets/ui/theme` or the root barrel.
+
+## Quick Routing
+
+- Need installation or global setup: run `bun uselets init` or read `references/package-guide.md`.
+- Need to install or update this skill locally: run `bun uselets skill`.
+- Need to choose a component: read `references/component-catalog.md`.
+- Need the exact local API: run `scripts/print-public-api.mjs`.
+- Need exact props for one module: open the matching `.d.ts` file in `node_modules/@uselets/ui/dist`.
+
+## Example Requests
+
+- "How do I install and configure `@uselets/ui` in my app?"
+- "Which `@uselets/ui` component should I use for this form?"
+- "Show me the correct import for `TooltipProvider` or `Sidebar`."
+- "Inspect the installed version of `@uselets/ui` and tell me what `button` exports."
+- "Build this screen only with `@uselets/ui` components."

package/dist/skills/uselets-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "@uselets/ui"
+  short_description: "Documents the @uselets/ui package for npm consumers."
+  default_prompt: "Use $uselets-ui to inspect the installed @uselets/ui package, choose the right public components and imports, and explain how to use it in this app."

package/dist/skills/uselets-ui/references/component-catalog.md

@@ -0,0 +1,232 @@
+# @uselets/ui component catalog
+
+This file is a portable snapshot of the public package API for `@uselets/ui`.
+
+Snapshot basis:
+
+- package name: `@uselets/ui`
+- snapshot version: `0.5.0`
+
+Use this snapshot to choose modules and imports when the package is not yet installed.
+When `@uselets/ui` is installed locally, confirm exact exports with:
+
+```bash
+node .agents/skills/uselets-ui/scripts/print-public-api.mjs
+# or, in Claude Code projects:
+node .claude/skills/uselets-ui/scripts/print-public-api.mjs
+```
+
+Unless noted otherwise, each module also exports its public `*Props` types from the same import path.
+
+## Core setup and utilities
+
+- `theme`
+  - Import path: `@uselets/ui/theme`
+  - Exports: `ThemeProvider`, `useTheme`, `ModeToggle`
+- `use-mobile`
+  - Import path: `@uselets/ui/hooks/use-mobile`
+  - Exports: `useIsMobile`
+- `use-breakpoint`
+  - Import path: `@uselets/ui/hooks/use-breakpoint`
+  - Exports: `useBreakpoint`, `Breakpoint`, `breakpointValues`
+  - Notes: returns whether the current viewport is at or above a Tailwind default breakpoint (`base`, `sm`, `md`, `lg`, `xl`, `2xl`)
+- `use-breakpoint-value`
+  - Import path: `@uselets/ui/hooks/use-breakpoint-value`
+  - Exports: `useBreakpointValue`, `ResponsiveValueMap`
+  - Notes: accepts a breakpoint value map such as `{ base: 1, md: 2 }` and returns the largest active value
+- `use-disclosure`
+  - Import path: `@uselets/ui/hooks/use-disclosure`
+  - Exports: `useDisclosure`
+- `use-interval`
+  - Import path: `@uselets/ui/hooks/use-interval`
+  - Exports: `useInterval`
+- `use-idle`
+  - Import path: `@uselets/ui/hooks/use-idle`
+  - Exports: `useIdle`
+- `use-document-visibility`
+  - Import path: `@uselets/ui/hooks/use-document-visibility`
+  - Exports: `useDocumentVisibility`
+- `use-local-storage`
+  - Import path: `@uselets/ui/hooks/use-local-storage`
+  - Exports: `useLocalStorage`, `UseLocalStorageOptions`
+  - Notes: returns a `[value, setValue]` tuple, stores values with JSON serialization, and syncs storage changes between browser tabs by default (`sync: true`)
+- `utils`
+  - Import path: `@uselets/ui/utils`
+  - Exports: `cn`, `randomId`
+- `color`
+  - Import path: `@uselets/ui/lib/color`
+  - Exports: `uiColors`, `UIColor`, `selectionControlColorVariants`
+  - Notes: canonical public color list used by `Button`, `Toggle`, `Checkbox`, `RadioGroupItem`, and `Switch`; `ButtonColor` is a compatibility alias for `UIColor`; `selectionControlColorVariants` is an internal styling map for checked selection controls
+- `sonner`
+  - Import path: `@uselets/ui/sonner`
+  - Exports: `Toaster`, `toast`
+- `tooltip`
+  - Import path: `@uselets/ui/tooltip`
+  - Exports: `TooltipProvider`, `Tooltip`, `TooltipTrigger`, `TooltipContent`
+
+## Typography
+
+- `anchor`
+  - Exports: `Anchor`, `anchorVariants`
+  - Notes: link primitive with text size, underline behavior variants, and `asChild`
+- `code`
+  - Exports: `Code`
+  - Notes: inline code primitive rendered as `<code>`
+- `heading`
+  - Exports: `Heading`, `headingVariants`
+  - Notes: heading primitive with `size` scale and `asChild`
+- `list`
+  - Exports: `List`, `ListItem`, `ListIcon`, `listVariants`
+  - Notes: supports `unordered` and `ordered` types, text size, item spacing, and icon marker replacement
+- `text`
+  - Exports: `Text`, `textVariants`
+  - Notes: text primitive with `size` scale and `asChild`
+
+## Actions and feedback
+
+- `alert`
+  - Exports: `Alert`, `AlertAction`, `AlertDescription`, `AlertTitle`
+  - Notes: alert surface with `default` and `destructive` variants
+- `alert-dialog`
+  - Exports: `AlertDialog`, `AlertDialogAction`, `AlertDialogCancel`, `AlertDialogContent`, `AlertDialogDescription`, `AlertDialogFooter`, `AlertDialogHeader`, `AlertDialogMedia`, `AlertDialogOverlay`, `AlertDialogPortal`, `AlertDialogTitle`, `AlertDialogTrigger`
+  - Notes: confirmation dialog composition
+- `badge`
+  - Exports: `Badge`, `badgeVariants`
+- `button`
+  - Exports: `Button`, `buttonVariants`
+  - Notes: action button with `solid`, `outline`, `subtle`, `ghost`, and `link` variants, `color: UIColor` (`primary` default), sizes from `xs` through `xl` plus icon sizes through `icon-xl`, and `loading`
+- `button-group`
+  - Exports: `ButtonGroup`, `ButtonGroupSeparator`, `ButtonGroupText`, `buttonGroupVariants`
+- `empty`
+  - Exports: `Empty`, `EmptyContent`, `EmptyDescription`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`
+- `progress`
+  - Exports: `Progress`
+- `skeleton`
+  - Exports: `Skeleton`
+- `spinner`
+  - Exports: `Spinner`, `spinnerVariants`
+
+## Forms and input composition
+
+- `field`
+  - Exports: `Field`, `FieldContent`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldLabel`, `FieldLegend`, `FieldSeparator`, `FieldSet`, `FieldTitle`
+  - Notes: form layout and validation helpers
+- `grid`
+  - Exports: `Grid`, `GridItem`
+  - Notes: 12-column CSS grid by default. `Grid` supports spacing props plus direct `templateRows` and `templateColumns`; `GridItem` defaults to `colSpan={12}` and supports numeric `colSpan` and `rowSpan`. Use `useBreakpointValue` when these values need to change by breakpoint.
+- `simple-grid`
+  - Exports: `SimpleGrid`
+  - Notes: simple grid with `cols`, `gap`, `rowGap`, and `columnGap`. `cols` accepts a number; spacing uses the `xs` to `xl` scale. Use `useBreakpointValue` when column count needs responsive values.
+- `visibility`
+  - Exports: `HiddenFrom`, `VisibleFrom`
+  - Notes: breakpoint visibility wrappers. `HiddenFrom breakpoint="md"` hides at `md` and above; `VisibleFrom breakpoint="md"` shows at `md` and above.
+- `input`
+  - Exports: `Input`
+- `textarea`
+  - Exports: `Textarea`
+- `input-group`
+  - Exports: `InputGroup`, `InputGroupAddon`, `InputGroupButton`, `InputGroupInput`, `InputGroupText`, `InputGroupTextarea`
+  - Notes: compose controls with prefixes, suffixes, or inline actions
+- `input-otp`
+  - Exports: `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot`, `REGEXP_ONLY_CHARS`, `REGEXP_ONLY_DIGITS`, `REGEXP_ONLY_DIGITS_AND_CHARS`
+- `checkbox`
+  - Exports: `Checkbox`
+  - Notes: supports `size: 'sm' | 'md' | 'lg'`, `color: UIColor` (default `primary`), `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; composed label text follows checkbox size (`sm` 12px, `md` 14px, `lg` 20px)
+- `switch`
+  - Exports: `Switch`
+  - Notes: supports `size: 'sm' | 'md' | 'lg'`, `color: UIColor` (default `green`), `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; `color` controls the checked track and indicator color only; track size is `sm` 34x16px, `md` 42x20px, and `lg` 48x22px; the thumb and internal indicator scale with the switch; composed label text follows switch size (`sm` 12px, `md` 14px, `lg` 20px)
+- `radio-group`
+  - Exports: `RadioGroup`, `RadioGroupItem`
+  - Notes: `RadioGroup` supports `color: UIColor` (default `primary`) for the group; `RadioGroupItem` supports `size: 'sm' | 'md' | 'lg'`, optional `color: UIColor` item overrides, `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; composed label text follows item size (`sm` 12px, `md` 14px, `lg` 20px)
+- `select`
+  - Exports: `Select`, `SelectContent`, `SelectGroup`, `SelectItem`, `SelectLabel`, `SelectScrollDownButton`, `SelectScrollUpButton`, `SelectSeparator`, `SelectTrigger`, `SelectValue`
+- `native-select`
+  - Exports: `NativeSelect`, `NativeSelectOptGroup`, `NativeSelectOption`
+- `combobox`
+  - Exports: `Combobox`, `ComboboxInput`, `ComboboxContent`, `ComboboxList`, `ComboboxItem`, `ComboboxGroup`, `ComboboxLabel`, `ComboboxCollection`, `ComboboxClear`, `ComboboxEmpty`, `ComboboxSeparator`, `ComboboxChips`, `ComboboxChip`, `ComboboxChipsInput`, `ComboboxTrigger`, `ComboboxValue`, `useComboboxAnchor`
+  - Notes: `ComboboxInput` supports `icon?: React.ReactNode`, `triggerIcon?: React.ReactNode`, `showTrigger?: boolean`, and `showClear?: boolean`; the trigger icon defaults to `IconSelector`
+- `dropzone`
+  - Exports: `Dropzone`, `DropzoneArea`, `DropzoneDescription`, `DropzoneFileList`, `DropzoneFileListItem`, `DropzoneFileMessage`, `DropzoneMessage`, `DropzoneRemoveFile`, `DropzoneRetryFile`, `DropzoneTrigger`, `InfiniteProgress`, `useDropzone`
+  - Notes: upload composition with validation, retry handling, status list UI, and optional `shiftOnMaxFiles`
+- `calendar`
+  - Exports: `Calendar`, `CalendarDayButton`
+  - Notes: also exports the `DateRange` type; weekends render with destructive text, week numbers are low-emphasis, and selected single/range endpoints use the `primary` palette with a subtle primary range fill
+- `date-range-picker`
+  - Exports: `DateRangePicker`, `DateRangePickerTrigger`, `DateRangePickerValue`, `DateRangePickerContent`, `DateRangePickerPresets`, `DateRangePickerPreset`, `DateRangePickerCalendar`, `DateRangePickerDateFields`, `DateRangePickerActions`, `DateRangePickerApply`, `DateRangePickerReset`
+  - Notes: compound popover picker using `Calendar` range mode with two months; draft changes from fixed presets, relative-day inputs, date inputs, and calendar stay synchronized until apply; reset and applied clear emit `null` through `onValueChange`; preset buttons show selected state when the draft range matches by calendar day
+- `slider`
+  - Exports: `Slider`
+- `label`
+  - Exports: `Label`
+- `toggle`
+  - Exports: `Toggle`, `toggleVariants`
+  - Notes: supports `color: UIColor` using the same color variants as `Button`
+- `toggle-group`
+  - Exports: `ToggleGroup`, `ToggleGroupItem`
+
+## Overlays and floating UI
+
+- `dialog`
+  - Exports: `Dialog`, `DialogClose`, `DialogContent`, `DialogDescription`, `DialogFooter`, `DialogHeader`, `DialogOverlay`, `DialogPortal`, `DialogTitle`, `DialogTrigger`
+- `drawer`
+  - Exports: `Drawer`, `DrawerClose`, `DrawerContent`, `DrawerDescription`, `DrawerFooter`, `DrawerHeader`, `DrawerOverlay`, `DrawerPortal`, `DrawerTitle`, `DrawerTrigger`
+- `popover`
+  - Exports: `Popover`, `PopoverAnchor`, `PopoverContent`, `PopoverDescription`, `PopoverHeader`, `PopoverTitle`, `PopoverTrigger`
+- `hover-card`
+  - Exports: `HoverCard`, `HoverCardTrigger`, `HoverCardContent`
+- `dropdown-menu`
+  - Exports: `DropdownMenu`, `DropdownMenuCheckboxItem`, `DropdownMenuContent`, `DropdownMenuGroup`, `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuPortal`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubContent`, `DropdownMenuSubTrigger`, `DropdownMenuTrigger`
+
+## Navigation
+
+- `breadcrumb`
+  - Exports: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`
+- `command`
+  - Exports: `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandShortcut`, `CommandSeparator`
+- `navigation-menu`
+  - Exports: `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuContent`, `NavigationMenuTrigger`, `NavigationMenuLink`, `NavigationMenuIndicator`, `NavigationMenuViewport`, `navigationMenuTriggerStyle`
+- `pagination`
+  - Exports: `Pagination`, `PaginationContent`, `PaginationEllipsis`, `PaginationItem`, `PaginationLink`, `PaginationNext`, `PaginationPrevious`
+- `sidebar`
+  - Exports: `Sidebar`, `SidebarContent`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupAction`, `SidebarGroupContent`, `SidebarGroupLabel`, `SidebarHeader`, `SidebarInput`, `SidebarInset`, `SidebarMenu`, `SidebarMenuAction`, `SidebarMenuBadge`, `SidebarMenuButton`, `SidebarMenuItem`, `SidebarMenuSkeleton`, `SidebarMenuSub`, `SidebarMenuSubButton`, `SidebarMenuSubItem`, `SidebarProvider`, `SidebarRail`, `SidebarSeparator`, `SidebarTrigger`, `useSidebar`
+- `tabs`
+  - Exports: `Tabs`, `TabsContent`, `TabsList`, `tabsListVariants`, `TabsTrigger`
+  - Notes: `TabsList.variant` supports `line` and `enclosed`, defaults to `line`, accepts `grow?: boolean` for equal-width horizontal tabs, and uses the `primary` color for the active line indicator
+
+## Layout and display
+
+- `accordion`
+  - Exports: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
+- `avatar`
+  - Exports: `Avatar`, `AvatarBadge`, `AvatarFallback`, `AvatarGroup`, `AvatarGroupCount`, `AvatarImage`
+- `card`
+  - Exports: `Card`, `CardAction`, `CardContent`, `CardDescription`, `CardFooter`, `CardHeader`, `CardTitle`
+- `carousel`
+  - Exports: `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`, `useCarousel`
+- `center`
+  - Exports: `Center`, `centerVariants`
+- `chart`
+  - Exports: `Bar`, `BarChart`, `CartesianGrid`, `XAxis`, `ChartContainer`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `ChartTooltip`, `ChartTooltipContent`
+- `collapsible`
+  - Exports: `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`
+- `container`
+  - Exports: `Container`, `containerVariants`
+- `group`
+  - Exports: `Group`, `groupVariants`
+  - Notes: supports `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` and `wrap`
+- `kbd`
+  - Exports: `Kbd`, `KbdGroup`
+- `resizable`
+  - Exports: `ResizableHandle`, `ResizablePanel`, `ResizablePanelGroup`
+- `scroll-area`
+  - Exports: `ScrollArea`, `ScrollBar`
+- `separator`
+  - Exports: `Separator`
+- `stack`
+  - Exports: `Stack`, `stackVariants`
+  - Notes: supports `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'`
+- `table`
+  - Exports: `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption`
+- `timeline`
+  - Exports: `Timeline`, `TimelineConnector`, `TimelineContent`, `TimelineDescription`, `TimelineEmpty`, `TimelineHeader`, `TimelineIcon`, `TimelineItem`, `TimelineTime`, `TimelineTitle`, `timelineVariants`
+  - Notes: timeline flow with root `size`, inherited `iconSize`, item `status`, optional loading/error states, and semantic icon or connector colors

package/dist/skills/uselets-ui/references/package-guide.md

@@ -0,0 +1,299 @@
+# @uselets/ui package guide
+
+## Purpose
+
+Use this reference in any app that consumes `@uselets/ui` from npm.
+It describes the public entrypoints, setup, and package-level usage patterns.
+
+## Source priority
+
+Use sources in this order:
+
+1. Installed package in the current workspace:
+   - `node_modules/@uselets/ui/package.json`
+   - `node_modules/@uselets/ui/README.md`
+   - `node_modules/@uselets/ui/dist/**/*.d.ts`
+2. This skill's bundled references:
+   - `references/package-guide.md`
+   - `references/component-catalog.md`
+
+If the package is not installed yet, use the bundled references as a snapshot and verify against the installed package after installation.
+
+## Requirements
+
+- React `>=19`
+- React DOM `>=19`
+- Tailwind CSS 4
+
+## Installation
+
+Use the project's package manager:
+
+```bash
+npm install @uselets/ui
+```
+
+```bash
+pnpm add @uselets/ui
+```
+
+```bash
+yarn add @uselets/ui
+```
+
+```bash
+bun add @uselets/ui
+```
+
+## Project setup command
+
+Run the package setup command from the project root to install dependencies, configure PostCSS, and prepare the global CSS imports:
+
+```bash
+bun uselets init
+```
+
+The command asks for the package theme, defaults the global CSS path to `src/styles/globals.css`, creates that CSS file when missing, preserves an existing `postcss.config.mjs`, and asks whether to install the agent skill.
+
+For non-interactive setup, provide explicit options:
+
+```bash
+bun uselets init --theme max --css src/styles/globals.css --no-install-skill
+```
+
+## Agent skill installation
+
+After installing `@uselets/ui`, projects can install or update this bundled agent skill:
+
+```bash
+bun uselets skill
+```
+
+By default, the command removes any existing skill copy in the current project and copies the current package version into place for both supported agent layouts:
+
+- `.agents/skills/uselets-ui` for Codex
+- `.claude/skills/uselets-ui` for Claude Code
+
+Use `bun uselets skill --agent codex` or `bun uselets skill --agent claude` to install only one target.
+
+## Public entrypoints
+
+`@uselets/ui` exposes these public entrypoint patterns:
+
+- `@uselets/ui`
+  - root barrel for components, hooks, and utilities re-exported by the package
+- `@uselets/ui/<module>`
+  - subpath import for components such as `button`, `dialog`, or `tooltip`
+- `@uselets/ui/hooks/<hook-module>`
+  - subpath import for dedicated hooks such as `use-mobile`, `use-disclosure`, or `use-local-storage`
+- `@uselets/ui/utils`
+  - utility helpers such as `cn` and `randomId`
+- `@uselets/ui/lib/color`
+  - shared UI color list and type: `uiColors`, `UIColor`
+- `@uselets/ui/styles.css`
+  - legacy compatibility stylesheet equivalent to the Max theme
+- `@uselets/ui/themes/max.css`
+  - Max theme tokens and component styles
+- `@uselets/ui/themes/gomax.css`
+  - GoMax theme tokens and component styles backed by the GoMax Figma palette
+- `@uselets/ui/postcss.config`
+  - reusable PostCSS preset for Tailwind v4 setups
+
+## Base setup
+
+Import one package theme once near the app entrypoint:
+
+```tsx
+import '@uselets/ui/themes/max.css'
+import '@fontsource-variable/inter'
+```
+
+For GoMax apps, import `@uselets/ui/themes/gomax.css` instead. The legacy `@uselets/ui/styles.css` entrypoint remains available as a Max-theme alias.
+
+If the app needs Tailwind v4 PostCSS setup, reuse the package preset:
+
+```js
+export { default } from '@uselets/ui/postcss.config'
+```
+
+Make sure Tailwind itself is imported in the app stylesheet:
+
+```css
+@import 'tailwindcss';
+```
+
+## Typography scale
+
+The Max theme uses Inter as `font-sans` and overrides Tailwind CSS text size utilities from `text-xs` through
+`text-6xl`. Each size includes a default line height equal to `font-size * 1.5`.
+
+| Utility | Font size | Line height |
+| --- | --- | --- |
+| `text-xs` | `0.75rem` / `12px` | `1.125rem` / `18px` |
+| `text-sm` | `0.875rem` / `14px` | `1.3125rem` / `21px` |
+| `text-base` | `1rem` / `16px` | `1.5rem` / `24px` |
+| `text-lg` | `1.125rem` / `18px` | `1.6875rem` / `27px` |
+| `text-xl` | `1.25rem` / `20px` | `1.875rem` / `30px` |
+| `text-2xl` | `1.5rem` / `24px` | `2.25rem` / `36px` |
+| `text-3xl` | `1.875rem` / `30px` | `2.8125rem` / `45px` |
+| `text-4xl` | `2.25rem` / `36px` | `3.375rem` / `54px` |
+| `text-5xl` | `3rem` / `48px` | `4.5rem` / `72px` |
+| `text-6xl` | `3.75rem` / `60px` | `5.625rem` / `90px` |
+
+## Import patterns
+
+Use these patterns:
+
+```tsx
+import { Alert, Button, cn, randomId } from '@uselets/ui'
+import type { UIColor } from '@uselets/ui'
+import { Dialog } from '@uselets/ui/dialog'
+import { useIsMobile } from '@uselets/ui/hooks/use-mobile'
+import { useDisclosure } from '@uselets/ui/hooks/use-disclosure'
+import { useLocalStorage } from '@uselets/ui/hooks/use-local-storage'
+import { Toaster, toast } from '@uselets/ui/sonner'
+```
+
+Guidance:
+
+- Prefer `@uselets/ui` for common imports.
+- Use `@uselets/ui/<module>` when the user asks for the exact module path or when documenting one specific module.
+- Use `@uselets/ui/hooks/<hook-module>` for dedicated hook subpaths.
+- Do not invent undocumented subpaths.
+
+Public hook subpaths currently include `hooks/use-mobile`, `hooks/use-disclosure`, `hooks/use-interval`, `hooks/use-idle`, `hooks/use-document-visibility`, and `hooks/use-local-storage`. Legacy `@uselets/ui/use-*` paths are not public entrypoints. Utility helpers are available from `@uselets/ui/utils`, and shared UI color helpers are available from the root barrel or `@uselets/ui/lib/color`.
+
+`useLocalStorage` uses an options object and returns a tuple like `useState`:
+
+```tsx
+const [settings, setSettings] = useLocalStorage('settings', {
+  defaultValue: { compact: false }
+})
+
+const [draft, setDraft] = useLocalStorage('draft', {
+  defaultValue: '',
+  sync: false
+})
+```
+
+It stores values with `JSON.stringify`, reads with `JSON.parse` with string fallback, and synchronizes changes from other browser tabs unless `sync` is set to `false`.
+
+## Package-wide wrappers and providers
+
+Use these package-level helpers when relevant:
+
+- `TooltipProvider`
+  - Wrap the app or feature root when using tooltips broadly.
+- `Toaster`
+  - Mount near the app root before calling `toast(...)`.
+- `ThemeProvider`
+  - Provide package theme state for `useTheme` and `ModeToggle`.
+
+Examples:
+
+```tsx
+import { TooltipProvider } from '@uselets/ui/tooltip'
+
+export function AppRoot({ children }: { children: React.ReactNode }) {
+  return <TooltipProvider delayDuration={200}>{children}</TooltipProvider>
+}
+```
+
+```tsx
+import { Toaster, toast } from '@uselets/ui/sonner'
+
+export function App() {
+  return (
+    <>
+      <button onClick={() => toast.success('Saved')}>Notify</button>
+      <Toaster />
+    </>
+  )
+}
+```
+
+```tsx
+import { ModeToggle, ThemeProvider } from '@uselets/ui/theme'
+
+export function AppRoot({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider defaultTheme="system">
+      <ModeToggle />
+      {children}
+    </ThemeProvider>
+  )
+}
+```
+
+## Theme tokens
+
+The package stylesheet exposes these palette families:
+
+- `primary`
+- `brand`
+- `gray`
+- `zinc`
+- `red`
+- `yellow`
+- `blue`
+- `indigo`
+- `pink`
+- `green`
+
+The same palette family names are exported as `uiColors` and `UIColor`. `Button`, `Toggle`, `Checkbox`, `RadioGroupItem`, and `Switch` use `UIColor` for color props. `ButtonColor` remains available as a compatibility alias, but new public APIs should use `UIColor`.
+
+Each palette family is exposed as:
+
+- CSS variables such as `--primary-500`, `--brand-500`, and `--zinc-900`
+- Tailwind v4 utilities such as `bg-primary-500`, `text-zinc-900`, `border-red-300`
+
+Primary semantic tokens:
+
+- surfaces and text: `background`, `foreground`, `card`, `popover`
+- actions and emphasis: `primary`, `secondary`, `accent`, `destructive`
+- controls: `border`, `input`, `ring`
+- sidebar: `sidebar`, `sidebar-primary`, `sidebar-accent`, `sidebar-border`, `sidebar-ring`
+- charts: `chart-1` through `chart-5`
+
+Additional tokens:
+
+- `--destructive-foreground`
+- `text-destructive-foreground`
+- `--gradient-primary`
+
+The `Button` component can apply those palette families directly through `color: UIColor`, with `primary` as the default. Its public variants are `solid`, `outline`, `subtle`, `ghost`, and `link`, with `solid` as the default. Its public sizes are `xs`, `sm`, `md`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, and `icon-xl`; `loading` shows a centered spinner, keeps native button content invisible to preserve size, and disables the button without dimming it.
+
+The `Checkbox` component can be used as a bare checkbox or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `primary` as the default color. When `label` is provided, it composes the package `Label`, accepts `labelProps` for that label, and generates an accessible `id`/`htmlFor` pair when no `id` prop is passed. Composed label text follows checkbox size: `sm` 12px, `md` 14px, and `lg` 20px.
+
+The `Switch` component can be used as a bare switch or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `green` as the default color. The `color` prop controls only the checked track and indicator color; unchecked remains neutral. Track size is `sm` 34x16px, `md` 42x20px, and `lg` 48x22px. The thumb and its internal indicator scale with the selected size. Composed label text follows switch size: `sm` 12px, `md` 14px, and `lg` 20px.
+
+The `TabsList` component supports `variant: 'line' | 'enclosed'`, with `line` as the default, and `grow?: boolean` for equal-width horizontal tabs. The `line` variant keeps a neutral border line across tabs and uses the `primary` color for the active indicator; use `enclosed` for the filled container treatment.
+
+The `RadioGroup` component supports `color: UIColor`, with `primary` as the default group color. `RadioGroupItem` can be used as a bare radio item inside `RadioGroup` or with `label?: React.ReactNode`; it supports `size: 'sm' | 'md' | 'lg'` and optional `color: UIColor` item overrides. Composed label text follows item size: `sm` 12px, `md` 14px, and `lg` 20px.
+
+The `DateRangePicker` component is a compound popover date range picker built on `Calendar` range mode. Use `DateRange | null` for controlled values; applying an empty draft or resetting emits `null` through `onValueChange`. Fixed presets, relative-day inputs, date inputs, and the calendar all edit the same draft, and `DateRangePickerPreset` displays a selected state when its range matches the current draft by calendar day.
+
+## Component selection
+
+Choose components by intent:
+
+- actions and status:
+  - `Button`, `Badge`, `Alert`, `Progress`, `Skeleton`, `Spinner`, `toast`
+- forms and inputs:
+  - `Field`, `Input`, `Textarea`, `Checkbox`, `Switch`, `RadioGroup`, `Select`, `NativeSelect`, `Combobox`, `Dropzone`, `InputGroup`, `InputOTP`, `Slider`, `DateRangePicker`
+- overlays and floating UI:
+  - `Dialog`, `Drawer`, `Popover`, `Tooltip`, `HoverCard`, `AlertDialog`
+- navigation:
+  - `Breadcrumb`, `NavigationMenu`, `Pagination`, `Sidebar`, `Tabs`, `DropdownMenu`, `Command`
+- typography:
+  - `Anchor`, `Code`, `Heading`, `List`, `Text`
+- layout and display:
+  - `Card`, `Accordion`, `Collapsible`, `Container`, `Group`, `Stack`, `Center`, `Separator`, `ScrollArea`, `Resizable`, `Table`, `Timeline`, `Chart`, `Carousel`, `Avatar`, `Empty`, `Kbd`
+
+## Inspection workflow
+
+When the local version matters:
+
+1. Run the installed `scripts/print-public-api.mjs` from this skill folder.
+2. Open the target declaration file under `node_modules/@uselets/ui/dist`
+3. Confirm the exact exported names and prop types before answering