npm - rizzo-css - Versions diffs - 0.0.11 → 0.0.13 - Mend

rizzo-css 0.0.11 → 0.0.13

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

Files changed (233) hide show

package/scaffold/astro-app/src/layouts/Layout.astro CHANGED Viewed

@@ -1,4 +1,6 @@
 ---
+import Navbar from '../components/Navbar.astro';
+import Settings from '../components/Settings.astro';
 interface Props {
   title?: string;
 }
@@ -16,7 +18,7 @@ const { title = '{{TITLE}}' } = Astro.props;
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <!-- Theme flash prevention + accessibility (same as main site) -->
     <script is:inline>
-      (function(){try{var s=localStorage.getItem('theme');var d='github-dark-classic';var l='github-light';var initial=document.documentElement.getAttribute('data-theme');var r=!s?(initial||(matchMedia('(prefers-color-scheme: dark)').matches?d:l)):s==='system'?(matchMedia('(prefers-color-scheme: dark)').matches?d:l):s;document.documentElement.setAttribute('data-theme',r);var f=localStorage.getItem('fontSizeScale');if(f)document.documentElement.style.setProperty('--font-size-scale',f);if(localStorage.getItem('reducedMotion')==='true')document.documentElement.classList.add('reduced-motion');if(localStorage.getItem('highContrast')==='true')document.documentElement.classList.add('high-contrast');var b=localStorage.getItem('scrollbarStyle')||'thin';if(b==='thick')document.documentElement.classList.add('scrollbar-thick');else if(b==='hidden')document.documentElement.classList.add('scrollbar-hidden','hide-scrollbars');}catch(e){}})();
+      (function(){try{var s=localStorage.getItem('theme');var d='{{DEFAULT_DARK}}';var l='{{DEFAULT_LIGHT}}';var initial=document.documentElement.getAttribute('data-theme');var r=!s?((initial&&initial!=='system')?initial:(matchMedia('(prefers-color-scheme: dark)').matches?d:l)):s==='system'?(matchMedia('(prefers-color-scheme: dark)').matches?d:l):s;document.documentElement.setAttribute('data-theme',r);var f=localStorage.getItem('fontSizeScale');if(f)document.documentElement.style.setProperty('--font-size-scale',f);if(localStorage.getItem('reducedMotion')==='true')document.documentElement.classList.add('reduced-motion');if(localStorage.getItem('highContrast')==='true')document.documentElement.classList.add('high-contrast');var b=localStorage.getItem('scrollbarStyle')||'thin';if(b==='thick')document.documentElement.classList.add('scrollbar-thick');else if(b==='hidden')document.documentElement.classList.add('scrollbar-hidden','hide-scrollbars');}catch(e){}})();
     </script>
     <!-- Toast: showToast, removeToast, removeAllToasts -->
     <script is:inline>
@@ -27,6 +29,13 @@ const { title = '{{TITLE}}' } = Astro.props;
     <title>{title}</title>
   </head>
   <body>
-    <slot />
+    <a href="#main-content" class="skip-link">Skip to main content</a>
+    <Navbar />
+    <Settings />
+    <main id="main-content">
+      <div class="layout__container">
+        <slot />
+      </div>
+    </main>
   </body>
 </html>

package/scaffold/astro-app/src/pages/components/accordion.astro ADDED Viewed

