sdocs 0.0.42 → 0.0.44

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.44] - 2026-07-04
+
+### Changed
+
+- The README documents the block format — the npm listing previously showed
+  the retired `export const meta` convention.
+
+## [0.0.43] - 2026-07-04
+
+### Added
+
+- **`projectSdoc` in `sdocs/language`** — a line-preserving projection of a
+  `.sdoc` file onto a virtual Svelte document: every authored line keeps its
+  exact position, sub-block openers become the same `{#snippet}` wrappers
+  the build generates, PAGE prose stays live with code regions masked, and
+  a trailer past the authored end marks everything as used. This is the
+  foundation of the VS Code extension's sdoc language server.
+
+### Changed
+
+- The Explorer's own UI library docs (`src/lib/ui/*.sdoc`) are converted to
+  the block format.
+
 ## [0.0.42] - 2026-07-04
 
 ### Changed

package/README.md

@@ -96,93 +96,80 @@ That's it — your docs page lives at `/docs` inside your existing app.
 
 ## Writing Docs
 
-sdocs supports three types of doc files:
+A `.sdoc` file is `<script>` at the top, entity blocks in the middle, and an
+optional `<style>` at the bottom. Every entity is its own sidebar entry, so
+one file can hold several.
 
-### Component Docs (`.sdoc`)
+### Component docs — `[DOCS]`
 
-Document a Svelte component with interactive controls and examples.
-
-```svelte
-<!-- Button.sdoc -->
+```sdoc
 <script lang="ts">
-  import Button from './Button.svelte';
-
-  export const meta = {
-    component: Button,
-    title: 'Components / Button',
-    description: 'A flexible button component.',
-    args: {
-      label: 'Click me',
-      size: 'md',
-      disabled: false,
-    },
-  };
+	import Button from './Button.svelte';
 </script>
 
