compote-ui 0.62.0 → 0.62.2

package/skills/production-checklist/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: production-checklist
+description: >
+  Load before shipping or reviewing a compote-ui integration. Checks peer
+  dependencies, theme import, SSR/browser-only image utility boundaries,
+  accessible labels, optional data-table peers, excluded companion libraries,
+  and local verification with bun run check and bun run lint.
+metadata:
+  type: lifecycle
+  library: compote-ui
+  library_version: '0.62.1'
+requires:
+  - getting-started
+  - component-usage
+  - theming
+sources:
+  - package.json
+  - CLAUDE.md
+  - .claude/skills/verify/SKILL.md
+  - src/lib/utils/image-processing.ts
+  - src/lib/components/data-table-v9/virtual/data-table-virtual-rows.svelte
+---
+
+This checklist builds on getting-started, component-usage, and theming.
+
+# Compote UI — Production Checklist
+
+Run through each section before shipping a compote-ui integration or library change.
+
+## Setup Checks
+
+### Check: Theme import order
+
+Expected:
+
+```css
+@import 'tailwindcss';
+@import 'compote-ui/theme.css';
+```
+
+Fail condition: components render without Compote token utilities or CSS variables.
+Fix: import `compote-ui/theme.css` after `tailwindcss`.
+
+### Check: Optional peers match imports
+
+Expected:
+
+```ts
+import * as DataTable from 'compote-ui/data-table';
+```
+
+Fail condition: app imports `compote-ui/data-table` without `@tanstack/svelte-table`.
+Fix: install `@tanstack/svelte-table`.
+
+Expected:
+
+```ts
+import * as VirtualDataTable from 'compote-ui/data-table/virtual';
+```
+
+Fail condition: app imports the virtual subpath without `@tanstack/svelte-virtual`.
+Fix: install `@tanstack/svelte-virtual`.
+
+## SSR And Browser Checks
+
+### Check: Image utilities run in browser handlers
+
+Expected:
+
+```ts
+async function handleFile(file: File) {
+	const src = await fileToDataUrl(file);
+	const blob = await processImage(src);
+}
+```
+
+Fail condition: `processImage`, `cropImage`, `fileToDataUrl`, or `loadImage` run in SvelteKit server code or a `load` function.
+Fix: call Canvas and File APIs from browser event handlers.
+
+## Accessibility Checks
+
+### Check: Icon-only controls have names
+
+Expected:
+
+```svelte
+<Button size="icon" aria-label="Settings">
+	<SettingsIcon class="size-4" />
+</Button>
+```
+
+Fail condition: icon-only `Button`, `Toggle`, trigger, or menu control has no accessible name.
+Fix: add `aria-label` or visible text.
+
+## Boundary Checks
+
+### Check: Companion libraries stay separate
+
+Expected:
+
+```ts
+import { Button } from 'compote-ui';
+```
+
+Fail condition: charts or TipTap editor imports are expected from `compote-ui`.
+Fix: use `compote-echart` for charts and `compote-editor` for editor work.
+
+## Common Mistakes
+
+### HIGH Skipping local verification
+
+Wrong:
+
+```bash
+git commit -m "change component"
+```
+
+Correct:
+
+```bash
+bun run check
+bun run lint
+```
+
+The repository expects Svelte type checking and linting after changes.
+
+Source: `.claude/skills/verify/SKILL.md`, `CLAUDE.md`
+
+### MEDIUM Assuming charts and editors are included
+
+Wrong:
+
+```ts
+import { Chart, RichTextEditor } from 'compote-ui';
+```
+
+Correct:
+
+```ts
+import { Button } from 'compote-ui';
+```
+
+Charts belong to `compote-echart`; TipTap editor functionality belongs to `compote-editor`.
+
+Source: maintainer interview
+
+### HIGH Forgetting component-specific peers
+
+Wrong:
+
+```ts
+import * as VirtualDataTable from 'compote-ui/data-table/virtual';
+```
+
+Correct:
+
+```bash
+bun add @tanstack/svelte-virtual
+```
+
+```ts
+import * as VirtualDataTable from 'compote-ui/data-table/virtual';
+```
+
+The virtual table subpath imports the optional virtualizer peer.
+
+Source: `package.json`, `src/lib/components/data-table-v9/virtual/data-table-virtual-rows.svelte`
+
+## Pre-Deploy Summary
+
+- [ ] App imports `tailwindcss` before `compote-ui/theme.css`.
+- [ ] Data table imports have matching TanStack peers.
+- [ ] Browser-only image utilities are not called during SSR.
+- [ ] Icon-only controls have accessible names.
+- [ ] Charts and editor features use their separate packages.
+- [ ] Repository changes pass `bun run check`.
+- [ ] Repository changes pass `bun run lint`.
+
+## References
+
+- [Production audit](references/production-audit.md)

