whale-igniter 1.2.3 → 1.3.1

package/ui-references/layout.md

@@ -0,0 +1,155 @@
+# Layout — UI References
+
+Layout components and patterns define how content is positioned, sized, and reflowed across viewports. They are the invisible scaffolding of every screen. Good layout is invisible — content feels natural and reachable. Bad layout manifests as content that overflows on mobile, pages that don't scale, or sidebar panels that get in the way.
+
+---
+
+## Container
+
+A centered, width-constrained wrapper that gives content a comfortable reading width and consistent horizontal margins. The outermost structural element on most pages.
+
+### Reference implementations
+
+- **[Vercel/Geist Container](https://vercel.com/geist/container)** — `max-width` variants (sm, md, lg, xl), centered with `margin: 0 auto`, horizontal padding that scales with viewport width. The pattern to copy for most web apps.
+- **[Tailwind CSS Container](https://tailwindcss.com/docs/container)** — `container` class with `mx-auto` and responsive padding; a widely-used baseline.
+
+### Minimum quality bar
+
+- [ ] Maximum width is appropriate for the content type (prose: 65–75ch; app UI: 1280px)
+- [ ] Horizontal padding on both sides that scales with viewport — at minimum 16px on mobile, 24–32px on desktop
+- [ ] Centers with `margin: 0 auto` — never with absolute positioning
+- [ ] Does not constrain child elements from filling their parent width
+- [ ] Nested containers: inner containers should not re-apply the outer max-width
+
+### Common mistakes
+
+- Using 100vw for the container width — includes scrollbar width and causes horizontal overflow on Windows
+- Container with no horizontal padding on mobile — content touches viewport edges
+- Nesting full-width sections inside a container that then applies max-width to everything
+
+---
+
+## Stack
+
+A one-dimensional layout that distributes children along a single axis (vertical or horizontal) with consistent spacing. The most frequent layout primitive.
+
+### Reference implementations
+
+- **[Every Layout — Stack](https://every-layout.dev/layouts/stack/)** — the canonical primitive: each child separated by a consistent gap, no global margin reset needed.
+- **[Radix UI Flex](https://www.radix-ui.com/themes/docs/layout/flex)** — flex-based stack with `gap`, `direction`, `align`, `justify` props; useful as a design system primitive.
+- **[Tailwind's flex/gap utilities](https://tailwindcss.com/docs/display#flex)** — `flex flex-col gap-4` is the practical implementation of a vertical stack in Tailwind.
+
+### Minimum quality bar
+
+- [ ] Spacing between children uses `gap`, not margin on individual children — `gap` does not collapse and doesn't affect the outermost children
+- [ ] Direction is explicit: vertical stack uses `flex-col`; horizontal uses `flex-row`
+- [ ] Wrapping behavior is explicit: decide whether children wrap to the next row or clip
+- [ ] Alignment: cross-axis alignment (`align-items`) defaults to `stretch` — be intentional about changing it
+- [ ] Nested stacks use their own `gap` — do not inherit from a parent
+
+### Common mistakes
+
+- Using margin-bottom on children for spacing — breaks the last-child, creates double margins when nesting
+- Gap on a non-flex/non-grid element — `gap` only works on flex and grid containers
+- Using negative margin to "fix" unwanted spacing from margins — indicates a structural problem, not a spacing one
+
+---
+
+## Grid
+
+A two-dimensional layout for aligning content in rows and columns. Use for card grids, form field layouts, and any content that requires both row and column alignment.
+
+### Reference implementations
+
+- **[Every Layout — Grid](https://every-layout.dev/layouts/grid/)** — the auto-fill/minmax pattern for responsive grids that reflow without breakpoints; the right default for card grids.
+- **[CSS Grid by Example](https://gridbyexample.com/)** — Rachel Andrew's reference; authoritative for advanced grid patterns.
+- **[Radix UI Grid](https://www.radix-ui.com/themes/docs/layout/grid)** — a grid primitive with explicit `columns` prop for column count control.
+
+### Minimum quality bar
+
+- [ ] Responsive: use `auto-fill` or `auto-fit` with `minmax()` for self-reflowing grids; explicit breakpoints for controlled column counts
+- [ ] Gutters use `gap`, not margin — ensures equal spacing horizontally and vertically
+- [ ] Items in the same row are the same height by default (CSS Grid stretches to match the tallest item)
+- [ ] Named grid areas for complex layouts: makes the layout intent readable in code
+
+### Common mistakes
+
+- Using `float` or `inline-block` for grid layouts — no longer appropriate; use Grid or Flexbox
+- Fixed-width columns that don't reflow — always pair fixed-width grids with `overflow-x: auto` or responsive breakpoints
+- `auto-fit` vs `auto-fill` confusion: `auto-fit` collapses empty tracks (items stretch); `auto-fill` preserves empty column tracks
+
+---
+
+## Responsive Patterns
+
+Strategies for adapting layout to different viewport widths. Not a component, but a set of decisions that every component must make.
+
+### Reference implementations
+
+- **[Every Layout](https://every-layout.dev/)** — the complete reference for responsive layout primitives (Stack, Box, Center, Cluster, Sidebar, Switcher, Cover, Grid, Frame, Reel, Imposter, Icon). These patterns cover 95% of layout needs without breakpoints.
+- **[Tailwind responsive prefixes](https://tailwindcss.com/docs/responsive-design)** — `sm:`, `md:`, `lg:`, `xl:` breakpoints for when intrinsic layouts are insufficient.
+
+### Minimum quality bar
+
+- [ ] Mobile-first: default styles are for small viewports; larger-viewport styles override with `@media (min-width: ...)`
+- [ ] No horizontal scroll on any viewport wider than 320px
+- [ ] Touch targets minimum 44×44px on all interactive elements
+- [ ] Text never smaller than 16px on mobile (prevents browser auto-zoom on iOS)
+- [ ] Images and media use `max-width: 100%` and `height: auto` — never overflow their container
+- [ ] Test at: 320px (smallest iPhone SE), 390px (iPhone 14), 768px (tablet), 1440px (desktop)
+
+### Common mistakes
+
+- Desktop-first design that patches mobile with `max-width` overrides — creates specificity battles
+- Layout that assumes a specific viewport height — mobile browsers have variable chrome heights
+- `vw` units for font size — creates tiny text on narrow viewports and huge text on wide ones; use `clamp()` for fluid typography
+
+---
+
+## Sidebar Layout
+
+A two-column layout with a persistent sidebar (navigation or contextual content) and a main content area. The most common structure for application dashboards.
+
+### Reference implementations
+
+- **[shadcn/ui Sidebar](https://ui.shadcn.com/docs/components/sidebar)** — comprehensive implementation: collapsible, icon-only mode, mobile sheet overlay, keyboard navigation, persistent open/closed state.
+- **[Linear's layout](https://linear.app)** — observe: resizable sidebar, persistent state across reloads, collapses to icon-only at narrower widths, slides away on mobile.
+- **[Radix UI layout primitives](https://www.radix-ui.com/themes/docs/layout/box)** — Box and Flex for building custom sidebar layouts.
+
+### Minimum quality bar
+
+- [ ] Sidebar width is either fixed or resizable within a min/max range
+- [ ] Sidebar open/closed state persists across navigation (local storage or cookie)
+- [ ] Mobile: sidebar slides off-screen; toggle button always visible; opens as overlay, not by pushing content
+- [ ] Main content area uses `min-width: 0` to allow flex children to shrink below content size
+- [ ] Keyboard: pressing a sidebar nav item moves focus into the main content area
+- [ ] Skip-to-content link at page top jumps past the sidebar for keyboard users
+
+### Common mistakes
+
+- Sidebar with `overflow: hidden` — clips content and breaks dropdown menus that extend beyond the sidebar
+- Sidebar that pushes content off-screen on resize — use CSS variables for width so transitions stay smooth
+- Mobile sidebar that requires a hard page navigation to close — use an overlay and an `×` button
+
+---
+
+## Cluster / Inline Group
+
+A horizontal group of items that wraps to the next line when the container is too narrow. Common for button groups, tag collections, filter chips, and navigation items.
+
+### Reference implementations
+
+- **[Every Layout — Cluster](https://every-layout.dev/layouts/cluster/)** — `flex-wrap: wrap` with `gap` is the complete pattern; no media queries needed.
+- **[Tailwind flex-wrap](https://tailwindcss.com/docs/flex-wrap)** — `flex flex-wrap gap-2` covers most cluster needs.
+
+### Minimum quality bar
+
+- [ ] `flex-wrap: wrap` so items reflow naturally rather than overflowing
+- [ ] `gap` (not margin) between items so wrapping rows also have vertical spacing
+- [ ] Alignment: `align-items: center` for mixed-height items (icon + text, badges + text)
+- [ ] When items must not wrap: `overflow-x: auto` with `-webkit-overflow-scrolling: touch` for mobile swipe
+
+### Common mistakes
+
+- Cluster with margin-right on children but no margin on the last item — creates right overhang
+- Mixing margin and gap for spacing in the same container — pick one

package/ui-references/navigation.md

@@ -0,0 +1,188 @@
+# Navigation — UI References
+
+Navigation elements help users understand where they are and move confidently through an application. Poor navigation is one of the top reasons users abandon software. Good navigation is invisible: users find what they need without thinking about the mechanism.
+
+---
+
+## Navigation Bar
+
+The persistent top bar that identifies the application and provides access to primary destinations. It must be consistent across all screens and never disappear unexpectedly.
+
+### Reference implementations
+
+- **[Linear's top nav](https://linear.app)** — observe in the app: no wordmark at scale (icon only), workspace switcher, command bar in center, user avatar at far right. Extremely low visual weight — chrome stays out of the way of content.
+- **[Vercel/Geist Header](https://vercel.com/geist/components)** — persistent nav with responsive collapse to hamburger on mobile; good reference for how a complex nav simplifies at small breakpoints.
+- **[GitHub Primer Global Nav](https://primer.style/components/nav-list/react/alpha)** — handles authenticated vs. unauthenticated states, notification badge, and global search without cluttering the bar.
+- **[Atlassian Navigation](https://atlassian.design/components/atlassian-navigation/examples)** — horizontal nav for complex products with overflow handling when items don't fit.
+
+### Minimum quality bar
+
+- [ ] `<nav>` element with `aria-label="Main"` (distinguish from secondary navs on the page)
+- [ ] Current page/section has `aria-current="page"` on its link
+- [ ] Keyboard: all links reachable by Tab; no keyboard traps
+- [ ] Mobile: all destinations accessible (not hidden behind a broken hamburger)
+- [ ] Logo links to home; clicking it from home does not reload the page in a disorienting way
+- [ ] Skip navigation link is the first focusable element on the page
+
+### Common mistakes
+
+- Multiple `<nav role="navigation">` without distinct `aria-label` — screen readers can't distinguish them
+- Hiding the hamburger menu without a visible open state indicator
+- Nav items that look like buttons but navigate — use `<a>`, not `<button>`
+
+---
+
+## Tabs
+
+Tabs switch between views of the same conceptual space. The content area changes; the URL may or may not change depending on whether tabs represent distinct routes.
+
+### Reference implementations
+
+- **[Radix UI Tabs](https://www.radix-ui.com/primitives/docs/components/tabs)** — the correct `tablist`/`tab`/`tabpanel` ARIA pattern. Arrow key navigation within the tab list, Tab to move focus into the panel. This is the keyboard interaction model to copy.
+- **[shadcn/ui Tabs](https://ui.shadcn.com/docs/components/tabs)** — clean Radix implementation showing horizontal and vertical orientations.
+- **[Linear's sidebar tabs](https://linear.app)** — vertical tabs in a sidebar context; icon+label on wider widths, icon-only on narrower widths with tooltip.
+
+### Minimum quality bar
+
+- [ ] `role="tablist"` on container, `role="tab"` on each trigger, `role="tabpanel"` on each panel
+- [ ] `aria-selected="true"` on the active tab, `aria-controls` pointing to its panel
+- [ ] Arrow keys (Left/Right for horizontal, Up/Down for vertical) navigate between tabs
+- [ ] Tab key moves focus into the active panel, not to the next tab
+- [ ] Active tab is visually distinct from inactive — not just a color change (underline or elevated background)
+- [ ] If tabs can have counts or badges, they don't overflow the tab trigger width
+
+### Common mistakes
+
+- Building tabs with buttons and state — without the ARIA roles, screen readers can't identify the pattern
+- Tab key navigating between tabs — breaks the WAI-ARIA tabs keyboard spec
+- Tabs that look like navigation links but don't change the URL — confuse back button behavior
+
+---
+
+## Sidebar Navigation
+
+A persistent vertical list of destinations, usually for primary navigation in dense applications. The sidebar is either always visible (persistent) or toggled (collapsible).
+
+### Reference implementations
+
+- **[Linear's sidebar](https://linear.app)** — collapsible sections with disclosure triangles, drag-to-reorder items, keyboard-accessible, active item highlighted with subtle background. The state of each section persists across sessions.
+- **[shadcn/ui Sidebar](https://ui.shadcn.com/docs/components/sidebar)** — comprehensive implementation with collapsible, icon-only mode, groups, and responsive mobile sheet behavior.
+- **[Radix UI Navigation Menu](https://www.radix-ui.com/primitives/docs/components/navigation-menu)** — for nested navigation with flyout submenus.
+
+### Minimum quality bar
+
+- [ ] `<nav>` element with `aria-label` distinct from any other nav
+- [ ] Active item has `aria-current="page"` and a visual highlight (not just color)
+- [ ] Collapsible sections use `<button>` with `aria-expanded`; the trigger is not the section heading itself
+- [ ] Keyboard: arrow keys navigate the tree; Enter expands/collapses; Escape collapses
+- [ ] Mobile: either always visible (if space allows) or a toggleable sheet/drawer — not a hamburger that hides destinations
+
+### Common mistakes
+
+- Using `<ul>` and `<li>` without navigation semantics — consider `role="navigation"` and `aria-label`
+- Active state using only color — inaccessible; add icon, weight, or background differentiation
+- Sidebar that hides off-screen on mobile but is still Tab-focusable — focus trap for keyboard users
+
+---
+
+## Breadcrumb
+
+Shows the user's location in a hierarchy and lets them jump to any ancestor level. Useful in deeply nested navigation trees; not needed for flat applications.
+
+### Reference implementations
+
+- **[Radix UI Breadcrumbs](https://www.radix-ui.com/themes/docs/components/breadcrumbs)** — correct `<nav aria-label="Breadcrumb">` wrapper with `<ol>` and `aria-current="page"` on the last item.
+- **[GitHub Primer Breadcrumb](https://primer.style/react/storybook/?path=/story/components-breadcrumbs--default)** — good handling of overflow: ellipsis in the middle, not at the start or end.
+
+### Minimum quality bar
+
+- [ ] `<nav aria-label="Breadcrumb">` wrapper around an `<ol>`
+- [ ] Last item has `aria-current="page"` and is not a link (it's the current page)
+- [ ] Separator (/) between items is decorative — `aria-hidden="true"` or CSS-generated
+- [ ] On mobile/constrained width: truncate middle items, always show root and current
+- [ ] Schema.org `BreadcrumbList` structured data for SEO when breadcrumbs appear in public pages
+
+### Common mistakes
+
+- Making the current page item a link — it should not be; it is the current location
+- Separators that are part of the link's tab stop — separators are decorative
+
+---
+
+## Dropdown Menu
+
+A contextual list of actions, exposed from a trigger element. Not a select (select chooses a value); a menu triggers actions.
+
+### Reference implementations
+
+- **[Radix UI Dropdown Menu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu)** — the complete reference: `menu`, `menuitem`, `menuitemcheckbox`, `menuitemradio` roles, keyboard navigation (arrow keys, Home/End, typeahead), sub-menus, separators.
+- **[shadcn/ui Dropdown Menu](https://ui.shadcn.com/docs/components/dropdown-menu)** — clean implementation with icons, keyboard shortcuts displayed inline, destructive item styling.
+- **[Linear's context menus](https://linear.app)** — observe: keyboard shortcuts shown in the menu (⌘D), dividers grouping related actions, destructive actions at the bottom, subtle hover highlight.
+
+### Minimum quality bar
+
+- [ ] `role="menu"` on the list, `role="menuitem"` (or `menuitemcheckbox`/`menuitemradio`) on items
+- [ ] Arrow keys navigate; Enter/Space activates; Escape closes and returns focus to trigger
+- [ ] Typeahead: pressing a letter jumps to first item starting with that letter
+- [ ] Nested submenus open on arrow-right; close on arrow-left or Escape
+- [ ] Destructive items visually distinct (red label); positioned last in the group
+- [ ] Menu closes when user clicks outside or navigates away; focus returns to trigger
+
+### Common mistakes
+
+- Using a dropdown menu for a select — `role="menu"` does not communicate value selection to screen readers
+- Not returning focus to the trigger when the menu closes
+- Sub-menus that open on hover (not arrow key) — inaccessible keyboard pattern
+
+---
+
+## Pagination
+
+Controls for navigating through paged data. Users need to know their current position, total pages (if known), and where to go next.
+
+### Reference implementations
+
+- **[shadcn/ui Pagination](https://ui.shadcn.com/docs/components/pagination)** — previous/next arrows with page number range in between; ellipsis for large ranges.
+- **[GitHub Primer Pagination](https://primer.style/components/pagination)** — handles `aria-label` per page link ("Page 2"), `aria-current="page"` on the active page, previous/next with icon + text.
+
+### Minimum quality bar
+
+- [ ] `<nav aria-label="Pagination">` wrapping the controls
+- [ ] Each page link has a unique, descriptive `aria-label` ("Page 3")
+- [ ] Current page has `aria-current="page"` and is not a link
+- [ ] Previous/Next buttons are disabled (not hidden) on the first/last page; `aria-disabled="true"` and `disabled`
+- [ ] Ellipsis items are not interactive and are `aria-hidden="true"`
+- [ ] Keyboard: Tab reaches each page link; Enter activates
+
+### Common mistakes
+
+- Hiding previous on page 1 and next on last page — users lose spatial context about the range
+- Ellipsis items that are also links — they should not be clickable
+
+---
+
+## Command Palette
+
+A keyboard-first search interface for navigating and acting across the entire application. Found in Linear, VSCode, GitHub, Vercel. The power-user's primary navigation.
+
+### Reference implementations
+
+- **[cmdk](https://cmdk.paco.me/)** — the canonical open-source command palette component; accessible, keyboard-driven, fuzzy search, used by shadcn/ui and Linear.
+- **[Linear's command palette](https://linear.app)** — press `⌘K`; observe: fuzzy search, grouping, keyboard shortcuts shown, recent items at top, no mouse required after open.
+- **[shadcn/ui Command](https://ui.shadcn.com/docs/components/command)** — cmdk with Tailwind styling; includes the modal wrapper pattern.
+
+### Minimum quality bar
+
+- [ ] Opens with `⌘K` (Mac) / `Ctrl+K` (Windows/Linux); closes with Escape
+- [ ] Focus is trapped inside while open; returns to previous element on close
+- [ ] Search input is focused immediately on open
+- [ ] Keyboard: arrow keys navigate items; Enter activates; Tab should also navigate
+- [ ] Items are grouped (e.g. "Navigation", "Actions", "Recent")
+- [ ] Empty state is shown when no matches (not a blank list)
+- [ ] `role="combobox"` on the input, `role="listbox"` on the list, `role="option"` on items
+
+### Common mistakes
+
+- Requiring mouse to open — defeats the purpose of a keyboard-first tool
+- No empty state — users don't know if the search is broken or there are no results
+- Slow filtering — command palettes must filter on every keystroke instantly (<16ms)

package/ui-references/surface.md

@@ -0,0 +1,188 @@
+# Surface — UI References
+
+Surface components are containers and overlays: they frame content, present it in context, and layer it above other content. The quality of a surface shows in its edge cases — what happens when content overflows, when it's positioned near a viewport edge, or when a screen reader announces it.
+
+---
+
+## Card
+
+A bounded content container that groups related information. Cards are surfaces, not actions: they can be clickable (linking to detail views) but clicking a card is navigation, not a form submission.
+
+### Reference implementations
+
+- **[shadcn/ui Card](https://ui.shadcn.com/docs/components/card)** — `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` composition pattern; clear separation of structural slots.
+- **[Radix UI Card](https://www.radix-ui.com/themes/docs/components/card)** — minimal themed card with consistent shadow and radius; good baseline for a design system.
+- **[Linear's cards](https://linear.app)** — observe in issues and project views: no excessive shadow, border defines the edge, hover state is a background tint (not elevation change), active selection uses a strong left border.
+- **[Vercel/Geist Card](https://vercel.com/geist/components)** — flat cards with border; the standard for enterprise/dashboard contexts.
+
+### Minimum quality bar
+
+- [ ] Consistent internal padding (match the project's grid unit)
+- [ ] Container border-radius matches the project's `container` radius value — not the `control` radius
+- [ ] If the whole card is clickable: `<a>` wrapping the card (not an `onClick` on a `<div>`)
+- [ ] If part of the card is clickable (e.g. title link + action button): use `::after` pseudo-element on the title link to expand its hit area to the card; action button has its own event without conflict
+- [ ] Hover state is visible; active/pressed state is visible
+- [ ] Card body does not use `overflow: hidden` aggressively — truncation should be controlled and indicated
+
+### Common mistakes
+
+- Wrapping an entire card in `<a>` when it also contains buttons — creates nested interactive elements and confuses screen readers
+- Elevation (box-shadow) as the primary border — elevation should supplement, not replace, a visible edge
+- Fixed height cards that hide overflow without indication — use truncation with ellipsis and tooltip, not silent clipping
+
+---
+
+## Popover
+
+A floating overlay anchored to a trigger element. Used for secondary actions, rich tooltips, or inline editing. Differs from a tooltip: popovers can contain interactive elements.
+
+### Reference implementations
+
+- **[Radix UI Popover](https://www.radix-ui.com/primitives/docs/components/popover)** — the reference: `role="dialog"` when interactive, focus moves into the popover on open, Escape closes and returns focus. `side`, `align`, and `avoidCollisions` handle positioning near viewport edges.
+- **[shadcn/ui Popover](https://ui.shadcn.com/docs/components/popover)** — Radix Popover with Tailwind; shows the trigger + content pattern cleanly.
+- **[Floating UI](https://floating-ui.com/)** — the positioning library underlying Radix, Headless UI, and others; consult for edge cases in custom positioning logic.
+
+### Minimum quality bar
+
+- [ ] `role="dialog"` with `aria-label` or `aria-labelledby` when the popover contains interactive content
+- [ ] Focus moves into the popover when it opens (for interactive popovers)
+- [ ] Escape closes the popover; click outside closes; focus returns to trigger
+- [ ] Stays within viewport: flips side and/or shifts along axis when near an edge
+- [ ] Arrow indicator (optional but helpful) points to the anchor and repositions when the popover flips
+- [ ] Does not scroll the page body when scrolling inside the popover
+
+### Common mistakes
+
+- Non-interactive popovers that receive focus — only interactive popovers should trap/move focus
+- Popover that overflows the viewport on small screens — always test positioning at mobile widths
+- Opening a popover on hover without a click fallback — hover-only is inaccessible
+
+---
+
+## Tooltip
+
+A small informational overlay that appears on hover (and focus). Tooltips explain UI elements; they do not contain interactive elements. If you need interactive content in the overlay, use a Popover.
+
+### Reference implementations
+
+- **[Radix UI Tooltip](https://www.radix-ui.com/primitives/docs/components/tooltip)** — `role="tooltip"` on the content, `aria-describedby` linking the trigger to the tooltip. Delay before showing (300ms default), immediate hide on mouse leave.
+- **[shadcn/ui Tooltip](https://ui.shadcn.com/docs/components/tooltip)** — clean implementation; the `TooltipProvider` wrapping pattern for shared delay configuration.
+- **[Floating UI Tooltip tutorial](https://floating-ui.com/docs/tooltip)** — explains hover + focus event handling without ARIA mistakes.
+
+### Minimum quality bar
+
+- [ ] `role="tooltip"` on the content element
+- [ ] Trigger has `aria-describedby` pointing to the tooltip id
+- [ ] Shows on hover AND on keyboard focus (not hover only)
+- [ ] Delay before showing (200–300ms) prevents tooltip flicker on cursor pass-through
+- [ ] Tooltip is dismissible via Escape key while visible
+- [ ] Does not obscure the element being described
+- [ ] Text content only — if you need a button inside, it's a Popover
+- [ ] Respects `prefers-reduced-motion` for entry animation
+
+### Common mistakes
+
+- Tooltip on a disabled element — disabled elements don't receive focus events; wrap the disabled element in a `<span>` for the tooltip
+- Tooltip that duplicates the visible label exactly — adds no value; tooltip text should supplement, not repeat
+- Interactive content (links, buttons) inside a tooltip — use Popover instead
+
+---
+
+## Sheet / Drawer
+
+A panel that slides in from an edge of the screen (most commonly the right). Used for secondary task panels, filter drawers, detail views, or mobile navigation.
+
+### Reference implementations
+
+- **[shadcn/ui Sheet](https://ui.shadcn.com/docs/components/sheet)** — four opening directions (top, right, bottom, left); `role="dialog"`, focus trap, Escape to close; uses the Radix UI Dialog primitive underneath.
+- **[Radix UI Dialog as Sheet](https://www.radix-ui.com/primitives/docs/components/dialog)** — sheets are typically implemented on top of a dialog primitive with CSS positioning.
+- **[Linear's right panel](https://linear.app)** — observe the issue detail panel: slides in from the right, does not cover the main content at wider viewports (side-by-side layout), full-screen on mobile.
+
+### Minimum quality bar
+
+- [ ] `role="dialog"`, `aria-modal="true"`, `aria-label` or `aria-labelledby`
+- [ ] Focus trap: Tab/Shift+Tab cycle inside the sheet while open
+- [ ] Opens with slide animation; closes with slide animation; `prefers-reduced-motion` respects instant open/close
+- [ ] Escape closes; clicking the scrim closes; close button always visible
+- [ ] On mobile: always full-screen or nearly full-screen — partial drawers cause content-below-fold confusion
+- [ ] Handles soft keyboard on mobile (input fields inside the sheet must be visible when keyboard opens)
+
+### Common mistakes
+
+- Sheet that cannot be closed without completing a form — always allow escape/scrim close
+- Sheet that scrolls the background page — lock body scroll while sheet is open
+- Nested sheets — avoid; create a single sheet that can change its contents instead
+
+---
+
+## Avatar
+
+Represents a user or entity with an image, initials, or icon. Appears in lists, comments, headers, and presence indicators.
+
+### Reference implementations
+
+- **[Radix UI Avatar](https://www.radix-ui.com/primitives/docs/components/avatar)** — image with `AvatarFallback` that shows while image loads or on error. The fallback timing (delay before fallback renders) avoids flash-of-initials before the image loads.
+- **[shadcn/ui Avatar](https://ui.shadcn.com/docs/components/avatar)** — clean implementation; the image + fallback pattern with consistent sizing.
+
+### Minimum quality bar
+
+- [ ] Image has `alt` text describing who it represents (not `alt=""` — that's for decorative images)
+- [ ] Fallback (initials or generic icon) when image fails to load or is not provided
+- [ ] Fallback renders deterministically — same initials/color every time for the same user
+- [ ] Consistent sizes across the product — define a size scale (sm/md/lg) and stick to it
+- [ ] Avatar groups (stacked avatars): `z-index` and margin-left negative offset done with CSS, not absolute positioning
+
+### Common mistakes
+
+- `alt=""` on user avatar images — these are meaningful, not decorative; describe who the image shows
+- Avatar that shows a broken image icon instead of fallback — always handle image load failure
+- Fallback background color that is too light against a white background — ensure sufficient contrast
+
+---
+
+## Separator / Divider
+
+A visual line that separates groups of content. Structural, not decorative — it communicates that what's above and below belong to different groups.
+
+### Reference implementations
+
+- **[Radix UI Separator](https://www.radix-ui.com/primitives/docs/components/separator)** — `role="separator"` (structural) or `role="none"` (decorative), horizontal and vertical orientation.
+- **[shadcn/ui Separator](https://ui.shadcn.com/docs/components/separator)** — thin horizontal/vertical rule.
+
+### Minimum quality bar
+
+- [ ] `role="separator"` when the line communicates structure (between sections); `role="none"` or `aria-hidden="true"` when purely decorative
+- [ ] Color passes 3:1 contrast against its background
+- [ ] Does not carry margin by default — let the container control spacing
+- [ ] Horizontal separators extend to the full width of their container unless explicitly inset
+
+### Common mistakes
+
+- Using `<hr>` inside inline contexts — `<hr>` has block display; use `role="separator"` on a `<span>` for inline separators
+- Separator with too much vertical margin — creates too much visual space between related groups
+
+---
+
+## Badge
+
+A small label applied to an element to communicate status, count, or category. Appears inline next to text or as an overlay on an icon.
+
+### Reference implementations
+
+- **[shadcn/ui Badge](https://ui.shadcn.com/docs/components/badge)** — variant system (default, secondary, destructive, outline); small, not button-like.
+- **[Radix UI Badge](https://www.radix-ui.com/themes/docs/components/badge)** — color-coded badges with good contrast defaults across themes.
+- **[Linear's labels](https://linear.app)** — observe issue labels: colored dot + text, keyboard accessible in filter panels, consistent small size.
+- **[GitHub Primer Label](https://primer.style/components/label/react/alpha)** — handles "filled" and "outline" variants with color theming.
+
+### Minimum quality bar
+
+- [ ] Not a button — badges are not interactive; if clicking a badge does something, it should be a `<button>` or `<a>` visually styled as a badge
+- [ ] Text must pass 4.5:1 contrast against its background color
+- [ ] Numeric badges (notification counts): `aria-label="N notifications"` on the parent container; the badge itself is `aria-hidden`
+- [ ] Never convey information through color alone — include text or icon alongside color coding
+- [ ] Consistent height and padding across all badge uses in the product
+
+### Common mistakes
+
+- Badge that is a `<div>` with `onClick` — should be `<button>` for interactivity or `<span>` for decoration
+- Too many badge variants — three variants (default, success, danger) cover most cases; more adds cognitive load