rizzo-css 0.0.12 → 0.0.13

package/scaffold/svelte-app/src/lib/rizzo-docs/pages/ThemeSwitcherDoc.svelte

@@ -0,0 +1,181 @@
+<script lang="ts">
+  import ThemeSwitcher from '$lib/rizzo/ThemeSwitcher.svelte';
+  import CodeBlock from '$lib/rizzo-docs/CodeBlock.svelte';
+</script>
+
+<section>
+  <h2>Theme Switcher component</h2>
+  <p>Accessible theme dropdown with <strong>Preference</strong> (System), <strong>Dark</strong>, and <strong>Light</strong> groups, a unique icon per theme, and a preview panel. Same behavior as the <a href="/docs/components/theme-switcher">Astro ThemeSwitcher</a>: persists in <code>localStorage</code> (key <code>theme</code>), sets <code>data-theme</code> on <code>&lt;html&gt;</code>.</p>
+
+  <h3>Live example</h3>
+  <div class="example">
+    <div class="example-title">Live Example</div>
+    <p>Try switching themes using the theme switcher below (Svelte component):</p>
+    <ThemeSwitcher />
+  </div>
+
+  <h3>Features</h3>
+  <ul>
+    <li><strong>Preference (System)</strong> — Option to follow OS light/dark; resolves to a concrete theme when applied. When System is selected, both System and the resolved theme show the active state in the UI.</li>
+    <li><strong>Preview panel</strong> — When the menu is open (viewports &gt;480px), a preview panel is always visible. It shows a fixed “Preview” label; the theme name, swatch, and accent bar show the <strong>current</strong> theme by default and the <strong>hovered</strong> theme on hover/focus. Full-height divider between list and preview. Hidden on small viewports.</li>
+    <li>Groups: Preference, Dark themes, Light themes; each theme has a unique icon (from <code>themes.ts</code>).</li>
+    <li>Trigger shows the active theme name and icon.</li>
+    <li>Persists selection in <code>localStorage</code> (<code>theme</code>: theme id or <code>system</code>).</li>
+    <li>Full keyboard navigation (Enter/Space to open/close, Arrow keys, Home/End, Escape, Tab).</li>
+  </ul>
+
+  <h3>Key BEM classes and data attributes</h3>
+  <ul>
+    <li><code>theme-switcher</code> — root; <code>data-theme-switcher</code> (for script or shared behavior).</li>
+    <li><code>theme-switcher__trigger</code> — button; <code>aria-expanded</code>, <code>aria-haspopup</code>, <code>aria-controls</code> = menu id.</li>
+    <li><code>theme-switcher__label-wrapper</code> — wraps label + optional icon; <code>data-theme-label-wrapper</code>.</li>
+    <li><code>theme-switcher__label</code> — current theme name; <code>data-theme-label</code>.</li>
+    <li><code>theme-switcher__icon</code> — chevron (open/close).</li>
+    <li><code>theme-switcher__menu</code> — dropdown; <code>role="menu"</code>, <code>aria-labelledby</code>, <code>aria-label</code>, <code>tabindex="-1"</code>. Add <code>theme-switcher__menu--open</code> when open.</li>
+    <li><code>theme-switcher__menu-options</code> — scrollable list of options; has a full-height border on the right (divider) on larger screens.</li>
+    <li><code>theme-switcher__group</code> — section; <code>role="group"</code>, <code>aria-label</code> (e.g. “Preference”, “Dark themes”, “Light themes”).</li>
+    <li><code>theme-switcher__group-label</code> — section heading; <code>role="presentation"</code>.</li>
+    <li><code>theme-switcher__option</code> — one theme option; <code>role="menuitemradio"</code>, <code>aria-checked</code>, <code>tabindex="-1"</code>. Add <code>theme-switcher__option--active</code> when selected. <code>data-theme-value</code> (theme id or <code>system</code>), <code>data-theme-type</code> (<code>system</code> / <code>dark</code> / <code>light</code>), <code>data-theme-bg</code>, <code>data-theme-accent</code>, <code>data-theme-label</code> for preview and styling.</li>
+    <li><code>theme-switcher__option-icon</code> — icon inside option.</li>
+    <li><code>theme-switcher__preview</code> — preview panel; <code>data-theme-preview</code>. On open, set <code>aria-hidden="false"</code> when viewport &gt;480px.</li>
+    <li><code>theme-switcher__preview-title</code> — fixed “Preview” label.</li>
+    <li><code>theme-switcher__preview-header</code> — theme name; <code>data-theme-preview-label</code>.</li>
+    <li><code>theme-switcher__preview-swatch-wrap</code>, <code>theme-switcher__preview-swatch</code> — swatch; <code>data-theme-preview-swatch</code>. Set background (e.g. from <code>data-theme-bg</code>) for the hovered/current theme.</li>
+    <li><code>theme-switcher__preview-accent</code> — accent bar; <code>data-theme-preview-accent</code>. Set background from <code>data-theme-accent</code>.</li>
+  </ul>
+
+  <h3>Theme utilities</h3>
+  <p>Use these (from <code>src/utils/theme.ts</code> or your port) to apply and display themes:</p>
+  <ul>
+    <li><code>applyTheme(value)</code> — Sets <code>data-theme</code> on <code>html</code> and saves to <code>localStorage</code> (<code>theme</code>). Use a theme id (e.g. <code>github-dark-classic</code>) or <code>system</code>. Dispatches <code>rizzo-theme-change</code>.</li>
+    <li><code>getThemeLabel(value)</code> / <code>getThemeInfo(value)</code> — Display name for a theme id or <code>system</code>.</li>
+    <li><code>getStoredTheme()</code> — Returns current value in <code>localStorage</code> (<code>theme</code> id or <code>system</code>).</li>
+    <li><code>resolveSystemTheme()</code> — Resolves OS preference to a concrete theme id (dark → default dark, light → default light).</li>
+    <li>Constants: <code>THEME_SYSTEM</code>, <code>DEFAULT_THEME_DARK</code>, <code>DEFAULT_THEME_LIGHT</code>.</li>
+  </ul>
+  <p>Theme IDs: run <code>npx rizzo-css theme</code> or see <a href="/docs/theming#available-themes">Theming – Available themes</a>. Listen for <code>rizzo-theme-change</code> to sync other UI when the theme changes.</p>
+
+  <h3>Structure example (simplified)</h3>
+  <CodeBlock
+    code={`<div class="theme-switcher" data-theme-switcher>
+  <button
+    type="button"
+    class="theme-switcher__trigger"
+    aria-expanded={open}
+    aria-haspopup="true"
+    aria-controls="theme-menu"
+    aria-label="Select theme"
+    onclick={() => (open = !open)}
+  >
+    <span class="theme-switcher__label-wrapper" data-theme-label-wrapper>
+      <span class="theme-switcher__label" data-theme-label>{currentLabel}</span>
+    </span>
+    <ChevronDown class="theme-switcher__icon" width={16} height={16} />
+  </button>
+  <div
+    class="theme-switcher__menu"
+    class:theme-switcher__menu--open={open}
+    id="theme-menu"
+    role="menu"
+    aria-label="Theme selection"
+    aria-hidden={!open}
+    tabindex="-1"
+  >
+    <div class="theme-switcher__menu-options">
+      <div class="theme-switcher__group" role="group" aria-label="Preference">
+        <div class="theme-switcher__group-label" role="presentation">Preference</div>
+        <div
+          class="theme-switcher__option"
+          class:theme-switcher__option--active={storedTheme === 'system'}
+          role="menuitemradio"
+          aria-checked={storedTheme === 'system'}
+          data-theme-value="system"
+          data-theme-type="system"
+          onclick={() => selectTheme('system')}
+        >System</div>
+      </div>
+      <div class="theme-switcher__group" role="group" aria-label="Dark themes">
+        <div class="theme-switcher__group-label" role="presentation">Dark</div>
+        {#each darkThemes as theme}
+          <div
+            class="theme-switcher__option"
+            class:theme-switcher__option--active={storedTheme === theme.value}
+            role="menuitemradio"
+            aria-checked={storedTheme === theme.value}
+            data-theme-value={theme.value}
+            data-theme-bg={theme.bg}
+            data-theme-accent={theme.accent}
+            data-theme-label={theme.label}
+            onclick={() => selectTheme(theme.value)}
+            onmouseenter={() => (previewTheme = theme.value)}
+          >{theme.label}</div>
+        {/each}
+      </div>
+      <!-- Light group similar -->
+    </div>
+    <div class="theme-switcher__preview" data-theme-preview aria-hidden={!open}>
+      <div class="theme-switcher__preview-title">Preview</div>
+      <div class="theme-switcher__preview-header" data-theme-preview-label>{previewLabel}</div>
+      <div class="theme-switcher__preview-swatch-wrap">
+        <div class="theme-switcher__preview-swatch" data-theme-preview-swatch style="background: {previewBg}"></div>
+      </div>
+      <div class="theme-switcher__preview-accent" data-theme-preview-accent style="background: {previewAccent}"></div>
+    </div>
+  </div>
+</div>`}
+    language="svelte"
+  />
+
+  <h3>Keyboard navigation</h3>
+  <ul>
+    <li><kbd>Enter</kbd> or <kbd>Space</kbd> — Open or close menu</li>
+    <li><kbd>ArrowDown</kbd> — Open menu and focus first option</li>
+    <li><kbd>ArrowUp</kbd> — Open menu and focus last option</li>
+    <li><kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd> — Move between options</li>
+    <li><kbd>Home</kbd> / <kbd>End</kbd> — First or last option</li>
+    <li><kbd>Enter</kbd> or <kbd>Space</kbd> — Select focused theme</li>
+    <li><kbd>Escape</kbd> — Close menu</li>
+    <li><kbd>Tab</kbd> — Close menu and tab to next element</li>
+  </ul>
+
+  <h3>Implementing in Svelte</h3>
+  <ul>
+    <li><strong>Open state:</strong> e.g. <code>let open = $state(false)</code>. Toggle <code>theme-switcher__menu--open</code> on the menu and set <code>aria-expanded</code> and <code>aria-hidden</code> accordingly.</li>
+    <li><strong>Current theme:</strong> Read from <code>getStoredTheme()</code> or your store; set <code>currentLabel</code> via <code>getThemeLabel(storedTheme)</code> (use resolved theme when stored value is <code>system</code>). Mark the matching option with <code>theme-switcher__option--active</code>.</li>
+    <li><strong>Select theme:</strong> On option click/keyboard select, call <code>applyTheme(value)</code> (or set <code>data-theme</code> on <code>document.documentElement</code> and <code>localStorage.setItem('theme', value)</code>). Close menu and restore focus to trigger.</li>
+    <li><strong>Preview on hover:</strong> Track <code>previewTheme</code> (theme id or null). On option <code>mouseenter</code>/focus, set it to that option’s <code>data-theme-value</code>; on <code>mouseleave</code>/blur from the list, set to <code>null</code> (show current). Update preview label, swatch background, and accent from the hovered option’s <code>data-theme-*</code> or from theme config. When <code>previewTheme</code> is null, show the current (resolved) theme in the preview.</li>
+    <li><strong>System preference:</strong> Listen for <code>prefers-color-scheme</code> and, when stored value is <code>system</code>, call <code>applyTheme('system')</code> again to re-resolve and update the document.</li>
+    <li><strong>Focus trap:</strong> When open, focus first option (or keep focus on trigger); trap Tab inside menu; on close, focus trigger.</li>
+  </ul>
+
+  <p><a href="/docs/components/theme-switcher">Full Astro Theme Switcher documentation</a> — implementation details and keyboard behavior.</p>
+  <p><a href="/docs/svelte/components">← Back to Svelte components</a></p>
+</section>
+
+<style>
+  .example {
+    margin: var(--spacing-6) 0;
+    padding: var(--spacing-4);
+    background: var(--background-alt);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+  }
+  .example-title {
+    font-size: var(--font-size-sm);
+    font-weight: var(--font-weight-medium);
+    color: var(--text-dim);
+    margin-bottom: var(--spacing-3);
+    text-transform: uppercase;
+    letter-spacing: var(--letter-spacing-wider);
+  }
+  kbd {
+    display: inline-block;
+    padding: var(--spacing-0-125) var(--spacing-0-375);
+    background-color: var(--background-alt);
+    border: var(--outline-width) solid var(--border);
+    border-radius: var(--radius);
+    font-family: var(--font-family-mono);
+    font-size: var(--font-size-xs);
+    line-height: 1;
+  }
+</style>

