admin-ui-starter-kit 0.6.8 → 0.7.0

package/.agents/skills/component-library-rules/references/components/features__products__actions.md

@@ -0,0 +1,37 @@
+---
+id: features/products/actions
+title: "Features · Products · Actions"
+description: "Product option and variant action menus that can be mounted inside tables, cards, rows, or fully custom consumer layouts."
+layer: features
+sourcePath: src/components/features/products
+examples:
+imports:
+publicImport: admin-ui-starter-kit/features/products
+tags:
+  - features
+  - products
+  - actions
+  - product
+  - option
+  - variant
+---
+
+# Features · Products · Actions
+
+Product option and variant action menus that can be mounted inside tables, cards, rows, or fully custom consumer layouts.
+
+**Layer:** `features`
+**Source:** `src/components/features/products`
+**Consumer import:** `admin-ui-starter-kit/features/products`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/products`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Standalone menus
+
+<Example name="StandaloneActionMenus" source={examplesSource}>
+	<Examples.StandaloneActionMenus />
+</Example>
+

package/.agents/skills/component-library-rules/references/components/features__products__support-rail.md

@@ -0,0 +1,73 @@
+---
+id: features/products/support-rail
+title: "Features · Products · Support Rail"
+description: "Secondary product cards for readiness, structure, operations, quote preview, and policies."
+layer: features
+sourcePath: src/components/features/products
+examples:
+  - ProductSupportRail
+imports:
+  - @/components/features/products
+publicImport: admin-ui-starter-kit/features/products
+tags:
+  - features
+  - products
+  - support
+  - rail
+  - secondary
+  - product
+---
+
+# Features · Products · Support Rail
+
+Secondary product cards for readiness, structure, operations, quote preview, and policies.
+
+**Layer:** `features`
+**Source:** `src/components/features/products`
+**Consumer import:** `admin-ui-starter-kit/features/products`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/products`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Rail cards
+
+<Example name="ProductSupportRail" source={examplesSource}>
+	<Examples.ProductSupportRail />
+</Example>
+
+## Examples
+
+```tsx
+import {
+	ProductOperationsCard,
+	ProductPoliciesCard,
+	ProductQuotePreviewCard,
+	ProductReadinessCard,
+	ProductStructureCard,
+} from '@/components/features/products';
+
+import { ProductPreviewViewport, railProps } from './fixtures';
+
+export function ProductSupportRail() {
+	const rail = railProps();
+
+	return (
+		<ProductPreviewViewport>
+			<div className="grid w-full gap-4 lg:grid-cols-2">
+				<ProductReadinessCard {...rail.readiness} />
+				<ProductStructureCard {...rail.structure} />
+				<ProductOperationsCard {...rail.operations} />
+				<ProductQuotePreviewCard {...rail.quote} />
+				<ProductPoliciesCard {...rail.policies} />
+			</div>
+		</ProductPreviewViewport>
+	);
+}
+```
+
+## Example exports
+
+- `ProductSupportRail`
+

package/.agents/skills/component-library-rules/references/components/features__products__variant-details.md

