@toa.io/extensions.configuration 1.0.0-alpha.273 → 1.0.0-alpha.274

package/ui/.agents/skills/shadcn-svelte/customization.md

@@ -0,0 +1,213 @@
+# Customization & Theming
+
+Components reference semantic CSS variable tokens. Change the variables to change every component.
+
+## Contents
+
+- How it works (CSS variables → Tailwind utilities → components)
+- Color variables and OKLCH format
+- Dark mode setup
+- Changing the theme (presets, CSS variables)
+- Adding custom colors (Tailwind v3 and v4)
+- Border radius
+- Customizing components (variants, class, wrappers)
+- Checking for updates
+
+---
+
+## How It Works
+
+1. CSS variables defined in `:root` (light) and `.dark` (dark mode).
+2. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
+3. Components use these utilities — changing a variable changes all components that reference it.
+
+---
+
+## Color Variables
+
+Every color follows the `name` / `name-foreground` convention. The base variable is for backgrounds, `-foreground` is for text/icons on that background.
+
+| Variable                                     | Purpose                          |
+| -------------------------------------------- | -------------------------------- |
+| `--background` / `--foreground`              | Page background and default text |
+| `--card` / `--card-foreground`               | Card surfaces                    |
+| `--primary` / `--primary-foreground`         | Primary buttons and actions      |
+| `--secondary` / `--secondary-foreground`     | Secondary actions                |
+| `--muted` / `--muted-foreground`             | Muted/disabled states            |
+| `--accent` / `--accent-foreground`           | Hover and accent states          |
+| `--destructive` / `--destructive-foreground` | Error and destructive actions    |
+| `--border`                                   | Default border color             |
+| `--input`                                    | Form input borders               |
+| `--ring`                                     | Focus ring color                 |
+| `--chart-1` through `--chart-5`              | Chart/data visualization         |
+| `--sidebar-*`                                | Sidebar-specific colors          |
+| `--surface` / `--surface-foreground`         | Secondary surface                |
+
+Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).
+
+---
+
+## Dark Mode
+
+Class-based toggle via `.dark` on the root element. In SvelteKit, use [mode-watcher](https://github.com/svecosystem/mode-watcher) (see [Dark mode — Svelte](https://shadcn-svelte.com/docs/dark-mode/svelte)):
+
+```svelte
+<script lang="ts">
+  import { ModeWatcher } from "mode-watcher";
+  let { children } = $props();
+</script>
+
+<ModeWatcher />
+{@render children?.()}
+```
+
+---
+
+## Changing the Theme
+
+Use a **preset** from the design-system builder on [shadcn-svelte.com](https://shadcn-svelte.com) and pass it to `init`:
+
+```bash
+npx shadcn-svelte@latest init --preset <code>
+```
+
+Or edit CSS variables directly in the file set in `components.json` as `tailwind.css` (for example `src/app.css`).
+
+To align config and components with a new preset, re-run `init` with `--preset` and confirm overwrites when prompted.
+
+---
+
+## Adding Custom Colors
+
+Add variables to the global CSS file path in `components.json` (`tailwind.css`). Do not create a second global CSS file for theming unless the project already uses that pattern.
+
+```css
+/* 1. Define in the global CSS file. */
+:root {
+  --warning: oklch(0.84 0.16 84);
+  --warning-foreground: oklch(0.28 0.07 46);
+}
+.dark {
+  --warning: oklch(0.41 0.11 46);
+  --warning-foreground: oklch(0.99 0.02 95);
+}
+```
+
+```css
+/* 2a. Register with Tailwind v4 (@theme inline). */
+@theme inline {
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+}
+```
+
+On Tailwind v3, register in `tailwind.config.js` (see the [Tailwind v3 docs](https://tw3.shadcn-svelte.com) if you maintain a legacy setup):
+
+```js
+// 2b. Register with Tailwind v3 (tailwind.config.js).
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        warning: "oklch(var(--warning) / <alpha-value>)",
+        "warning-foreground":
+          "oklch(var(--warning-foreground) / <alpha-value>)",
+      },
+    },
+  },
+};
+```
+
+```svelte
+<!-- 3. Use in components. -->
+<div class="bg-warning text-warning-foreground">Warning</div>
+```
+
+---
+
+## Border Radius
+
+`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `var(--radius)`, `rounded-md` = `calc(var(--radius) - 2px)`).
+
+---
+
+## Customizing Components
+
+See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.
+
+Prefer these approaches in order:
+
+### 1. Built-in variants
+
+```svelte
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+</script>
+
+<Button variant="outline" size="sm">Click</Button>
+```
+
+### 2. Tailwind classes via `class`
+
+```svelte
+<script lang="ts">
+  import * as Card from "$lib/components/ui/card";
+</script>
+
+<Card.Root class="mx-auto max-w-md">
+  <Card.Content>...</Card.Content>
+</Card.Root>
+```
+
+### 3. Add a new variant
+
+Edit the component source to add a variant via `tailwind-variants` / `cva` in the `.svelte` or shared variants file:
+
+```ts
+// e.g. in button variants
+warning: "bg-warning text-warning-foreground hover:bg-warning/90",
+```
+
+### 4. Wrapper components
+
+Compose shadcn-svelte primitives into higher-level `.svelte` files:
+
+```svelte
+<script lang="ts">
+  import * as AlertDialog from "$lib/components/ui/alert-dialog";
+  let { title, description, onConfirm, children } = $props();
+  let open = $state(false);
+</script>
+
+<AlertDialog.Root bind:open>
+  <AlertDialog.Trigger>
+    {@render children?.()}
+  </AlertDialog.Trigger>
+  <AlertDialog.Content>
+    <AlertDialog.Header>
+      <AlertDialog.Title>{title}</AlertDialog.Title>
+      <AlertDialog.Description>{description}</AlertDialog.Description>
+    </AlertDialog.Header>
+    <AlertDialog.Footer>
+      <AlertDialog.Cancel>Cancel</AlertDialog.Cancel>
+      <AlertDialog.Action
+        onclick={() => {
+          onConfirm?.();
+          open = false;
+        }}>Confirm</AlertDialog.Action
+      >
+    </AlertDialog.Footer>
+  </AlertDialog.Content>
+</AlertDialog.Root>
+```
+
+---
+
+## Checking for Updates
+
+```bash
+npx shadcn-svelte@latest update button
+npx shadcn-svelte@latest update --all
+```
+
+See [Updating Components in SKILL.md](./SKILL.md#updating-components). Review `git diff` after `update` to see what changed.

package/ui/.agents/skills/shadcn-svelte/evals/evals.json

@@ -0,0 +1,47 @@
+{
+	"skill_name": "shadcn-svelte",
+	"evals": [
+		{
+			"id": 1,
+			"prompt": "I'm building a SvelteKit app with shadcn-svelte (nova style, lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as toggle options). Add validation states for required fields.",
+			"expected_output": "A Svelte component using Field.FieldGroup, Field.Field, ToggleGroup, data-invalid/aria-invalid validation, gap-* spacing, and semantic colors.",
+			"files": [],
+			"expectations": [
+				"Uses Field.FieldGroup and Field.Field for form layout instead of raw div with space-y",
+				"Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
+				"Uses data-invalid on Field and aria-invalid on the input control for validation states",
+				"Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
+				"Uses semantic color tokens (e.g. bg-background, text-muted-foreground, text-destructive) instead of raw colors like bg-red-500",
+				"No manual dark: color overrides"
+			]
+		},
+		{
+			"id": 2,
+			"prompt": "Create a dialog component for editing a user profile. It should have the user's avatar at the top, input fields for name and bio, and Save/Cancel buttons with appropriate icons. Using shadcn-svelte with tabler icons.",
+			"expected_output": "A Svelte component with Dialog.Title, Avatar with Avatar.Fallback, data-icon on icon buttons, no icon sizing classes, @tabler/icons-svelte imports.",
+			"files": [],
+			"expectations": [
+				"Includes Dialog.Title for accessibility (visible or with sr-only class)",
+				"Avatar includes Avatar.Fallback",
+				"Icons on buttons use the data-icon attribute (data-icon=\"inline-start\" or data-icon=\"inline-end\")",
+				"No sizing classes on icons inside components (no size-4, w-4, h-4, etc.)",
+				"Uses tabler icons (@tabler/icons-svelte) instead of @lucide/svelte when tabler is configured",
+				"Uses shadcn-svelte Dialog patterns (e.g. Dialog.Trigger wrapping the control, or bind:open on Dialog.Root)"
+			]
+		},
+		{
+			"id": 3,
+			"prompt": "Create a dashboard component that shows 4 stat cards in a grid. Each card has a title, large number, percentage change badge, and a loading skeleton state. Using shadcn-svelte with lucide icons.",
+			"expected_output": "A Svelte component with full Card composition, Skeleton for loading, Badge for changes, semantic colors, gap-* spacing.",
+			"files": [],
+			"expectations": [
+				"Uses full Card composition with Card.Header, Card.Title, Card.Content (not dumping everything into Card.Content)",
+				"Uses Skeleton component for loading placeholders instead of custom animate-pulse divs",
+				"Uses Badge component for percentage change instead of custom styled spans",
+				"Uses semantic color tokens instead of raw color values like bg-green-500 or text-red-600",
+				"Uses gap-* instead of space-y-* or space-x-* for spacing",
+				"Uses size-* when width and height are equal instead of separate w-* h-*"
+			]
+		}
+	]
+}

package/ui/.agents/skills/shadcn-svelte/rules/composition.md

@@ -0,0 +1,244 @@
+# Component Composition
+
+## Contents
+
+- Items always inside their Group component
+- Callouts use Alert
+- Empty states use Empty component
+- Toast notifications use svelte-sonner
+- Choosing between overlay components
+- Dialog, Sheet, and Drawer always need a Title
+- Card structure
+- Button has no isPending or isLoading prop
+- Tabs.Trigger must be inside Tabs.List
+- Avatar always needs Avatar.Fallback
+- Use Separator instead of raw hr or border divs
+- Use Skeleton for loading placeholders
+- Use Badge instead of custom styled spans
+
+---
+
+## Items always inside their Group component
+
+Never render items directly inside the content container.
+
+**Incorrect:**
+
+```svelte
+<script lang="ts">
+  import * as Select from "$lib/components/ui/select";
+</script>
+
+<Select.Content>
+  <Select.Item value="apple">Apple</Select.Item>
+  <Select.Item value="banana">Banana</Select.Item>
+</Select.Content>
+```
+
+**Correct:**
+
+```svelte
+<script lang="ts">
+  import * as Select from "$lib/components/ui/select";
+</script>
+
+<Select.Content>
+  <Select.Group>
+    <Select.Item value="apple">Apple</Select.Item>
+    <Select.Item value="banana">Banana</Select.Item>
+  </Select.Group>
+</Select.Content>
+```
+
+This applies to all group-based components:
+
+| Item                                                          | Group                |
+| ------------------------------------------------------------- | -------------------- |
+| `Select.Item`, `Select.Label`                                 | `Select.Group`       |
+| `DropdownMenu.Item`, `DropdownMenu.Label`, `DropdownMenu.Sub` | `DropdownMenu.Group` |
+| `Menubar.Item`                                                | `Menubar.Group`      |
+| `ContextMenu.Item`                                            | `ContextMenu.Group`  |
+| `Command.Item`                                                | `Command.Group`      |
+
+---
+
+## Callouts use Alert
+
+```svelte
+<script lang="ts">
+  import * as Alert from "$lib/components/ui/alert";
+</script>
+
+<Alert.Root>
+  <Alert.Title>Warning</Alert.Title>
+  <Alert.Description>Something needs attention.</Alert.Description>
+</Alert.Root>
+```
+
+---
+
+## Empty states use Empty component
+
+```svelte
+<script lang="ts">
+  import * as Empty from "$lib/components/ui/empty";
+  import { Button } from "$lib/components/ui/button";
+  import FolderIcon from "@lucide/svelte/icons/folder";
+</script>
+
+<Empty.Root>
+  <Empty.Header>
+    <Empty.Media variant="icon"><FolderIcon /></Empty.Media>
+    <Empty.Title>No projects yet</Empty.Title>
+    <Empty.Description
+      >Get started by creating a new project.</Empty.Description
+    >
+  </Empty.Header>
+  <Empty.Content>
+    <Button>Create Project</Button>
+  </Empty.Content>
+</Empty.Root>
+```
+
+---
+
+## Toast notifications use svelte-sonner
+
+```svelte
+<script lang="ts">
+  import { toast } from "svelte-sonner";
+</script>
+```
+
+```ts
+toast.success("Changes saved.");
+toast.error("Something went wrong.");
+toast("File deleted.", {
+  action: { label: "Undo", onClick: () => undoDelete() },
+});
+```
+
+Mount the `Toaster` from your UI folder once in the app layout (see [Sonner](https://shadcn-svelte.com/docs/components/sonner)).
+
+---
+
+## Choosing between overlay components
+
+| Use case                           | Component     |
+| ---------------------------------- | ------------- |
+| Focused task that requires input   | `Dialog`      |
+| Destructive action confirmation    | `AlertDialog` |
+| Side panel with details or filters | `Sheet`       |
+| Mobile-first bottom panel          | `Drawer`      |
+| Quick info on hover                | `HoverCard`   |
+| Small contextual content on click  | `Popover`     |
+
+---
+
+## Dialog, Sheet, and Drawer always need a Title
+
+`Dialog.Title`, `Sheet.Title`, `Drawer.Title` are required for accessibility. Use `class="sr-only"` if visually hidden.
+
+```svelte
+<script lang="ts">
+  import * as Dialog from "$lib/components/ui/dialog";
+</script>
+
+<Dialog.Content>
+  <Dialog.Header>
+    <Dialog.Title>Edit Profile</Dialog.Title>
+    <Dialog.Description>Update your profile.</Dialog.Description>
+  </Dialog.Header>
+  ...
+</Dialog.Content>
+```
+
+---
+
+## Card structure
+
+Use full composition — don't dump everything into `Card.Content`:
+
+```svelte
+<script lang="ts">
+  import * as Card from "$lib/components/ui/card";
+  import { Button } from "$lib/components/ui/button";
+</script>
+
+<Card.Root>
+  <Card.Header>
+    <Card.Title>Team Members</Card.Title>
+    <Card.Description>Manage your team.</Card.Description>
+  </Card.Header>
+  <Card.Content>...</Card.Content>
+  <Card.Footer>
+    <Button>Invite</Button>
+  </Card.Footer>
+</Card.Root>
+```
+
+---
+
+## Button has no isPending or isLoading prop
+
+Compose with `Spinner` inside `Button` + `disabled`:
+
+```svelte
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+  import { Spinner } from "$lib/components/ui/spinner";
+</script>
+
+<Button disabled>
+  <Spinner data-icon="inline-start" />
+  Saving...
+</Button>
+```
+
+---
+
+## Tabs.Trigger must be inside Tabs.List
+
+Never render `Tabs.Trigger` directly inside `Tabs.Root` — always wrap in `Tabs.List`:
+
+```svelte
+<script lang="ts">
+  import * as Tabs from "$lib/components/ui/tabs";
+  let tab = $state("account");
+</script>
+
+<Tabs.Root bind:value={tab}>
+  <Tabs.List>
+    <Tabs.Trigger value="account">Account</Tabs.Trigger>
+    <Tabs.Trigger value="password">Password</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="account">...</Tabs.Content>
+</Tabs.Root>
+```
+
+---
+
+## Avatar always needs Avatar.Fallback
+
+Always include `Avatar.Fallback` for when the image fails to load:
+
+```svelte
+<script lang="ts">
+  import * as Avatar from "$lib/components/ui/avatar";
+</script>
+
+<Avatar.Root>
+  <Avatar.Image src="/avatar.png" alt="User" />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+</Avatar.Root>
+```
+
+---
+
+## Use existing components instead of custom markup
+
+| Instead of                                     | Use                                                                                         |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `<hr>` or `<div class="border-t">`             | `<Separator />` (`import { Separator } from "$lib/components/ui/separator"`)                |
+| `<div class="animate-pulse">` with styled divs | `<Skeleton class="h-4 w-3/4" />` (`import { Skeleton } from "$lib/components/ui/skeleton"`) |
+| `<span class="rounded-full bg-green-100 ...">` | `<Badge variant="secondary">` (`import { Badge } from "$lib/components/ui/badge"`)          |