package/scaffold/svelte-app/src/lib/rizzo-docs/pages/Theming.svelte

@@ -0,0 +1,6 @@
+<section>
+  <h2>Theming</h2>
+  <p>The theme system is framework-agnostic: the same CSS variables and <code>data-theme</code> attribute apply. Use the built-in themes or create custom ones as described in the main docs.</p>
+  <p><a href="/docs/theming">Full theming documentation</a> — same CSS variables and <code>data-theme</code> in Svelte.</p>
+  <p><a href="/docs/svelte">← Back to Svelte docs</a></p>
+</section>

package/scaffold/svelte-app/src/lib/rizzo-docs/pages/ToastDoc.svelte

@@ -0,0 +1,136 @@
+<script lang="ts">
+  import CodeBlock from '$lib/rizzo-docs/CodeBlock.svelte';
+
+  function showToastGlobal(message: string, options?: { variant?: string; position?: string; autoDismiss?: number }) {
+    if (typeof window !== 'undefined' && (window as any).showToast) {
+      (window as any).showToast(message, options);
+    }
+  }
+
+  function removeAllToastsGlobal() {
+    if (typeof window !== 'undefined' && (window as any).removeAllToasts) {
+      (window as any).removeAllToasts();
+    }
+  }
+</script>
+
+<section>
+  <h2>Toast component</h2>
+  <p>Fixed-position notifications (success, error, warning, info). Use the <strong>Toast</strong> component for a single static toast, or the <strong>programmatic API</strong> (<code>showToast</code>, <code>removeToast</code>, <code>removeAllToasts</code>) for dynamic toasts. Same BEM and behavior as the Astro/docs site.</p>
+
+  <h3>Features</h3>
+  <ul>
+    <li>Six positions: top-right, top-left, top-center, bottom-right, bottom-left, bottom-center</li>
+    <li>Variants: success, error, warning, info (same as Alert)</li>
+    <li>Auto-dismiss with configurable duration (default 5s); set to <code>0</code> to disable</li>
+    <li>Dismissible with close button (default: true)</li>
+    <li>Multiple toasts stack vertically in the same position</li>
+    <li>Smooth slide-in/out (respects <code>prefers-reduced-motion</code>)</li>
+    <li>ARIA (<code>role="alert"</code>, <code>aria-live="polite"</code>)</li>
+    <li>Theme-aware; full width on mobile</li>
+  </ul>
+
+  <h3>Programmatic API</h3>
+  <p>Import the toast utility and call it from Svelte (e.g. in an event handler or after a mutation):</p>
+  <CodeBlock
+    code={`import { showToast, removeToast, removeAllToasts } from '../utils/toast';
+
+// Show a toast (returns toast id)
+const id = showToast('Saved!', { variant: 'success' });
+
+// With options
+showToast('Error occurred', {
+  variant: 'error',
+  position: 'top-right',
+  autoDismiss: 5000,
+  dismissible: true
+});
+
+// Remove by id
+removeToast(id);
+
+// Remove all toasts
+removeAllToasts();`}
+    language="javascript"
+  />
+  <p>On the docs site, <code>window.showToast</code>, <code>window.removeToast</code>, and <code>window.removeAllToasts</code> are also available (injected by the layout).</p>
+
+  <h3>Live examples (programmatic)</h3>
+  <div class="example">
+    <div class="example-title">Show toasts</div>
+    <div class="example-buttons">
+      <button type="button" class="btn btn-success" onclick={() => showToastGlobal('Success! Your changes have been saved.', { variant: 'success' })}>Success</button>
+      <button type="button" class="btn btn-error" onclick={() => showToastGlobal('Something went wrong.', { variant: 'error' })}>Error</button>
+      <button type="button" class="btn btn-warning" onclick={() => showToastGlobal('Please review.', { variant: 'warning' })}>Warning</button>
+      <button type="button" class="btn btn-info" onclick={() => showToastGlobal('New features available.', { variant: 'info' })}>Info</button>
+      <button type="button" class="btn" onclick={() => removeAllToastsGlobal()}>Clear all</button>
+    </div>
+  </div>
+
+  <h3>Positions</h3>
+  <div class="example">
+    <div class="example-title">Position examples</div>
+    <div class="example-buttons">
+      <button type="button" class="btn btn-primary" onclick={() => showToastGlobal('Top right', { position: 'top-right' })}>Top right</button>
+      <button type="button" class="btn btn-primary" onclick={() => showToastGlobal('Top left', { position: 'top-left' })}>Top left</button>
+      <button type="button" class="btn btn-primary" onclick={() => showToastGlobal('Bottom right', { position: 'bottom-right' })}>Bottom right</button>
+      <button type="button" class="btn btn-primary" onclick={() => showToastGlobal('Bottom left', { position: 'bottom-left' })}>Bottom left</button>
+    </div>
+  </div>
+
+  <h3>Static Toast component</h3>
+  <p>For a single toast rendered in the template (e.g. a fixed “Saved” message in a form section), use the Toast component. It wraps Alert with toast positioning. Use it when the toast is part of your layout; for one-off messages use the programmatic API above.</p>
+  <div class="example">
+    <div class="example-title">Static Toast (top-right, dismissible, 5s auto-dismiss)</div>
+    <p>Click to show the same toast via the static component pattern (no toast on page load):</p>
+    <button type="button" class="btn btn-success" onclick={() => showToastGlobal('Changes saved.', { variant: 'success', autoDismiss: 5000 })}>Show “Changes saved” toast</button>
+  </div>
+
+  <h3>Toast options</h3>
+  <ul>
+    <li><code>variant</code> — <code>success</code>, <code>error</code>, <code>warning</code>, <code>info</code> (default: <code>info</code>)</li>
+    <li><code>dismissible</code> — Show close button (default: <code>true</code>)</li>
+    <li><code>autoDismiss</code> — Duration in ms; <code>0</code> to disable (default: <code>5000</code>)</li>
+    <li><code>position</code> — <code>top-right</code>, <code>top-left</code>, <code>top-center</code>, <code>bottom-right</code>, <code>bottom-left</code>, <code>bottom-center</code> (default: <code>top-right</code>)</li>
+    <li><code>id</code> — Optional id for the toast (for <code>removeToast(id)</code>)</li>
+  </ul>
+
+  <h3>Key BEM classes</h3>
+  <ul>
+    <li><strong>Static wrapper:</strong> <code>toast</code>, <code>toast--top-right</code> (etc.); <code>data-toast-container</code>. Contains an Alert.</li>
+    <li><strong>Programmatic container:</strong> <code>toast-container</code>, <code>toast-container--top-right</code> (etc.). Created by <code>showToast()</code>; holds elements with class <code>alert alert--{'{variant}'}</code> (same as Alert component).</li>
+  </ul>
+
+  <h3>Usage (Svelte)</h3>
+  <CodeBlock
+    code={`<script>
+  import Toast from './components/svelte/Toast.svelte';
+  import { showToast, removeToast, removeAllToasts } from './utils/toast';
+
+  function onSave() {
+    saveData();
+    showToast('Saved!', { variant: 'success' });
+  }
+</script>
+
+<!-- Static toast -->
+<Toast variant="success" dismissible autoDismiss={5000} position="top-right">
+  Changes saved.
+</Toast>
+
+<!-- Or programmatic only -->
+<button onclick={onSave}>Save</button>`}
+    language="svelte"
+  />
+
+  <p><a href="/docs/components/toast">Full Astro Toast documentation</a> — options and programmatic API.</p>
+  <p><a href="/docs/svelte/components">← Back to Svelte components</a></p>
+</section>
+
+<style>
+  .example-buttons {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--spacing-3);
+  }
+</style>