@@ -0,0 +1,97 @@
+---
+id: features/products/variant-details
+title: "Features · Products · Variant Details"
+description: "Variant detail and editor surfaces for product-specific edit flows. Persistence, validation, and routing stay callback-owned by the consumer."
+layer: features
+sourcePath: src/components/features/products
+examples:
+  - VariantDetailsAndEditor
+imports:
+  - @/components/features/products
+publicImport: admin-ui-starter-kit/features/products
+tags:
+  - features
+  - products
+  - variant
+  - details
+  - detail
+  - editor
+---
+
+# Features · Products · Variant Details
+
+Variant detail and editor surfaces for product-specific edit flows. Persistence, validation, and routing stay callback-owned by the consumer.
+
+**Layer:** `features`
+**Source:** `src/components/features/products`
+**Consumer import:** `admin-ui-starter-kit/features/products`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/products`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Details and editor
+
+<Example name="VariantDetailsAndEditor" source={examplesSource}>
+	<Examples.VariantDetailsAndEditor />
+</Example>
+
+## Examples
+
+```tsx
+import { useState } from 'react';
+
+import {
+	ProductVariantDetails,
+	ProductVariantEditor,
+	type ProductVariantEditorValues,
+} from '@/components/features/products';
+
+import {
+	ProductMediaPreview,
+	ProductPreviewViewport,
+	noop,
+	options,
+	variantEditorValue,
+	variantOptionFields,
+	variantStatusOptions,
+	variants,
+} from './fixtures';
+
+export function VariantDetailsAndEditor() {
+	const [value, setValue] = useState<ProductVariantEditorValues>(variantEditorValue);
+
+	return (
+		<ProductPreviewViewport>
+			<div className="grid w-full gap-4 xl:grid-cols-[minmax(0,0.9fr)_minmax(0,1.1fr)]">
+				<ProductVariantDetails
+					variant={variants[0]}
+					optionItems={options.slice(0, 2)}
+					media={<ProductMediaPreview frame="wide" />}
+					onBack={noop}
+					onSelectVariant={noop}
+					onEditVariant={noop}
+					onDuplicateVariant={noop}
+					onDeleteVariant={noop}
+					onSelectOption={noop}
+				/>
+				<ProductVariantEditor
+					value={value}
+					optionFields={variantOptionFields}
+					statusOptions={variantStatusOptions}
+					onValueChange={setValue}
+					onSubmit={noop}
+					onCancel={noop}
+					onDelete={noop}
+				/>
+			</div>
+		</ProductPreviewViewport>
+	);
+}
+```
+
+## Example exports
+
+- `VariantDetailsAndEditor`
+

package/.agents/skills/component-library-rules/references/components/features__products__variant-management.md

@@ -0,0 +1,269 @@
+---
+id: features/products/variant-management
+title: "Features · Products · Variant Management"
+description: "Option matrix and generated variants table with controlled collapse, selection, editable cells, render-props, and bulk callbacks."
+layer: features
+sourcePath: src/components/features/products
+examples:
+  - VariantManagement
+  - VariantTableControls
+imports:
+  - @/components/base/badge
+  - @/components/features/products
+publicImport: admin-ui-starter-kit/features/products
+tags:
+  - features
+  - products
+  - variant
+  - management
+  - option
+  - matrix
+---
+
+# Features · Products · Variant Management
+
+Option matrix and generated variants table with controlled collapse, selection, editable cells, render-props, and bulk callbacks.
+
+**Layer:** `features`
+**Source:** `src/components/features/products`
+**Consumer import:** `admin-ui-starter-kit/features/products`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/products`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Manager
+
+The manager example shows the production layout: options stay editable above
+the grouped variants table, while the variant table uses an inset frame,
+selection toolbar, and horizontal overflow instead of squeezing editable fields.
+
+<Example name="VariantManagement" source={examplesSource}>
+	<Examples.VariantManagement />
+</Example>
+
+## Table controls
+
+Use the table directly when consumers need to own the surrounding card or
+toolbar, while still keeping variant cells configurable as text, tags, fields,
+or custom render-props.
+
+<Example name="VariantTableControls" source={examplesSource}>
+	<Examples.VariantTableControls />
+</Example>
+
+## Examples
+
+```tsx
+import { useState } from 'react';
+
+import { Badge } from '@/components/base/badge';
+import {
+	ProductVariantsBulkTable,
+	ProductVariantsManager,
+	type ProductOptionEditDraft,
+	type ProductOptionGroup,
+	type ProductVariantEditableField,
+	type ProductVariantRow,
+} from '@/components/features/products';
+
+import {
+	optionGroups,
+	variantRows,
+} from './fixtures';
+
+function updateVariantField(
+	rows: ProductVariantRow[],
+	variantId: string,
+	field: ProductVariantEditableField,
+	value: string,
+) {
+	return rows.map((row) => (
+		row.id === variantId ? { ...row, [field]: value } : row
+	));
+}
+
+export function VariantManagement() {
+	const [selectedIds, setSelectedIds] = useState<string[]>([]);
+	const [optionState, setOptionState] = useState<ProductOptionGroup[]>(optionGroups);
+	const [variantState, setVariantState] = useState<ProductVariantRow[]>(variantRows);
+	const [collapsedOptionIds, setCollapsedOptionIds] = useState<string[]>([]);
+	const [configuredOptionId, setConfiguredOptionId] = useState<string | null>(null);
+
+	return (
+		<ProductVariantsManager
+			optionGroups={optionState}
+			variants={variantState}
+			optionCombinationDisplay="tags"
+			cellDisplay={{ sku: 'field', price: 'field', inventory: 'field' }}
+			visibleColumns={['variant', 'price', 'inventory', 'status']}
+			collapsedOptionIds={collapsedOptionIds}
+			onCollapsedOptionIdsChange={(ids) => setCollapsedOptionIds(ids)}
+			editingOptionId={configuredOptionId}
+			onEditingOptionIdChange={(id) => setConfiguredOptionId(id)}
+			selectedVariantIds={selectedIds}
+			onSelectedVariantIdsChange={(ids) => setSelectedIds(ids)}
+			onCreateOption={() => {
+				const nextIndex = optionState.length + 1;
+				const nextId = `custom-option-${nextIndex}`;
+				setOptionState((current) => [
+					...current,
+					{
+						id: nextId,
+						name: `Custom option ${nextIndex}`,
+						description: 'Consumer-owned option added from the preview.',
+						usedForVariants: false,
+						values: [{ id: `${nextId}-value-1`, label: 'New value' }],
+					},
+				]);
+				setConfiguredOptionId(nextId);
+			}}
+			onEditOption={(option) => setConfiguredOptionId(option.id)}
+			onDeleteOption={(option) => {
+				setOptionState((current) => current.filter((item) => item.id !== option.id));
+				if (configuredOptionId === option.id) {
+					setConfiguredOptionId(null);
+				}
+			}}
+			onSaveEditingOption={(option, draft: ProductOptionEditDraft) => {
+				setOptionState((current) => current.map((item) => (
+					item.id === option.id
+						? {
+							...item,
+							name: draft.name.trim() || item.name,
+							values: draft.values.map((value, index) => ({
+								...value,
+								id: value.id || `${item.id}-value-${index + 1}`,
+								label: String(value.label).trim() || `Value ${index + 1}`,
+							})),
+						}
+						: item
+				)));
+				setConfiguredOptionId(null);
+			}}
+			onCancelEditingOption={() => setConfiguredOptionId(null)}
+			onToggleUsedForVariants={(option, used) => {
+				setOptionState((current) => current.map((item) => (
+					item.id === option.id ? { ...item, usedForVariants: used } : item
+				)));
+			}}
+			onVariantFieldChange={(variant, field, value) => {
+				setVariantState((current) => updateVariantField(current, variant.id, field, value));
+			}}
+			onVariantFieldBlur={(variant, field, value) => {
+				setVariantState((current) => updateVariantField(current, variant.id, field, value.trim()));
+			}}
+			onSelectVariant={(variant) => setSelectedIds([variant.id])}
+			onEditVariant={(variant) => setSelectedIds([variant.id])}
+			onCreateVariant={() => {
+				const nextIndex = variantState.length + 1;
+				setVariantState((current) => [
+					...current,
+					{
+						id: `custom-variant-${nextIndex}`,
+						name: `Custom variant ${nextIndex}`,
+						sku: `CUSTOM-${nextIndex}`,
+						price: '0.00',
+						inventory: '0',
+						status: 'Draft',
+						statusVariant: 'secondary',
+						optionValueIds: {
+							'guest-count': 'one',
+							format: 'online',
+							'voucher-type': 'online',
+						},
+					},
+				]);
+			}}
+			onDuplicateVariant={(variant) => {
+				const nextIndex = variantState.length + 1;
+				setVariantState((current) => [
+					...current,
+					{
+						...variant,
+						id: `${variant.id}-copy-${nextIndex}`,
+						sku: `${variant.sku ?? 'SKU'}-COPY`,
+						status: 'Draft',
+						statusVariant: 'secondary',
+					},
+				]);
+			}}
+			onDeleteVariant={(variant) => {
+				setVariantState((current) => current.filter((item) => item.id !== variant.id));
+				setSelectedIds((current) => current.filter((id) => id !== variant.id));
+			}}
+			onBulkEdit={(selected) => {
+				const selectedSet = new Set(selected.map((variant) => variant.id));
+				setVariantState((current) => current.map((variant) => (
+					selectedSet.has(variant.id)
+						? { ...variant, status: 'Review', statusVariant: 'warning' }
+						: variant
+				)));
+			}}
+			onBulkApply={(selected) => {
+				const selectedSet = new Set(selected.map((variant) => variant.id));
+				setVariantState((current) => current.map((variant) => (
+					selectedSet.has(variant.id)
+						? { ...variant, status: 'Active', statusVariant: 'success' }
+						: variant
+				)));
+			}}
+			onBulkDelete={(selected) => {
+				const selectedSet = new Set(selected.map((variant) => variant.id));
+				setVariantState((current) => current.filter((variant) => !selectedSet.has(variant.id)));
+				setSelectedIds([]);
+			}}
+			strings={{
+				title: 'Variants',
+				description: '',
+			}}
+			variantsStrings={{
+				bulkApplyLabel: 'Mark active',
+			}}
+		/>
+	);
+}
+
+export function VariantTableControls() {
+	const [rows, setRows] = useState<ProductVariantRow[]>(variantRows.slice(0, 5));
+
+	return (
+		<ProductVariantsBulkTable
+			variants={rows}
+			optionGroups={optionGroups}
+			optionCombinationDisplay="tags"
+			selectionMode="none"
+			cellDisplay={{ sku: 'field', price: 'field' }}
+			visibleColumns={['variant', 'sku', 'price', 'inventory', 'status', 'updated']}
+			onVariantFieldChange={(variant, field, value) => {
+				setRows((current) => updateVariantField(current, variant.id, field, value));
+			}}
+			onVariantFieldBlur={(variant, field, value) => {
+				setRows((current) => updateVariantField(current, variant.id, field, value.trim()));
+			}}
+			renderCell={(variant, context) => {
+				if (context.column === 'status') {
+					return (
+						<Badge variant={variant.statusVariant ?? 'secondary'}>
+							{variant.status ?? 'Draft'}
+						</Badge>
+					);
+				}
+
+				return undefined;
+			}}
+			strings={{
+				title: 'Variant table controls',
+				description: 'Use table-level props for read-only, editable, tag-based, or custom-rendered variant cells.',
+			}}
+		/>
+	);
+}
+```
+
+## Example exports
+
+- `VariantManagement`
+- `VariantTableControls`
+