@@ -0,0 +1,172 @@
+---
+import DocsLayout from '../../layouts/DocsLayout.astro';
+import AccordionComponent from '../../components/Accordion.astro';
+import CodeBlock from '../../components/CodeBlock.astro';
+---
+<DocsLayout title="Accordion Component — Astro" description="Accessible accordion with collapsible sections, single or multiple open states, and keyboard navigation">
+	<p class="docs__read-docs">Read the full docs for this component at <a href="https://rizzo-css.vercel.app/docs/components/accordion" target="_blank" rel="noopener noreferrer">https://rizzo-css.vercel.app/docs/components/accordion</a>.</p>
+		<section>
+		<h2>Accordion Component</h2>
+		<p>An accessible accordion for collapsible sections. Supports single or multiple open panels and full keyboard navigation.</p>
+		<h3>Props</h3>
+		<ul>
+			<li><code>items</code> (array, required) - Array of objects with <code>id</code>, <code>title</code>, and optional <code>content</code></li>
+			<li><code>id</code> (string, optional) - Unique identifier for the accordion</li>
+			<li><code>allowMultiple</code> (boolean, optional) - Allow multiple panels open at once (default: <code>false</code>)</li>
+			<li><code>defaultExpanded</code> (string | string[], optional) - ID or array of IDs to expand by default (defaults to first item)</li>
+			<li><code>class</code> (string, optional) - Additional CSS classes</li>
+		</ul>
+		<h3>Item Structure</h3>
+		<ul>
+			<li><code>id</code> (string, required) - Unique identifier for the item</li>
+			<li><code>title</code> (string, required) - Heading text for the trigger</li>
+			<li><code>content</code> (string, optional) - HTML content for the panel (alternative to using slots)</li>
+		</ul>
+		<h3>Basic Usage (Single Open)</h3>
+		<p>By default only one panel is open at a time. Provide panel content as children in the same order as the items array:</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<AccordionComponent
+				items={[
+					{ id: 'one', title: 'Section one' },
+					{ id: 'two', title: 'Section two' },
+					{ id: 'three', title: 'Section three' },
+				]}
+			>
+				<div>
+					<p>Content for section one. Only one panel is open at a time.</p>
+				</div>
+				<div>
+					<p>Content for section two.</p>
+				</div>
+				<div>
+					<p>Content for section three.</p>
+				</div>
+			</AccordionComponent>
+		</div>
+		<CodeBlock code={`---
+import Accordion from '../../components/Accordion.astro';
+---
+<Accordion
+  items={[
+    { id: 'one', title: 'Section one' },
+    { id: 'two', title: 'Section two' },
+    { id: 'three', title: 'Section three' },
+  ]}
+>
+  <div><p>Content for section one</p></div>
+  <div><p>Content for section two</p></div>
+  <div><p>Content for section three</p></div>
+</Accordion>`} language="astro" />
+		<h3>Multiple Panels Open</h3>
+		<p>Set <code>allowMultiple</code> to <code>true</code> to allow multiple panels to be open at once:</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<AccordionComponent
+				allowMultiple
+				items={[
+					{ id: 'a', title: 'First' },
+					{ id: 'b', title: 'Second' },
+					{ id: 'c', title: 'Third' },
+				]}
+			>
+				<div><p>First panel content. You can open several at once.</p></div>
+				<div><p>Second panel content.</p></div>
+				<div><p>Third panel content.</p></div>
+			</AccordionComponent>
+		</div>
+		<CodeBlock code={`<Accordion
+  allowMultiple
+  items={[
+    { id: 'a', title: 'First' },
+    { id: 'b', title: 'Second' },
+    { id: 'c', title: 'Third' },
+  ]}
+>
+  <div><p>First panel content</p></div>
+  <div><p>Second panel content</p></div>
+  <div><p>Third panel content</p></div>
+</Accordion>`} language="astro" />
+		<h3>With Content Property</h3>
+		<p>You can provide panel content directly in the item object:</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<AccordionComponent
+				items={[
+					{ id: 'faq1', title: 'What is Rizzo CSS?', content: '<p>A design system and component library built with semantic CSS variables and Astro.</p>' },
+					{ id: 'faq2', title: 'Is it accessible?', content: '<p>Yes. Components follow WCAG 2.1 AA and use proper ARIA patterns.</p>' },
+					{ id: 'faq3', title: 'Can I use it with other frameworks?', content: '<p>The CSS is framework-agnostic. See the multi-framework documentation.</p>' },
+				]}
+			/>
+		</div>
+		<CodeBlock code={`<Accordion
+  items={[
+    { id: 'faq1', title: 'Question one', content: '<p>Answer one</p>' },
+    { id: 'faq2', title: 'Question two', content: '<p>Answer two</p>' },
+  ]}
+/>`} language="astro" />
+		<h3>Default Expanded</h3>
+		<p>Control which panel(s) are open initially with <code>defaultExpanded</code>:</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<AccordionComponent
+				defaultExpanded="second"
+				items={[
+					{ id: 'first', title: 'First' },
+					{ id: 'second', title: 'Second (open by default)' },
+					{ id: 'third', title: 'Third' },
+				]}
+			>
+				<div><p>First panel</p></div>
+				<div><p>Second panel is expanded by default.</p></div>
+				<div><p>Third panel</p></div>
+			</AccordionComponent>
+		</div>
+		<CodeBlock code={`<Accordion
+  defaultExpanded="second"
+  items={[
+    { id: 'first', title: 'First' },
+    { id: 'second', title: 'Second' },
+    { id: 'third', title: 'Third' },
+  ]}
+>
+  <div><p>First</p></div>
+  <div><p>Second</p></div>
+  <div><p>Third</p></div>
+</Accordion>`} language="astro" />
+		<h3>Features</h3>
+		<ul>
+			<li><strong>Collapsible sections</strong> - Expand and collapse panels with smooth transitions</li>
+			<li><strong>Single or multiple open</strong> - <code>allowMultiple</code> controls whether only one or several panels can be open</li>
+			<li><strong>Keyboard navigation</strong> - Arrow Up/Down, Home, End, Enter, and Space</li>
+			<li><strong>ARIA</strong> - <code>aria-expanded</code>, <code>aria-controls</code>, <code>region</code>, <code>aria-labelledby</code></li>
+			<li><strong>Content from props or slots</strong> - Use <code>content</code> (HTML string) or pass children for panel content</li>
+			<li><strong>Theme-aware</strong> - Uses design system variables</li>
+		</ul>
+		<h3>Keyboard Navigation</h3>
+		<ul>
+			<li><strong>Arrow Down</strong> - Focus next trigger</li>
+			<li><strong>Arrow Up</strong> - Focus previous trigger</li>
+			<li><strong>Home</strong> - Focus first trigger</li>
+			<li><strong>End</strong> - Focus last trigger</li>
+			<li><strong>Enter / Space</strong> - Toggle focused panel</li>
+		</ul>
+		<p><strong>Svelte & Vanilla:</strong> <a href="/docs/svelte/components/accordion">Svelte</a> · Vanilla: same HTML and BEM as in Usage above; add minimal JS for expand/collapse.</p>
+	</section>
+</DocsLayout>

