rizzo-css 0.0.12 → 0.0.13

package/scaffold/astro-app/src/pages/components/pagination.astro

@@ -0,0 +1,126 @@
+---
+import DocsLayout from '../../layouts/DocsLayout.astro';
+import PaginationComponent from '../../components/Pagination.astro';
+import CodeBlock from '../../components/CodeBlock.astro';
+---
+
+<DocsLayout title="Pagination Component — Astro" description="Accessible pagination navigation with previous/next, page numbers, and ellipsis">
+	
+	<p class="docs__read-docs">Read the full docs for this component at <a href="https://rizzo-css.vercel.app/docs/components/pagination" target="_blank" rel="noopener noreferrer">https://rizzo-css.vercel.app/docs/components/pagination</a>.</p>
+	
+		<section>
+		<h2>Pagination Component</h2>
+		<p>An accessible pagination component for navigating between pages. Supports previous/next, first/last, page numbers with ellipsis for long ranges, and a configurable URL pattern.</p>
+		
+		<h3>Props</h3>
+		<ul>
+			<li><code>currentPage</code> (number, required) - The current page number (1-based)</li>
+			<li><code>totalPages</code> (number, required) - Total number of pages</li>
+			<li><code>hrefTemplate</code> (string, optional) - URL pattern with <code>{'{page}'}</code> placeholder (default: <code>?page={'{page}'}</code>)</li>
+			<li><code>showFirstLast</code> (boolean, optional) - Show First and Last links (default: <code>true</code>)</li>
+			<li><code>maxVisible</code> (number, optional) - Max page numbers to show before using ellipsis (default: <code>5</code>)</li>
+			<li><code>class</code> (string, optional) - Additional CSS classes</li>
+		</ul>
+
+		<h3>Basic Usage</h3>
+		<p>Click any page to see the current page update. The example uses <code>syncHash</code> so the URL hash and current page stay in sync.</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<PaginationComponent
+				currentPage={3}
+				totalPages={10}
+				maxVisible={10}
+				hrefTemplate={"#page-{page}"}
+				syncHash
+			/>
+		</div>
+
+		<CodeBlock code={`---
+import Pagination from '../../components/Pagination.astro';
+---
+
+<Pagination
+  currentPage={3}
+  totalPages={10}
+  hrefTemplate="?page={page}"
+/>`} language="astro" />
+
+		<h3>With Query String</h3>
+		<p>Use <code>hrefTemplate</code> to build URLs. The <code>{'{page}'}</code> placeholder is replaced with the page number. For in-page demos we use hash links with <code>syncHash</code> so the current page updates without a full reload:</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<PaginationComponent
+				currentPage={2}
+				totalPages={5}
+				hrefTemplate={"#page-{page}"}
+				syncHash
+			/>
+		</div>
+
+		<CodeBlock code={`<Pagination
+  currentPage={2}
+  totalPages={5}
+  hrefTemplate="/blog?page={page}"
+/>`} language="astro" />
+
+		<h3>Without First/Last</h3>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<PaginationComponent
+				currentPage={5}
+				totalPages={10}
+				maxVisible={10}
+				showFirstLast={false}
+				hrefTemplate={"#page-{page}"}
+				syncHash
+			/>
+		</div>
+
+		<CodeBlock code={`<Pagination
+  currentPage={5}
+  totalPages={10}
+  showFirstLast={false}
+  hrefTemplate="?page={page}"
+/>`} language="astro" />
+
+		<h3>Many Pages (Ellipsis)</h3>
+		<p>When <code>totalPages</code> exceeds <code>maxVisible</code>, ellipsis (…) is shown between the first/last and the range around the current page:</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<PaginationComponent
+				currentPage={7}
+				totalPages={20}
+				maxVisible={5}
+				hrefTemplate={"#page-{page}"}
+				syncHash
+			/>
+		</div>
+
+		<h3>First and Last Page</h3>
+		<p>Previous/Next and First/Last are disabled when on the first or last page:</p>
+		<div class="example">
+			<div class="example-title">Live Example (Page 1 of 5)</div>
+			<PaginationComponent
+				currentPage={1}
+				totalPages={5}
+				hrefTemplate={"#page-{page}"}
+				syncHash
+			/>
+		</div>
+
+		<h3>Verifying the examples</h3>
+		<p>All live examples above use <code>hrefTemplate="#page-{'{page}'}"</code> and <code>syncHash</code>. To confirm they work: open this page, click different page numbers (and First/Previous/Next/Last where shown). The URL hash should update (e.g. <code>#page-5</code>) and the current page highlight should move. Changing the hash in the address bar (e.g. to <code>#page-1</code>) should update the highlighted page.</p>
+
+		<h3>Features</h3>
+		<ul>
+			<li><strong>Semantic markup</strong> - <code>&lt;nav aria-label="Pagination"&gt;</code> with list of links</li>
+			<li><strong>Previous / Next</strong> - Always shown; disabled (non-clickable) on first/last page</li>
+			<li><strong>First / Last</strong> - Optional; controlled by <code>showFirstLast</code></li>
+			<li><strong>Page numbers</strong> - Current page has <code>aria-current="page"</code> and is not a link</li>
+			<li><strong>Ellipsis</strong> - When many pages, shows 1 … 4 5 6 … 10 style range</li>
+			<li><strong>Configurable URLs</strong> - <code>hrefTemplate</code> with <code>{'{page}'}</code> placeholder</li>
+			<li><strong>Theme-aware</strong> - Uses design system variables</li>
+		</ul>
+		<p><strong>Svelte & Vanilla:</strong> <a href="/docs/svelte/components/pagination">Svelte</a> · Vanilla: same HTML and BEM as in Usage above.</p>
+	</section>
+</DocsLayout>

package/scaffold/astro-app/src/pages/components/progress-bar.astro

@@ -0,0 +1,94 @@
+---
+import DocsLayout from '../../layouts/DocsLayout.astro';
+import ProgressBarComponent from '../../components/ProgressBar.astro';
+import CodeBlock from '../../components/CodeBlock.astro';
+---
+
+<DocsLayout title="Progress Bar Component — Astro" description="Accessible progress bar with variants, sizes, and indeterminate state">
+	
+	<p class="docs__read-docs">Read the full docs for this component at <a href="https://rizzo-css.vercel.app/docs/components/progress-bar" target="_blank" rel="noopener noreferrer">https://rizzo-css.vercel.app/docs/components/progress-bar</a>.</p>
+	
+		<section>
+		<h2>Progress Bar Component</h2>
+		<p>An accessible progress bar for showing completion or loading state. Supports determinate (value-based) and indeterminate (animated) modes, multiple variants and sizes, and an optional percentage label.</p>
+		
+		<h3>Props</h3>
+		<ul>
+			<li><code>value</code> (number, optional) - Current value, 0 to max (default: 0)</li>
+			<li><code>max</code> (number, optional) - Maximum value (default: 100)</li>
+			<li><code>variant</code> (string, optional) - <code>primary</code>, <code>success</code>, <code>warning</code>, <code>error</code>, <code>info</code> (default: primary)</li>
+			<li><code>size</code> (string, optional) - <code>sm</code>, <code>md</code>, <code>lg</code> (default: md)</li>
+			<li><code>showLabel</code> (boolean, optional) - Show percentage label (default: false)</li>
+			<li><code>indeterminate</code> (boolean, optional) - Animated loading state, ignores value (default: false)</li>
+			<li><code>label</code> (string, optional) - Accessible label (aria-label)</li>
+			<li><code>class</code> (string, optional) - Additional CSS classes</li>
+		</ul>
+
+		<h3>Basic Usage</h3>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<ProgressBarComponent value={60} max={100} />
+		</div>
+		<CodeBlock code={`---
+import ProgressBar from '../../components/ProgressBar.astro';
+---
+
+<ProgressBar value={60} max={100} />`} language="astro" />
+
+		<h3>With Label</h3>
+		<p>Use <code>showLabel</code> to display the percentage next to the bar.</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<ProgressBarComponent value={75} max={100} showLabel />
+		</div>
+		<CodeBlock code={`<ProgressBar value={75} max={100} showLabel />`} language="astro" />
+
+		<h3>Variants</h3>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<div style="display: flex; flex-direction: column; gap: var(--spacing-4);">
+				<ProgressBarComponent value={40} variant="primary" />
+				<ProgressBarComponent value={55} variant="success" />
+				<ProgressBarComponent value={70} variant="warning" />
+				<ProgressBarComponent value={85} variant="error" />
+				<ProgressBarComponent value={25} variant="info" />
+			</div>
+		</div>
+
+		<h3>Sizes</h3>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<div style="display: flex; flex-direction: column; gap: var(--spacing-4);">
+				<ProgressBarComponent value={50} size="sm" />
+				<ProgressBarComponent value={50} size="md" />
+				<ProgressBarComponent value={50} size="lg" />
+			</div>
+		</div>
+
+		<h3>Indeterminate</h3>
+		<p>Use <code>indeterminate</code> for loading states when progress is unknown. The bar shows an animated fill. Provide an <code>aria-label</code> (e.g. "Loading") for accessibility.</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<ProgressBarComponent indeterminate label="Loading" />
+		</div>
+		<CodeBlock code={`<ProgressBar indeterminate label="Loading" />`} language="astro" />
+
+		<h3>Custom Max</h3>
+		<p>Use <code>max</code> and <code>value</code> for non-percentage progress (e.g. steps). The bar width is computed as value/max.</p>
+		<div class="example">
+			<div class="example-title">Live Example (3 of 5 steps)</div>
+			<ProgressBarComponent value={3} max={5} showLabel />
+		</div>
+		<CodeBlock code={`<ProgressBar value={3} max={5} showLabel />`} language="astro" />
+
+		<h3>Features</h3>
+		<ul>
+			<li><strong>Semantic</strong> - <code>role="progressbar"</code> with <code>aria-valuenow</code>, <code>aria-valuemin</code>, <code>aria-valuemax</code></li>
+			<li><strong>Indeterminate</strong> - <code>aria-valuetext="Loading"</code> when progress is unknown</li>
+			<li><strong>Variants</strong> - Primary, success, warning, error, info using theme variables</li>
+			<li><strong>Sizes</strong> - sm, md, lg bar heights</li>
+			<li><strong>Reduced motion</strong> - Indeterminate animation disabled when user prefers reduced motion</li>
+		</ul>
+		<p><strong>Svelte & Vanilla:</strong> <a href="/docs/svelte/components/progress-bar">Svelte</a> · Vanilla: same HTML and BEM as in Usage above.</p>
+	</section>
+</DocsLayout>

package/scaffold/astro-app/src/pages/components/search.astro

@@ -0,0 +1,155 @@
+---
+import DocsLayout from '../../layouts/DocsLayout.astro';
+import SearchComponent from '../../components/Search.astro';
+import CodeBlock from '../../components/CodeBlock.astro';
+---
+
+<DocsLayout title="Search Component — Astro" description="Search component with Algolia integration and live filtering">
+	
+	<p class="docs__read-docs">Read the full docs for this component at <a href="https://rizzo-css.vercel.app/docs/components/search" target="_blank" rel="noopener noreferrer">https://rizzo-css.vercel.app/docs/components/search</a>.</p>
+	
+		<section>
+		<h2>Search Component</h2>
+		<p>An accessible search component with Algolia integration for fast, relevant search results. Includes live filtering, keyboard navigation, and a client-side fallback.</p>
+	</section>
+	
+	<section>
+		<h2>Features</h2>
+		<ul>
+			<li><strong>Full-screen overlay</strong> - When open, the overlay covers the viewport; the search modal is centered inside it both horizontally and vertically</li>
+			<li>Algolia integration with client-side fallback</li>
+			<li>Keyboard shortcut - <kbd>Ctrl+K</kbd> / <kbd>Cmd+K</kbd> to open</li>
+			<li>Close button on desktop (X icon with screen reader label)</li>
+			<li>Close button on mobile with text label</li>
+			<li>Live search results as you type</li>
+			<li>Full keyboard navigation (Arrow keys, Enter, Escape, Tab)</li>
+			<li>Mobile responsive - Full-width panel on mobile</li>
+			<li>Mutually exclusive with mobile menu (only one open at a time)</li>
+			<li>Accessible - ARIA attributes and screen reader support</li>
+		</ul>
+	</section>
+	
+	<section>
+		<h2>Live example</h2>
+		<p>Search is in the navbar (top of page) — click the search icon or press <kbd>Ctrl+K</kbd> / <kbd>Cmd+K</kbd>. You can also use the standalone search below.</p>
+		<div class="example">
+			<div class="example-title">Standalone search (same as navbar)</div>
+			<div class="search-doc-example">
+				<SearchComponent />
+			</div>
+		</div>
+	</section>
+	
+	<section>
+		<h2>Usage</h2>
+		<CodeBlock code={`---
+import Search from '../../components/Search.astro';
+---
+
+<!-- Client-side search (default; uses built-in index when no Algolia credentials) -->
+<Search />
+
+<!-- With Algolia (pass credentials via props or env) -->
+<Search
+  useAlgolia={true}
+  algoliaAppId="YOUR_APP_ID"
+  algoliaApiKey="YOUR_SEARCH_ONLY_API_KEY"
+  algoliaIndexName="rizzo-css-docs"
+/>`} language="astro" />
+	</section>
+	
+	<section>
+		<h2>Props</h2>
+		<ul>
+			<li><code>useAlgolia</code> (boolean, optional) - Enable Algolia search (default: <code>false</code>)</li>
+			<li><code>algoliaAppId</code> (string, optional) - Algolia Application ID</li>
+			<li><code>algoliaApiKey</code> (string, optional) - Algolia Search-Only API Key</li>
+			<li><code>algoliaIndexName</code> (string, optional) - Algolia index name (default: <code>"rizzo-css-docs"</code>)</li>
+		</ul>
+	</section>
+	
+	<section>
+		<h2>Keyboard Shortcuts</h2>
+		<ul>
+			<li><kbd>Ctrl+K</kbd> / <kbd>Cmd+K</kbd> - Open/close search</li>
+			<li><kbd>Escape</kbd> - Close search</li>
+			<li><kbd>Arrow Down</kbd> - Navigate to next result</li>
+			<li><kbd>Arrow Up</kbd> - Navigate to previous result</li>
+			<li><kbd>Enter</kbd> - Navigate to selected result</li>
+		</ul>
+	</section>
+	
+	<section>
+		<h2>Algolia Setup</h2>
+		<p>To use Algolia search in production:</p>
+		<ol>
+			<li>Create an account at <a href="https://www.algolia.com/" target="_blank" rel="noopener noreferrer">algolia.com</a></li>
+			<li>Create a new application and get your credentials</li>
+			<li>Index your documentation using the indexing script:
+				<CodeBlock code={`# Install Algolia client
+pnpm add algoliasearch
+
+# Set environment variables
+export ALGOLIA_APP_ID="your-app-id"
+export ALGOLIA_API_KEY="your-admin-api-key"
+export ALGOLIA_INDEX_NAME="rizzo-css-docs"
+
+# Run indexing script
+node scripts/index-docs.js`} language="nodejs" />
+			</li>
+			<li>Configure your Search component with the credentials</li>
+		</ol>
+		<p>See <a href="/docs/search">Search Documentation</a> for complete setup instructions.</p>
+	</section>
+	
+	<section>
+		<h2>Accessibility</h2>
+		<p>The Search component includes comprehensive accessibility features:</p>
+		<ul>
+			<li><strong>ARIA Roles:</strong> <code>role="dialog"</code>, <code>role="listbox"</code>, <code>role="option"</code></li>
+			<li><strong>ARIA Labels:</strong> Descriptive labels for all interactive elements</li>
+			<li><strong>Keyboard Navigation:</strong> Full keyboard support for all interactions</li>
+			<li><strong>Focus Management:</strong> Focus trapping and restoration</li>
+			<li><strong>Screen Reader Support:</strong> Proper announcements and labels</li>
+			<li><strong>Live Regions:</strong> Search results announced to screen readers</li>
+		</ul>
+		<p><strong>Svelte & Vanilla:</strong> <a href="/docs/svelte/components/search">Svelte</a> · Vanilla: same HTML and BEM as in Usage above; add JS for Cmd+K and Algolia.</p>
+	</section>
+</DocsLayout>
+
+<style>
+	/* Search trigger matches navbar size (base .search__trigger already has same padding/min) */
+	.search-doc-example {
+		display: flex;
+		align-items: center;
+		gap: var(--spacing-4);
+	}
+	@media (width <= 1023px) {
+		.search-doc-example .search__trigger {
+			width: auto;
+			justify-content: center;
+		}
+		.search-doc-example .search__trigger-text,
+		.search-doc-example .search__kbd {
+			position: absolute;
+			width: 1px;
+			height: 1px;
+			padding: 0;
+			margin: -1px;
+			overflow: hidden;
+			clip-path: inset(50%);
+			white-space: nowrap;
+			border: 0;
+		}
+	}
+	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/astro-app/src/pages/components/settings.astro

@@ -0,0 +1,78 @@
+---
+import DocsLayout from '../../layouts/DocsLayout.astro';
+import CodeBlock from '../../components/CodeBlock.astro';
+import Gear from '../../components/icons/Gear.astro';
+---
+
+<DocsLayout title="Settings Component — Astro" description="Comprehensive settings panel for theme switching, font size adjustment, and accessibility options">
+	
+	<p class="docs__read-docs">Read the full docs for this component at <a href="https://rizzo-css.vercel.app/docs/components/settings" target="_blank" rel="noopener noreferrer">https://rizzo-css.vercel.app/docs/components/settings</a>.</p>
+	
+		<section>
+		<h2>Settings Component</h2>
+		<p>A comprehensive settings panel for theme switching, font size adjustment, and accessibility options.</p>
+		
+		<h3>Features</h3>
+		<ul>
+			<li><strong>Theme Switcher</strong> - Integrated ThemeSwitcher component with theme icons (persists in localStorage as <code>theme</code>)</li>
+			<li><strong>Font Size Slider</strong> - Adjustable from 75% to 150% with filled track indicator (uses CSS gradient with <code>--slider-progress</code> variable). Persists in localStorage as <code>fontSizeScale</code></li>
+			<li><strong>Reduce Motion Toggle</strong> - Applies <code>.reduced-motion</code> class to document root. Persists in localStorage as <code>reducedMotion</code></li>
+			<li><strong>High Contrast Toggle</strong> - Applies <code>.high-contrast</code> class to document root. Persists in localStorage as <code>highContrast</code></li>
+			<li><strong>Scrollbar Style</strong> - Radio button group with three options: Thin (default, 0.5rem/8px), Thick (1.5rem/24px), and Hidden. Applies classes to <code>html</code> element (<code>.scrollbar-thick</code> or <code>.scrollbar-hidden</code>). Persists in localStorage as <code>scrollbarStyle</code> (values: <code>thin</code>, <code>thick</code>, <code>hidden</code>)</li>
+			<li><strong>Opening and Closing Animations</strong> - Smooth slide-in from right with overlay fade (respects <code>prefers-reduced-motion</code>)</li>
+			<li><strong>Focus Trapping</strong> - Tab cycles within panel when open</li>
+			<li><strong>Focus Management</strong> - Returns focus to trigger element on close</li>
+			<li>Slide-in panel with overlay</li>
+			<li><strong>All settings persist in localStorage</strong> - All preferences are automatically saved and restored on page load</li>
+			<li>Full keyboard navigation (Escape to close)</li>
+			<li>Accessible ARIA attributes</li>
+			<li>Slider track visibility optimized for all themes</li>
+			<li><strong>Mobile Responsive</strong> - Full width on mobile devices, optimized layout</li>
+		</ul>
+		
+		<h3>Settings Persistence</h3>
+		<p>All settings options automatically persist to localStorage and are restored when the page loads:</p>
+		<ul>
+			<li><code>theme</code> - Selected theme name (e.g., <code>github-dark-classic</code>, <code>github-light</code>)</li>
+			<li><code>fontSizeScale</code> - Font size multiplier (e.g., <code>1.0</code> for 100%, <code>1.25</code> for 125%)</li>
+			<li><code>reducedMotion</code> - Boolean string (<code>true</code> or <code>false</code>)</li>
+			<li><code>highContrast</code> - Boolean string (<code>true</code> or <code>false</code>)</li>
+			<li><code>scrollbarStyle</code> - Scrollbar style preference (<code>thin</code>, <code>thick</code>, or <code>hidden</code>)</li>
+		</ul>
+		
+		<h3>Live example</h3>
+		<p>Open Settings via the gear icon in the navbar or the button below (same as navbar).</p>
+		<div class="example">
+			<div class="example-title">Open Settings</div>
+			<button type="button" class="navbar__settings-btn" aria-label="Open settings" onclick="window.openSettings && window.openSettings()">
+				<Gear class="navbar__settings-icon" width={20} height={20} />
+				<span class="navbar__settings-label">Settings</span>
+			</button>
+		</div>
+		
+		<h3>Usage</h3>
+		<CodeBlock code={`---
+import Settings from '../../components/Settings.astro';
+---
+
+<!-- Include once in layout (e.g. with Navbar). Default closed. -->
+<Settings open={false} />
+
+<!-- Open/close from JS (e.g. navbar gear button): -->
+<!-- window.openSettings(); window.closeSettings(); -->`} language="astro" />
+		
+		<h3>Props</h3>
+		<ul>
+			<li><code>open</code> (boolean, optional) - Whether settings panel is open by default (default: false)</li>
+		</ul>
+		
+		<h3>Opening Settings</h3>
+		<p>The Settings component registers <code>window.openSettings()</code> and <code>window.closeSettings()</code>. The Navbar gear button calls <code>openSettings()</code>.</p>
+		<CodeBlock code={`// Open the settings panel (e.g. from a button or navbar)
+window.openSettings();
+
+// Close the settings panel
+window.closeSettings();`} language="javascript" />
+		<p><strong>Svelte & Vanilla:</strong> <a href="/docs/svelte/components/settings">Svelte</a> · Vanilla: same HTML and BEM as in Usage above; scaffold includes <code>openSettings()</code>.</p>
+	</section>
+</DocsLayout>

package/scaffold/astro-app/src/pages/components/spinner.astro

@@ -0,0 +1,81 @@
+---
+import DocsLayout from '../../layouts/DocsLayout.astro';
+import SpinnerComponent from '../../components/Spinner.astro';
+import CodeBlock from '../../components/CodeBlock.astro';
+---
+
+<DocsLayout title="Spinner Component — Astro" description="Accessible loading spinner with variants and sizes">
+	
+	<p class="docs__read-docs">Read the full docs for this component at <a href="https://rizzo-css.vercel.app/docs/components/spinner" target="_blank" rel="noopener noreferrer">https://rizzo-css.vercel.app/docs/components/spinner</a>.</p>
+	
+		<section>
+		<h2>Spinner Component</h2>
+		<p>An accessible loading spinner for indicating progress when content is loading. Uses <code>role="status"</code> and an <code>aria-label</code> (default: "Loading") so screen readers announce the state. Supports multiple sizes and color variants.</p>
+		
+		<h3>Props</h3>
+		<ul>
+			<li><code>size</code> (string, optional) - <code>sm</code>, <code>md</code>, <code>lg</code> (default: md)</li>
+			<li><code>variant</code> (string, optional) - <code>primary</code>, <code>success</code>, <code>warning</code>, <code>error</code>, <code>info</code> (default: primary)</li>
+			<li><code>label</code> (string, optional) - Accessible label for screen readers (default: "Loading")</li>
+			<li><code>class</code> (string, optional) - Additional CSS classes</li>
+		</ul>
+
+		<h3>Basic Usage</h3>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<SpinnerComponent />
+		</div>
+		<CodeBlock code={`---
+import Spinner from '../../components/Spinner.astro';
+---
+
+<Spinner />`} language="astro" />
+
+		<h3>Sizes</h3>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<div style="display: flex; align-items: center; gap: var(--spacing-6); flex-wrap: wrap;">
+				<SpinnerComponent size="sm" />
+				<SpinnerComponent size="md" />
+				<SpinnerComponent size="lg" />
+			</div>
+		</div>
+		<CodeBlock code={`<Spinner size="sm" />
+<Spinner size="md" />
+<Spinner size="lg" />`} language="astro" />
+
+		<h3>Variants</h3>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<div style="display: flex; align-items: center; gap: var(--spacing-6); flex-wrap: wrap;">
+				<SpinnerComponent variant="primary" />
+				<SpinnerComponent variant="success" />
+				<SpinnerComponent variant="warning" />
+				<SpinnerComponent variant="error" />
+				<SpinnerComponent variant="info" />
+			</div>
+		</div>
+		<CodeBlock code={`<Spinner variant="primary" />
+<Spinner variant="success" />
+<Spinner variant="warning" />
+<Spinner variant="error" />
+<Spinner variant="info" />`} language="astro" />
+
+		<h3>Custom Label</h3>
+		<p>Use the <code>label</code> prop to describe the loading context for screen readers (e.g. "Loading results", "Saving…").</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<SpinnerComponent label="Loading results…" />
+		</div>
+		<CodeBlock code={`<Spinner label="Loading results…" />`} language="astro" />
+
+		<h3>Features</h3>
+		<ul>
+			<li><strong>Accessible</strong> - <code>role="status"</code> and <code>aria-label</code> so screen readers announce loading</li>
+			<li><strong>Variants</strong> - Primary, success, warning, error, info using theme variables</li>
+			<li><strong>Sizes</strong> - sm, md, lg</li>
+			<li><strong>Reduced motion</strong> - Animation disabled when user prefers reduced motion; static segment shown instead</li>
+		</ul>
+		<p><strong>Svelte & Vanilla:</strong> <a href="/docs/svelte/components/spinner">Svelte</a> · Vanilla: same HTML and BEM as in Usage above.</p>
+	</section>
+</DocsLayout>