package/scaffold/svelte-app/src/lib/rizzo-docs/pages/TooltipDoc.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+  import Tooltip from '$lib/rizzo/Tooltip.svelte';
+  import Button from '$lib/rizzo/Button.svelte';
+  import CodeBlock from '$lib/rizzo-docs/CodeBlock.svelte';
+</script>
+
+<section>
+  <h2>Tooltip component</h2>
+  <p>Wrap the trigger in <code>tooltip-wrapper</code> and set <code>aria-describedby</code> to the tooltip <code>id</code>. Positions: top, bottom, left, right.</p>
+
+  <h3>Basic and positions</h3>
+  <div class="example">
+    <div class="example-title">Live examples</div>
+    <div class="example-tooltips">
+      <div class="tooltip-wrapper" aria-describedby="tooltip-svelte-top">
+        <Button variant="primary">Hover me (top)</Button>
+        <Tooltip id="tooltip-svelte-top" text="Tooltip on top" position="top" />
+      </div>
+      <div class="tooltip-wrapper" aria-describedby="tooltip-svelte-bottom">
+        <Button variant="primary">Bottom</Button>
+        <Tooltip id="tooltip-svelte-bottom" text="Tooltip on bottom" position="bottom" />
+      </div>
+      <div class="tooltip-wrapper" aria-describedby="tooltip-svelte-left">
+        <Button variant="outline">Left</Button>
+        <Tooltip id="tooltip-svelte-left" text="Left" position="left" />
+      </div>
+      <div class="tooltip-wrapper" aria-describedby="tooltip-svelte-right">
+        <Button variant="outline">Right</Button>
+        <Tooltip id="tooltip-svelte-right" text="Right" position="right" />
+      </div>
+    </div>
+  </div>
+
+  <h3>Usage</h3>
+  <CodeBlock
+    code={`<script>
+  import Button from './components/svelte/Button.svelte';
+  import Tooltip from './components/svelte/Tooltip.svelte';
+</script>
+
+<div class="tooltip-wrapper" aria-describedby="my-tooltip">
+  <Button variant="primary">Hover me</Button>
+  <Tooltip id="my-tooltip" text="Help text" position="top" />
+</div>`}
+    language="svelte"
+  />
+</section>
+
+<style>
+  .example-tooltips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--spacing-4);
+    align-items: center;
+    padding: var(--spacing-8);
+  }
+</style>

