atlas-react-kit 0.4.1 → 0.5.0

package/dist/progress.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+import { Progress as ProgressPrimitive } from "radix-ui";
+/**
+ * Determinate progress (uploads, multi-step jobs). `value` is 0–100; omit
+ * it for an indeterminate state and pair the bar with a visible label.
+ */
+declare function Progress({ className, value, ...props }: React.ComponentProps<typeof ProgressPrimitive.Root>): React.JSX.Element;
+export { Progress };

package/dist/progress.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Progress as ProgressPrimitive } from "radix-ui";
+import { cn } from "./utils.js";
+/**
+ * Determinate progress (uploads, multi-step jobs). `value` is 0–100; omit
+ * it for an indeterminate state and pair the bar with a visible label.
+ */
+function Progress({ className, value, ...props }) {
+    return (_jsx(ProgressPrimitive.Root, { "data-slot": "progress", value: value, className: cn("relative h-2 w-full overflow-hidden rounded-none bg-primary/15", className), ...props, children: _jsx(ProgressPrimitive.Indicator, { "data-slot": "progress-indicator", className: "h-full w-full flex-1 bg-primary transition-transform", style: { transform: `translateX(-${100 - (value ?? 0)}%)` } }) }));
+}
+export { Progress };

package/dist/radio-group.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+import { RadioGroup as RadioGroupPrimitive } from "radix-ui";
+/**
+ * One choice from a short, visible list. Arrow keys move the selection.
+ * Use `Select` or `Combobox` when the list is long.
+ */
+declare function RadioGroup({ className, ...props }: React.ComponentProps<typeof RadioGroupPrimitive.Root>): React.JSX.Element;
+/**
+ * Radio dot. Radios stay round (a circle, per the shape rules) so they read
+ * differently from square checkboxes.
+ */
+declare function RadioGroupItem({ className, ...props }: React.ComponentProps<typeof RadioGroupPrimitive.Item>): React.JSX.Element;
+export { RadioGroup, RadioGroupItem };

package/dist/radio-group.js

@@ -0,0 +1,20 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { RadioGroup as RadioGroupPrimitive } from "radix-ui";
+import { cn } from "./utils.js";
+/**
+ * One choice from a short, visible list. Arrow keys move the selection.
+ * Use `Select` or `Combobox` when the list is long.
+ */
+function RadioGroup({ className, ...props }) {
+    return (_jsx(RadioGroupPrimitive.Root, { "data-slot": "radio-group", className: cn("grid gap-3", className), ...props }));
+}
+/**
+ * Radio dot. Radios stay round (a circle, per the shape rules) so they read
+ * differently from square checkboxes.
+ */
+function RadioGroupItem({ className, ...props }) {
+    return (_jsx(RadioGroupPrimitive.Item, { "data-slot": "radio-group-item", className: cn("peer relative flex aspect-square size-4.5 shrink-0 items-center justify-center rounded-full border border-input bg-transparent shadow-xs transition-shadow outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/30 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-2 aria-invalid:ring-destructive/20 data-checked:border-primary", className), ...props, children: _jsx(RadioGroupPrimitive.Indicator, { "data-slot": "radio-group-indicator", className: "flex items-center justify-center", children: _jsx("span", { className: "size-2 rounded-full bg-primary" }) }) }));
+}
+export { RadioGroup, RadioGroupItem };

package/dist/spinner.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+/**
+ * Indeterminate loading indicator for a button or small region. Announced as
+ * "Loading" by default; pass `aria-label` for something more specific. Use
+ * `Skeleton` or `TableBodySkeleton` when the layout of the result is known.
+ */
+declare function Spinner({ className, "aria-label": ariaLabel, ...props }: React.ComponentProps<"svg">): React.JSX.Element;
+export { Spinner };

