@page "/docs/accessibility"
@namespace Lumeo.Docs.Pages.Docs

<PageTitle>Accessibility — Lumeo</PageTitle>

<Container MaxWidth="3xl" Padding="0" Center="false">
<Stack Gap="10">

    <!-- Header -->
    <Stack Gap="4">
        <Heading Level="1" Size="3xl">Accessibility</Heading>
        <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
            Lumeo is built with accessibility as a core principle. All components follow WAI-ARIA guidelines,
            support keyboard navigation, and work with screen readers out of the box.
        </Lumeo.Text>
    </Stack>

    <Separator Class="my-4" />

    <!-- Philosophy -->
    <Stack Gap="4">
        <Heading Level="2">Our approach</Heading>
        <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
            Accessibility is not an afterthought in Lumeo. Every component is designed from the start with proper
            semantic markup, ARIA attributes, keyboard interactions, and focus management. Our goal is to make
            it easy to build inclusive applications without requiring accessibility expertise from every developer
            on your team.
        </Lumeo.Text>
        <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
            Lumeo components follow the
            <Lumeo.Link Href="https://www.w3.org/WAI/ARIA/apg/" Class="text-foreground underline underline-offset-4 hover:text-muted-foreground transition-colors">WAI-ARIA Authoring Practices Guide</Lumeo.Link>
            for interaction patterns, and use native HTML semantics wherever possible. When ARIA roles are necessary,
            they are applied automatically so you do not need to add them manually.
        </Lumeo.Text>
    </Stack>

    <Separator Class="my-4" />

    <!-- Keyboard Navigation -->
    <Stack Gap="4">
        <Heading Level="2">Keyboard navigation</Heading>
        <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
            All interactive components in Lumeo are fully operable via keyboard. The library follows standard keyboard
            conventions so users who rely on keyboard navigation will find familiar interaction patterns.
        </Lumeo.Text>

        <Stack Gap="3">
            <Heading Level="3">General patterns</Heading>
            <ul class="space-y-2 text-sm text-muted-foreground list-none">
                <li class="flex items-start gap-2">
                    <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                    <span><Kbd>Tab</Kbd> moves focus between interactive elements. <Kbd>Shift+Tab</Kbd> moves focus backward.</span>
                </li>
                <li class="flex items-start gap-2">
                    <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                    <span><Kbd>Enter</Kbd> or <Kbd>Space</Kbd> activates buttons, toggles, checkboxes, and selectable items.</span>
                </li>
                <li class="flex items-start gap-2">
                    <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                    <span><Kbd>Escape</Kbd> closes overlays including Dialog, Sheet, Drawer, Alert Dialog, Dropdown Menu, Popover, Context Menu, Combobox, and Color Picker.</span>
                </li>
                <li class="flex items-start gap-2">
                    <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                    <span><Kbd>Arrow</Kbd> keys navigate within composite widgets like Select, Combobox, Dropdown Menu, Context Menu, Menubar, Tabs, Rating, Carousel, and OTP Input.</span>
                </li>
                <li class="flex items-start gap-2">
                    <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                    <span><Kbd>Home</Kbd> and <Kbd>End</Kbd> jump to the first and last item in lists and menus.</span>
                </li>
            </ul>
        </Stack>

        <Stack Gap="3">
            <Heading Level="3">Component-specific keyboard support</Heading>
            <div class="overflow-x-auto rounded-lg border border-border/40">
                <Table>
                    <TableHeader>
                        <TableRow>
                            <TableHead Class="w-40">Component</TableHead>
                            <TableHead>Keys</TableHead>
                            <TableHead>Behavior</TableHead>
                        </TableRow>
                    </TableHeader>
                    <TableBody>
                        <TableRow>
                            <TableCell Class="font-medium">Select</TableCell>
                            <TableCell><Kbd>Up</Kbd> <Kbd>Down</Kbd> <Kbd>Enter</Kbd> <Kbd>Escape</Kbd></TableCell>
                            <TableCell>Navigate options, select, close</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Combobox</TableCell>
                            <TableCell><Kbd>Up</Kbd> <Kbd>Down</Kbd> <Kbd>Enter</Kbd> <Kbd>Escape</Kbd></TableCell>
                            <TableCell>Navigate filtered results, select, close</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Dropdown Menu</TableCell>
                            <TableCell><Kbd>Up</Kbd> <Kbd>Down</Kbd> <Kbd>Enter</Kbd> <Kbd>Escape</Kbd></TableCell>
                            <TableCell>Navigate items, activate, close</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Context Menu</TableCell>
                            <TableCell><Kbd>Up</Kbd> <Kbd>Down</Kbd> <Kbd>Enter</Kbd> <Kbd>Escape</Kbd></TableCell>
                            <TableCell>Navigate items, activate, close</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Tabs</TableCell>
                            <TableCell><Kbd>Left</Kbd> <Kbd>Right</Kbd> (or <Kbd>Up</Kbd> <Kbd>Down</Kbd> vertical)</TableCell>
                            <TableCell>Switch between tabs based on orientation</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Dialog / Sheet / Drawer</TableCell>
                            <TableCell><Kbd>Escape</Kbd> <Kbd>Tab</Kbd></TableCell>
                            <TableCell>Close overlay, cycle focus within trap</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Alert Dialog</TableCell>
                            <TableCell><Kbd>Escape</Kbd> <Kbd>Tab</Kbd></TableCell>
                            <TableCell>Close (if allowed), cycle focus within trap</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Accordion</TableCell>
                            <TableCell><Kbd>Enter</Kbd> <Kbd>Space</Kbd></TableCell>
                            <TableCell>Toggle section open/closed</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Carousel</TableCell>
                            <TableCell><Kbd>Left</Kbd> <Kbd>Right</Kbd></TableCell>
                            <TableCell>Navigate between slides</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Rating</TableCell>
                            <TableCell><Kbd>Left</Kbd> <Kbd>Right</Kbd></TableCell>
                            <TableCell>Decrease or increase rating value</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">OTP Input</TableCell>
                            <TableCell><Kbd>Left</Kbd> <Kbd>Right</Kbd> <Kbd>Backspace</Kbd></TableCell>
                            <TableCell>Move between digits, delete and move back</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Cascader</TableCell>
                            <TableCell><Kbd>Up</Kbd> <Kbd>Down</Kbd> <Kbd>Right</Kbd> <Kbd>Escape</Kbd></TableCell>
                            <TableCell>Navigate levels, expand children, close</TableCell>
                        </TableRow>
                    </TableBody>
                </Table>
            </div>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- Focus Management -->
    <Stack Gap="4">
        <Heading Level="2">Focus management</Heading>
        <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
            Proper focus management is critical for keyboard and screen reader users. Lumeo handles focus automatically
            in overlay components so you do not need to manage it manually.
        </Lumeo.Text>

        <Stack Gap="3">
            <Heading Level="3">Focus trapping</Heading>
            <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                When a modal overlay opens (Dialog, Sheet, Drawer, Alert Dialog), Lumeo automatically traps focus
                inside the overlay content. Pressing <Kbd>Tab</Kbd> cycles through focusable elements within the overlay,
                and focus cannot escape to the page behind it. This is implemented via
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">ComponentInteropService.SetupFocusTrap()</code>
                and cleaned up with
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">RemoveFocusTrap()</code>
                when the overlay closes.
            </Lumeo.Text>
        </Stack>

        <Stack Gap="3">
            <Heading Level="3">Scroll locking</Heading>
            <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                When a modal overlay is open, background scroll is locked via
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">ComponentInteropService.LockScroll()</code>
                to prevent users from accidentally scrolling the page behind the overlay.
                Scroll is restored when the overlay closes. This applies to Dialog, Sheet, Drawer, Alert Dialog, Tour, and Image preview.
            </Lumeo.Text>
        </Stack>

        <Stack Gap="3">
            <Heading Level="3">Click-outside dismissal</Heading>
            <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                Non-modal overlays like Popover, Dropdown Menu, Context Menu, Combobox, and Color Picker register
                click-outside handlers via
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">ComponentInteropService.RegisterClickOutside()</code>.
                Clicking outside the overlay content dismisses it, which is the expected behavior for these patterns.
            </Lumeo.Text>
        </Stack>

        <Stack Gap="3">
            <Heading Level="3">Focus-visible rings</Heading>
            <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                All interactive elements display a visible focus ring when navigated to via keyboard. The ring uses the
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">focus-visible</code>
                pseudo-class, so it only appears for keyboard users and does not show on mouse click. The ring color
                is set via the <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--ring</code>
                CSS variable, which adapts to light and dark mode.
            </Lumeo.Text>
        </Stack>

        <Stack Gap="3">
            <Heading Level="3">Cleanup</Heading>
            <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                All overlay components implement <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">IAsyncDisposable</code>
                to properly clean up focus traps, scroll locks, and click-outside handlers. Cleanup code handles
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">JSDisconnectedException</code>
                gracefully to avoid errors during Blazor circuit disconnection.
            </Lumeo.Text>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- Screen Reader Support -->
    <Stack Gap="4">
        <Heading Level="2">Screen reader support</Heading>
        <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
            Lumeo components use semantic HTML elements and ARIA attributes to provide a meaningful experience
            for screen reader users. Roles, states, and properties are applied automatically.
        </Lumeo.Text>

        <Stack Gap="3">
            <Heading Level="3">ARIA roles and attributes by component</Heading>
            <div class="overflow-x-auto rounded-lg border border-border/40">
                <Table>
                    <TableHeader>
                        <TableRow>
                            <TableHead Class="w-44">Component</TableHead>
                            <TableHead Class="w-36">ARIA Role</TableHead>
                            <TableHead>Key Attributes</TableHead>
                        </TableRow>
                    </TableHeader>
                    <TableBody>
                        <TableRow>
                            <TableCell Class="font-medium">Dialog</TableCell>
                            <TableCell><code class="text-xs font-mono">dialog</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-modal</code>, <code class="text-xs font-mono">aria-labelledby</code>, <code class="text-xs font-mono">aria-describedby</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Alert Dialog</TableCell>
                            <TableCell><code class="text-xs font-mono">alertdialog</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-modal</code>, <code class="text-xs font-mono">aria-labelledby</code>, <code class="text-xs font-mono">aria-describedby</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Sheet / Drawer</TableCell>
                            <TableCell><code class="text-xs font-mono">dialog</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-modal</code>, <code class="text-xs font-mono">aria-labelledby</code>, <code class="text-xs font-mono">aria-describedby</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Alert</TableCell>
                            <TableCell><code class="text-xs font-mono">alert</code></TableCell>
                            <TableCell>Dismiss button has <code class="text-xs font-mono">aria-label</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Toast</TableCell>
                            <TableCell><code class="text-xs font-mono">alert</code></TableCell>
                            <TableCell>Live region announcements for screen readers</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Checkbox</TableCell>
                            <TableCell><code class="text-xs font-mono">checkbox</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-checked</code> (supports <code class="text-xs font-mono">mixed</code> for indeterminate)</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Switch</TableCell>
                            <TableCell><code class="text-xs font-mono">switch</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-checked</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Toggle</TableCell>
                            <TableCell>button</TableCell>
                            <TableCell><code class="text-xs font-mono">aria-pressed</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Toggle Group</TableCell>
                            <TableCell><code class="text-xs font-mono">group</code></TableCell>
                            <TableCell>Each item has <code class="text-xs font-mono">aria-pressed</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Radio Group</TableCell>
                            <TableCell><code class="text-xs font-mono">radiogroup</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-label</code>, <code class="text-xs font-mono">aria-labelledby</code>; items have <code class="text-xs font-mono">aria-checked</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Select</TableCell>
                            <TableCell><code class="text-xs font-mono">combobox</code> / <code class="text-xs font-mono">listbox</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-haspopup</code>, <code class="text-xs font-mono">aria-expanded</code>, <code class="text-xs font-mono">aria-controls</code>, <code class="text-xs font-mono">aria-activedescendant</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Combobox</TableCell>
                            <TableCell><code class="text-xs font-mono">combobox</code> / <code class="text-xs font-mono">listbox</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-haspopup</code>, <code class="text-xs font-mono">aria-expanded</code>, <code class="text-xs font-mono">aria-autocomplete</code>, <code class="text-xs font-mono">aria-activedescendant</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Dropdown Menu</TableCell>
                            <TableCell>button / menu</TableCell>
                            <TableCell><code class="text-xs font-mono">aria-haspopup</code>, <code class="text-xs font-mono">aria-expanded</code>, <code class="text-xs font-mono">aria-controls</code>; items have <code class="text-xs font-mono">menuitem</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Context Menu</TableCell>
                            <TableCell><code class="text-xs font-mono">menuitem</code> / <code class="text-xs font-mono">menuitemcheckbox</code> / <code class="text-xs font-mono">menuitemradio</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-checked</code> on checkbox and radio items</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Tabs</TableCell>
                            <TableCell><code class="text-xs font-mono">tablist</code> / <code class="text-xs font-mono">tab</code> / <code class="text-xs font-mono">tabpanel</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-selected</code>, <code class="text-xs font-mono">aria-controls</code>, <code class="text-xs font-mono">aria-orientation</code>, <code class="text-xs font-mono">aria-labelledby</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Accordion</TableCell>
                            <TableCell>button</TableCell>
                            <TableCell><code class="text-xs font-mono">aria-expanded</code> on trigger buttons</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Rating</TableCell>
                            <TableCell><code class="text-xs font-mono">radiogroup</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-label</code> ("Rate X out of Y") on each star</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Progress</TableCell>
                            <TableCell><code class="text-xs font-mono">progressbar</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-valuenow</code>, <code class="text-xs font-mono">aria-valuemin</code>, <code class="text-xs font-mono">aria-valuemax</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Breadcrumb</TableCell>
                            <TableCell><code class="text-xs font-mono">navigation</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-label="breadcrumb"</code>; current page has <code class="text-xs font-mono">aria-current="page"</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Pagination</TableCell>
                            <TableCell><code class="text-xs font-mono">navigation</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-label="pagination"</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Carousel</TableCell>
                            <TableCell><code class="text-xs font-mono">region</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-roledescription="carousel"</code>; slides have <code class="text-xs font-mono">aria-roledescription="slide"</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Tooltip</TableCell>
                            <TableCell><code class="text-xs font-mono">tooltip</code></TableCell>
                            <TableCell>Content announced on focus/hover</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Tree View / Tree Select</TableCell>
                            <TableCell><code class="text-xs font-mono">tree</code> / <code class="text-xs font-mono">treeitem</code></TableCell>
                            <TableCell><code class="text-xs font-mono">aria-expanded</code>, <code class="text-xs font-mono">aria-selected</code></TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Menubar</TableCell>
                            <TableCell><code class="text-xs font-mono">menubar</code></TableCell>
                            <TableCell>Items use <code class="text-xs font-mono">menuitem</code> role</TableCell>
                        </TableRow>
                        <TableRow>
                            <TableCell Class="font-medium">Steps</TableCell>
                            <TableCell><code class="text-xs font-mono">list</code> / <code class="text-xs font-mono">listitem</code></TableCell>
                            <TableCell>Semantic step progression</TableCell>
                        </TableRow>
                    </TableBody>
                </Table>
            </div>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- Color & Contrast -->
    <Stack Gap="4">
        <Heading Level="2">Color and contrast</Heading>
        <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
            Lumeo uses CSS custom properties for all colors, which means color contrast can be controlled at the
            theme level rather than per component.
        </Lumeo.Text>

        <ul class="space-y-2 text-sm text-muted-foreground list-none">
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">No hardcoded colors.</strong> Every color in Lumeo is a CSS variable (<code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--foreground</code>, <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--primary</code>, <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--muted</code>, etc.). Swapping the theme swaps all colors at once.</span>
            </li>
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Dark mode via variable swaps.</strong> Dark mode is handled entirely through CSS variable overrides. There are no <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">dark:</code> Tailwind prefixes anywhere in the library, ensuring a consistent and clean approach.</span>
            </li>
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Foreground / background pairing.</strong> Every background color variable has a matching foreground variable (e.g. <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--primary</code> paired with <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--primary-foreground</code>) to maintain readable contrast ratios.</span>
            </li>
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Built-in themes tested for contrast.</strong> The 7 built-in color themes (Zinc, Blue, Green, Rose, Violet, Amber, Teal) are designed with sufficient contrast between foreground and background in both light and dark modes.</span>
            </li>
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Muted text uses proper contrast.</strong> The <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--muted-foreground</code> variable is calibrated to provide readable secondary text without disappearing against the background.</span>
            </li>
        </ul>
    </Stack>

    <Separator Class="my-4" />

    <!-- Best Practices -->
    <Stack Gap="4">
        <Heading Level="2">Best practices for your app</Heading>
        <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
            While Lumeo handles component-level accessibility, there are application-level practices you should follow
            to ensure a fully accessible experience.
        </Lumeo.Text>

        <ul class="space-y-2 text-sm text-muted-foreground list-none">
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Use Label with form inputs.</strong> Always pair Input, Select, Checkbox, Radio Group, Switch, and other form controls with a <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">&lt;Label&gt;</code> component. This creates an accessible name for screen readers.</span>
            </li>
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Provide meaningful text.</strong> Avoid icon-only buttons without an <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">aria-label</code>. If a button only has an icon, pass <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">aria-label="Description"</code> via AdditionalAttributes.</span>
            </li>
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Use semantic headings.</strong> Use the <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">&lt;Heading&gt;</code> component with appropriate <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Level</code> values (1 through 6) to create a logical heading hierarchy. Screen readers use headings to navigate page structure.</span>
            </li>
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Test with keyboard only.</strong> Try navigating your application using only the keyboard. Every action should be reachable without a mouse.</span>
            </li>
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Test with a screen reader.</strong> Run through key flows with NVDA (Windows), VoiceOver (macOS), or Narrator (Windows) to verify the experience.</span>
            </li>
            <li class="flex items-start gap-2">
                <Lumeo.Text As="span" Class="mt-1.5 h-1.5 w-1.5 rounded-full bg-foreground shrink-0"></Lumeo.Text>
                <span><strong class="text-foreground">Respect user preferences.</strong> Lumeo supports <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">prefers-color-scheme</code> for automatic dark mode. Avoid overriding user system preferences without offering a toggle.</span>
            </li>
        </ul>
    </Stack>

</Stack>
</Container>