package/scaffold/svelte-app/src/routes/+page.svelte

@@ -16,8 +16,8 @@
   <h1 style="font-size: clamp(2.5rem, 8vw, 4rem); font-weight: 800; line-height: 1.1; margin: 0 0 var(--spacing-4) 0; color: var(--text);">Build something great</h1>
   <p style="font-size: var(--font-size-xl); color: var(--text-dim); max-width: 42ch; margin: 0 0 var(--spacing-8) 0; line-height: var(--line-height-relaxed);">Same design system as Vanilla JS and Astro — 14 themes, 24 components, full keyboard and screen reader support.</p>
   <div class="flex flex-wrap justify-center gap-4 mb-12">
-    <a href="https://rizzo-css.vercel.app/docs/getting-started" class="btn btn-primary" target="_blank" rel="noopener noreferrer">Get started</a>
-    <a href="https://rizzo-css.vercel.app/docs/components" class="btn btn-outline" target="_blank" rel="noopener noreferrer">Components</a>
+    <a href="/components" class="btn btn-primary">Component showcase</a>
+    <a href="https://rizzo-css.vercel.app/docs/getting-started" class="btn btn-outline" target="_blank" rel="noopener noreferrer">Get started (docs)</a>
     <button type="button" class="btn btn-outline" on:click={showDemoToast}>Show toast</button>
   </div>
   <div class="flex flex-wrap justify-center gap-3 mb-16">