package/dist/spinner.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Loader2Icon } from "lucide-react";
+import { cn } from "./utils.js";
+/**
+ * Indeterminate loading indicator for a button or small region. Announced as
+ * "Loading" by default; pass `aria-label` for something more specific. Use
+ * `Skeleton` or `TableBodySkeleton` when the layout of the result is known.
+ */
+function Spinner({ className, "aria-label": ariaLabel = "Loading", ...props }) {
+    return (_jsx(Loader2Icon, { role: "status", "aria-label": ariaLabel, "data-slot": "spinner", className: cn("size-4 animate-spin", className), ...props }));
+}
+export { Spinner };

package/dist/switch.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+import { Switch as SwitchPrimitive } from "radix-ui";
+/**
+ * On/off setting that applies immediately (notifications, dark mode). Use
+ * `Checkbox` for choices submitted with a form. Square like the other
+ * primitives; checked uses the primary fill, as `Checkbox` does.
+ */
+declare function Switch({ className, ...props }: React.ComponentProps<typeof SwitchPrimitive.Root>): React.JSX.Element;
+export { Switch };

package/dist/switch.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Switch as SwitchPrimitive } from "radix-ui";
+import { cn } from "./utils.js";
+/**
+ * On/off setting that applies immediately (notifications, dark mode). Use
+ * `Checkbox` for choices submitted with a form. Square like the other
+ * primitives; checked uses the primary fill, as `Checkbox` does.
+ */
+function Switch({ className, ...props }) {
+    return (_jsx(SwitchPrimitive.Root, { "data-slot": "switch", className: cn("peer inline-flex h-5 w-9 shrink-0 items-center rounded-none border border-transparent bg-input p-0.5 shadow-xs transition-colors outline-none focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/30 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-2 aria-invalid:ring-destructive/20 data-checked:bg-primary dark:bg-input/80 dark:data-checked:bg-primary", className), ...props, children: _jsx(SwitchPrimitive.Thumb, { "data-slot": "switch-thumb", className: "pointer-events-none block size-3.5 rounded-none bg-background shadow-sm ring-0 transition-transform data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0 dark:data-[state=checked]:bg-primary-foreground" }) }));
+}
+export { Switch };

package/dist/table.d.ts

@@ -2,6 +2,8 @@ import * as React from "react";
 /**
  * Data table. The root is a `min-w-0 overflow-x-auto` scroller so nowrap
  * columns scroll inside the table instead of widening a card or panel.
+ * While it overflows, the scroller joins the tab order so keyboard users can
+ * scroll it with the arrow keys (WCAG 2.1.1).
  * Cell padding is `px-2` below `sm` and the original `p-3` from `sm` up.
  */
 declare function Table({ className, ...props }: React.ComponentProps<"table">): React.JSX.Element;

package/dist/table.js

