whale-igniter 1.3.0 → 1.3.2

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