atlas-react-kit 0.4.0 → 0.5.0

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);
@@ -202,4 +202,43 @@
   [data-slot="card-footer"].border-t {
     padding-top: var(--card-p);
   }
+
+  /*
+   * Horizontal scroll shadows: edge fades stay pinned (`scroll`) while
+   * matching covers ride with the content (`local`), so a clipped column
+   * like LICENSE is visible as overflow instead of looking truncated.
+   */
+  [data-slot="table-container"] {
+    --table-scroll-fade: var(--background);
+    background:
+      linear-gradient(to right, var(--table-scroll-fade) 40%, transparent),
+      linear-gradient(to left, var(--table-scroll-fade) 40%, transparent),
+      linear-gradient(
+        to right,
+        color-mix(in oklch, var(--foreground) 16%, transparent),
+        transparent 80%
+      ),
+      linear-gradient(
+        to left,
+        color-mix(in oklch, var(--foreground) 16%, transparent),
+        transparent 80%
+      );
+    background-repeat: no-repeat;
+    background-size:
+      1.5rem 100%,
+      1.5rem 100%,
+      0.75rem 100%,
+      0.75rem 100%;
+    background-position:
+      left center,
+      right center,
+      left center,
+      right center;
+    background-attachment: local, local, scroll, scroll;
+  }
+
+  /* Covers match the card face so the fade does not flash the page background. */
+  [data-slot="card"] [data-slot="table-container"] {
+    --table-scroll-fade: var(--card);
+  }
 }