package/scaffold/astro-app/src/pages/components/alert.astro ADDED Viewed

@@ -0,0 +1,250 @@
+---
+import DocsLayout from '../../layouts/DocsLayout.astro';
+import CodeBlock from '../../components/CodeBlock.astro';
+---
+<DocsLayout title="Alert Component — Astro" description="Accessible alert component with variants and dismissible functionality">
+	<p class="docs__read-docs">Read the full docs for this component at <a href="https://rizzo-css.vercel.app/docs/components/alert" target="_blank" rel="noopener noreferrer">https://rizzo-css.vercel.app/docs/components/alert</a>.</p>
+		<section>
+		<h2>Alert Component</h2>
+		<p>An accessible alert component for displaying important messages to users. Supports success, error, warning, and info variants with optional dismissible functionality.</p>
+	</section>
+	<section>
+		<h2>Variants</h2>
+		<p>Alerts come in four semantic variants that use theme-aware colors. Click the buttons below to see them in action:</p>
+		<div class="example">
+			<div class="example-title">Live Examples</div>
+			<div style="display: flex; flex-wrap: wrap; gap: var(--spacing-3); margin-bottom: var(--spacing-4);">
+				<button class="btn btn-success" onclick="showAlert('success', 'Success! Your changes have been saved successfully.')">Show Success Alert</button>
+				<button class="btn btn-error" onclick="showAlert('error', 'Error! Something went wrong. Please try again.')">Show Error Alert</button>
+				<button class="btn btn-warning" onclick="showAlert('warning', 'Warning! This action cannot be undone.')">Show Warning Alert</button>
+				<button class="btn btn-info" onclick="showAlert('info', 'Info: New features are available in the latest update.')">Show Info Alert</button>
+			</div>
+			<div id="alert-examples-container" class="alert-examples-container" style="min-height: 1px; margin-top: var(--spacing-4);"></div>
+		</div>
+	</section>
+	<section>
+		<h2>Auto-Dismiss</h2>
+		<p>Alerts can automatically dismiss after a set duration:</p>
+		<div class="example">
+			<div class="example-title">Auto-Dismiss Examples</div>
+			<div style="display: flex; flex-wrap: wrap; gap: var(--spacing-3); margin-bottom: var(--spacing-4);">
+				<button class="btn btn-primary" onclick="showAlert('success', 'This alert will auto-dismiss in 3 seconds', true, 3000, 'alert-auto-dismiss-container')">3 Second Auto-Dismiss</button>
+				<button class="btn btn-primary" onclick="showAlert('info', 'This alert will auto-dismiss in 5 seconds', true, 5000, 'alert-auto-dismiss-container')">5 Second Auto-Dismiss</button>
+				<button class="btn btn-primary" onclick="showAlert('warning', 'This alert will auto-dismiss in 7 seconds', true, 7000, 'alert-auto-dismiss-container')">7 Second Auto-Dismiss</button>
+			</div>
+			<div id="alert-auto-dismiss-container" class="alert-examples-container" style="min-height: 1px; margin-top: var(--spacing-4);"></div>
+		</div>
+	</section>
+	<section>
+		<h2>Usage</h2>
+		<CodeBlock code={`---
+import Alert from '../../components/Alert.astro';
+---
+<!-- Basic alert -->
+<Alert variant="success">
+  Your changes have been saved.
+</Alert>
+<!-- Dismissible alert -->
+<Alert variant="error" dismissible>
+  An error occurred. Please try again.
+</Alert>
+<!-- Auto-dismiss alert -->
+<Alert variant="success" dismissible autoDismiss={5000}>
+  This alert will automatically dismiss in 5 seconds.
+</Alert>`} language="astro" />
+	</section>
+	<section>
+		<h2>Props</h2>
+		<ul>
+			<li><code>variant</code> (string, optional) - Alert variant: <code>"success"</code>, <code>"error"</code>, <code>"warning"</code>, or <code>"info"</code> (default: <code>"info"</code>)</li>
+			<li><code>dismissible</code> (boolean, optional) - Whether the alert can be dismissed (default: <code>false</code>)</li>
+			<li><code>autoDismiss</code> (number, optional) - Auto-dismiss duration in milliseconds. Set to <code>0</code> to disable (default: <code>0</code>). Common values: <code>3000</code> (3s), <code>5000</code> (5s), <code>7000</code> (7s)</li>
+			<li><code>id</code> (string, optional) - Unique ID for the alert. If not provided, a random ID will be generated</li>
+			<li><code>class</code> (string, optional) - Additional CSS classes</li>
+		</ul>
+	</section>
+	<section>
+		<h2>Features</h2>
+		<ul>
+			<li>Four semantic variants (success, error, warning, info)</li>
+			<li>Theme-aware colors using semantic variables</li>
+			<li>Dismissible functionality with smooth animations</li>
+			<li><strong>Auto-dismiss functionality</strong> - Automatically dismiss after a set duration</li>
+			<li>Full keyboard accessibility (Enter/Space to dismiss)</li>
+			<li>ARIA attributes for screen readers (<code>role="alert"</code>, <code>aria-live="polite"</code>)</li>
+			<li>Screen reader announcements when dismissed</li>
+			<li>Respects <code>prefers-reduced-motion</code></li>
+			<li>Focus management for close button</li>
+		</ul>
+		<h3>Toast Notifications</h3>
+		<p>For toast notifications (fixed position alerts), see the <a href="/docs/components/toast">Toast Component documentation</a>.</p>
+	</section>
+	<section>
+		<h2>Accessibility</h2>
+		<p>The Alert component includes comprehensive accessibility features:</p>
+		<ul>
+			<li><strong>ARIA Roles:</strong> Uses <code>role="alert"</code> for important messages</li>
+			<li><strong>Live Regions:</strong> <code>aria-live="polite"</code> for screen reader announcements</li>
+			<li><strong>Labels:</strong> Each variant has an appropriate <code>aria-label</code></li>
+			<li><strong>Keyboard Support:</strong> Close button responds to Enter/Space keys</li>
+			<li><strong>Focus Management:</strong> Close button has visible focus indicators</li>
+			<li><strong>Screen Reader Feedback:</strong> Announces when alerts are dismissed</li>
+		</ul>
+		<p><strong>Svelte & Vanilla:</strong> <a href="/docs/svelte/components/alert">Svelte</a> · Vanilla: same HTML and BEM as in Usage above; add minimal JS for dismiss.</p>
+	</section>
+</DocsLayout>
+<script is:inline>
+	// Make function available globally immediately
+	function showAlert(variant, message, dismissible, autoDismiss, containerId) {
+		if (!message) return;
+		variant = variant || 'info';
+		dismissible = dismissible !== undefined ? dismissible : true;
+		autoDismiss = autoDismiss !== undefined ? autoDismiss : 0;
+		containerId = containerId || 'alert-examples-container';
+		// Find the specific alert container
+		var container = document.getElementById(containerId);
+		if (!container) {
+			// Fallback to first container with class
+			container = document.querySelector('.alert-examples-container');
+		}
+		if (!container) {
+			console.error('Alert container not found:', containerId);
+			return;
+		}
+		var alertId = 'alert-' + Math.random().toString(36).substr(2, 9);
+		var alertEl = document.createElement('div');
+		alertEl.id = alertId;
+		alertEl.className = 'alert alert--' + variant;
+		alertEl.setAttribute('role', 'alert');
+		alertEl.setAttribute('aria-live', 'polite');
+		// Ensure alert is visible and has proper display
+		alertEl.style.display = 'flex';
+		alertEl.style.visibility = 'visible';
+		alertEl.style.opacity = '1';
+		var content = document.createElement('div');
+		content.className = 'alert__content';
+		// Extract variant label and message - remove duplicate variant label from message
+		var variantLabel = variant.charAt(0).toUpperCase() + variant.slice(1);
+		var variantPrefix = variantLabel + '!';
+		var variantPrefixWithColon = variantLabel + ':';
+		// Remove variant label from the beginning of the message if it exists
+		var cleanMessage = message;
+		if (message.toLowerCase().startsWith(variantPrefix.toLowerCase())) {
+			cleanMessage = message.substring(variantPrefix.length).trim();
+		} else if (message.toLowerCase().startsWith(variantPrefixWithColon.toLowerCase())) {
+			cleanMessage = message.substring(variantPrefixWithColon.length).trim();
+		}
+		// Show just the variant label in bold, then the clean message
+		content.innerHTML = '<strong>' + variantPrefix + '</strong> ' + cleanMessage;
+		// Ensure content is visible
+		content.style.color = 'inherit';
+		content.style.display = 'block';
+		content.style.visibility = 'visible';
+		content.style.opacity = '1';
+		alertEl.appendChild(content);
+		var closeBtn = null;
+		if (dismissible) {
+			closeBtn = document.createElement('button');
+			closeBtn.type = 'button';
+			closeBtn.className = 'alert__close';
+			closeBtn.setAttribute('aria-label', 'Dismiss alert');
+			closeBtn.innerHTML = '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="4" y1="4" x2="12" y2="12"></line><line x1="12" y1="4" x2="4" y2="12"></line></svg>';
+			// Ensure close button is visible
+			closeBtn.style.color = 'inherit';
+			closeBtn.style.opacity = '0.8';
+			closeBtn.style.display = 'flex';
+			closeBtn.style.visibility = 'visible';
+			alertEl.appendChild(closeBtn);
+		}
+		container.appendChild(alertEl);
+		// Force CSS to apply after element is in DOM - especially important for warning variant
+		requestAnimationFrame(function() {
+			// Force reflow to apply CSS classes
+			alertEl.offsetHeight;
+			// Get computed styles
+			var computedStyle = window.getComputedStyle(alertEl);
+			var textColor = computedStyle.color;
+			var bgColor = computedStyle.backgroundColor;
+			// For warning alerts, ensure theme variable text color is applied
+			if (variant === 'warning') {
+				// Use CSS variable for theming support
+				alertEl.style.color = 'var(--warning-text)';
+				content.style.color = 'var(--warning-text)';
+				if (closeBtn) {
+					closeBtn.style.color = 'var(--warning-text)';
+					closeBtn.style.opacity = '0.9';
+				}
+			} else {
+				// For other variants, just ensure color is inherited
+				if (textColor && textColor !== 'transparent' && textColor !== 'rgba(0, 0, 0, 0)') {
+					content.style.color = textColor;
+				} else {
+					content.style.color = 'inherit';
+				}
+			}
+			// Double-check content is visible
+			var contentStyle = window.getComputedStyle(content);
+			if (contentStyle.display === 'none' || contentStyle.visibility === 'hidden' || contentStyle.opacity === '0') {
+				content.style.display = 'block';
+				content.style.visibility = 'visible';
+				content.style.opacity = '1';
+			}
+		});
+		var closeAlert = function() {
+			alertEl.style.opacity = '0';
+			alertEl.style.transform = 'translateY(-10px)';
+			setTimeout(function() {
+				if (alertEl && alertEl.parentNode) {
+					alertEl.remove();
+				}
+			}, 200);
+		};
+		if (closeBtn) {
+			closeBtn.addEventListener('click', closeAlert);
+			if (autoDismiss > 0) {
+				var timeoutId = setTimeout(closeAlert, autoDismiss);
+				closeBtn.addEventListener('click', function() {
+					clearTimeout(timeoutId);
+				});
+			}
+		} else if (autoDismiss > 0) {
+			setTimeout(closeAlert, autoDismiss);
+		}
+	}
+	// Make available on window for global access
+	window.showAlert = showAlert;
+</script>