package/scaffold/svelte-app/src/routes/components/+page.svelte

@@ -0,0 +1,4 @@
+<script lang="ts">
+  import SvelteDocPage from '$lib/rizzo-docs/SvelteDocPage.svelte';
+</script>
+<SvelteDocPage slug="components" />

package/scaffold/svelte-app/src/routes/components/[slug]/+page.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+  import SvelteDocPage from '$lib/rizzo-docs/SvelteDocPage.svelte';
+  import { page } from '$app/stores';
+
+  const slug = $derived($page.params.slug ? 'components/' + $page.params.slug : 'components');
+</script>
+<SvelteDocPage slug={slug} />

package/scaffold/vanilla/README.md

@@ -1,6 +1,6 @@
 # Vanilla JS + Rizzo CSS
 
-This project was scaffolded with `npx rizzo-css init` (Vanilla JS).
+This project was scaffolded with `npx rizzo-css init` when you chose **Create new project** and Vanilla JS. This full clone (home, component showcase) is only generated for new projects; **Add to existing project** only adds the CSS and optional files.
 
 ## First-time setup
 
@@ -13,10 +13,17 @@ If you prefer to load CSS from a CDN instead of the local file, replace the `<li
 - `<link rel="stylesheet" href="https://unpkg.com/rizzo-css@latest/dist/rizzo.min.css" />`  
 - Or jsDelivr: `https://cdn.jsdelivr.net/npm/rizzo-css@latest/dist/rizzo.min.css`  
 