-{#snippet Default()}
-  <Button {...args} />
-{/snippet}
+[DOCS title="Components / Button" description="A flexible button component."]
+
+	[preview component={Button} args={{ label: 'Click me', disabled: false }}]
+		<Button {...args} />
+	[/preview]
 
-{#snippet WithIcon()}
-  <Button>
-    <Icon name="settings" /> Settings
-  </Button>
-{/snippet}
+	[example title="With icon"]
+		<Button><Icon name="settings" /> Settings</Button>
+	[/example]
+
+[/DOCS]
 ```
 
-- **`component`** — the Svelte component to document (auto-extracts props, events, snippets, methods, state, CSS custom properties)
-- **`title`** — slash-separated path for sidebar navigation (e.g. `'Components / Button'`)
-- **`args`** — default prop values, used as initial values for interactive controls
-- **`Default` snippet** — gets live interactive controls. Auto-generated as `<Component {...args} />` if omitted.
-- **Named snippets** — static examples listed in the sidebar
+- **`[preview]`** — a live showcase with interactive controls.
+  `component={X}` names the previewed component (its props, events,
+  snippets, methods, state, and CSS custom properties are extracted
+  automatically) and `args` sets the control defaults. A `[DOCS]` block can
+  hold several previews — they render as tabs, each fully live.
+- **`[example]`** — frozen showcases rendered exactly as written, shown
+  below the preview area. Each needs a unique `title`.
+- **`title`** — slash-separated path for sidebar navigation.
 
-### Page Docs (`.page.sdoc`)
+### Pages — `[PAGE]`
 
-Freeform content pages with auto-generated table of contents.
+Freeform markdown content with `{expression}` interpolation and Svelte
+component islands; code fences are inert. The table of contents is generated
+from the headings.
 
-```svelte
-<!-- GettingStarted.page.sdoc -->
-<script lang="ts">
-  export const meta = {
-    title: 'Docs / Getting Started',
-    description: 'How to set up sdocs.',
-  };
-</script>
+```sdoc
+[PAGE title="Docs / Getting Started"]
 
-<h1>Getting Started</h1>
-<p>Install sdocs and create your first doc file.</p>
+	## Installation
 
-<h2>Installation</h2>
-<p>Run <code>npm install sdocs</code>...</p>
-```
+	Run `npm install sdocs` and create your first doc file.
 
-Table of contents is auto-generated from `<h2>`, `<h3>`, and `<h4>` headings.
+[/PAGE]
+```
 
-### Layout Docs (`.layout.sdoc`)
+### Layouts — `[LAYOUT]`
 
-Component compositions rendered in an isolated iframe.
+Full-page component compositions rendered on an isolated stage.
 
-```svelte
-<!-- LoginForm.layout.sdoc -->
+```sdoc
 <script lang="ts">
-  import Card from './Card.svelte';
-  import Input from './Input.svelte';
-  import Button from './Button.svelte';
-
-  export const meta = {
-    title: 'Patterns / Login Form',
-    description: 'A login form combining multiple components.',
-    settings: { padding: '24px' },
-  };
+	import Card from './Card.svelte';
+	import Input from './Input.svelte';
+	import Button from './Button.svelte';
 </script>
 
-<Card padding="24px">
-  <Input label="Email" type="email" />
-  <Input label="Password" type="password" />
-  <Button>Sign in</Button>
-</Card>
+[LAYOUT title="Patterns / Login Form" padding="24px"]
+
+	<Card padding="24px">
+		<Input label="Email" type="email" />
+		<Input label="Password" type="password" />
+		<Button>Sign in</Button>
+	</Card>
+
+[/LAYOUT]
 ```
 
+The full language reference lives at
+[gabilungu.github.io/sdocs/language](https://gabilungu.github.io/sdocs/language).
+
 ## Prop Extraction
 
 sdocs automatically extracts from your Svelte components:
@@ -200,7 +187,7 @@ JSDoc comments on props are picked up as descriptions.
 
 ## Interactive Controls
 
-The Default snippet gets live controls based on prop types:
+Each preview gets live controls based on prop types:
 
 | Prop Type | Control |
 |-----------|---------|
@@ -275,6 +262,8 @@ sidebar: {
 | `sdocs/vite` | Vite plugin function |
 | `sdocs/explorer` | Explorer.svelte UI component |
 | `sdocs/ui` | Reusable UI components (Button, Frame, Icon, Control, NavTree, Stack) |
+| `sdocs/language` | The sdoc scanner, parser, and Svelte projection |
+| `sdocs/grammar/sdoc.tmLanguage.json` | TextMate grammar for editors and highlighters |
 
 ## License
 

package/dist/language/index.d.ts

@@ -1,2 +1,3 @@
 export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, type Span, type EntityKind, type SubBlockKind, type AttrValue, type Attrs, type SubBlock, type Entity, type TagBlock, type ScanError, type SdocFile, } from './scanner.js';
+export { projectSdoc, type SdocProjection, type ProjectedLineKind, } from './projection.js';
 export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, type ArgValue, type PreviewBlock, type ExampleBlock, type DocsEntity, type PageEntity, type LayoutEntity, type SdocEntity, type SdocDocument, } from './parser.js';

package/dist/language/index.js

@@ -1,2 +1,3 @@
 export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, } from './scanner.js';
+export { projectSdoc, } from './projection.js';
 export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, } from './parser.js';

package/dist/language/projection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Line-preserving projection of a .sdoc file into a virtual Svelte document.
+ *
+ * Every authored line keeps its exact (line, column) in the virtual text, so
+ * editor position mapping is the identity function. Block syntax the Svelte
+ * compiler must not see becomes blank lines; sub-block openers are rewritten
+ * IN PLACE to `{#snippet …(args)}` wrappers — byte-compatible with the shape
+ * the build pipeline generates at runtime — and a trailer appended past the
+ * authored end renders every snippet and references previewed components, so
+ * nothing draws unused-import noise. Diagnostics on trailer lines
+ * (line >= sourceLineCount) are generated, never authored.
+ */
+import type { SdocFile } from './scanner.js';
+export type ProjectedLineKind = 'verbatim' | 'blank' | 'wrapper' | 'masked';
+export interface SdocProjection {
+    /** The virtual Svelte document text */
+    text: string;
+    /** Authored line count; virtual lines at or past this are generated */
+    sourceLineCount: number;
+    /** Per authored line: how it was projected */
+    lineKinds: ProjectedLineKind[];
+}
+export declare function projectSdoc(file: SdocFile): SdocProjection;

