fractalstyler2 0.4.0 → 0.7.0

package/README.md

@@ -1,145 +1,164 @@
-# fractalstyler2
+# Fractalstyler
 
-A fractal-composition styling system for SvelteKit. **Every style unit is a SASS mixin ("a fractal"), and components and layouts are recipes of smaller fractals.**
+> **A composition styling system — plain CSS or editable SASS — with a fluid design token engine and a runtime preset architecture.**
+>
+> The class registry is the public API. You compose in markup; you do not write a stylesheet.
 
-Use it either as a **shadcn-style scaffolder** (copying editable SASS directly into your project's `src/lib/styles`) or as a **direct package dependency**.
+[![npm version](https://img.shields.io/npm/v/fractalstyler2.svg?style=flat-square)](https://www.npmjs.com/package/fractalstyler2)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
----
+Every styling decision in `Fractalstyler` is a modular fractal: unitary tokens, dimensions, and container primitives that compose into higher layers while retaining mathematical harmony, responsiveness, and zero-runtime bloat.
 
-## Quickstart (shadcn-style Scaffolding)
+Ships two ways, from one source:
 
-Scaffold the complete, customizable SASS design system directly into your project:
+| | | |
+|:--|:--|:--|
+| **Plain CSS** | one file, no toolchain | `npx fractalstyler2 init --css` |
+| **SASS** | editable partials, retunable generators | `npx fractalstyler2 init` |
 
-```bash
-# Scaffold into src/lib/styles
-npx fractalstyler2 init
+The compiled CSS is emitted from the same partials the SASS path scaffolds, so
+the two are byte-identical. SASS buys exactly one thing: the ability to retune
+the generators — the literal ladder and the responsive seam — before compiling.
+
+---
 
-# Or using pnpm
-pnpm --package=fractalstyler2 dlx fractalstyler2 init
+## The Fractal Mental Model
+
+```
+Tokens (L0) ──► Dimensions (L1) ──► Containers (L2) ──► Layouts (L3) ──► Shells (L4) ──► Visuals (L5)
 ```
 
-### Next Steps in Your Project
+1. **Tokens (L0)**: 31 semantic colour tokens, 41 themes, and fluid Utopia typography/space scales.
+2. **Dimensions (L1)**: 17 space families (`.gap-sm`, `.pad-md`, `.marg-xs`), negative margins (`.marg--sm`), literal pixel utilities (`.w-120`, `.radius-8`), and `-mob` / `-desk` bands.
+3. **Containers (L2)**: Flexible flow primitives (`.box`, `.row`, `.grid`) with strict physical X/Y axis alignment (`.xcenter`, `.ycenter`, `.xbetween`).
+4. **Layouts (L3)**: Gridding Golden Rules ($3\to1$, $4\to2\to1$, $6\to3\to2\to1$), `.card-grid`, reading measure `.prose`, and scroll-snap `.reel`.
+5. **Shells (L4)**: Full application frames (`.app-shell`, `.app-header`, `.app-main`, `.sidebar-left`, `.sidebar-right`, `.page-split`, `.drawer`, `.dialog`, `.popover`, `.accordion`).
+6. **Visuals & Interactions (L5)**: Bare surfaces (`.bg`, `.surface`, `.raised`), text inks, 1px hairline borders, the button quartet (`.primary`, `.ghost`, `.active`, `.is-icon`), and form controls (`.input`, `.select`).
 
-**1. Import the stylesheet once globally in your root `src/routes/+layout.svelte`:**
-```svelte
-<script>
-	import '$lib/styles/index.sass';
-</script>
+---
+
+## Quick Start
+
+### Plain CSS — no build step
+
+Most projects want this. One stylesheet, nothing to configure:
+
+```bash
+npx fractalstyler2 init --css
 ```
 
-**2. Compose your components using the pure mixin barrel:**
-```svelte
-<div class="pricing-card">
-	<span class="badge" data-status="released">Pro Plan</span>
-	<h3>$29/mo</h3>
-	<p>Full access to all fractal components and layouts.</p>
-</div>
-
-<style lang="sass">
-	@use '$lib/styles/fractals' as *
-
-	.pricing-card
-		+surface(surface, m, 6, md)    // bg + border + radius(6px) + padding + shadow
-		+stack(s, start)               // flex-column + gap(s) + top-anchored flow
-</style>
+```html
+<link rel="stylesheet" href="/src/styles/fractalstyler.css" />
 ```
 
----
+Themes and the four preset axes are classes and attributes, so they work with
+JavaScript disabled:
 
-## Alternative: Direct Package Dependency
+```html
+<html class="theme-night-dark" data-mode="dark" data-shape="sharp">
+```
 
-If you prefer importing from `node_modules` instead of scaffolding local files:
+For runtime switching and zero-flicker restore, there is a framework-free
+runtime at `fractalstyler2/presets`:
+
+```js
+import { initPresets, setPreset, getPresetScript } from 'fractalstyler2/presets';
+initPresets();
+```
+
+### SASS — if you want to retune the generators
 
 ```bash
-pnpm add fractalstyler2
-pnpm add -D sass
+pnpm add -D sass fractalstyler2
+npx fractalstyler2 init
 ```
 
-### Use from `node_modules`:
+In your root layout (`src/routes/+layout.svelte`):
 
 ```svelte
-<script>
-	import 'fractalstyler2/styles';
+<script lang="ts">
+  import 'fractalstyler2/styles';
+  import { initPresets, getPresetScript } from 'fractalstyler2';
+  import { onMount } from 'svelte';
+
+  let { children } = $props();
+
+  onMount(() => {
+    initPresets();
+  });
 </script>
 
-<style lang="sass">
-	@use 'fractalstyler2/fractals' as *
+<svelte:head>
+  {@html `<script>${getPresetScript()}</script>`}
+</svelte:head>
 
-	.card
-		+surface(surface, s, 6)
-		+stack(s)
-</style>
+{@render children()}
 ```
 
 ---
 
-## The Physical Scale Hierarchy
+## The Four Preset Tuning Axes
 
-The design system files in `src/lib/styles/` are numbered sequentially from indivisible math to page layouts:
+Fractalstyler includes a runtime tuning engine governing four fundamental aesthetic axes:
 
+```html
+<!-- HTML root attribute contract -->
+<html data-layout="tight" data-shape="sharp" data-color="clean" data-motion="active">
 ```
-index.sass             ──► Master Entrypoint (Forwards fractals + loads CSS cascade)
-_fractals.sass         ──► Pure Mixin Barrel (Emits 0 bytes CSS)
-
-── Phase 1: Pure Functions & Math (Zero CSS Emitted) ─────────────────────────
-_00_tokens.sass        ──► Raw CSS custom properties on :root & theme modes
-_01_config.sass        ──► Scales, maps, resolvers (space, radius, surface, ink)
-_02_fonts.sass         ──► Local @font-face declarations
-_03_responsive.sass    ──► Breakpoint helpers (+at, +below, +between)
-_04_atoms.sass         ──► Single-decision primitives (+box, +row, +bg, +ink, +pad, +gap)
-_05_molecules.sass     ──► Compositions of atoms (+stack, +cluster, +surface, +cols)
-_06_recipes.sass       ──► Macro component archetypes (=control, =select, =card, =partition)
-
-── Phase 2: CSS Cascade Emitters (Loaded once globally by index.sass) ─────────
-_07_base.sass          ──► Global HTML element resets
-_08_blocks.sass        ──► Semantic component classes (.surface, .panel, .select, .badge)
-_09_utilities.sass     ──► 1:1 atomic markup projections (.pad-*, .pad-top-*, .gap-*, .hide-desktop)
-_10_layouts.sass       ──► Page layout templates (.docs, .card-grid, .hero, .holy-grail)
-_11_own.sass           ──► Bespoke local project overrides
-```
+
+| Axis | Options | Description |
+|:---|:---|:---|
+| **Layout** (`data-layout`) | `tight` · `comfortable` *(default)* · `sprawling` | Scales gap and padding density factors independently. |
+| **Shape** (`data-shape`) | `round` · `curved` *(default)* · `pro` · `sharp` | Controls corner radii scale down to strict $0\text{px}$ sharp edges. |
+| **Color** (`data-color`) | `clean` · `general` *(default)* · `vibrant` | Adjusts background contrasts and surface elevations. |
+| **Motion** (`data-motion`) | `reduced` · `heavy` · `active` *(default)* · `springy` | Sets transition durations and spring easing physics. |
 
 ---
 
-## The Strict 21-Token Contract
+## The Complete Grepable Registry
 
-All themes and surface colors resolve from the 21 variables defined in `_00_tokens.sass`:
+The master class dictionary is documented in [**`REGISTRY.md`**](./REGISTRY.md) and programmatically exposed via [`registry.json`](./registry.json).
 
-- **Surfaces**: `--bg`, `--bg-surface`, `--bg-raised`, `--bg-panel`, `--bg-footer`, `--bg-popover`, `--bg-dialog`, `--bg-terminal`, `--bg-input`, `--bg-canvas`
-- **Text & Ink**: `--text-primary`, `--text-secondary`, `--text-muted`, `--text-inverse`
-- **States & Feedback**: `--state-hover`, `--state-hover-subtle`, `--state-selected`
-- **Borders & Accents**: `--border`, `--border-subtle`, `--theme-color`, `--theme-color-alt` *(aliased to `--theme`)*
+To regenerate the registry after editing stylesheet files:
 
----
+```bash
+pnpm registry
+```
 
-## Color Mode
+---
 
-Light is the marker-free default (SSR-safe). Dark mode is activated via `prefers-color-scheme: dark` or explicitly via `data-mode="dark"` on `<html>`:
+## Documentation Index
 
-```js
-import { toggleMode, setMode } from 'fractalstyler2';
-toggleMode();       // flip light/dark
-setMode('dark');    // force mode
-```
+| Chapter | Document | Scope & Contents |
+|:---|:---|:---|
+| **01** | [**`01-introduction.md`**](./docs/01-introduction.md) | Philosophy, $L0 \to L5$ mental model, and design invariants. |
+| **02** | [**`02-getting-started.md`**](./docs/02-getting-started.md) | Installation (CSS or SASS), CLI init, SvelteKit setup, and the 41 built-in themes. |
+| **03** | [**`03-structure.md`**](./docs/03-structure.md) | Numbered physical scale (`_00` through `_08`) and cascade order. |
+| **04** | [**`04-tokens.md`**](./docs/04-tokens.md) | 30 semantic colors, fluid Utopia scales, and dark/light modes. |
+| **05** | [**`05-dimensions.md`**](./docs/05-dimensions.md) | 17 space families, the literal px ladder, and `-mob`/`-desk` bands. |
+| **06** | [**`06-containers.md`**](./docs/06-containers.md) | `.box`, `.row`, `.grid`, and physical X/Y axis alignment. |
+| **07** | [**`07-layouts.md`**](./docs/07-layouts.md) | Gridding Golden Rules, `.card-grid`, `.prose`, and `.reel`. |
+| **08** | [**`08-shells-and-markups.md`**](./docs/08-shells-and-markups.md) | Canonical App Shell, role-bound sidebars, mobile disclosures, overlays. |
+| **09** | [**`09-visuals-and-interactions.md`**](./docs/09-visuals-and-interactions.md) | Surfaces, inks, hairline borders, buttons, and form inputs. |
+| **10** | [**`10-presets.md`**](./docs/10-presets.md) | Presets runtime, `presets.svelte.ts` API, and Svelte UI pickers. |
+| **11** | [**`11-mcp-server.md`**](./docs/11-mcp-server.md) | Model Context Protocol server tools and agent connection configs. |
+| **12** | [**`12-agent-plugin.md`**](./docs/12-agent-plugin.md) | `agent-plugins.org` spec, the bundled `fractal-styler` skill. |
+| **13** | [**`13-cookbook.md`**](./docs/13-cookbook.md) | The Zero-SASS Recipe Gallery: real-world UI patterns composed in HTML. |
+| **Registry** | [**`REGISTRY.md`**](./REGISTRY.md) | Comprehensive, grepable class dictionary and token table. |
 
 ---
 
-## Documentation Index
+## AI Agent Integration & MCP
 
-| Guide | Description |
-|---|---|
-| [01. Philosophy](docs/01-philosophy.md) | The fractal model, self-similarity, and dual consumption |
-| [02. Structure](docs/02-structure.md) | File anatomy, the 12-file numbered scale, and cascade order |
-| [03. Getting Started](docs/03-getting-started.md) | Scaffolding, imports, and wiring into SvelteKit |
-| [04. Fractals Reference](docs/04-fractals-reference.md) | Comprehensive reference for every atom and molecule mixin |
-| [05. Tokens & Theming](docs/05-tokens-and-theming.md) | Fluid scales, the 21-variable contract, and dark mode |
-| [06. Utilities Reference](docs/06-utilities.md) | Generated atomic classes, directional padding, and visibility |
-| [07. Components & Layouts](docs/07-components-and-layouts.md) | Shipped blocks, cards, and page layout templates |
-| [08. Recipes & Patterns](docs/08-recipes.md) | Worked examples: pricing card, responsive docs shell, dialog |
-| [09. Migration from v1](docs/09-migration-from-v1.md) | Upgrading from older unnumbered stylesheets |
-| [DESIGN.md](DESIGN.md) | Golden UI invariants, card containment laws, and defect prevention |
+Fractalstyler2 includes a native MCP server (`fractalstyler2-mcp`) providing 7 tools for AI coding agents:
+- `compile_fractals`: Compiles a SASS snippet to CSS, for the rare declaration that genuinely does not compose.
+- `get_design_tokens`: Structured token queries by category.
+- `snap_to_tokens`: Snaps raw pixel measurements to nearest token steps.
+- `css_to_fractals`: Converts raw CSS declarations to idiomatic markup classes.
+- `validate_recipe`: Lints snippets against design system rules.
 
 ---
 
 ## License
 
-MIT
+MIT © [Fractal Mandala](https://github.com/fractalmandala)

package/dist/cli.js

@@ -3,22 +3,45 @@ import { existsSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
 import { dirname, join, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
-function getTemplatesDir() {
+/**
+ * Where the scaffoldable partials live.
+ *
+ * These ARE the published stylesheet — `svelte-package` copies
+ * src/lib/styles into dist/styles, so `init` hands over the same files the
+ * package imports. There is deliberately no separate templates/ copy to
+ * drift out of sync.
+ *
+ * Resolves for both layouts: dist/cli.js -> dist/styles, and the in-repo
+ * src/lib/cli.ts -> src/lib/styles.
+ */
+function getStylesDir() {
     const HERE = dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        join(HERE, '..', 'templates'),
-        join(HERE, '..', '..', 'templates'),
-        join(HERE, 'templates')
+        join(HERE, 'styles'),
+        join(HERE, '..', 'styles'),
+        join(HERE, '..', 'lib', 'styles')
     ];
     for (const candidate of candidates) {
-        if (existsSync(candidate))
+        // index.sass is the marker: an empty or unrelated directory is not it.
+        if (existsSync(join(candidate, 'index.sass')))
             return candidate;
     }
-    throw new Error(`Templates directory not found. Searched in: ${candidates.join(', ')}`);
+    throw new Error(`fractalstyler2 stylesheet source not found. Searched in:\n  ${candidates.join('\n  ')}`);
+}
+/** The compiled CSS distribution, emitted by scripts/build-css.js at pack time. */
+function getCssDir() {
+    const HERE = dirname(fileURLToPath(import.meta.url));
+    const candidates = [join(HERE, 'css'), join(HERE, '..', 'css'), join(HERE, '..', 'dist', 'css')];
+    for (const candidate of candidates) {
+        if (existsSync(join(candidate, 'fractalstyler.css')))
+            return candidate;
+    }
+    throw new Error(`fractalstyler2 CSS distribution not found. Searched in:\n  ${candidates.join('\n  ')}\n` +
+        `If you are working from a clone, run \`npm run css\` first.`);
 }
 function printUsage() {
     console.log(`
-fractalstyler2 — SASS fractal design system scaffolder & MCP server
+fractalstyler2 — composition styling system scaffolder & MCP server
 
 Usage:
   npx fractalstyler2 init [dest] [options]
@@ -27,31 +50,41 @@ Usage:
   npx fractalstyler2 mcp:export [dest]
 
 Commands:
-  init [dest]         Scaffold SASS partials into target directory (default: src/lib/styles)
+  init [dest]         Scaffold the design system into a target directory
+                      (default: src/lib/styles)
   mcp                 Start the Model Context Protocol (MCP) server for OpenDesign, Claude, etc.
   mcp:install         Automatically install MCP schemas & config into Antigravity & OpenCode
   mcp:export [dest]   Export static MCP tool schema JSON files to target directory (default: .mcp)
 
 Options:
+      --css           Scaffold the compiled stylesheet (no toolchain needed)
+      --sass          Scaffold the editable SASS partials (the default)
   -f, --force         Overwrite files if they already exist
   -h, --help          Show this help message
 
 Examples:
   npx fractalstyler2 init
+  npx fractalstyler2 init --css
+  npx fractalstyler2 init src/styles --css
   npx fractalstyler2 mcp
   npx fractalstyler2 mcp:install
   npx fractalstyler2 mcp:export ~/.gemini/antigravity/mcp/fractalstyler2
 `);
 }
-function init(destArg, force) {
-    const dest = destArg ?? 'src/lib/styles';
+function init(destArg, force, flavour) {
+    const dest = destArg ?? (flavour === 'css' ? 'src/styles' : 'src/lib/styles');
     const cwd = process.cwd();
     const targetDir = resolve(cwd, dest);
     console.log(`\n▲ fractalstyler2 init\n`);
-    console.log(`Scaffolding SASS design system into: ${dest}\n`);
+    console.log(`Scaffolding ${flavour === 'css' ? 'compiled CSS' : 'SASS'} into: ${dest}\n`);
     mkdirSync(targetDir, { recursive: true });
-    const templatesDir = getTemplatesDir();
-    const files = readdirSync(templatesDir).filter((f) => f.endsWith('.sass'));
+    const stylesDir = flavour === 'css' ? getCssDir() : getStylesDir();
+    const files = flavour === 'css'
+        ? ['fractalstyler.css', 'fractalstyler.min.css']
+        : readdirSync(stylesDir).filter((f) => f.endsWith('.sass'));
+    // The L4 shells are only half a definition without their markup, so the
+    // contract ships alongside the stylesheet in both flavours.
+    const markups = join(getStylesDir(), 'canonical-markups.md');
     let created = 0;
     let overwritten = 0;
     let skipped = 0;
@@ -60,7 +93,7 @@ function init(destArg, force) {
         const relPath = relative(cwd, targetFile);
         if (existsSync(targetFile)) {
             if (force) {
-                copyFileSync(join(templatesDir, file), targetFile);
+                copyFileSync(join(stylesDir, file), targetFile);
                 console.log(`  \x1b[33moverwrite\x1b[0m ${relPath}`);
                 overwritten++;
             }
@@ -70,33 +103,80 @@ function init(destArg, force) {
             }
         }
         else {
-            copyFileSync(join(templatesDir, file), targetFile);
+            copyFileSync(join(stylesDir, file), targetFile);
             console.log(`  \x1b[32mcreate\x1b[0m    ${relPath}`);
             created++;
         }
     }
+    if (existsSync(markups)) {
+        const target = join(targetDir, 'canonical-markups.md');
+        if (!existsSync(target) || force) {
+            copyFileSync(markups, target);
+            console.log(`  \x1b[32mcreate\x1b[0m    ${relative(cwd, target)}`);
+            created++;
+        }
+    }
     console.log(`\nDone: ${created} created, ${overwritten} overwritten, ${skipped} skipped.\n`);
+    if (flavour === 'css') {
+        const cssPath = `${dest}/fractalstyler.css`;
+        console.log(`Next steps:
+  1. Link the stylesheet once, in your document head:
+       <link rel="stylesheet" href="/${cssPath}" />
+
+     Or import it, if you have a bundler:
+       import '${cssPath}';
+
+  2. Compose in markup. The registry is the API — .box, .row and .grid
+     carry most layouts, with .gap-* / .pad-* for space and .surface /
+     .border for the dress:
+       <div class="row ycenter xbetween gap-sm pad-md surface border">
+         <span class="text-md weight-600">Title</span>
+         <button class="button primary">Continue</button>
+       </div>
+
+  3. Themes and presets need no JavaScript to work:
+       <html class="theme-night-dark" data-mode="dark" data-shape="sharp">
+
+     To let people change them at runtime, and to avoid a flash of the
+     wrong theme on load:
+       import { initPresets, setPreset, getPresetScript } from 'fractalstyler2/presets';
+
+  4. For page and application shells, copy the structures in the scaffolded
+     canonical-markups.md verbatim. The responsive behaviour — rails that
+     retract, drawers that open — follows from the markup, so an
+     approximation of it will not behave.
+
+  5. Before writing any custom CSS, check docs/13-cookbook.md. Nearly every
+     common pattern is already composable.
+`);
+        return;
+    }
     const importPath = dest === 'src/lib/styles' ? '$lib/styles/index.sass' : `${dest}/index.sass`;
-    const fractalsPath = dest === 'src/lib/styles' ? '$lib/styles/fractals' : `${dest}/fractals`;
+    const ownPath = dest === 'src/lib/styles' ? '$lib/styles/_08_own.sass' : `${dest}/_08_own.sass`;
     console.log(`Next steps:
   1. Import the stylesheet once globally (e.g. in src/routes/+layout.svelte):
        <script>
          import '${importPath}';
        </script>
 
-  2. Compose your components with fractal mixins:
-       <style lang="sass">
-         @use '${fractalsPath}' as *
+  2. Compose in markup. The registry is the API — .box, .row and .grid
+     carry most layouts, with .gap-* / .pad-* for space and .surface /
+     .border for the dress:
+       <div class="row ycenter xbetween gap-sm pad-md surface border">
+         <span class="text-md weight-600">Title</span>
+         <button class="button primary">Continue</button>
+       </div>
 
-         .card
-           +surface(surface, s, 6)
-           +stack(s)
-       </style>
+  3. Before writing any custom class, check docs/13-cookbook.md — nearly
+     every common pattern is already composable. Keep
+       ${ownPath}
+     for what genuinely is not (third-party widget overrides, mostly).
 `);
 }
 const args = process.argv.slice(2);
 const showHelp = args.includes('-h') || args.includes('--help');
 const force = args.includes('-f') || args.includes('--force');
+const flavour = args.includes('--css') ? 'css' : 'sass';
 const positional = args.filter((a) => !a.startsWith('-'));
 const command = positional[0];
 const VALID_COMMANDS = ['init', 'mcp', 'mcp:export', 'mcp:install'];
@@ -143,9 +223,9 @@ else if (command === 'mcp:install') {
     });
 }
 else if (command === 'init') {
-    init(positional[1], force);
+    init(positional[1], force, flavour);
 }
 else {
     // Default to init if no subcommand given (e.g., `npx fractalstyler2`)
-    init(positional[0], force);
+    init(positional[0], force, flavour);
 }

package/dist/components/Accordion.svelte

@@ -0,0 +1,44 @@
+<script lang="ts" module>
+	export interface AccordionCtx {
+		/** Called by an item when it opens, so the group can close the others. */
+		claim: (id: symbol) => void;
+		register: (id: symbol, close: () => void) => () => void;
+	}
+	export const ACCORDION = Symbol('fs2.accordion');
+</script>
+
+<script lang="ts">
+	import { setContext, type Snippet } from 'svelte';
+
+	/**
+	 * Accordion group, from canonical-markups.md §3.
+	 *
+	 * `single` is the "accordion parent that regulates what closes when what
+	 * opens" the introduction describes: opening one item closes its siblings.
+	 * Default is independent items, which is what most navigation trees want.
+	 */
+	interface Props {
+		children: Snippet;
+		/** Only one item open at a time. */
+		single?: boolean;
+		class?: string;
+	}
+	let { children, single = false, class: className = '' }: Props = $props();
+
+	const items = new Map<symbol, () => void>();
+
+	setContext<AccordionCtx>(ACCORDION, {
+		register(id, close) {
+			items.set(id, close);
+			return () => items.delete(id);
+		},
+		claim(id) {
+			if (!single) return;
+			for (const [other, close] of items) if (other !== id) close();
+		}
+	});
+</script>
+
+<div class="accordion {className}">
+	{@render children()}
+</div>

package/dist/components/Accordion.svelte.d.ts

@@ -0,0 +1,23 @@
+export interface AccordionCtx {
+    /** Called by an item when it opens, so the group can close the others. */
+    claim: (id: symbol) => void;
+    register: (id: symbol, close: () => void) => () => void;
+}
+export declare const ACCORDION: unique symbol;
+import { type Snippet } from 'svelte';
+/**
+ * Accordion group, from canonical-markups.md §3.
+ *
+ * `single` is the "accordion parent that regulates what closes when what
+ * opens" the introduction describes: opening one item closes its siblings.
+ * Default is independent items, which is what most navigation trees want.
+ */
+interface Props {
+    children: Snippet;
+    /** Only one item open at a time. */
+    single?: boolean;
+    class?: string;
+}
+declare const Accordion: import("svelte").Component<Props, {}, "">;
+type Accordion = ReturnType<typeof Accordion>;
+export default Accordion;

package/dist/components/AccordionItem.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+	import { getContext, onMount, type Snippet } from 'svelte';
+	import { ACCORDION, type AccordionCtx } from './Accordion.svelte';
+
+	/**
+	 * One disclosure, from canonical-markups.md §3.
+	 *
+	 * Emits all three parts of the contract: `.accordion-item` carries `.open`,
+	 * `.accordion-content` is the grid that animates, and `.accordion-panel` is
+	 * the element that actually clips. The panel is the easiest to omit by hand
+	 * and the failure is silent — the content simply never collapses.
+	 *
+	 * State stays on native attributes: the trigger carries `aria-expanded`.
+	 */
+	interface Props {
+		/** The always-visible trigger row. */
+		trigger: Snippet;
+		children: Snippet;
+		open?: boolean;
+		class?: string;
+	}
+	let { trigger, children, open = $bindable(false), class: className = '' }: Props = $props();
+
+	const id = Symbol();
+	const group = getContext<AccordionCtx | undefined>(ACCORDION);
+
+	onMount(() => group?.register(id, () => (open = false)));
+
+	function toggle(): void {
+		open = !open;
+		if (open) group?.claim(id);
+	}
+</script>
+
+<div class="accordion-item {className}" class:open>
+	<button type="button" class="accordion-trigger" aria-expanded={open} onclick={toggle}>
+		{@render trigger()}
+	</button>
+	<div class="accordion-content">
+		<div class="accordion-panel box gap-2xs pad-x-xs">
+			{@render children()}
+		</div>
+	</div>
+</div>

package/dist/components/AccordionItem.svelte.d.ts

@@ -0,0 +1,21 @@
+import { type Snippet } from 'svelte';
+/**
+ * One disclosure, from canonical-markups.md §3.
+ *
+ * Emits all three parts of the contract: `.accordion-item` carries `.open`,
+ * `.accordion-content` is the grid that animates, and `.accordion-panel` is
+ * the element that actually clips. The panel is the easiest to omit by hand
+ * and the failure is silent — the content simply never collapses.
+ *
+ * State stays on native attributes: the trigger carries `aria-expanded`.
+ */
+interface Props {
+    /** The always-visible trigger row. */
+    trigger: Snippet;
+    children: Snippet;
+    open?: boolean;
+    class?: string;
+}
+declare const AccordionItem: import("svelte").Component<Props, {}, "open">;
+type AccordionItem = ReturnType<typeof AccordionItem>;
+export default AccordionItem;