-(Replace `@latest` with a specific version, e.g. `@0.0.12`, in production.)
+(Replace `@latest` with a specific version, e.g. `@0.0.13`, in production.)
 
 The CLI replaces placeholders in `index.html` (e.g. `{{DATA_THEME}}`, `{{TITLE}}`) when you run `rizzo-css init`. The theme selected during init is used on first load when you have no saved preference in the browser.
 
+## Editing the cloned site
+
+- **Home** — `index.html` (hero, links to component showcase and docs). Edit the main content or add your own.
+- **Component showcase** — `components/index.html` lists all components; `components/<name>.html` (e.g. `button.html`) each has a "Read the full docs" link to the main site. Edit or add HTML files; keep the same header/footer if you want the theme switcher and settings on every page.
+- **CSS** — The CLI copies `css/rizzo.min.css`; the link uses `{{LINK_HREF}}` (replaced at init). To use a CDN, replace that with the CDN URL.
+- **Scripts** — `js/main.js` provides theme sync, settings panel, toast, tabs, modal, dropdown, accordion. Customize or extend as needed.
+
 ## What’s included
 
 - **Theme flash prevention** — Small inline script in `<head>` applies saved theme and settings before first paint.
@@ -41,7 +48,7 @@ pnpm dlx serve .
 
 ## Other scaffolds
 
-- **Astro:** `scaffold/astro-app/` — minimal Astro app (see its README).
-- **Svelte:** `scaffold/svelte-app/` — SvelteKit app (see its README).
+- **Astro:** `scaffold/astro-app/` — navbar, home, component showcase (see its README).
+- **Svelte:** `scaffold/svelte-app/` — SvelteKit with /components and /components/[slug] (see its README).
 
 Docs: [rizzo-css.vercel.app](https://rizzo-css.vercel.app)