@@ -2,13 +2,37 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "./utils.js";
+/**
+ * True while the element's content is wider than its box. Re-checked when
+ * the container or its content resizes.
+ */
+function useHorizontalOverflow(ref) {
+    const [overflowing, setOverflowing] = React.useState(false);
+    React.useEffect(() => {
+        const element = ref.current;
+        if (!element || typeof ResizeObserver === "undefined")
+            return;
+        const check = () => setOverflowing(element.scrollWidth > element.clientWidth + 1);
+        check();
+        const observer = new ResizeObserver(check);
+        observer.observe(element);
+        if (element.firstElementChild)
+            observer.observe(element.firstElementChild);
+        return () => observer.disconnect();
+    }, [ref]);
+    return overflowing;
+}
 /**
  * Data table. The root is a `min-w-0 overflow-x-auto` scroller so nowrap
  * columns scroll inside the table instead of widening a card or panel.
+ * While it overflows, the scroller joins the tab order so keyboard users can
+ * scroll it with the arrow keys (WCAG 2.1.1).
  * Cell padding is `px-2` below `sm` and the original `p-3` from `sm` up.
  */
 function Table({ className, ...props }) {
-    return (_jsx("div", { "data-slot": "table-container", className: "relative w-full min-w-0 max-w-full overflow-x-auto overscroll-x-contain", children: _jsx("table", { "data-slot": "table", className: cn("w-full min-w-full caption-bottom text-sm", className), ...props }) }));
+    const containerRef = React.useRef(null);
+    const scrollable = useHorizontalOverflow(containerRef);
+    return (_jsx("div", { ref: containerRef, "data-slot": "table-container", tabIndex: scrollable ? 0 : undefined, className: "relative w-full min-w-0 max-w-full overflow-x-auto overscroll-x-contain outline-none focus-visible:ring-2 focus-visible:ring-ring/30", children: _jsx("table", { "data-slot": "table", className: cn("w-full min-w-full caption-bottom text-sm", className), ...props }) }));
 }
 function TableHeader({ className, ...props }) {
     return (_jsx("thead", { "data-slot": "table-header", className: cn("[&_tr]:border-b", className), ...props }));

package/dist/tabs.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 import { Tabs as TabsPrimitive } from "radix-ui";
-import { tabsListVariants } from "./internal/tabs-styles.js";
+import { tabsListVariants, tabsTriggerVariants } from "./internal/tabs-styles.js";
 declare function Tabs({ className, orientation, ...props }: React.ComponentProps<typeof TabsPrimitive.Root>): React.JSX.Element;
 declare function TabsList({ className, variant, ...props }: React.ComponentProps<typeof TabsPrimitive.List> & VariantProps<typeof tabsListVariants>): React.JSX.Element;
 declare function TabsTrigger({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Trigger>): React.JSX.Element;
@@ -9,9 +9,12 @@ declare function TabsContent({ className, ...props }: React.ComponentProps<typeo
 /**
  * Tab-styled links for a view switcher that changes the URL. Use this, not
  * `Tabs` + `TabsTrigger asChild`, when there are no `TabsContent` panels:
- * tabs would point assistive tech at panels that don't exist.
+ * tabs would point assistive tech at panels that don't exist. Style each link
+ * with `tabsTriggerVariants()` and mark the active one with
+ * `data-state="active"` and `aria-current="page"` (the Next adapter
+ * `TabsNavLink` does this for you).
  */
 declare function TabsNav({ className, children, ...props }: React.ComponentProps<"nav"> & {
     "aria-label": string;
 }): React.JSX.Element;
-export { Tabs, TabsList, TabsTrigger, TabsContent, TabsNav, tabsListVariants };
+export { Tabs, TabsList, TabsTrigger, TabsContent, TabsNav, tabsListVariants, tabsTriggerVariants, };

package/dist/tabs.js

@@ -20,9 +20,12 @@ function TabsContent({ className, ...props }) {
 /**
  * Tab-styled links for a view switcher that changes the URL. Use this, not
  * `Tabs` + `TabsTrigger asChild`, when there are no `TabsContent` panels:
- * tabs would point assistive tech at panels that don't exist.
+ * tabs would point assistive tech at panels that don't exist. Style each link
+ * with `tabsTriggerVariants()` and mark the active one with
+ * `data-state="active"` and `aria-current="page"` (the Next adapter
+ * `TabsNavLink` does this for you).
  */
 function TabsNav({ className, children, ...props }) {
     return (_jsx("nav", { "data-slot": "tabs-nav", "data-orientation": "horizontal", className: cn("group/tabs", className), ...props, children: _jsx("div", { "data-slot": "tabs-list", "data-variant": "default", className: tabsListVariants(), children: children }) }));
 }
-export { Tabs, TabsList, TabsTrigger, TabsContent, TabsNav, tabsListVariants };
+export { Tabs, TabsList, TabsTrigger, TabsContent, TabsNav, tabsListVariants, tabsTriggerVariants, };

package/dist/theme-provider.d.ts

@@ -3,7 +3,8 @@ import { useTheme, type ThemeProviderProps as NextThemesProviderProps } from "ne
 export type ThemeProviderProps = NextThemesProviderProps & {
     /**
      * When true, pressing `d` toggles dark/light unless focus is in an editable
-     * field. Defaults to true.
+     * field or a widget with letter typeahead (such as `Select`). Defaults to
+     * true.
      */
     enableShortcut?: boolean;
 };

package/dist/theme-provider.js

@@ -2,22 +2,46 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { ThemeProvider as NextThemesProvider, useTheme, } from "next-themes";
-const EDITABLE_SELECTOR = "input, textarea, select, [contenteditable]:not([contenteditable='false'])";
-function isEditableTarget(target) {
+/**
+ * Targets where a bare `d` is input, not a shortcut: native and ARIA text
+ * fields, plus widgets with letter typeahead (Select trigger and list, menus,
+ * trees, grids).
+ */
+const KEY_CONSUMING_SELECTOR = [
+    "input",
+    "textarea",
+    "select",
+    "[contenteditable]:not([contenteditable='false'])",
+    ...[
+        "textbox",
+        "searchbox",
+        "spinbutton",
+        "combobox",
+        "listbox",
+        "menu",
+        "menubar",
+        "tree",
+        "treegrid",
+        "grid",
+    ].map((role) => `[role="${role}"]`),
+].join(", ");
+function isKeyConsumingTarget(target) {
     if (!(target instanceof HTMLElement))
         return false;
-    return Boolean(target.closest(EDITABLE_SELECTOR));
+    return Boolean(target.closest(KEY_CONSUMING_SELECTOR));
 }
 /** Listens for the optional `d` shortcut inside an existing theme context. */
 function ThemeShortcut() {
     const { resolvedTheme, setTheme } = useTheme();
     React.useEffect(() => {
         function onKeyDown(event) {
+            if (event.defaultPrevented || event.repeat || event.isComposing)
+                return;
             if (event.metaKey || event.ctrlKey || event.altKey)
                 return;
             if (event.key !== "d" && event.key !== "D")
                 return;
-            if (isEditableTarget(event.target))
+            if (isKeyConsumingTarget(event.target))
                 return;
             event.preventDefault();
             setTheme(resolvedTheme === "dark" ? "light" : "dark");

package/dist/toggle.js

@@ -4,7 +4,7 @@ import * as React from "react";
 import { cva } from "class-variance-authority";
 import { Toggle as TogglePrimitive } from "radix-ui";
 import { cn } from "./utils.js";
-const toggleVariants = cva("group/toggle inline-flex items-center justify-center gap-1.5 rounded-none text-xs font-semibold tracking-widest whitespace-nowrap uppercase transition-colors outline-none hover:border-primary hover:bg-selected hover:text-primary focus-visible:border-primary focus-visible:text-primary focus-visible:ring-[3px] focus-visible:ring-primary/30 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-selected aria-pressed:text-selected-foreground dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5", {
+const toggleVariants = cva("group/toggle inline-flex items-center justify-center gap-1.5 rounded-none text-xs font-semibold tracking-widest whitespace-nowrap uppercase transition-colors outline-none hover:border-primary hover:bg-selected hover:text-selected-foreground focus-visible:border-primary focus-visible:text-selected-foreground focus-visible:ring-[3px] focus-visible:ring-primary/30 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-selected aria-pressed:text-selected-foreground dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5", {
     variants: {
         variant: {
             default: "bg-transparent",

package/dist/tooltip.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+import { Tooltip as TooltipPrimitive } from "radix-ui";
+/**
+ * Shares open delay across tooltips. `Tooltip` adds one per instance, so a
+ * provider at the app root is optional; add it to tune `delayDuration`.
+ */
+declare function TooltipProvider({ delayDuration, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>): React.JSX.Element;
+/**
+ * Short label for an icon button or truncated text. Opens on hover and
+ * keyboard focus; put essential information in visible text instead.
+ */
+declare function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>): React.JSX.Element;
+declare function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>): React.JSX.Element;
+declare function TooltipContent({ className, sideOffset, children, ...props }: React.ComponentProps<typeof TooltipPrimitive.Content>): React.JSX.Element;
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };

package/dist/tooltip.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Tooltip as TooltipPrimitive } from "radix-ui";
+import { cn } from "./utils.js";
+/**
+ * Shares open delay across tooltips. `Tooltip` adds one per instance, so a
+ * provider at the app root is optional; add it to tune `delayDuration`.
+ */
+function TooltipProvider({ delayDuration = 0, ...props }) {
+    return (_jsx(TooltipPrimitive.Provider, { "data-slot": "tooltip-provider", delayDuration: delayDuration, ...props }));
+}
+/**
+ * Short label for an icon button or truncated text. Opens on hover and
+ * keyboard focus; put essential information in visible text instead.
+ */
+function Tooltip({ ...props }) {
+    return (_jsx(TooltipProvider, { children: _jsx(TooltipPrimitive.Root, { "data-slot": "tooltip", ...props }) }));
+}
+function TooltipTrigger({ ...props }) {
+    return _jsx(TooltipPrimitive.Trigger, { "data-slot": "tooltip-trigger", ...props });
+}
+function TooltipContent({ className, sideOffset = 4, children, ...props }) {
+    return (_jsx(TooltipPrimitive.Portal, { children: _jsxs(TooltipPrimitive.Content, { "data-slot": "tooltip-content", sideOffset: sideOffset, className: cn("z-50 w-fit max-w-xs origin-(--radix-tooltip-content-transform-origin) rounded-none bg-foreground px-3 py-1.5 text-xs text-balance text-background duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-[state=instant-open]:animate-in data-[state=instant-open]:fade-in-0", className), ...props, children: [children, _jsx(TooltipPrimitive.Arrow, { className: "fill-foreground" })] }) }));
+}
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas-react-kit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Shared React components and Tailwind theme for Atlas",
   "type": "module",
   "license": "MIT",
@@ -13,16 +13,33 @@
     "theme.css",
     "DESIGN_RULES.md",
     "COMPONENTS.md",
-    "NOTICE"
+    "NOTICE",
+    "skills"
   ],
   "sideEffects": [
     "**/*.css"
   ],
   "exports": {
+    "./accordion": {
+      "types": "./dist/accordion.d.ts",
+      "default": "./dist/accordion.js"
+    },
+    "./alert": {
+      "types": "./dist/alert.d.ts",
+      "default": "./dist/alert.js"
+    },
+    "./avatar": {
+      "types": "./dist/avatar.d.ts",
+      "default": "./dist/avatar.js"
+    },
     "./badge": {
       "types": "./dist/badge.d.ts",
       "default": "./dist/badge.js"
     },
+    "./breadcrumb": {
+      "types": "./dist/breadcrumb.d.ts",
+      "default": "./dist/breadcrumb.js"
+    },
     "./button": {
       "types": "./dist/button.d.ts",
       "default": "./dist/button.js"
@@ -47,10 +64,18 @@
       "types": "./dist/date-picker.d.ts",
       "default": "./dist/date-picker.js"
     },
+    "./date-time-picker": {
+      "types": "./dist/date-time-picker.d.ts",
+      "default": "./dist/date-time-picker.js"
+    },
     "./dialog": {
       "types": "./dist/dialog.d.ts",
       "default": "./dist/dialog.js"
     },
+    "./dropdown-menu": {
+      "types": "./dist/dropdown-menu.d.ts",
+      "default": "./dist/dropdown-menu.js"
+    },
     "./empty-panel": {
       "types": "./dist/empty-panel.d.ts",
       "default": "./dist/empty-panel.js"
@@ -71,10 +96,22 @@
       "types": "./dist/label.d.ts",
       "default": "./dist/label.js"
     },
+    "./pagination": {
+      "types": "./dist/pagination.d.ts",
+      "default": "./dist/pagination.js"
+    },
     "./popover": {
       "types": "./dist/popover.d.ts",
       "default": "./dist/popover.js"
     },
+    "./progress": {
+      "types": "./dist/progress.d.ts",
+      "default": "./dist/progress.js"
+    },
+    "./radio-group": {
+      "types": "./dist/radio-group.d.ts",
+      "default": "./dist/radio-group.js"
+    },
     "./select": {
       "types": "./dist/select.d.ts",
       "default": "./dist/select.js"
@@ -87,13 +124,21 @@
       "types": "./dist/skeleton.d.ts",
       "default": "./dist/skeleton.js"
     },
+    "./sonner": {
+      "types": "./dist/sonner.d.ts",
+      "default": "./dist/sonner.js"
+    },
     "./sortable-table-head": {
       "types": "./dist/sortable-table-head.d.ts",
       "default": "./dist/sortable-table-head.js"
     },
-    "./sonner": {
-      "types": "./dist/sonner.d.ts",
-      "default": "./dist/sonner.js"
+    "./spinner": {
+      "types": "./dist/spinner.d.ts",
+      "default": "./dist/spinner.js"
+    },
+    "./switch": {
+      "types": "./dist/switch.d.ts",
+      "default": "./dist/switch.js"
     },
     "./table": {
       "types": "./dist/table.d.ts",
@@ -123,10 +168,18 @@
       "types": "./dist/toggle-group.d.ts",
       "default": "./dist/toggle-group.js"
     },
+    "./tooltip": {
+      "types": "./dist/tooltip.d.ts",
+      "default": "./dist/tooltip.js"
+    },
     "./form/date-picker-field": {
       "types": "./dist/form/date-picker-field.d.ts",
       "default": "./dist/form/date-picker-field.js"
     },
+    "./form/date-time-picker-field": {
+      "types": "./dist/form/date-time-picker-field.d.ts",
+      "default": "./dist/form/date-time-picker-field.js"
+    },
     "./form/field-error": {
       "types": "./dist/form/field-error.d.ts",
       "default": "./dist/form/field-error.js"

package/skills/atlas-react-kit/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: atlas-react-kit
+description: Build and change React UI with the atlas-react-kit design system (Atlas) instead of hand-rolled markup or another UI library. Use this whenever the project depends on atlas-react-kit (check package.json) and the task touches UI, such as pages, forms, inputs, pickers, selects, dialogs, tables, cards, tabs, badges, toasts, empty or loading states, theming, or dark mode, even if the user never says "Atlas" or "design system". Also use it when the user mentions Atlas components, design tokens, or making UI match the kit.
+---
+
+# Atlas React Kit
+
+atlas-react-kit is a shared React 19 + Tailwind 4 component library with a fixed
+look: square corners, semantic color tokens, uppercase tracked headings, and a
+purple "selected" wash for active states. Apps compose its components; they do
+not restyle or fork them. Following that keeps every app consistent and makes
+kit upgrades a version bump instead of a merge.
+
+## 1. Read the docs for the installed version
+
+The package ships its own guides, versioned with the code. Read both before
+writing UI, because props and rules change between releases and your memory of
+a previous version may be wrong:
+
+```sh
+KIT=$(dirname "$(node -p "require.resolve('atlas-react-kit/package.json')")")
+cat "$KIT/DESIGN_RULES.md" "$KIT/COMPONENTS.md"
+```
+
+`COMPONENTS.md` lists every import subpath and its props. When a prop is not
+listed there, check the type declarations in `$KIT/dist/<subpath>.d.ts` rather
+than guessing.
+
+## 2. Check the project setup once
+
+Components render unstyled unless the app's global stylesheet imports the theme
+and tells Tailwind to scan the kit's compiled files:
+
+```css
+@import "tailwindcss";
+@import "atlas-react-kit/theme.css";
+@source "../node_modules/atlas-react-kit/dist"; /* relative to this CSS file */
+```
+
+Dark mode needs `ThemeProvider` from `atlas-react-kit/theme-provider` near the
+root (or a `dark` class on an ancestor). Toasts need one `<Toaster />` from
+`atlas-react-kit/sonner`; call `toast()` from the `sonner` package, which the
+app should list as its own dependency. Fix missing setup rather than working
+around unstyled components.
+
+## 3. Pick the kit component for the job
+
+Import each component from its subpath, e.g.
+`import { Button } from "atlas-react-kit/button"`. There is no root barrel, and
+`dist/` or `internal/` paths are not public API.
+
+| Need                                            | Use                                                                                                 |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Short fixed list (a handful of options)         | `Select` family from `select`                                                                       |
+| Long or searchable list (timezones, currencies) | `Combobox` from `combobox` with `{ value, label }[]` options                                        |
+| One date, or a from/to range                    | `DatePickerButton` from `date-picker` (`mode="range"` for ranges)                                   |
+| Date and time (not `datetime-local`)            | `DateTimePickerButton` from `date-time-picker`                                                      |
+| Labelled field with error text                  | `FormTextField`, `FormSelectField`, `FormDatePickerField`, `FormDateTimePickerField` from `form/*`  |
+| Form-level error (save failed)                  | `FormFeedbackField` from `form/feedback-field`                                                      |
+| Content panels on one page                      | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` from `tabs`                                        |
+| View switch that changes the URL                | `TabsNav` with links: `TabsNavLink` from `next/tabs-nav-link` in Next, else `tabsTriggerVariants()` |
+| Status chip (paid, pending, failed)             | `Badge variant="soft"` with `tone="success"`, `"warning"`, `"destructive"`, or `"neutral"`          |
+| Data table                                      | `Table` family from `table`; `SortableTableHead`; `TableBodySkeleton` while loading                 |
+| Nothing to show yet                             | `EmptyPanel` from `empty-panel`                                                                     |
+| Grouped content                                 | `Card` family from `card`; `<Card flush>` for an edge-to-edge table or list                         |
+| Modal                                           | `Dialog` family from `dialog`                                                                       |
+| Label for an icon button, or a short hint       | `Tooltip` from `tooltip`; keep `aria-label` on icon buttons                                         |
+| Row actions or an overflow menu of commands     | `DropdownMenu` family from `dropdown-menu`                                                          |
+| Setting that applies immediately                | `Switch` from `switch`; `Checkbox` for choices submitted with a form                                |
+| One choice from a few visible options           | `RadioGroup` and `RadioGroupItem` from `radio-group`                                                |
+| Inline message about a page or section          | `Alert` from `alert` (`success`, `warning`, `destructive` variants)                                 |
+| Person or workspace image                       | `Avatar`, `AvatarImage`, `AvatarFallback` from `avatar`                                             |
+| Sections that expand in place                   | `Accordion` family from `accordion`                                                                 |
+| Pages of a long list                            | `Pagination` family from `pagination`                                                               |
+| Where the page sits in a hierarchy              | `Breadcrumb` family from `breadcrumb`                                                               |
+| Work in progress                                | `Progress` from `progress` when the percent is known, else `Spinner` from `spinner`                 |
+| Crash recovery around a section                 | `ErrorBoundary` from `error-boundary`                                                               |
+| Conditional classes                             | `cn` from `utils`                                                                                   |
+
+If nothing fits, build the piece in the app from kit primitives and semantic
+tokens. Do not copy kit source into the app; a missing shared component belongs
+in the atlas-design-system repository.
+
+Existing app code may predate the kit (raw colors, rounded boxes, hand-styled
+buttons). Don't copy that style into new UI. Move what the task touches onto kit
+components and tokens, and mention the rest to the user instead of rewriting
+files the task doesn't need.
+
+## 4. Style with tokens, not values
+
+These rules are what make Atlas look like Atlas. `DESIGN_RULES.md` has the full
+list; the ones that come up most:
+
+- **Semantic colors only**: `bg-primary`, `text-muted-foreground`,
+  `border-border`, `bg-card`, `text-destructive`. Raw palette classes
+  (`bg-purple-600`, `text-gray-500`) and paired `dark:` colors drift from the
+  theme; tokens already switch with light and dark.
+- **Selected and active state**: `bg-selected text-selected-foreground` for the
+  current nav item, chip, row, or toggle. Grey fills read as hover, not
+  selection.
+- **Status**: `success`, `warning`, and `destructive` for good, caution, and
+  bad. Use them as text or soft tints (the `Badge` tones), which meet AA in
+  both themes. Don't override a soft badge's colors. There is no foreground
+  token for text on a solid status fill, so avoid that combination.
+- **Brand-colored text**: `text-selected-foreground`, not `text-primary`,
+  which is too dark to read on the dark background.
+- **Accessibility**: the kit targets WCAG 2.2 AA. Give every control a name
+  (`Label htmlFor`, or `aria-label` on icon-only buttons and an unlabelled
+  `Combobox`), keep the shipped focus rings, and don't lower contrast with raw
+  colors or opacity.
+- **Square corners**: primitives have none. Use `rounded-full` only for real
+  circles (avatars, dots). Adding `rounded-md` to a card or button breaks the
+  system.
+- **Don't restyle kit controls**: `Input`, `SelectTrigger`, `DatePickerButton`,
+  `DateTimePickerButton`, and `Combobox` share 40px form-control chrome.
+  Overriding their height, padding, or border makes one field look different
+  from its neighbors.
+- **Layout overrides**: `CardContent className="px-0"` makes one section flush
+  without `!important`. Tables already scroll horizontally inside cards, so do
+  not wrap them in another overflow container.
+- **Headings**: `CardTitle` and `DialogTitle` already apply the uppercase,
+  tracked heading style; use `font-heading` for other headings.
+
+## 5. Check before you finish
+
+Run these over the files you changed and fix what they find (an app's own
+brand colors, kept outside kit components, are the only expected hits):
+
+```sh
+# Raw palette colors instead of tokens
+grep -nE '\b(bg|text|border|ring|fill|stroke)-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}\b' <files>
+# Rounded corners on primitives
+grep -nE '\brounded-(sm|md|lg|xl|2xl|3xl)\b' <files>
+# Non-public imports
+grep -nE "from ['\"]atlas-react-kit(/dist|/internal|['\"])" <files>
+```
+
+Then typecheck: wrong prop names usually mean the component was guessed rather
+than read from `COMPONENTS.md` or the `.d.ts`.

package/theme.css

@@ -96,18 +96,18 @@
   --secondary: oklch(0.967 0.001 286.375);
   --secondary-foreground: oklch(0.21 0.006 285.885);
   --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
+  /* 4.8:1 on --muted and 5.3:1 on the page, so muted text also works on muted fills. */
+  --muted-foreground: oklch(0.53 0 0);
   --accent: oklch(0.97 0 0);
   --accent-foreground: oklch(0.205 0 0);
   /* Soft brand-purple wash for selected/active chrome (nav, tabs, chips, rows). */
   --selected: color-mix(in oklch, var(--primary) 12%, var(--background));
   --selected-foreground: var(--primary);
-  --destructive: oklch(0.577 0.245 27.325);
+  /* AA as text on the page (6.4:1) and on its own /10 and /15 tints. */
+  --destructive: oklch(0.505 0.213 27.518);
   /* Status tones: AA (4.5:1) as text on the page, on a card, and on a /10–/25
      tint of themselves; also used as solid fills (meters). No -foreground:
-     nothing puts text on a solid fill. See DESIGN_RULES.md. --destructive
-     (above) passes as text on the page and card but not yet on its own tint
-     in light mode (about 3.6:1 on /15). */
+     nothing puts text on a solid fill. See DESIGN_RULES.md. */
   --success: oklch(0.45 0.11 160);
   --warning: oklch(0.48 0.115 70);
   --border: oklch(0.922 0 0);