npm - stitch-kit - Versions diffs - 1.5.0 - Mend

stitch-kit 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/AGENTS.md +139 -0
package/CHANGELOG.md +86 -0
package/README.md +167 -0
package/agents/stitch-kit.md +93 -0
package/bin/stitch-kit.mjs +430 -0
package/docs/architecture.md +118 -0
package/docs/color-prompt-guide.md +119 -0
package/docs/mcp-naming-convention.md +64 -0
package/docs/mcp-schemas/README.md +130 -0
package/docs/mcp-schemas/apply_design_system.json +36 -0
package/docs/mcp-schemas/create_design_system.json +78 -0
package/docs/mcp-schemas/create_project.json +290 -0
package/docs/mcp-schemas/delete_project.json +20 -0
package/docs/mcp-schemas/edit_screens.json +46 -0
package/docs/mcp-schemas/generate_screen_from_text.json +242 -0
package/docs/mcp-schemas/generate_variants.json +77 -0
package/docs/mcp-schemas/get_project.json +137 -0
package/docs/mcp-schemas/get_screen.json +92 -0
package/docs/mcp-schemas/list_design_systems.json +32 -0
package/docs/mcp-schemas/list_projects.json +136 -0
package/docs/mcp-schemas/list_screens.json +56 -0
package/docs/mcp-schemas/update_design_system.json +32 -0
package/docs/mcp-schemas/upload_screens_from_images.json +52 -0
package/docs/prd-to-stitch-workflow.md +137 -0
package/docs/skills-index.md +108 -0
package/docs/tailwind-reference.md +207 -0
package/package.json +41 -0
package/skills/stitch-a11y/SKILL.md +428 -0
package/skills/stitch-a11y/resources/audit-checklist.md +102 -0
package/skills/stitch-animate/SKILL.md +371 -0
package/skills/stitch-animate/resources/animation-patterns.md +248 -0
package/skills/stitch-design-md/SKILL.md +215 -0
package/skills/stitch-design-md/examples/DESIGN.md +54 -0
package/skills/stitch-design-md/examples/usage.md +67 -0
package/skills/stitch-design-md/scripts/fetch-stitch.sh +35 -0
package/skills/stitch-design-system/SKILL.md +314 -0
package/skills/stitch-design-system/resources/tokens-template.css +237 -0
package/skills/stitch-html-components/SKILL.md +344 -0
package/skills/stitch-html-components/resources/architecture-checklist.md +74 -0
package/skills/stitch-html-components/scripts/fetch-stitch.sh +45 -0
package/skills/stitch-loop/SKILL.md +183 -0
package/skills/stitch-loop/examples/SITE.md +39 -0
package/skills/stitch-loop/examples/next-prompt.md +24 -0
package/skills/stitch-loop/examples/usage.md +77 -0
package/skills/stitch-mcp-apply-design-system/SKILL.md +82 -0
package/skills/stitch-mcp-create-design-system/SKILL.md +117 -0
package/skills/stitch-mcp-create-project/SKILL.md +77 -0
package/skills/stitch-mcp-delete-project/SKILL.md +62 -0
package/skills/stitch-mcp-edit-screens/SKILL.md +121 -0
package/skills/stitch-mcp-generate-screen-from-text/SKILL.md +102 -0
package/skills/stitch-mcp-generate-screen-from-text/examples/desktop.md +53 -0
package/skills/stitch-mcp-generate-screen-from-text/examples/mobile.md +71 -0
package/skills/stitch-mcp-generate-variants/SKILL.md +124 -0
package/skills/stitch-mcp-get-project/SKILL.md +67 -0
package/skills/stitch-mcp-get-screen/SKILL.md +117 -0
package/skills/stitch-mcp-get-screen/scripts/fetch-stitch.sh +35 -0
package/skills/stitch-mcp-list-design-systems/SKILL.md +84 -0
package/skills/stitch-mcp-list-projects/SKILL.md +77 -0
package/skills/stitch-mcp-list-screens/SKILL.md +69 -0
package/skills/stitch-mcp-update-design-system/SKILL.md +82 -0
package/skills/stitch-mcp-upload-screens-from-images/SKILL.md +95 -0
package/skills/stitch-mcp-upload-screens-from-images/scripts/encode-image.sh +43 -0
package/skills/stitch-nextjs-components/SKILL.md +181 -0
package/skills/stitch-nextjs-components/resources/architecture-checklist.md +65 -0
package/skills/stitch-nextjs-components/resources/component-template.tsx +101 -0
package/skills/stitch-nextjs-components/scripts/fetch-stitch.sh +45 -0
package/skills/stitch-orchestrator/SKILL.md +337 -0
package/skills/stitch-orchestrator/examples/workflow.md +173 -0
package/skills/stitch-react-components/SKILL.md +236 -0
package/skills/stitch-react-components/references/tailwind-to-react.md +117 -0
package/skills/stitch-react-components/resources/architecture-checklist.md +34 -0
package/skills/stitch-react-components/resources/component-template.tsx +35 -0
package/skills/stitch-react-components/scripts/fetch-stitch.sh +35 -0
package/skills/stitch-react-native-components/SKILL.md +333 -0
package/skills/stitch-react-native-components/resources/architecture-checklist.md +74 -0
package/skills/stitch-react-native-components/resources/component-template.tsx +104 -0
package/skills/stitch-react-native-components/scripts/fetch-stitch.sh +45 -0
package/skills/stitch-remotion/SKILL.md +280 -0
package/skills/stitch-setup/SKILL.md +183 -0
package/skills/stitch-shadcn-ui/SKILL.md +255 -0
package/skills/stitch-skill-creator/SKILL.md +257 -0
package/skills/stitch-skill-creator/references/output-patterns.md +71 -0
package/skills/stitch-skill-creator/scripts/init_stitch_skill.py +229 -0
package/skills/stitch-svelte-components/SKILL.md +282 -0
package/skills/stitch-svelte-components/resources/architecture-checklist.md +62 -0
package/skills/stitch-svelte-components/resources/component-template.svelte +193 -0
package/skills/stitch-svelte-components/scripts/fetch-stitch.sh +36 -0
package/skills/stitch-swiftui-components/SKILL.md +424 -0
package/skills/stitch-swiftui-components/resources/architecture-checklist.md +83 -0
package/skills/stitch-swiftui-components/resources/component-template.swift +131 -0
package/skills/stitch-swiftui-components/resources/layout-mapping.md +155 -0
package/skills/stitch-swiftui-components/scripts/fetch-stitch.sh +45 -0
package/skills/stitch-ued-guide/SKILL.md +124 -0
package/skills/stitch-ui-design-spec-generator/SKILL.md +115 -0
package/skills/stitch-ui-design-spec-generator/examples/usage.md +79 -0
package/skills/stitch-ui-design-variants/SKILL.md +127 -0
package/skills/stitch-ui-prompt-architect/SKILL.md +196 -0
package/skills/stitch-ui-prompt-architect/references/KEYWORDS.md +170 -0