package/dist/language/projection.js

@@ -0,0 +1,136 @@
+/**
+ * Line-preserving projection of a .sdoc file into a virtual Svelte document.
+ *
+ * Every authored line keeps its exact (line, column) in the virtual text, so
+ * editor position mapping is the identity function. Block syntax the Svelte
+ * compiler must not see becomes blank lines; sub-block openers are rewritten
+ * IN PLACE to `{#snippet …(args)}` wrappers — byte-compatible with the shape
+ * the build pipeline generates at runtime — and a trailer appended past the
+ * authored end renders every snippet and references previewed components, so
+ * nothing draws unused-import noise. Diagnostics on trailer lines
+ * (line >= sourceLineCount) are generated, never authored.
+ */
+function lineStartsOf(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] === '\n')
+            starts.push(i + 1);
+    }
+    return starts;
+}
+function lineOfOffset(starts, offset) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}
+/** Mask markdown code so a PAGE body reads as Svelte-safe prose: fence lines
+ * and fence interiors go blank; inline `code` spans are space-overwritten
+ * (column-preserving). Everything else — prose, {expressions}, component
+ * islands — stays verbatim. */
+function maskMarkdownLine(line, state) {
+    const fenceMarker = /^\s*(`{3,}|~{3,})/.test(line);
+    if (fenceMarker) {
+        state.inFence = !state.inFence;
+        return { text: '', masked: true };
+    }
+    if (state.inFence)
+        return { text: '', masked: true };
+    if (!line.includes('`'))
+        return { text: line, masked: false };
+    const text = line.replace(/`[^`]*`/g, (m) => ' '.repeat(m.length));
+    return { text, masked: text !== line };
+}
+export function projectSdoc(file) {
+    const source = file.source;
+    const starts = lineStartsOf(source);
+    const total = starts.length;
+    const out = new Array(total).fill('');
+    const kinds = new Array(total).fill('blank');
+    const copyVerbatim = (span) => {
+        const first = lineOfOffset(starts, span.start);
+        const last = lineOfOffset(starts, Math.max(span.start, span.end - 1));
+        for (let l = first; l <= last; l++) {
+            const end = l + 1 < total ? starts[l + 1] - 1 : source.length;
+            out[l] = source.slice(starts[l], end).replace(/\r$/, '');
+            kinds[l] = 'verbatim';
+        }
+    };
+    if (file.script)
+        copyVerbatim(file.script.span);
+    if (file.style)
+        copyVerbatim(file.style.span);
+    const isTs = /lang\s*=\s*["']ts["']/.test(file.script?.attrsText ?? '');
+    const argsParam = isTs ? '(args: any)' : '(args)';
+    const snippets = [];
+    const componentRefs = new Set();
+    const wrapBlock = (name, openerSpan, bodySpan, closerLineOf, // block span; its end sits on the closer line
+    withArgs, maskBody) => {
+        const openFirst = lineOfOffset(starts, openerSpan.start);
+        const openLast = lineOfOffset(starts, Math.max(openerSpan.start, openerSpan.end - 1));
+        out[openFirst] = `{#snippet ${name}${withArgs ? argsParam : '()'}}`;
+        kinds[openFirst] = 'wrapper';
+        for (let l = openFirst + 1; l <= openLast; l++) {
+            out[l] = '';
+            kinds[l] = 'blank';
+        }
+        if (bodySpan.end > bodySpan.start) {
+            if (maskBody) {
+                const first = lineOfOffset(starts, bodySpan.start);
+                const last = lineOfOffset(starts, Math.max(bodySpan.start, bodySpan.end - 1));
+                const state = { inFence: false };
+                for (let l = first; l <= last; l++) {
+                    const end = l + 1 < total ? starts[l + 1] - 1 : source.length;
+                    const line = source.slice(starts[l], end).replace(/\r$/, '');
+                    const masked = maskMarkdownLine(line, state);
+                    out[l] = masked.text;
+                    kinds[l] = masked.masked ? 'masked' : 'verbatim';
+                }
+            }
+            else {
+                copyVerbatim(bodySpan);
+            }
+        }
+        const closeLine = lineOfOffset(starts, Math.max(closerLineOf.start, closerLineOf.end - 1));
+        out[closeLine] = '{/snippet}';
+        kinds[closeLine] = 'wrapper';
+        snippets.push({ name, withArgs });
+    };
+    file.entities.forEach((entity, e) => {
+        if (entity.kind === 'DOCS') {
+            entity.blocks.forEach((block, b) => {
+                wrapBlock(`__sdocs$${e}_${b}`, block.openerSpan, block.bodySpan, block.span, true, false);
+                const component = block.attrs.component;
+                if (component?.kind === 'expression') {
+                    const name = component.raw.trim();
+                    if (/^[A-Z][A-Za-z0-9_]*$/.test(name))
+                        componentRefs.add(name);
+                }
+            });
+        }
+        else {
+            wrapBlock(`__sdocs$${e}`, entity.openerSpan, entity.bodySpan, entity.span, false, entity.kind === 'PAGE');
+        }
+    });
+    // Trailer: render every snippet and reference previewed components so the
+    // Svelte/TS layer sees everything as used. Lives past the authored end.
+    const trailer = ['{#if false}'];
+    for (const snippet of snippets) {
+        trailer.push(`{@render ${snippet.name}(${snippet.withArgs ? '{}' : ''})}`);
+    }
+    for (const name of componentRefs) {
+        trailer.push(`<${name} />`);
+    }
+    trailer.push('{/if}');
+    return {
+        text: out.join('\n') + '\n' + trailer.join('\n') + '\n',
+        sourceLineCount: total,
+        lineKinds: kinds,
+    };
+}

package/dist/language/projection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/language/projection.test.js

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { compile } from 'svelte/compiler';
+import { scanSdoc } from './scanner.js';
+import { projectSdoc } from './projection.js';
+const SOURCE = `<script lang="ts">
+	import Tabs from './Tabs.svelte';
+	import Tab from './Tab.svelte';
+	const shared = 1;
+</script>
+
+[DOCS title="Nav / Tabs" description="A tab bar."]
+
+	[preview component={Tabs} args={{ active: 0 }}]
+		<Tabs {...args} active={shared}>x</Tabs>
+	[/preview]
+
+	[example title="Wrapped child"]
+		<Tabs><Tab {...args} /></Tabs>
+	[/example]
+
+[/DOCS]
+
+[PAGE title="Guide"]
+
+	## Heading
+
+	Uses {shared} and <Tabs />.
+
+	\`\`\`svelte
+	<NotReal {broken} />
+	\`\`\`
+
+	Inline \`{code}\` is masked.
+
+[/PAGE]
+
+<style>
+	.x { color: red; }
+</style>
+`;
+describe('projectSdoc', () => {
+    const projection = projectSdoc(scanSdoc(SOURCE));
+    const lines = projection.text.split('\n');
+    const sourceLines = SOURCE.split('\n');
+    it('preserves every authored line position', () => {
+        expect(projection.sourceLineCount).toBe(sourceLines.length);
+        for (let i = 0; i < sourceLines.length; i++) {
+            const kind = projection.lineKinds[i];
+            if (kind === 'verbatim')
+                expect(lines[i]).toBe(sourceLines[i]);
+            if (kind === 'blank')
+                expect(lines[i]).toBe('');
+        }
+    });
+    const at = (needle) => sourceLines.findIndex((l) => l.includes(needle));
+    it('keeps script, style, and bodies verbatim at identical lines', () => {
+        expect(lines[1]).toBe("\timport Tabs from './Tabs.svelte';");
+        expect(lines[at('{...args} active')]).toBe(sourceLines[at('{...args} active')]);
+        expect(lines[at('color: red')]).toContain('color: red');
+    });
+    it('rewrites sub-block openers to snippet wrappers in place', () => {
+        expect(lines[at('[preview')]).toBe('{#snippet __sdocs$0_0(args: any)}');
+        expect(lines[at('[/preview]')]).toBe('{/snippet}');
+        expect(lines[at('[example')]).toBe('{#snippet __sdocs$0_1(args: any)}');
+    });
+    it('blanks entity tags and masks PAGE code while keeping prose live', () => {
+        expect(lines[at('[DOCS')]).toBe('');
+        const proseLine = sourceLines.findIndex((l) => l.includes('Uses {shared}'));
+        expect(lines[proseLine]).toBe(sourceLines[proseLine]);
+        const fenceBody = sourceLines.findIndex((l) => l.includes('NotReal'));
+        expect(lines[fenceBody]).toBe('');
+        const inline = sourceLines.findIndex((l) => l.includes('Inline'));
+        expect(lines[inline]).not.toContain('{code}');
+        expect(lines[inline].length).toBe(sourceLines[inline].length);
+    });
+    it('appends a trailer that renders snippets and references components', () => {
+        const trailer = lines.slice(projection.sourceLineCount).join('\n');
+        expect(trailer).toContain('{@render __sdocs$0_0({})}');
+        expect(trailer).toContain('{@render __sdocs$1()}');
+        expect(trailer).toContain('<Tabs />');
+    });
+    it('produces text the Svelte compiler accepts', () => {
+        expect(() => compile(projection.text, { generate: false })).not.toThrow();
+    });
+});
+describe('projectSdoc over the real corpus', () => {
+    const dirs = [
+        resolve(__dirname, '../../../../../apps/site/src/lib/ui'),
+        resolve(__dirname, '../../../../../apps/testapp-embedded/src/lib/UI'),
+        resolve(__dirname, '../../../../../apps/testapp-standalone/src'),
+    ];
+    const files = [];
+    for (const dir of dirs) {
+        try {
+            for (const f of readdirSync(dir, { recursive: true })) {
+                if (f.endsWith('.sdoc'))
+                    files.push(resolve(dir, f));
+            }
+        }
+        catch {
+            // corpus dir not present in this checkout
+        }
+    }
+    it('found the corpus', () => {
+        expect(files.length).toBeGreaterThanOrEqual(10);
+    });
+    for (const file of files) {
+        it(`compiles ${file.split('/').slice(-1)[0]}`, () => {
+            const source = readFileSync(file, 'utf-8');
+            const projection = projectSdoc(scanSdoc(source));
+            expect(projection.sourceLineCount).toBe(source.split('\n').length);
+            expect(() => compile(projection.text, { generate: false })).not.toThrow();
+        });
+    }
+});

package/dist/ui/About.sdoc

@@ -0,0 +1,28 @@
+[PAGE title=":Pages / About"]
+
+	# About sdocs
+
+	sdocs is a lightweight documentation tool for Svelte 5 components.
+	It discovers `.sdoc` files in your project and renders an interactive
+	component explorer with live previews.
+
+	## Features
+
+	- Zero-config component discovery
+	- Live preview with prop controls
+	- Multiple titled examples per component
+	- Page and layout support
+	- Light and dark themes
+
+	## Getting Started
+
+	Create a `.sdoc` file next to your component and add a `[DOCS]` block
+	with a `[preview]` naming the component.
+
+	## Entities
+
+	- **`[DOCS]`** — component documentation with previews and examples
+	- **`[PAGE]`** — standalone content pages
+	- **`[LAYOUT]`** — full-page layout previews
+
+[/PAGE]

package/dist/ui/Button/Button.sdoc

@@ -1,52 +1,49 @@
 <script lang="ts">
-	import type { ComponentProps } from 'svelte';
 	import Button from './Button.svelte';
 	import { Icon } from '../Icon/index.js';
-
-	export const meta = {
-		component: Button,
-		title: 'Button',
-		description: 'A flexible button with optional left and right snippet slots for icons or badges.',
-	};
 </script>
 
-{#snippet Default(args: ComponentProps<typeof Button>)}
-	<Button {...args}>Click me</Button>
-{/snippet}
-
-{#snippet WithLeftIcon()}
-	<Button onclick={() => alert('Settings')}>
-		{#snippet left()}<Icon name="folder" --w="14px" --h="14px" />{/snippet}
-		Settings
-	</Button>
-{/snippet}
-
-{#snippet WithRightIcon()}
-	<Button>
-		Next
-		{#snippet right()}<Icon name="chevron-right" --w="14px" --h="14px" />{/snippet}
-	</Button>
-{/snippet}
-
-{#snippet BothSlots()}
-	<Button>
-		{#snippet left()}<Icon name="file-text" --w="14px" --h="14px" />{/snippet}
-		Export
-		{#snippet right()}<span style="font-size: 11px; opacity: 0.6;">PDF</span>{/snippet}
-	</Button>
-{/snippet}
-
-{#snippet IconOnly()}
-	<div style="display: flex; gap: 8px;">
-		<Button title="Light theme" --p="4px 6px">
-			{#snippet left()}<Icon name="sun" --w="16px" --h="16px" />{/snippet}
+[DOCS title="Button" description="A flexible button with optional left and right snippet slots for icons or badges."]
+
+	[preview component={Button}]
+		<Button {...args}>Click me</Button>
+	[/preview]
+
+	[example title="WithLeftIcon"]
+		<Button onclick={() => alert('Settings')}>
+			{#snippet left()}<Icon name="folder" --w="14px" --h="14px" />{/snippet}
+			Settings
+		</Button>
+	[/example]
+
+	[example title="WithRightIcon"]
+		<Button>
+			Next
+			{#snippet right()}<Icon name="chevron-right" --w="14px" --h="14px" />{/snippet}
 		</Button>
-		<Button title="Fullscreen" --p="4px 6px">
-			{#snippet left()}<Icon name="maximize" --w="16px" --h="16px" />{/snippet}
+	[/example]
+
+	[example title="BothSlots"]
+		<Button>
+			{#snippet left()}<Icon name="file-text" --w="14px" --h="14px" />{/snippet}
+			Export
+			{#snippet right()}<span style="font-size: 11px; opacity: 0.6;">PDF</span>{/snippet}
 		</Button>
-	</div>
-{/snippet}
+	[/example]
+
+	[example title="IconOnly"]
+		<div style="display: flex; gap: 8px;">
+			<Button title="Light theme" --p="4px 6px">
+				{#snippet left()}<Icon name="sun" --w="16px" --h="16px" />{/snippet}
+			</Button>
+			<Button title="Fullscreen" --p="4px 6px">
+				{#snippet left()}<Icon name="maximize" --w="16px" --h="16px" />{/snippet}
+			</Button>
+		</div>
+	[/example]
+
+	[example title="Disabled"]
+		<Button disabled>Can't click</Button>
+	[/example]
 
-{#snippet Disabled()}
-	<Button disabled>Can't click</Button>
-{/snippet}
+[/DOCS]

package/dist/ui/Control/Checkbox.sdoc

@@ -1,17 +1,11 @@
 <script lang="ts">
 	import Checkbox from './Checkbox.svelte';
-
-	export const meta = {
-		component: Checkbox,
-		title: 'Control / Checkbox',
-		description: 'A checkbox control for boolean values.',
-		args: {
-			label: 'Enabled',
-			value: true,
-		},
-	};
 </script>
 
-{#snippet Default(args)}
-	<Checkbox {...args} onchange={(v) => console.log('changed:', v)} />
-{/snippet}
+[DOCS title="Control / Checkbox" description="A checkbox control for boolean values."]
+
+	[preview component={Checkbox} args={{ label: 'Enabled', value: true }}]
+		<Checkbox {...args} onchange={(v) => console.log('changed:', v)} />
+	[/preview]
+
+[/DOCS]

package/dist/ui/Control/Color.sdoc

@@ -1,17 +1,11 @@
 <script lang="ts">
 	import Color from './Color.svelte';
-
-	export const meta = {
-		component: Color,
-		title: 'UI / Control / Color',
-		description: 'A color picker control.',
-		args: {
-			label: 'Background',
-			value: '#3b82f6',
-		},
-	};
 </script>
 
-{#snippet Default(args)}
-	<Color {...args} onchange={(v) => console.log('changed:', v)} />
-{/snippet}
+[DOCS title="UI / Control / Color" description="A color picker control."]
+
+	[preview component={Color} args={{ label: 'Background', value: '#3b82f6' }}]
+		<Color {...args} onchange={(v) => console.log('changed:', v)} />
+	[/preview]
+
+[/DOCS]