package/.agents/skills/component-library-rules/references/components/layout__layout-auth.md

@@ -211,7 +211,7 @@ function LogoMark() {
 function Wordmark() {
 	return (
 		<div className="flex flex-col items-center gap-1 text-center">
-			<Text tag="div" className="font-serif text-2xl leading-none tracking-normal text-foreground">
+			<Text tag="div" className="font-serif text-base leading-none tracking-normal text-foreground">
 				Gift come true
 			</Text>
 			<div className="h-px w-16 bg-foreground/40" />

package/.agents/skills/component-library-rules/references/testing.md

@@ -24,7 +24,7 @@ forwards props to a primitive. You **do** need tests when:
 - The component owns business logic (a parser, formatter, async
   options hook).
 - A class name change would silently break a downstream consumer
-  (e.g. badge size class moved from `text-[10px]` to `text-xxs` —
+  (e.g. badge size class moved from `text-[10px]` to `text-xs` —
   consumers depending on the old class need a clear failure).
 
 ## Pattern: `<UIProvider>` config in tests

package/.agents/skills/token-system/SKILL.md

@@ -71,7 +71,10 @@ npx admin-ui-starter-kit-publish-theme
 
 That command publishes editable `theme.css` and a flattened `defaults.css`
 containing package-owned token layers into the consumer app. See
-`references/consumer-overrides.md` for the decision tree.
+`references/consumer-overrides.md` for the decision tree. For downstream
+consumer migrations that also need additional themes, dark-scope wiring, or
+`<UIProvider>` defaults, use
+`../admin-ui-consumer-migration/references/theme-overrides.md`.
 
 ## Checks
 

package/AGENTS.md

@@ -34,7 +34,7 @@ The architectural goals — and the reason every rule below exists — are:
    (default currency, week-start, default badge size, …) live in a
    single zustand store wrapped by `<UIProvider>` (see
    `@/lib/ui-provider`). One provider, no nesting.
-5. **Admin-density**: workhorses are `text-sm` and `text-xs`. `text-base`
+5. **Admin-density**: workhorses are `text-sm` and `text-pxs`. `text-base`
    is rare. Rows breathe at `py-2` minimum.
 6. **Visual-quality first**: every shipped surface is evaluated as a
    designer would — spacing, hierarchy, focus states, voice consistency.
@@ -373,7 +373,8 @@ When in doubt, model new work on these reference implementations:
 ## Common mistakes — don't repeat these
 
 - **`text-[10px]` / `text-[11px]` etc.** Forbidden as semantic sizes.
-  10px → `text-xxs`, 11px/13px → `text-xs`, 0.8rem → `text-xs`. The
+  10px/11px are below the admin scale; use 12px → `text-xs`, 13px → `text-pxs`,
+  14px → `text-sm`. The
   exception is density-toggled overrides in tables/calendars where the
   bespoke size is intentional and load-bearing — those are explicitly
   scoped (see the `SKIP` list in any token sweep).
@@ -448,7 +449,7 @@ When in doubt, model new work on these reference implementations:
   `--control-height`. Consumers can override them at `:root` or on a scoped
   wrapper to densify a surface.
 - **Token-driven typography** — Tailwind text utilities resolve through
-  `--text-scale` and the `--text-xxs/xs/sm/base/lg/xl/2xl` scale. Consumers
+  `--text-scale` and the `--text-xxs/xs/pxs/sm/base/lg/xl/2xl` scale. Consumers
   override `--text-scale` first, then individual text tokens only when needed.
 
 ## Commit / PR conventions

package/COMPONENT_SELECTION.md

@@ -35,6 +35,8 @@ or documented here, treat it as private.
 | Selected resource card | `ResourceSelectorCard` | `admin-ui-starter-kit/composed/data-display` |
 | Settings/security action rows and token manager | `ActionList`, `ActionRow`, `SensitiveActionCard`, `CopyableSecretAlert`, `ApiTokenManager` | `admin-ui-starter-kit/composed/admin` |
 | Commerce/order/product surfaces | commerce surfaces | `admin-ui-starter-kit/composed/commerce` |
+| Product editor, options, variants, support rail | product feature surfaces | `admin-ui-starter-kit/features/products` |
+| Search engine listing / SEO score | `SeoListingCard`, `calculateSeoListingScore` | `admin-ui-starter-kit/composed/commerce` |
 | Timeline | timeline surfaces | `admin-ui-starter-kit/composed/timelines` |
 | Comments panel | `Comments` | `admin-ui-starter-kit/features/comments` |
 | Filter bar/facets/query helpers | filters feature, `parseFiltersFromQuery`, `serializeFiltersToQuery`, `mergeFilterQuery` | `admin-ui-starter-kit/features/filters` |
@@ -128,6 +130,17 @@ Use `ResourceSelectorCard` for a selected resource inside forms, dialogs, or
 show pages. The app owns the picker overlay and routing; the card only renders
 the selected resource through accessors and calls `onSelect` / `onRemove`.
 
+Use `ProductVariantsManager` when a product editor needs option groups and a
+generated variants table with shared callbacks, selection, editable cells,
+grouping, and action menus. Use `ProductOptionsMatrix` or
+`ProductVariantsBulkTable` directly only when the app owns the surrounding card
+or needs a custom editor composition.
+
+Use `SeoListingCard` for search-engine listing previews and SEO scoring inside
+commerce/product editors. The package owns title, description, permalink, and
+keyword checks through `calculateSeoListingScore`; the app owns persistence,
+field editing, routing, and translations.
+
 Use `DataTable` selection toolbar props plus `ResourceCell`,
 `StatusClusterCell`, and `DateMetaCell` for dense index pages. Keep URL state,
 sorting persistence, row navigation, and data fetching in the app.
@@ -185,6 +198,8 @@ import { Button } from 'admin-ui-starter-kit/base/buttons';
 import { Text } from 'admin-ui-starter-kit/typography';
 import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
 import { MetadataList } from 'admin-ui-starter-kit/composed/data-display';
+import { SeoListingCard } from 'admin-ui-starter-kit/composed/commerce';
+import { ProductVariantsManager } from 'admin-ui-starter-kit/features/products';
 ```
 
 Do not use:

package/INTEGRATION.md

@@ -46,10 +46,12 @@ import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
 import { MetadataList } from 'admin-ui-starter-kit/composed/data-display';
 import { ChartCard } from 'admin-ui-starter-kit/composed/analytics';
 import { ActionList, ApiTokenManager } from 'admin-ui-starter-kit/composed/admin';
+import { SeoListingCard } from 'admin-ui-starter-kit/composed/commerce';
 import { ResourceSelectorCard } from 'admin-ui-starter-kit/composed/data-display';
 import { Comments } from 'admin-ui-starter-kit/features/comments';
 import { mergeFilterQuery, parseFiltersFromQuery, serializeFiltersToQuery } from 'admin-ui-starter-kit/features/filters';
 import { MediaLibraryDialog } from 'admin-ui-starter-kit/features/media-library';
+import { ProductVariantsManager } from 'admin-ui-starter-kit/features/products';
 import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
 import { AuthShell } from 'admin-ui-starter-kit/layout/auth';
 import { PageHeader } from 'admin-ui-starter-kit/layout/page';
@@ -108,6 +110,14 @@ Common primitive choices:
   `ApiTokenManager` for selected-resource, settings, security, and token
   management surfaces. Persistence and confirmation behavior stay callback
   driven.
+- Use `SeoListingCard` from `admin-ui-starter-kit/composed/commerce` for
+  search-engine listing previews and scoring. The package owns the title,
+  description, permalink, and keyword checks; the app owns field editing,
+  persistence, routes, and translations.
+- Use `ProductVariantsManager` from
+  `admin-ui-starter-kit/features/products` for product option and variant
+  editors. Use `ProductOptionsMatrix` and `ProductVariantsBulkTable` directly
+  only when the app owns the surrounding layout.
 - Use `SchemaForm` from `admin-ui-starter-kit/features/schema-form` when the
   app already has backend-provided field definitions, tenant settings, or
   integration configuration that should render as a cohesive form or section
@@ -171,8 +181,9 @@ layers. Keep the split clear when overriding them:
 
 For product-wide scale changes, override `--text-scale`, `--space-scale`, and
 `--density-scale` first. Use public structural variables such as
-`--control-height`, `--control-x`, `--row-y`, `--surface-x`, `--icon`,
-`--avatar`, and `--shell-sidebar-width` only when the scale knobs are too broad.
+`--height-control`, `--height-action`, `--control-x`, `--row-y`,
+`--surface-x`, `--icon`, `--avatar`, and `--shell-sidebar-width` only when the
+scale knobs are too broad.
 Use the package utilities (`h-control`, `px-control`, `gap-space-md`,
 `py-row-y`, `px-surface`, `size-icon`, `size-avatar`) instead of arbitrary
 `text-[...]`, `gap-[...]`, `px-[...]`, or `size-[...]` values for ordinary
@@ -199,6 +210,34 @@ token layers. Import
 overrides. Use `source.css` only when the app intentionally rebuilds Tailwind
 instead of importing `admin-ui-starter-kit/style.css`.
 
+### Additional themes and dark scopes
+
+Define extra brand themes by scoping shadcn-compatible variables and structural
+tokens on an app-owned selector:
+
+```css
+[data-theme='acme'] {
+	--primary: oklch(0.48 0.14 165);
+	--primary-foreground: oklch(0.99 0 0);
+	--background: oklch(1 0 0);
+	--foreground: oklch(0.24 0 0);
+	--surface-x: calc(1rem * var(--space-scale));
+	--shell-sidebar-width: 17rem;
+}
+
+[data-theme='acme'].dark,
+.dark [data-theme='acme'] {
+	--background: oklch(0.22 0 0);
+	--foreground: oklch(0.98 0 0);
+	--card: oklch(0.18 0 0);
+	--border: oklch(1 0 0 / 12%);
+}
+```
+
+If the app relies on package `dark:` utilities, place `.dark` on or above the
+theme scope. A `data-theme='dark'` attribute changes variables but does not
+activate Tailwind's `.dark *` selectors by itself.
+
 ## 4. Wire frameworks at the call site
 
 The library never imports routing, query, backend, or i18n integrations.