package/skills/production-checklist/references/production-audit.md

@@ -0,0 +1,40 @@
+# Production Audit
+
+Commands for repository changes:
+
+```bash
+bun run check
+bun run lint
+```
+
+Theme:
+
+```css
+@import 'tailwindcss';
+@import 'compote-ui/theme.css';
+```
+
+Data table peers:
+
+- `compote-ui/data-table` needs `@tanstack/svelte-table`.
+- `compote-ui/data-table/virtual` needs `@tanstack/svelte-virtual`.
+
+Browser-only APIs:
+
+- `loadImage`
+- `fileToDataUrl`
+- `cropImage`
+- `processImage`
+
+Do not call these in SvelteKit server modules or `load` functions.
+
+Accessibility:
+
+- Icon-only buttons need `aria-label`.
+- Data tables should have `caption`.
+- Dialogs should include `Dialog.Title`.
+
+Package boundaries:
+
+- Charts: `compote-echart`.
+- TipTap editor: `compote-editor`.

package/skills/theming/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: theming
+description: >
+  Load when configuring compote-ui/theme.css, Tailwind CSS 4 integration, CSS
+  variables, dark and light mode, class overrides, focus rings, consumer brand
+  tokens, --compote-* variables, @theme inline, or color-scheme behavior.
+metadata:
+  type: core
+  library: compote-ui
+  library_version: '0.62.1'
+sources:
+  - src/lib/theme.css
+  - src/routes/layout.css
+  - .prettierrc
+  - CLAUDE.md
+---
+
+# Compote UI — Theming
+
+Import `tailwindcss` first, then `compote-ui/theme.css`. Override `--compote-*` variables in the consuming app.
+
+## Setup
+
+```css
+@import 'tailwindcss';
+@import 'compote-ui/theme.css';
+
+:root {
+	--compote-primary: oklch(55% 0.2 270);
+	--compote-ring: var(--compote-primary);
+	--radius: 4px;
+	--font-sans: Inter, sans-serif;
+}
+```
+
+## Core Patterns
+
+### Override semantic tokens
+
+```css
+:root {
+	--compote-ink: light-dark(var(--gray-15), var(--gray-1));
+	--compote-ink-dim: light-dark(var(--gray-11), var(--gray-5));
+	--compote-surface-1: light-dark(var(--gray-3), var(--gray-13));
+	--compote-surface-document: light-dark(var(--gray-2), var(--gray-14));
+	--compote-border: var(--compote-surface-3);
+}
+```
+
+`theme.css` maps these to Tailwind utilities such as `text-ink`, `bg-surface-1`, `border-border`, and `ring-ring`.
+
+### Force light or dark mode
+
+```svelte
+<svelte:head>
+	<script>
+		document.documentElement.classList.toggle('dark', true);
+	</script>
+</svelte:head>
+```
+
+The theme follows system preference by default through `color-scheme: light dark`.
+
+### Extend component classes through class props
+
+```svelte
+<Button class="rounded-full px-5">Save</Button>
+<Dialog.Root contentClass="max-w-4xl">
+	<Dialog.Title>Wide dialog</Dialog.Title>
+</Dialog.Root>
+```
+
+Components merge class props with defaults; use token utilities instead of hard-coded colors.
+
+## Common Mistakes
+
+### HIGH Adding duplicate dark media block
+
+Wrong:
+
+```css
+@media (prefers-color-scheme: dark) {
+	:root {
+		--compote-surface-1: #111;
+	}
+}
+```
+
+Correct:
+
+```css
+:root {
+	--compote-surface-1: light-dark(var(--gray-3), var(--gray-13));
+}
+
+.dark {
+	color-scheme: dark;
+}
+
+.light {
+	color-scheme: light;
+}
+```
+
+The theme uses `light-dark()` plus `color-scheme`, so duplicating dark variables fights the model.
+
+Source: `src/lib/theme.css`, `CLAUDE.md`
+
+### MEDIUM Styling colored text as white
+
+Wrong:
+
+```svelte
+<Button class="text-white">Save</Button>
+```
+
+Correct:
+
+```svelte
+<Button class="text-ink-inverse">Save</Button>
+```
+
+Text on colored backgrounds should use `text-ink-inverse` so consumers can retheme it.
+
+Source: `CLAUDE.md`, `src/lib/theme.css`
+
+### MEDIUM Using primary for focus rings
+
+Wrong:
+
+```svelte
+<input class="focus-visible:ring-primary" />
+```
+
+Correct:
+
+```svelte
+<input class="focus-visible:ring-ring" />
+```
+
+Focus rings should use `ring-ring` so `--compote-ring` can be customized independently.
+
+Source: `CLAUDE.md`, `src/lib/theme.css`
+
+## References
+
+- [Theme tokens](references/theme-tokens.md)