package/scaffold/astro-app/src/pages/components/avatar.astro ADDED Viewed

@@ -0,0 +1,102 @@
+---
+import DocsLayout from '../../layouts/DocsLayout.astro';
+import AvatarComponent from '../../components/Avatar.astro';
+import CodeBlock from '../../components/CodeBlock.astro';
+---
+<DocsLayout title="Avatar Component — Astro" description="User avatar with image or initials fallback, sizes and shapes">
+	<p class="docs__read-docs">Read the full docs for this component at <a href="https://rizzo-css.vercel.app/docs/components/avatar" target="_blank" rel="noopener noreferrer">https://rizzo-css.vercel.app/docs/components/avatar</a>.</p>
+		<section>
+		<h2>Avatar Component</h2>
+		<p>An accessible avatar for users: show a profile image when available, or initials derived from a name (or custom initials) when no image is provided. Supports multiple sizes and circle or square shape.</p>
+		<h3>Props</h3>
+		<ul>
+			<li><code>src</code> (string, optional) - Image URL; when provided, the image is shown</li>
+			<li><code>alt</code> (string, optional) - Alt text for the image</li>
+			<li><code>name</code> (string, optional) - Full name used to derive initials when no image (e.g. "Jane Doe" → "JD")</li>
+			<li><code>initials</code> (string, optional) - Override initials when no image (e.g. "JD"); ignored if <code>name</code> is provided</li>
+			<li><code>size</code> (string, optional) - <code>sm</code>, <code>md</code>, <code>lg</code> (default: md)</li>
+			<li><code>shape</code> (string, optional) - <code>circle</code>, <code>square</code> (default: circle)</li>
+			<li><code>class</code> (string, optional) - Additional CSS classes</li>
+		</ul>
+		<h3>Basic Usage (initials)</h3>
+		<p>When no <code>src</code> is provided, use <code>name</code> to show initials (first letter of first and last word, or first two letters of a single word).</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<div style="display: flex; align-items: center; gap: var(--spacing-4); flex-wrap: wrap;">
+				<AvatarComponent name="Jane Doe" />
+				<AvatarComponent name="Alice" />
+				<AvatarComponent initials="AB" />
+			</div>
+		</div>
+		<CodeBlock code={`---
+import Avatar from '../../components/Avatar.astro';
+---
+<Avatar name="Jane Doe" />
+<Avatar name="Alice" />
+<Avatar initials="AB" />`} 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-4); flex-wrap: wrap;">
+				<AvatarComponent name="Jane Doe" size="sm" />
+				<AvatarComponent name="Jane Doe" size="md" />
+				<AvatarComponent name="Jane Doe" size="lg" />
+			</div>
+		</div>
+		<CodeBlock code={`<Avatar name="Jane Doe" size="sm" />
+<Avatar name="Jane Doe" size="md" />
+<Avatar name="Jane Doe" size="lg" />`} language="astro" />
+		<h3>Shape</h3>
+		<p>Use <code>shape="square"</code> for a rounded square; default is <code>circle</code>.</p>
+		<div class="example">
+			<div class="example-title">Live Example</div>
+			<div style="display: flex; align-items: center; gap: var(--spacing-4); flex-wrap: wrap;">
+				<AvatarComponent name="Jane Doe" shape="circle" />
+				<AvatarComponent name="Jane Doe" shape="square" />
+			</div>
+		</div>
+		<CodeBlock code={`<Avatar name="Jane Doe" shape="circle" />
+<Avatar name="Jane Doe" shape="square" />`} language="astro" />
+		<h3>With image</h3>
+		<p>Pass <code>src</code> (and <code>alt</code>) to show a profile image. The image is scaled to cover the avatar with <code>object-fit: cover</code>.</p>
+		<div class="example">
+			<div class="example-title">Live Example (placeholder image)</div>
+			<div style="display: flex; align-items: center; gap: var(--spacing-4); flex-wrap: wrap;">
+				<AvatarComponent
+					src="https://api.dicebear.com/7.x/initials/svg?seed=Jane"
+					alt="Jane Doe"
+					size="md"
+				/>
+				<AvatarComponent
+					src="https://api.dicebear.com/7.x/initials/svg?seed=Alice"
+					alt="Alice"
+					size="lg"
+				/>
+			</div>
+		</div>
+		<CodeBlock code={`<Avatar
+  src="/path/to/photo.jpg"
+  alt="Jane Doe"
+  size="md"
+/>`} language="astro" />
+		<h3>Features</h3>
+		<ul>
+			<li><strong>Accessible</strong> - <code>role="img"</code> and <code>aria-label</code> from alt, name, or initials</li>
+			<li><strong>Initials</strong> - Derived from <code>name</code> (e.g. "Jane Doe" → "JD") or set via <code>initials</code></li>
+			<li><strong>Image</strong> - Optional <code>src</code> with <code>loading="lazy"</code> and <code>object-fit: cover</code></li>
+			<li><strong>Sizes</strong> - sm, md, lg</li>
+			<li><strong>Shape</strong> - circle (default) or square with rounded corners</li>
+		</ul>
+		<p><strong>Svelte & Vanilla:</strong> <a href="/docs/svelte/components/avatar">Svelte</a> · Vanilla: same HTML and BEM as in Usage above.</p>
+	</section>
+</DocsLayout>