Carsxe Design System
Install and use @carsxe/design-system — shadcn components, Button, CSS tokens. Do not run shadcn add in consumer apps.Save as
.cursor/skills/carsxe-design-system/SKILL.md. Copy other files in this skill into the same folder.SKILL.md
markdown
---
name: carsxe-design-system
description: Use @carsxe/design-system as the Carsxe UI kit. Covers shadcn components (Button and others), CSS tokens, install, and theming. Do not run shadcn add in consumer apps. Widget/edit-mode belongs in @carsxe/ui.
---
# Carsxe Design System
Use this skill whenever you build UI with `@carsxe/design-system` — buttons, inputs, dialogs, tokens, or any shadcn primitive in a Carsxe app.
The package name is `@carsxe/design-system`. `@carsxe/ui` is a separate widget package. Do not confuse them.
Ark-inspired advanced controls such as Tour, Tree View, Image Cropper, Color
Picker, and Signature Pad are native Carsxe components. Import them from this
package; do not add Ark UI or Zag to a consumer.
## Install
```bash
bun add @carsxe/design-system
```
```bash
npm install @carsxe/design-system
```
```bash
pnpm add @carsxe/design-system
```
Peer dependencies: `react` and `react-dom`.
## Import components
Prefer the per-component path:
```tsx
import { Button } from "@carsxe/design-system/components/button"
```
The package root also works:
```tsx
import { Button } from "@carsxe/design-system"
```
## Load CSS
If the app already uses Tailwind v4:
```ts
import "@carsxe/design-system/globals.css"
```
Otherwise use the prebuilt stylesheet:
```ts
import "@carsxe/design-system/styles.css"
```
Both of those put the palette on `:root`. If the app has its own palette and
only part of the page should be ours — a header inside an app themed some other
way — take the tokens on their own and scope them instead:
```ts
import "@carsxe/design-system/tokens.css"
```
```tsx
<div className="cx-theme">{/* design system components */}</div>
```
Custom properties inherit, so everything inside that class gets our palette and
the rest of the page keeps its own. `tokens.css` carries no utilities, so the
host maps the variables in its own config — plain hex, no `hsl()`:
```js
colors: { popover: "var(--popover)", accent: "var(--accent)" }
```
Non-colour tokens — shadows, radii — map straight across too:
```js
boxShadow: {
panel: "var(--panel-shadow)"
}
```
## Do not
- Do not run `shadcn add` in the consumer app. Components ship from this package.
- Do not copy component source into the app.
- Do not create wrapper components around design-system primitives.
- Do not add widget or edit-mode behavior to these primitives. That belongs in the consumer (`@carsxe/ui`).
## Customize
Use `variant`, `size`, `className`, and native element props (`value`, `onChange`, `disabled`, and so on). Tokens live on `:root` and `.dark`. `--radius` is `0` (sharp corners). Toggle dark mode by adding the `dark` class on a parent, usually `<html>`.
See `reference.md` in this folder for the component list, import paths, and token names.
reference.md
markdown
# @carsxe/design-system reference
## CSS
| Import | When to use |
| ----------------------------------- | --------------------------------------------------------- |
| `@carsxe/design-system/globals.css` | The app already compiles Tailwind v4 |
| `@carsxe/design-system/styles.css` | The app does not compile Tailwind; use the prebuilt sheet |
Dark mode is activated with a `.dark` class on an ancestor (typically `<html>`).
## Fonts
Loaded by the CSS import:
- Sans / UI: Manrope (`--font-sans`)
- Headings: DM Sans (`--font-heading`)
- Body / inputs: Manrope (`--font-body`)
- Mono / code: DM Mono (`--font-mono`)
## Radius
`--radius` is `0`. Corners are sharp. Circular controls (`Switch`, radio, slider thumbs, progress, avatars) keep `rounded-full`.
Default control height is `40px` (`h-10`).
## Tokens
Light (`:root`) values:
| Token | Value |
| --------------------- | --------- |
| `--primary` | `#065774` |
| `--primary-hover` | `#387990` |
| `--primary-disabled` | `#83BACC` |
| `--foreground` | `#3A3A3A` |
| `--muted-foreground` | `#A8A8A8` |
| `--border` | `#EBEBEB` |
| `--background` | `#F9F9F9` |
| `--success` | `#00A63E` |
| `--destructive` | `#DA373E` |
| `--warning` | `#F79008` |
| `--success-muted` | `#E6F6EC` |
| `--destructive-muted` | `#FDF0F1` |
| `--warning-muted` | `#FEF7E6` |
| `--radius` | `0` |
Also: `--primary-foreground`, `--card`, `--accent`, `--ring`, `--sidebar-*`.
## Components
Import from `@carsxe/design-system/components/<name>` or the package root.
| Component | Path |
| ----------------- | ---------------------------------------------------- |
| Accordion | `@carsxe/design-system/components/accordion` |
| Alert | `@carsxe/design-system/components/alert` |
| Alert dialog | `@carsxe/design-system/components/alert-dialog` |
| Angle Slider | `@carsxe/design-system/components/angle-slider` |
| Aspect ratio | `@carsxe/design-system/components/aspect-ratio` |
| Attachment | `@carsxe/design-system/components/attachment` |
| Autocomplete | `@carsxe/design-system/components/autocomplete` |
| Avatar | `@carsxe/design-system/components/avatar` |
| Badge | `@carsxe/design-system/components/badge` |
| Breadcrumb | `@carsxe/design-system/components/breadcrumb` |
| Bubble | `@carsxe/design-system/components/bubble` |
| Button | `@carsxe/design-system/components/button` |
| Button group | `@carsxe/design-system/components/button-group` |
| Calendar | `@carsxe/design-system/components/calendar` |
| Card | `@carsxe/design-system/components/card` |
| Carousel | `@carsxe/design-system/components/carousel` |
| Chart | `@carsxe/design-system/components/chart` |
| D3 Charts | `@carsxe/design-system/components/d3-chart` |
| Checkbox | `@carsxe/design-system/components/checkbox` |
| Clipboard | `@carsxe/design-system/components/clipboard` |
| Code Block | `@carsxe/design-system/components/code-block` |
| Collapsible | `@carsxe/design-system/components/collapsible` |
| Color Picker | `@carsxe/design-system/components/color-picker` |
| Combobox | `@carsxe/design-system/components/combobox` |
| Command | `@carsxe/design-system/components/command` |
| Context menu | `@carsxe/design-system/components/context-menu` |
| Date Input | `@carsxe/design-system/components/date-input` |
| Dialog | `@carsxe/design-system/components/dialog` |
| Direction | `@carsxe/design-system/components/direction` |
| Drawer | `@carsxe/design-system/components/drawer` |
| Dropdown menu | `@carsxe/design-system/components/dropdown-menu` |
| Editable | `@carsxe/design-system/components/editable` |
| Empty | `@carsxe/design-system/components/empty` |
| Field | `@carsxe/design-system/components/field` |
| Floating Panel | `@carsxe/design-system/components/floating-panel` |
| Format | `@carsxe/design-system/components/format` |
| Heatmap | `@carsxe/design-system/components/heatmap` |
| Highlight | `@carsxe/design-system/components/highlight` |
| Hover card | `@carsxe/design-system/components/hover-card` |
| Image Cropper | `@carsxe/design-system/components/image-cropper` |
| Input | `@carsxe/design-system/components/input` |
| Input group | `@carsxe/design-system/components/input-group` |
| Input OTP | `@carsxe/design-system/components/input-otp` |
| Item | `@carsxe/design-system/components/item` |
| JSON Tree View | `@carsxe/design-system/components/json-tree-view` |
| Kbd | `@carsxe/design-system/components/kbd` |
| Knob | `@carsxe/design-system/components/knob` |
| Label | `@carsxe/design-system/components/label` |
| Listbox | `@carsxe/design-system/components/listbox` |
| Marker | `@carsxe/design-system/components/marker` |
| Marquee | `@carsxe/design-system/components/marquee` |
| Mega menu | `@carsxe/design-system/components/mega-menu` |
| Menubar | `@carsxe/design-system/components/menubar` |
| Message | `@carsxe/design-system/components/message` |
| Message scroller | `@carsxe/design-system/components/message-scroller` |
| Native select | `@carsxe/design-system/components/native-select` |
| Navigation menu | `@carsxe/design-system/components/navigation-menu` |
| Number Input | `@carsxe/design-system/components/number-input` |
| Pagination | `@carsxe/design-system/components/pagination` |
| Password Input | `@carsxe/design-system/components/password-input` |
| Popover | `@carsxe/design-system/components/popover` |
| Progress | `@carsxe/design-system/components/progress` |
| QR Code | `@carsxe/design-system/components/qr-code` |
| Questionnaire | `@carsxe/design-system/components/questionnaire` |
| Radio group | `@carsxe/design-system/components/radio-group` |
| Rating Group | `@carsxe/design-system/components/rating-group` |
| Resizable | `@carsxe/design-system/components/resizable` |
| Scroll area | `@carsxe/design-system/components/scroll-area` |
| Select | `@carsxe/design-system/components/select` |
| Separator | `@carsxe/design-system/components/separator` |
| Sheet | `@carsxe/design-system/components/sheet` |
| Sidebar | `@carsxe/design-system/components/sidebar` |
| Signature Pad | `@carsxe/design-system/components/signature-pad` |
| Skeleton | `@carsxe/design-system/components/skeleton` |
| Slider | `@carsxe/design-system/components/slider` |
| Sonner | `@carsxe/design-system/components/sonner` |
| Spinner | `@carsxe/design-system/components/spinner` |
| Split Button | `@carsxe/design-system/components/split-button` |
| Steps | `@carsxe/design-system/components/steps` |
| Swap | `@carsxe/design-system/components/swap` |
| Switch | `@carsxe/design-system/components/switch` |
| Table | `@carsxe/design-system/components/table` |
| Table of Contents | `@carsxe/design-system/components/table-of-contents` |
| Tabs | `@carsxe/design-system/components/tabs` |
| Tags Input | `@carsxe/design-system/components/tags-input` |
| Textarea | `@carsxe/design-system/components/textarea` |
| Timeline | `@carsxe/design-system/components/timeline` |
| Timer | `@carsxe/design-system/components/timer` |
| Toast | `@carsxe/design-system/components/toast` |
| Toggle | `@carsxe/design-system/components/toggle` |
| Toggle group | `@carsxe/design-system/components/toggle-group` |
| Tour | `@carsxe/design-system/components/tour` |
| Tree View | `@carsxe/design-system/components/tree-view` |
| Tooltip | `@carsxe/design-system/components/tooltip` |
| World Map Chart | `@carsxe/design-system/components/world-map-chart` |
Sidebar also exposes `useIsMobile` from `@carsxe/design-system/hooks/use-mobile`.
Chart includes token-aware Recharts composition for Area, Bar, Line, Pie/Donut,
Radar, and Radial charts. D3 Charts exports `SankeyChart`,
`ForceDirectedGraph`, `TreemapChart`, and `SunburstChart` for relationship and
hierarchy data.
World Map Chart is a Chart.js choropleth with bundled world geometry. Pass
`data={[{ countryCode: "US", value: 18420 }]}` using ISO alpha-2, alpha-3, or
numeric codes. It provides a CarsXE token scale, hover and keyboard previews,
controlled or uncontrolled country selection, an accessible live region, and
light/dark theme updates without runtime map fetches.
Heatmap is a GitHub-style calendar heatmap. Pass
`data={[{ date: "2026-08-12", value: 1240 }]}` (string dates are `YYYY-MM-DD`,
parsed as local days); values quantize into as many levels as the `colors`
array (five heatmap tokens by default, theme-aware), with zero or missing days
rendered in `emptyColor`. It has no `height` prop — height derives from width
and the number of weeks so cells stay square. `valueFormatter` drives both the
cell tooltips and the legend's "up to" maximum.
Code Block uses Shiki with a searchable catalog of all bundled light and dark
themes. It follows the app's `.dark` class by default, loads the selected theme
and language on demand, and includes copy feedback. Pass `theme="dracula"` for
an explicit theme or keep `theme="system"` for light/dark defaults.
Signature Pad can be used as the `SignaturePad` convenience component or with
the compound `SignaturePadRoot`, `SignaturePadLabel`, `SignaturePadControl`,
`SignaturePadSegment`, `SignaturePadGuide`, history triggers, and
`SignaturePadHiddenInput`. Use `useSignaturePad` with
`SignaturePadRootProvider` when the state and export methods must be controlled
outside the component tree.
Password Input is a masked input with a visibility toggle (`toggleMask`,
`showIcon`/`hideIcon`, controlled `visible`/`onVisibleChange`). Set `feedback`
to open a strength panel while the input is focused, rating the value weak,
medium, or strong; customize the captions with `promptLabel`/`weakLabel`/
`mediumLabel`/`strongLabel`, replace the rating with `getStrength`, and add
suggestions through `feedbackHeader`/`feedbackFooter`. The default
`getPasswordStrength` is exported.
Split Button is the data-driven pairing of a primary action with a menu. It
takes every `Button` prop (including `variant`, `size`, and `onClick`) plus
`items` of `{ id, label, icon, onSelect, href, disabled, destructive,
separator, items }`; `items` on an item nests one level of submenu. `loading`
shows a spinner and disables both halves, and `menuLabel` names the menu
trigger. Build it by hand from `ButtonGroup` + `Button` + `DropdownMenu` when
the menu needs arbitrary markup.
Steps is both a standalone indicator (`steps`, `value`/`defaultValue`/
`onValueChange`, `orientation`, `linear`) and the indicator for a wizard: wrap
it in `StepsRoot` with `StepsContent` and one `StepsPanel step="<id>"` per step.
Inactive panels stay mounted but hidden, so form state survives navigation.
`useSteps()` returns `{ steps, index, value, isFirst, isLast, linear, next,
prev, goTo }` for footer buttons; `linear` only blocks clicking the indicator,
never programmatic navigation.
Tree View takes `items` of `{ id, label, children }` and keeps selection in
`value` as an array of ids. `selectionMode="checkbox"` cascades to descendants
and ancestors, with `value` holding only the fully checked ids — partial state
is derived and reported as `aria-checked="mixed"`. `showFilter` adds a search
field debounced by `filterDelay`; `filterMode="strict"` prunes a matched branch
to the matching path. A `lazy` item calls `onExpand` once and shows a spinner
until it resolves. `dragAndDrop` reports moves through `onItemsMove`, which
hands back the reordered tree. Helpers: `collectTreeViewIds`,
`findTreeViewItem`, `filterTreeViewItems`, `moveTreeViewItem`, and
`toggleTreeViewChecked`.
Data Table, Date Picker, Forms, and Typography are composition recipes in the docs, not component import paths.
`Input` has no `size` variant prop — native `<input size>` is a number. Use `className` for compact heights (for example `h-8`).
Alert and Badge include `success` and `warning` variants in addition to the usual shadcn set.
## Example
```tsx
import { Button } from "@carsxe/design-system/components/button"
import "@carsxe/design-system/globals.css"
export function Example() {
return <Button>Get started</Button>
}
```