package/skills/stitch-design-system/SKILL.md ADDED Viewed

@@ -0,0 +1,314 @@
+---
+name: stitch-design-system
+description: Extracts a Stitch design and generates production code artifacts — CSS custom properties with dark mode tokens, a Tailwind v4 @theme block, and a semantic design system document. Run this before framework conversion skills.
+allowed-tools:
+  - "stitch*:*"
+  - "Bash"
+  - "Read"
+  - "Write"
+---
+# Stitch → Design System Code Artifacts
+You are a design systems engineer. You analyze Stitch designs and generate **code artifacts** — not just documentation. While the `design-md` skill produces a human-readable markdown file, this skill produces files you actually import into your codebase: CSS custom properties with dark mode, Tailwind v4 configuration, and typography tokens.
+**Use this skill first, before `stitch-nextjs-components` or `stitch-svelte-components`.** The generated tokens become the foundation for all subsequent component generation.
+## When to use this skill
+Use this skill when:
+- Starting a new project from a Stitch design
+- The user mentions "design tokens", "CSS variables", "dark mode tokens", "Tailwind config"
+- Running before framework conversion skills to ensure design consistency
+- Updating an existing project's design system after a Stitch design update
+## What this skill generates
+Three output files:
+| File | Purpose |
+|------|---------|
+| `design-tokens.css` | CSS custom properties — import this in your framework's global CSS |
+| `tailwind-theme.css` | Tailwind v4 `@theme` block — paste into your `globals.css` |
+| `DESIGN.md` | Extended design document (richer than `design-md`, includes dark mode + animation tokens) |
+## Step 1: Retrieve the Stitch design
+1. **Namespace discovery** — Run `list_tools` to find the Stitch MCP prefix.
+2. **Fetch screen** — Call `[prefix]:get_screen` with `projectId` and `screenId`.
+3. **Download HTML** — Run:
+   ```bash
+   bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
+   ```
+4. **Visual reference** — Check `screenshot.downloadUrl` to see the full design intent.
+If multiple screens exist, retrieve all of them. Run `[prefix]:list_screens` and fetch each one to ensure the token set covers every pattern in the design.
+## Step 2: Extract raw design values
+From the Stitch HTML and screenshot, extract:
+### Colors
+Identify every distinct color. For each, determine:
+- **Exact hex value** (from Tailwind config in `<head>`, or infer from screenshot)
+- **Semantic role**: What does this color DO? (primary action, surface, text, border, error, success...)
+- **Usage frequency**: How dominant is it?
+Aim for 8-12 semantic tokens, not 50 specific shades.
+### Typography
+- Font families (heading, body, mono — if present)
+- Type scale sizes (the actual `px` or `rem` values used in the design)
+- Font weights used
+- Line heights
+### Spacing & geometry
+- Base spacing unit (usually 4px or 8px)
+- Border radius values
+- Shadow definitions
+### Motion
+- Transition durations used (or infer: 150ms for micro, 300ms for panels)
+- Easing styles (linear, ease-out, spring-like)
+## Step 3: Generate `design-tokens.css`
+Create `design-tokens.css` with full light + dark mode token sets.
+**Naming convention:**
+- `--color-*` — Color tokens
+- `--font-*` — Typography
+- `--spacing-*` — Spacing scale
+- `--radius-*` — Border radius
+- `--shadow-*` — Elevation
+- `--motion-*` — Animation timing
+**Template:**
+```css
+/* =============================================================
+   Design Tokens — extracted from Stitch project: [Project Name]
+   Generated by stitch-design-system skill
+   ============================================================= */
+/* ---- Light mode (default) ---- */
+:root {
+  /* Colors: Semantic roles, not visual names */
+  --color-background:       [hex];  /* Page background */
+  --color-surface:          [hex];  /* Card, panel backgrounds */
+  --color-surface-elevated: [hex];  /* Tooltip, dropdown backgrounds */
+  --color-primary:          [hex];  /* Primary CTA, key actions */
+  --color-primary-hover:    [hex];  /* Primary at hover state */
+  --color-primary-fg:       [hex];  /* Text/icon on primary bg */
+  --color-secondary:        [hex];  /* Secondary actions, accents */
+  --color-secondary-fg:     [hex];  /* Text/icon on secondary bg */
+  --color-text:             [hex];  /* Body text */
+  --color-text-muted:       [hex];  /* Secondary, supporting text */
+  --color-text-disabled:    [hex];  /* Disabled element text */
+  --color-border:           [hex];  /* Dividers, input borders */
+  --color-border-focus:     [hex];  /* Focus ring color */
+  --color-error:            [hex];  /* Error states */
+  --color-success:          [hex];  /* Success states */
+  --color-warning:          [hex];  /* Warning states */
+  /* Typography */
+  --font-sans:    [font-family-stack];   /* Heading and UI font */
+  --font-body:    [font-family-stack];   /* Body text font (may equal --font-sans) */
+  --font-mono:    [monospace-stack];     /* Code, technical content */
+  /* Type scale */
+  --text-xs:   0.75rem;   /* 12px */
+  --text-sm:   0.875rem;  /* 14px */
+  --text-base: 1rem;      /* 16px */
+  --text-lg:   1.125rem;  /* 18px */
+  --text-xl:   1.25rem;   /* 20px */
+  --text-2xl:  1.5rem;    /* 24px */
+  --text-3xl:  1.875rem;  /* 30px */
+  --text-4xl:  2.25rem;   /* 36px */
+  /* Spacing scale (base 4px) */
+  --space-1:  0.25rem;   /* 4px */
+  --space-2:  0.5rem;    /* 8px */
+  --space-3:  0.75rem;   /* 12px */
+  --space-4:  1rem;      /* 16px */
+  --space-6:  1.5rem;    /* 24px */
+  --space-8:  2rem;      /* 32px */
+  --space-12: 3rem;      /* 48px */
+  --space-16: 4rem;      /* 64px */
+  /* Geometry */
+  --radius-sm: [value];  /* Small elements: badges, chips */
+  --radius-md: [value];  /* Buttons, inputs */
+  --radius-lg: [value];  /* Cards, panels */
+  --radius-xl: [value];  /* Modals, drawers */
+  --radius-full: 9999px; /* Pills, avatars */
+  /* Shadows */
+  --shadow-sm: [value];  /* Subtle card lift */
+  --shadow-md: [value];  /* Dropdown, tooltip */
+  --shadow-lg: [value];  /* Modal, sheet */
+  /* Motion tokens */
+  --motion-duration-fast:   150ms;   /* Hover states, micro interactions */
+  --motion-duration-base:   250ms;   /* Typical UI transitions */
+  --motion-duration-slow:   400ms;   /* Page-level, large panel */
+  --motion-ease-default:    cubic-bezier(0.4, 0, 0.2, 1);  /* Material ease */
+  --motion-ease-out:        cubic-bezier(0, 0, 0.2, 1);    /* Entries */
+  --motion-ease-in:         cubic-bezier(0.4, 0, 1, 1);    /* Exits */
+  --motion-ease-spring:     cubic-bezier(0.34, 1.56, 0.64, 1); /* Bouncy open */
+}
+/* ---- Dark mode ---- */
+/* Applied via .dark class (Next.js + next-themes) or [data-theme="dark"] (Svelte) */
+.dark,
+[data-theme="dark"] {
+  --color-background:       [dark-hex];
+  --color-surface:          [dark-hex];
+  --color-surface-elevated: [dark-hex];
+  --color-primary:          [dark-hex];  /* Same hue, lighter for dark bg contrast */
+  --color-primary-hover:    [dark-hex];
+  --color-primary-fg:       [dark-hex];
+  --color-secondary:        [dark-hex];
+  --color-secondary-fg:     [dark-hex];
+  --color-text:             [dark-hex];
+  --color-text-muted:       [dark-hex];
+  --color-text-disabled:    [dark-hex];
+  --color-border:           [dark-hex];
+  --color-border-focus:     [dark-hex];
+  --color-error:            [dark-hex];
+  --color-success:          [dark-hex];
+  --color-warning:          [dark-hex];
+  /* Typography, spacing, geometry, motion tokens: unchanged in dark mode */
+}
+```
+## Step 4: Generate `tailwind-theme.css`
+For projects using **Tailwind v4** (no `tailwind.config.js`), generate a `@theme` block.
+**Important:** Tailwind v4 uses `@theme` in CSS, not a JS config file. Map tokens to Tailwind's namespace:
+```css
+/* tailwind-theme.css — paste into your globals.css or import it */
+@import "tailwindcss";
+@theme {
+  /* Wire Tailwind color utilities to your CSS variables */
+  --color-background: var(--color-background);
+  --color-surface: var(--color-surface);
+  --color-primary: var(--color-primary);
+  --color-primary-hover: var(--color-primary-hover);
+  --color-text: var(--color-text);
+  --color-text-muted: var(--color-text-muted);
+  --color-border: var(--color-border);
+  /* Fonts */
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+  /* Radius */
+  --radius-sm: var(--radius-sm);
+  --radius-md: var(--radius-md);
+  --radius-lg: var(--radius-lg);
+  /* Animation duration utilities */
+  --animate-duration-fast: var(--motion-duration-fast);
+  --animate-duration-base: var(--motion-duration-base);
+  --animate-duration-slow: var(--motion-duration-slow);
+}
+```
+For **Tailwind v3** projects (with `tailwind.config.js`), instead generate a `tailwind.config.js` section using the extracted hex values directly.
+## Step 5: Generate `DESIGN.md`
+Produce an extended design document. It has all sections from the standard `design-md` skill plus:
+```markdown
+# Design System: [Project Name]
+> Generated by stitch-design-system from Stitch project [ID]
+> Screens analyzed: [list]
+## 1. Visual Theme & Atmosphere
+[Mood, density, aesthetic philosophy — 2-3 sentences]
+## 2. Color Palette & Roles
+| Token | Light | Dark | Role |
+|-------|-------|------|------|
+| --color-primary | #... | #... | Main CTA, key actions |
+| --color-background | #... | #... | Page background |
+| ... | | | |
+## 3. Typography
+- **Heading font**: [Family, weights used, where]
+- **Body font**: [Family, weights used, where]
+- **Type scale**: xs (12px) → sm (14px) → base (16px) → lg (18px) → ... → 4xl (36px)
+## 4. Geometry & Elevation
+- **Border radius**: sm [Xpx] | md [Xpx] | lg [Xpx] | xl [Xpx]
+- **Shadows**: [describe the elevation system]
+## 5. Motion System
+- **Micro** (hovers, toggles): [duration]ms [easing]
+- **Meso** (panels, drawers): [duration]ms [easing]
+- **Macro** (page transitions): [duration]ms [easing]
+- **Spring** (playful elements): cubicOut spring
+## 6. Stitch Prompt Copy-Paste Block
+Use this block in every Stitch prompt for design consistency:
+```
+[Primary color: NAME (#HEX)] — used for buttons and key actions
+[Background: #HEX] — clean and [mood adjective]
+[Typography: FONT NAME] — [weight] weight for headings, regular for body
+[Aesthetic: 2-3 adjectives describing the visual style]
+[Border radius: SIZE — rounded/sharp/pill-shaped elements]
+```
+## 7. Dark Mode Notes
+[Specific notes on how the dark theme differs — any color roles that change significantly, any elements that need special treatment in dark mode]
+```
+## Step 6: Output & integration
+Write all three files to the project root (or wherever the user specifies):
+- `design-tokens.css`
+- `tailwind-theme.css`
+- `DESIGN.md`
+Then tell the user how to use them:
+**For Next.js:**
+```tsx
+// app/globals.css
+@import '../design-tokens.css';
+@import '../tailwind-theme.css';
+```
+**For SvelteKit:**
+```svelte
+<!-- src/app.css -->
+@import '$lib/design-tokens.css';
+```
+**For the Stitch loop:**
+> Copy Section 6 from `DESIGN.md` into every Stitch prompt to maintain design consistency across generated screens.
+## Troubleshooting
+| Issue | Fix |
+|-------|-----|
+| Can't determine dark mode hex values | Use the light-mode hue, desaturate slightly, and increase lightness by 30-40% |
+| Font not loading | Add Google Fonts `@import` to `design-tokens.css` |
+| Tailwind v3 vs v4 confusion | Check `package.json` — v4 uses `"tailwindcss": "^4"` and no config file |
+| Tokens not applying | Ensure `design-tokens.css` is imported BEFORE component CSS |
+## Integration with other skills
+- Run this skill **before** `stitch-nextjs-components` or `stitch-svelte-components`
+- The framework skills will import `design-tokens.css` instead of hardcoding values
+- The `DESIGN.md` Section 6 feeds into `stitch-loop` for multi-page consistency
+## References
+- `resources/tokens-template.css` — Full template with all token categories

package/skills/stitch-design-system/resources/tokens-template.css ADDED Viewed

@@ -0,0 +1,237 @@
+/* =============================================================
+   Design Tokens — Template
+   Copy this file, fill in the values from your Stitch design,
+   and save as design-tokens.css in your project root.
+   Usage:
+     Next.js:   @import '../design-tokens.css'; in app/globals.css
+     SvelteKit: @import '$lib/design-tokens.css'; in src/app.css
+   ============================================================= */
+/* ---- Google Fonts (update to match your Stitch design) ---- */
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+/* ---- Light mode (default) ---- */
+:root {
+  /* ── Colors ── */
+  /* Backgrounds */
+  --color-background:       ;  /* Page/app background */
+  --color-surface:          ;  /* Card, panel, input backgrounds */
+  --color-surface-elevated: ;  /* Tooltip, popover, dropdown */
+  /* Brand */
+  --color-primary:          ;  /* Main CTA, links, key actions */
+  --color-primary-hover:    ;  /* Primary at :hover */
+  --color-primary-active:   ;  /* Primary at :active */
+  --color-primary-fg:       ;  /* Text/icon on primary background */
+  --color-secondary:        ;  /* Secondary actions, tags, accents */
+  --color-secondary-hover:  ;
+  --color-secondary-fg:     ;  /* Text/icon on secondary background */
+  /* Text */
+  --color-text:             ;  /* Default body text */
+  --color-text-muted:       ;  /* Captions, helper text, placeholders */
+  --color-text-disabled:    ;  /* Disabled state text */
+  --color-text-inverse:     ;  /* Text on dark backgrounds */
+  /* Borders */
+  --color-border:           ;  /* Default dividers, input borders */
+  --color-border-strong:    ;  /* Emphasized separators */
+  --color-border-focus:     ;  /* Focus ring color */
+  /* Status */
+  --color-error:            ;
+  --color-error-bg:         ;  /* Error message background */
+  --color-success:          ;
+  --color-success-bg:       ;  /* Success message background */
+  --color-warning:          ;
+  --color-warning-bg:       ;  /* Warning message background */
+  --color-info:             ;
+  /* ── Typography ── */
+  --font-sans:   'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-body:   var(--font-sans);    /* Often same as sans; separate if design uses different body font */
+  --font-mono:   ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, monospace;
+  /* Type scale */
+  --text-xs:   0.75rem;     /* 12px */
+  --text-sm:   0.875rem;    /* 14px */
+  --text-base: 1rem;        /* 16px — body default */
+  --text-lg:   1.125rem;    /* 18px */
+  --text-xl:   1.25rem;     /* 20px */
+  --text-2xl:  1.5rem;      /* 24px */
+  --text-3xl:  1.875rem;    /* 30px */
+  --text-4xl:  2.25rem;     /* 36px */
+  --text-5xl:  3rem;        /* 48px */
+  /* Font weights */
+  --weight-regular:   400;
+  --weight-medium:    500;
+  --weight-semibold:  600;
+  --weight-bold:      700;
+  /* Line heights */
+  --leading-tight:   1.25;
+  --leading-normal:  1.5;
+  --leading-relaxed: 1.625;
+  /* ── Spacing ── */
+  /* Base unit: 4px. Scale: 1=4px, 2=8px, 3=12px, 4=16px, 6=24px, 8=32px, 12=48px, 16=64px */
+  --space-px:  1px;
+  --space-0-5: 0.125rem;  /* 2px */
+  --space-1:   0.25rem;   /* 4px */
+  --space-2:   0.5rem;    /* 8px */
+  --space-3:   0.75rem;   /* 12px */
+  --space-4:   1rem;      /* 16px */
+  --space-5:   1.25rem;   /* 20px */
+  --space-6:   1.5rem;    /* 24px */
+  --space-8:   2rem;      /* 32px */
+  --space-10:  2.5rem;    /* 40px */
+  --space-12:  3rem;      /* 48px */
+  --space-16:  4rem;      /* 64px */
+  --space-20:  5rem;      /* 80px */
+  --space-24:  6rem;      /* 96px */
+  /* ── Geometry ── */
+  --radius-none: 0;
+  --radius-sm:   ;    /* e.g. 4px — small elements */
+  --radius-md:   ;    /* e.g. 8px — buttons, inputs */
+  --radius-lg:   ;    /* e.g. 12px — cards */
+  --radius-xl:   ;    /* e.g. 16px — modals, sheets */
+  --radius-2xl:  ;    /* e.g. 24px — large panels */
+  --radius-full: 9999px;  /* Pills, circles */
+  /* ── Shadows (Elevation) ── */
+  --shadow-none:  none;
+  --shadow-sm:    0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+  --shadow-md:    0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
+  --shadow-lg:    0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
+  --shadow-xl:    0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
+  --shadow-inner: inset 0 2px 4px 0 rgb(0 0 0 / 0.05);
+  /* ── Motion ── */
+  --motion-duration-instant: 0ms;
+  --motion-duration-fast:    150ms;   /* Hovers, toggles, micro interactions */
+  --motion-duration-base:    250ms;   /* Standard UI transitions */
+  --motion-duration-slow:    400ms;   /* Page elements, larger panels */
+  --motion-duration-slower:  600ms;   /* Significant page transitions */
+  --motion-ease-linear:  linear;
+  --motion-ease-default: cubic-bezier(0.4, 0, 0.2, 1);   /* Standard — most interactions */
+  --motion-ease-in:      cubic-bezier(0.4, 0, 1, 1);      /* Exits — element leaving */
+  --motion-ease-out:     cubic-bezier(0, 0, 0.2, 1);      /* Entries — element appearing */
+  --motion-ease-spring:  cubic-bezier(0.34, 1.56, 0.64, 1); /* Playful bounce */
+  /* ── Z-Index ── */
+  --z-base:    0;
+  --z-raised:  10;
+  --z-dropdown: 100;
+  --z-sticky:   200;
+  --z-overlay:  300;
+  --z-modal:    400;
+  --z-toast:    500;
+  --z-tooltip:  600;
+}
+/* ---- Dark mode ---- */
+/* Applied via:
+   - .dark class on <html> (Next.js + next-themes)
+   - [data-theme="dark"] on <html> (Svelte)
+   Only override color tokens — spacing, typography, motion stay the same. */
+.dark,
+[data-theme="dark"] {
+  /* Backgrounds */
+  --color-background:       ;
+  --color-surface:          ;
+  --color-surface-elevated: ;
+  /* Brand — typically same hue, adjusted lightness for dark bg */
+  --color-primary:          ;
+  --color-primary-hover:    ;
+  --color-primary-active:   ;
+  --color-primary-fg:       ;
+  --color-secondary:        ;
+  --color-secondary-hover:  ;
+  --color-secondary-fg:     ;
+  /* Text */
+  --color-text:             ;
+  --color-text-muted:       ;
+  --color-text-disabled:    ;
+  --color-text-inverse:     ;
+  /* Borders */
+  --color-border:           ;
+  --color-border-strong:    ;
+  --color-border-focus:     ;
+  /* Status — may need adjusted for dark bg visibility */
+  --color-error:            ;
+  --color-error-bg:         ;
+  --color-success:          ;
+  --color-success-bg:       ;
+  --color-warning:          ;
+  --color-warning-bg:       ;
+  --color-info:             ;
+}
+/* ---- Accessibility utilities ---- */
+/* Visually hidden but readable by screen readers */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+/* Skip navigation link */
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  top: auto;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+}
+.skip-link:focus {
+  position: fixed;
+  top: 1rem;
+  left: 1rem;
+  width: auto;
+  height: auto;
+  padding: 0.5rem 1rem;
+  background: var(--color-primary);
+  color: var(--color-primary-fg);
+  border-radius: var(--radius-md);
+  font-weight: var(--weight-semibold);
+  z-index: var(--z-tooltip);
+}
+/* ---- Global focus ring ---- */
+/* Visible on keyboard focus only — not mouse click */
+*:focus-visible {
+  outline: 2px solid var(--color-border-focus);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+/* ---- Reduced motion ---- */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}