package/skills/theming/references/theme-tokens.md

@@ -0,0 +1,56 @@
+# Theme Tokens
+
+Primary CSS variables:
+
+```css
+:root {
+	--radius: 6px;
+	--font-sans: 'Nunito Sans Variable', sans-serif;
+	--font-serif: Merriweather, serif;
+	--font-mono: Fira Code, monospace;
+
+	--compote-ink: light-dark(var(--gray-15), var(--gray-1));
+	--compote-ink-dim: light-dark(var(--gray-11), var(--gray-5));
+	--compote-ink-inverse: white;
+	--compote-surface-3: light-dark(var(--gray-5), var(--gray-10));
+	--compote-surface-2: light-dark(var(--gray-4), var(--gray-12));
+	--compote-surface-1: light-dark(var(--gray-3), var(--gray-13));
+	--compote-surface-document: light-dark(var(--gray-2), var(--gray-14));
+	--compote-well: light-dark(var(--gray-1), var(--gray-15));
+
+	--compote-primary: oklch(from var(--color-7) l c var(--hue-orange));
+	--compote-danger: oklch(from var(--color-7) l c var(--hue-red));
+	--compote-warning: oklch(from var(--color-7) l c var(--hue-yellow));
+	--compote-success: oklch(from var(--color-7) l c var(--hue-green));
+	--compote-info: oklch(from var(--color-7) l c var(--hue-blue));
+
+	--compote-border: var(--compote-surface-3);
+	--compote-ring: var(--compote-primary);
+}
+```
+
+Tailwind utility mapping from `@theme inline`:
+
+- `text-ink`
+- `text-ink-dim`
+- `text-ink-inverse`
+- `bg-surface-1`
+- `bg-surface-2`
+- `bg-surface-3`
+- `bg-surface-document`
+- `bg-well`
+- `bg-primary`, `text-primary`
+- `border-border`
+- `ring-ring`
+
+Dark/light control:
+
+```css
+.dark {
+	color-scheme: dark;
+}
+
+.light {
+	color-scheme: light;
+}
+```