菜单
Design system rules, page archetypes, spacing rhythm, surface hierarchy, responsive strategy. Use when building any new UI, page, or component to ensure visual consistency.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Security patterns, CSP nonces, input validation, auth checks, Supabase SSR patterns. Use when implementing authentication, forms, security features, or when user mentions security/validation/auth.
Use when running the superpowers plugin lifecycle inside PinPoint — brainstorming, writing-plans, subagent-driven-development, requesting/receiving-code-review, or finishing-a-development-branch — and when a superpowers step wants to merge a branch locally, remove a worktree by hand, run generic npm/pytest tests, dispatch subagents without a scale gate, or write a spec/plan from the read-only root. Also when deciding which bead field a spec, plan, acceptance criterion, or landing note belongs in.
Orchestrate parallel subagent work in git worktrees — task selection, end-to-end dispatch, monitoring, follow-up, and cleanup.
Full PR lifecycle for PinPoint — commit, push, CI monitoring, Copilot + human review handling (via MCP), readiness labeling, gate-enforced merge. Use when committing changes, opening PRs, watching CI, addressing review comments, or merging.
Per-PR /audit-override escape hatch for unrelated pnpm audit failures blocking CI Gate. Use when a PR's audit job goes red on a freshly-published advisory unrelated to the PR's own changes, or when explaining/debugging the /audit-override command.
Supabase/Postgres pooler and connection-string reference for PinPoint — Supavisor transaction vs session pooler, IPv4/IPv6, prepared statements, and the resolved PP-d8l8 silent-commit-loss incident. Use when touching src/server/db/**, scripts/migrate-production.ts, scripts/lib/pg-client.mjs, or any DB connection/pooler config.
| name | pinpoint-design-bible |
| description | Design system rules, page archetypes, spacing rhythm, surface hierarchy, responsive strategy. Use when building any new UI, page, or component to ensure visual consistency. |
Use this skill when:
PinPoint uses a dark neon aesthetic -- deep charcoal backgrounds with neon green and teal accents.
| Token | Value | Usage |
|---|---|---|
| Primary | #4ade80 | Actions, active states, CTAs, links |
| Secondary | #2dd4bf | Accents, decorative highlights |
| Background | #0f0f11 | Page background |
| Surface | #0f0f11 | Content areas, full-width sections |
| Card | #18151b | Elevated containers |
| Surface-variant/30 | -- | Dimmed/closed items |
Purple is not in the palette. It was removed in favor of teal so the
primary and secondary read as one green-family pairing rather than two
competing brands. Do not reintroduce a purple/magenta/fuchsia secondary, or
raw purple-* / fuchsia-* / magenta-* classes, in new code. The one
exception is the legacy raw-Tailwind purple used for a handful of entries in
STATUS_CONFIG and PRIORITY_CONFIG (both in
src/lib/issues/status.ts) -- those are
tracked for conversion to semantic tokens and should be migrated
opportunistically, not extended.
Rules:
text-purple-400, bg-amber-500/20, border-fuchsia-500) or hardcoded hex (#d946ef, bg-[#abcdef]) anywhere under src/app/**, src/components/**, or any .tsx / .ts file that renders or styles UI. Use text-primary, bg-destructive, text-muted-foreground, border-success/40, etc.dark: utility classes are forbidden. PinPoint is dark-only; dark: classes are dead code. Remove them when you touch a file that still contains them.src/lib/issues/status.ts (STATUS_CONFIG, SEVERITY_CONFIG, PRIORITY_CONFIG, FREQUENCY_CONFIG) and the equivalent mapping in src/lib/machines/presence.ts may use raw Tailwind palette classes — because the raw palette is the design decision being expressed. Component code consumes the resulting class strings via STATUS_CONFIG[status].styles; never replicate those class strings at call sites.STATUS_CONFIG / SEVERITY_CONFIG / PRIORITY_CONFIG / FREQUENCY_CONFIG -- never freestyle status colors in components.glow-primary, glow-secondary) are for interactive hover states only, never static decoration. Apply hover:glow-primary to navigable card surfaces: machine cards (list and dashboard panels), issue cards, and interactive stat cards. Apply hover:glow-success to "recently fixed" machine cards where the success color already conveys status semantically. Do not apply any glow to form controls, buttons, modals, destructive actions, nav links, input fields, or dropdown triggers. Glow is permitted as an interactivity affordance on editable fields — a text-glow that fades in on hover marks "you can edit this" (glow-editable-text, PP-43q3). This is distinct from decorative glow on arbitrary form controls, which remains banned. Editable Machine Settings fields use it via ~/components/machines/settings/affordance.backdrop-blur-sm) is reserved for navigation chrome.aria-label / sr-only. Decorative icons that accompany the color cue should be marked aria-hidden="true" so screen readers receive the label, not the icon. Under deuteranopia / protanopia (combined ~8% of men), destructive-red and warning-amber collapse to similar mustard shades and are not distinguishable by hue. Concretely: <Alert variant="destructive"> and <Alert variant="warning"> include a leading AlertOctagon / AlertTriangle (or equivalent) as aria-hidden decoration plus body text that names the condition; destructive buttons carry a verb label like "Delete" (with any icon aria-hidden); status / severity / priority badges expose .label alongside their icon.Pick the surface level based on the element's role:
| When building... | Use |
|---|---|
| Page background | bg-background (#0f0f11) |
| Full-width content section | bg-surface (#0f0f11) |
| Card, popover, elevated container | bg-card (#18151b, fully opaque) |
| Header, app header, tab bar (nav chrome) | bg-card/85 backdrop-blur-sm |
| Header band inside a card/section | bg-muted (#27272a, opaque) |
| Closed/archived/dimmed item | bg-surface-variant/30 |
Key distinction: Navigation chrome gets the frosted glass treatment (opacity + blur). Content cards are always fully opaque bg-card.
Header band: when a card or full-bleed section gives its header zone (title + meta) its own surface distinct from the body, use opaque bg-muted — the same token table <thead>s use. Don't brighten past ~16% white-equivalent: text-muted-foreground on the band drops below the 4.5:1 AA floor. Reference implementation: SettingsSetCard.
These values are fixed. Do not deviate.
| Element | Value |
|---|---|
| App header | 56px (h-14), sticky, z-20, frosted glass |
| Bottom tab bar | 56px min-height, fixed, z-50, md:hidden |
| Tab bar safe | env(safe-area-inset-bottom) padding |
| Content bottom | pb-[calc(88px+env(safe-area-inset-bottom))] md:pb-0 |
| Scroll padding | scroll-pt-14 md:scroll-pt-14 |
| Mobile/desktop | md: (768px) is THE breakpoint (standard viewport, no hacks) |
If you add a new page: it MUST include the content bottom padding or content will be hidden behind the tab bar on mobile.
PinPoint uses a two-layer responsive framework. Each layer has a distinct job. Never use both layers to solve the same layout problem.
Use viewport breakpoints when the decision depends on the browser window size — showing or hiding entire sections, switching page-level grid columns, top-level padding.
| Breakpoint | Viewport | Role | Example |
|---|---|---|---|
md: | 768px | Primary layout pivot | Single column → multi-column, show nav icons |
lg: | 1024px | Element enrichment | Icon-only nav → icon+text, APC logo appears |
sm: | 640px | Padding/spacing only | sm:px-8, sm:gap-4 — no structural changes |
sm: is padding only. Never use sm:grid-cols-2, sm:flex-row, or hidden sm:block.
Use container queries when the decision depends on the component's available width — not the viewport. A component inside the issue detail content column has less space than the same component full-width, regardless of screen size.
These are NOT viewport sizes. They are the width of the nearest @container ancestor.
| Query | Container width | Typical use |
|---|---|---|
@lg: | 512px | First internal layout shift (e.g., stack → row) |
@xl: | 576px | Expanded row layout, additional columns |
@2xl: | 672px | Further enrichment, multi-column grids |
@3xl: | 768px | Full-featured component layout |
"Show/hide entire section?" → Viewport (md: / lg:)
"Component internal layout?" → Container query (@lg: / @xl:) if variable-width parent, else viewport
| Element | Value |
|---|---|
| App header | z-20 |
| Bottom tab bar | z-50 |
| Modals (Radix) | z-50+ |
md: / @lg: overrides.md: shows/hides sections and sets page structure. lg: enriches elements (icon → icon+text).md: (icon-only), text labels expand at lg:. See Section 8.window.innerWidth, useMediaQuery, or matchMedia — use CSS. These cause hydration mismatches and duplicate CSS's job.@container propagation: Adding @container to a parent changes how all descendant container queries resolve. Audit children before adding it to an existing element.assertNoHorizontalOverflow() in its smoke test — document.scrollWidth <= document.clientWidth at both mobile (375px) and desktop (1024px) viewports. Add new pages to e2e/smoke/responsive-overflow.spec.ts.use-table-responsive-columns for IssueList (PP-rs9) uses a JS hook — this is the sole approved exception.When building a new page, pick the closest archetype and follow its pattern.
max-w-6xl -- Stats in grid-cols-1 md:grid-cols-3, lists in md:grid-cols-2.
max-w-7xl -- Filters + card grid md:grid-cols-2 lg:grid-cols-3.
grid md:grid-cols-[minmax(0,1fr)_320px] -- Sidebar hidden md:block, collapses to inline strips on mobile.
Note: Issue detail migrated off this archetype (see "Detail Page with Inline Metadata" below). Machine and Location detail still use this pattern.
max-w-3xl (PageContainer size="narrow") single-column main flow. Metadata uses IssueMetadata (container query reflows 1-col → 2-col at @xl:). Mobile sticky comment composer opens a Sheet. Reading-content-shaped pages prefer narrow over standard — issue detail is text + form rows, not a dashboard.
Note: Replaces "Detail Page with Sidebar" for issue detail; eliminates desktop/mobile divergence. Use for new detail pages; migrate existing sidebar pages opportunistically.
PageContainer size="standard" wrapping a persistent header zone + URL-driven tab strip + tab content. Each tab is a real route, not client state — deep-linkable and back-button-friendly. Reference implementation: src/app/(app)/m/[initials]/ (layout.tsx renders header + MachineTabStrip; sibling page.tsx and {slug}/page.tsx files render per-tab content).
[initials chip] [game name (truncates)]. No status badge, no presence badge, no owner display, no primary action button. Not sticky on scroll. The rationale: identity stays in one place across tab navigation; everything else (status, owner, actions) moves into the tab content where it belongs to that tab's context.Service [3] in amber for needs_service). Hidden when count is 0. This single element carries both the urgency (color, from status) and the scale (number, from open-issue count) — replaces the persistent header's status display.flex row inside overflow-x-auto. Active tab uses border-b-2 border-primary text-primary. A right-edge fade gradient (pointer-events-none absolute bg-gradient-to-l from-background) is rendered only when the strip can scroll further right — tracked via a scroll listener + ResizeObserver so the fade hides cleanly when all tabs already fit or when the user has scrolled to the end.scrollIntoView({ inline: 'center' }) on mount centers the active tab on deep-link.cache()-wrapped query (e.g., getMachineForLayout in _data.ts) — both call the same function within one request and the second call returns the cached result. Layout calls notFound() for missing entities so children can assume existence.<Tabs>: that primitive is state-driven (client-only). URL-driven tabs are a navigation strip, not a tabs widget — build with <Link> + usePathname().max-w-2xl -- Form inside a card, back button + title in header.
max-w-3xl -- Vertical sections separated by Separator components.
max-w-6xl -- Full-width Table with fixed column widths.
max-w-md -- Centered card, no MainLayout wrapper.
max-w-3xl -- Prose content inside a card.
max-w-3xl -- Card grid sm:grid-cols-2.
| Context | Value |
|---|---|
| Standard pages | py-10 |
| Settings / forms | py-6 |
| Detail pages (mobile-adj) | py-4 sm:py-10 |
MainLayout provides px-4 sm:px-8 lg:px-10. Pages use max-w-* mx-auto only -- do NOT add their own px-*.
| Context | Value |
|---|---|
| Standard section gaps | space-y-6 |
| Major detail sections | space-y-8 |
| Card grids | gap-6 |
| Main + sidebar layouts | gap-8 |
Use shadcn defaults: CardHeader (px-6 pt-6 pb-3), CardContent (px-6 pb-6). Override only with a documented reason. Compact cards use p-3.
bg-card + hover:glow-primary + border-outline-variant hover:border-primary/50. (Earlier drafts called for bg-surface here, but the cards are content surfaces, not full-width sections — see §2 Surface Hierarchy.)bg-surface-variant/30, no glow.IssueCard has normal and compact variants -- use compact for secondary/nested lists.IssueBadgeGrid has variant="normal" (grid layout) and variant="strip" (inline flex).hidden md:flex.hidden lg:inline on <span>. Icons always visible with title for tooltip/a11y.HelpCircle icon button with badge dot when unread changelog entries exist./whats-new), Help (/help), About (/about).md:hidden)AppHeader because BottomTabBar spreads the same NAV_ITEMS array.Sheet (bottom drawer) with Feedback, What's New, Help, About, Admin (role-gated).text-primary.text-muted-foreground hover:text-primary.isNavItemActive() from nav-utils.ts with pathname matching and special cases (e.g., issue detail highlights the Issues tab).assertNoHorizontalOverflow(page) in e2e/support/actions.ts checks document.scrollWidth <= document.clientWidth. Every new page must be added to e2e/smoke/responsive-overflow.spec.ts.await page.evaluate(() => { document.querySelector('[data-testid="content-wrapper"]')!.style.width = '576px'; }) — triggers @xl: breakpoints independently of viewport.@container elements.| Element | Classes |
|---|---|
| Page title (desktop) | text-3xl font-bold |
| Page title (detail page) | text-3xl font-bold |
| Section heading | text-xl font-semibold |
| Card title (normal) | text-base |
| Card title (compact) | text-sm |
| Metadata / labels | text-xs text-muted-foreground |
| Issue IDs | font-mono (e.g., AFM-3) |
| Machine name in cards | text-xs font-medium underline decoration-primary/30 underline-offset-2 |
Text wrapping (text-balance / text-pretty):
text-balance on headings that may wrap onto multiple lines (page titles, card titles, dialog titles, hero copy, section headings).text-pretty on multi-line body copy that may wrap (card descriptions, alert/dialog descriptions, PageHeader subtitles, auth intro copy, feature descriptions).The shared primitives (CardTitle/CardDescription, AlertTitle/AlertDescription, DialogTitle/DialogDescription, AlertDialogTitle/AlertDialogDescription, EmptyState, PageHeader) bake these in by default — call sites rarely need to add them manually.
| Context | Treatment |
|---|---|
| Navigation chrome | border-primary/50 |
| Content cards | border-outline-variant |
| Form sections | Separator component |
| Page header bottom | border-b border-outline-variant pb-6 |
Two canonical durations standardize all animated feedback:
| Intent | Duration | Class | Typical use |
|---|---|---|---|
| Hover feedback, color shifts | 150ms | duration-150 | Button hover, text color, icon state |
| Layout changes, structural animations | 300ms | duration-300 | Panel slides, accordion expand, drawer open |
Property selection: Prefer specific transitions over transition-all — list the properties that actually animate. This improves performance and clarity.
transition-colors duration-150 for button hovers, link colors, icon fillstransition-opacity duration-150 for opacity-only reveals (badges, icons)transition-transform duration-150 for small rotations (chevrons, badges)transition-[color,background-color,border-color,box-shadow] duration-150duration-300: transition-[height,width] duration-300, transition-[grid-template-rows] duration-300, etc. Reserve transition-all duration-300 for cases where the set of animating properties genuinely isn't enumerable.Rule: Never introduce a duration other than 150 or 300 unless the canonical two genuinely don't fit. If you find an edge case, add a new row to this table first, document the use case, then use it consistently across similar elements.
Motion sensitivity: Every animate-* and non-essential transition-* utility pairs with motion-reduce:animate-none / motion-reduce:transition-none (CORE-A11Y-002). Loading spinners use animate-spin motion-reduce:animate-none — the static icon still communicates "loading." Essential motion (e.g., a Sheet sliding into view — the slide is what conveys "this came from the side") can omit the variant; document the choice in a one-line comment so reviewers know it was deliberate.
Before building something new, check if one of these already exists:
| Component | Purpose |
|---|---|
AppHeader | Two-tier responsive header. Icon-only nav at md:, icon+text at lg:. APC logo at lg: only. |
HelpMenu | Dropdown with Feedback, What's New, Help, About. Badge dot for unread changelog. |
BottomTabBar | Mobile tab bar (md:hidden). Dashboard, Machines, Issues, Report, More. |
IssueBadgeGrid | Status/severity/priority/frequency display |
IssueBadge | Individual status badge with color |
IssueCard | Issue summary card (normal/compact) |
IssueRow | Table row variant of issue display |
SidebarActions | Issue metadata editing (compact/full, rowLayout) |
SaveCancelButtons | Form action buttons |
Card / CardHeader / CardContent | shadcn/ui card |
Sheet | Bottom drawer (mobile "More" menu) |
NotificationList | Notification bell + dropdown |
UserMenu | Avatar + dropdown menu (includes Admin link for admin role) |
BackToIssuesLink | Breadcrumb back navigation |
EmptyState | Icon + title + optional body + optional action. variant="card" (default) or variant="bare". |
Alert (shadcn) | Inline message. variant="destructive" for errors. Never hand-roll <div role="alert">. |
Skeleton (shadcn) | Loading placeholder. Shape it like the content that will arrive. |
Every page will eventually need one of these three states: empty, loading, error. Each has a canonical pattern. Reach for the pattern first; don't invent a variant.
Canonical component. Use
<EmptyState>from~/components/ui/empty-statewhenever a list, collection, or section has zero items to display. Prefer the shared component over hand-rolled inline empty-state layouts so copy, spacing, and visual hierarchy stay consistent across the app.
Use <EmptyState> whenever a list, collection, or section has zero items to display.
| Prop | Purpose |
|---|---|
icon | A lucide-react icon. Rendered at size-12 in a muted circle. |
title | Short heading (e.g., "No machines yet", "No issues found"). |
description | Optional body text. Explain what would populate this section. |
action | Optional CTA — typically a <Button> or <Link> styled as such. |
variant | "card" (default, wraps in <Card>) or "bare" (plain container). |
When to use each variant:
variant="card" — the empty state IS the content of the section. Dashboard widgets, standalone "no results" pages.variant="bare" — the empty state is rendered inside a list that's already wrapped in a Card or container. No double-border effect.Rules:
<div> + icon + heading. Always use <EmptyState>.description.action only if the user can do something productive from here (e.g., "Report the first issue"). Don't provide dead-end CTAs.Prefer <Skeleton> rectangles shaped like the content that will appear. Skeletons reduce layout shift and communicate progress better than spinners.
| Situation | Use |
|---|---|
| Async data not yet available (lists, tables) | <Skeleton> rectangles matching the shape of incoming rows |
| In-flight form submission | <Button loading> — handles spinner + disabled state |
| Long-running background work | Toast with an inline spinner / progress indicator |
| Optimistic UI (actions with predictable end) | Update immediately, revert on error |
Rules:
<Loader2> or similar directly into components. If you need one, use Button's loading prop.loading.tsx files unless a route takes >500ms to stream initial HTML. Most pages render fast enough that a skeleton-shaped flicker is worse than the brief "empty for a moment" state.Three tiers based on scope. Pick the narrowest one that fits.
| Scope | Pattern |
|---|---|
| Form-level (submission failed) | <Alert variant="destructive"><AlertDescription> at top of form |
| Field-level (one field invalid) | <FormMessage> (react-hook-form) or inline text-sm text-destructive |
| Inline list edit (cell update) | toast.error("Failed to update X") |
| Entire route crashed | error.tsx boundary (already implemented) |
| Route not found | not-found.tsx boundary (already implemented) |
Rules:
<div role="alert" className="rounded-md border border-red-900/50...">. Use <Alert variant="destructive"> — it already exists in ~/components/ui/alert.When something happens in response to user action, where should they see feedback?
| What happened | Where to show feedback |
|---|---|
| Form submit success → redirect | Server Action does the write, then redirect(...); if needed, show success on the destination page |
| Form submit success → stay on page (settings) | Return success state from the Server Action; <SaveCancelButtons> green flash (3s "Saved!") |
| Form submit error | <Alert variant="destructive"> at top + <FormMessage> under fields |
| Field validation error (Zod) | Inline <FormMessage> |
| Inline list edit (status change, priority change) | toast for both success and error |
| optimistic action (toggle, bookmark) | Immediate UI update; toast.error() on failure |
| Long-running background work (uploads) | Toast with progress indicator |
| Short in-place work (counter increment) | Immediate UI update, no notification |
Why server-side redirect instead of toast.success() + router.push()? The project's progressive-enhancement rule (AGENTS.md §2.1 "Progressive Enhancement") requires forms to work without JavaScript. <form action={serverAction}> + server-side redirect(...) works with JS off; a toast.success() + router.push() pattern only fires after hydration. If a success toast is genuinely needed on the destination page, persist a one-time success state (e.g., via a search param or short-lived cookie read in the destination route) and render it there.
Rule of thumb: If the user initiated it and waited → feedback. If it was instant or invisible → no feedback.
Why not toast for everything? Toasts are ephemeral and noisy. Use them for transient events (row updated, file uploaded). Use inline alerts for persistent state (form has errors, save failed, retry needed).
Why <SaveCancelButtons> has its own success flash instead of a toast? Settings pages don't redirect, so a toast would disappear while the user is still looking at the form. A button that briefly turns green keeps the feedback anchored to the action.
Status — implemented. Three canonical helpers live in
src/lib/dates.ts. Use them; never callformatDistanceToNowortoLocaleDateStringdirectly from a component.
| Helper | Output | When to use |
|---|---|---|
formatRelative(date) | "3 days ago", "in 2 hours" | Activity timestamps — comments, issue updates, notifications |
formatDate(date) | "Apr 17, 2026" | Absolute dates in detail views, created-at fields |
formatDateTime(date) | "Apr 17, 2026, 9:30 PM" | Admin audit logs, precise timestamps, debug info |
All three accept Date | string | number. For null / undefined dates, null-guard at the call site and choose a context-appropriate placeholder (e.g., hiding the element, rendering "—", or using a semantic placeholder like "never").
Why a vocabulary instead of raw calls?
toLocaleDateString() renders differently per locale, which breaks visual regression tests.date-fns to Temporal or add tooltips showing absolute dates on hover, we change one file.Don't: build custom formatting helpers per feature. If formatRelative / formatDate / formatDateTime don't cover a case, expand the vocabulary rather than inlining a new variant.
lucide-react is the only icon library for new work. Do not introduce new inline SVGs, and do not import icons from other libraries. Some existing inline <svg> usage is legacy (signup confirmation state, AssigneePicker chevron, NotificationList dismiss icon); when you touch those areas, prefer migrating them to lucide-react opportunistically where doing so does not change behavior.
| Class | Usage |
|---|---|
size-4 (1rem) | Default inline, buttons, nav links, table cells |
size-5 | Heading emphasis (CardTitle/DialogTitle with leading icon) |
size-6 | Callouts, prominent indicators |
size-8 | Section decorative |
size-10+ | EmptyState icons (rendered at size-12 in a muted circle), hero uses |
Critical rule: Use size-*, never h-* w-*. The size-* utility is Tailwind v4 canon; h-4 w-4 is legacy and creates two classes where one would do.
Buttons auto-size icons. <Button> has [&_svg:not([class*='size-'])]:size-4 built in, so you don't need to specify size-4 on an icon child. Only add an explicit size if you're overriding.
Color: Icons inherit from parent text color. Add text-* to the parent or the icon itself; don't use fill= or stroke= overrides.
Accessibility: Icon-only buttons must have aria-label or a visible <span className="sr-only">. Nav icons that are part of a labeled nav item (<Link> with text that may be hidden at some breakpoints) should have title as a tooltip fallback.
Two canonical modal patterns. Use shadcn primitives directly; don't extract a composite unless duplication exceeds rule-of-three.
<Dialog open={open} onOpenChange={setOpen}>
<DialogTrigger asChild>
<Button variant="outline">Edit</Button>
</DialogTrigger>
<DialogContent className="sm:max-w-lg">
<DialogHeader>
<DialogTitle>Edit machine</DialogTitle>
<DialogDescription>Update the name and location.</DialogDescription>
</DialogHeader>
<form action={updateMachine} className="space-y-4">
<!-- fields -->
<DialogFooter>
<Button variant="outline" type="button" onClick={() => setOpen(false)}>Cancel</Button>
<Button type="submit">Save</Button>
</DialogFooter>
</form>
</DialogContent>
</Dialog>
<AlertDialog>
<AlertDialogTrigger asChild>
<Button variant="destructive">Delete</Button>
</AlertDialogTrigger>
<AlertDialogContent>
<AlertDialogHeader>
<AlertDialogTitle>Delete machine?</AlertDialogTitle>
<AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
</AlertDialogHeader>
<AlertDialogFooter>
<AlertDialogCancel>Cancel</AlertDialogCancel>
<AlertDialogAction onClick={deleteMachine}>Delete</AlertDialogAction>
</AlertDialogFooter>
</AlertDialogContent>
</AlertDialog>
| Size | Class | Use case |
|---|---|---|
| Default | (no override) | Short confirmation prompts |
| Medium | sm:max-w-lg | Most forms (2-6 fields) |
| Large | sm:max-w-xl / 2xl | Forms with rich content (editors, previews) |
DialogFooter uses flex flex-col-reverse gap-2 sm:flex-row sm:justify-end. Write the buttons in source order as [Cancel, Save] (or [Cancel, Delete] for AlertDialog). That renders:
flex-col-reverse): primary action (Save/Delete) on top, Cancel below. The reversal intentionally puts the primary action above the fold / closer to the focus point for small-screen readers.sm:flex-row sm:justify-end): horizontal row on the bottom-right, Cancel left, primary action rightmost — matching the standard "primary action anchors the right edge" convention.Do not reorder the buttons to try to "fix" the mobile stack — the reversal is by design.
Modal or Drawer component — Dialog / AlertDialog / Sheet cover every case.<form> inside a DropdownMenuItem — Radix closes the dropdown before the form submits. Use onSelect={() => serverAction()} instead.action={async () => await serverAction()} breaks progressive enhancement. Pass the Server Action directly: action={serverAction}.AlertDialog — it has semantics (role="alertdialog") that screen readers announce more urgently.inert on the page-root container (CORE-A11Y-006). Radix uses aria-hidden + pointer-events on the background; inert is the platform primitive that also removes the background from tab order.<dialog>.showModal() (Baseline Widely available; Baseline since Mar 2023 per §19) is not the default for product UI — shadcn <Dialog> / <AlertDialog> / <Sheet> are. Reach for <dialog> only for one-off, self-contained, single-purpose surfaces that don't earn a place in the shadcn variant system (e.g., a debug-only inspector, a tightly-scoped help blurb). See pinpoint-ui skill § "Native HTML primitives alongside shadcn/Radix".Any surface whose primary job is composing free-form rich text (timeline notes, issue comments, and future equivalents) follows two rules. Length-limited single-line fields — titles, names, search boxes — are explicitly exempt; these rules are about multi-line writing surfaces only.
Bottom sheet on mobile. On small screens a composer SHOULD open in a bottom <Sheet side="bottom">, not an inline block buried in the page. The sheet owns the keyboard-adjusted viewport so the editor and its Post button stay visible while typing, and the capture affordance is reachable without scrolling past existing content. On desktop the composer may render inline (or in a side sheet / dialog when triggered from a header action). One composer component, viewport-aware presentation — do not fork into two components.
Quick → full editor transition. The editor opens in quick mode: the formatting toolbar is hidden so it reads as a fast jot, not a document. A single toggle (a "format"/Aa button beside the primary controls) reveals the full toolbar; the toggle is two-way (content is always stored as the same rich-text document regardless of mode, so flipping back is lossless). Default to the lightest classification (e.g. the timeline composer defaults its tag to note) and never block submit on a classification the author has not been asked to make. Support Cmd/Ctrl+Enter to submit.
The timeline composer (PP-0x98) establishes the basic pattern; generalizing it across every mobile editor and extracting a shared primitive is tracked separately (do it on the third use site, per rule-of-three — §17 intro).
globals.css defines two parallel token vocabularies. The MD-era tokens predate Tailwind v4's semantic token naming and are kept in CSS for backward compatibility, but new code must use the canonical Tailwind semantic tokens.
| MD-era (deprecated in code) | Canonical Tailwind semantic |
|---|---|
text-on-surface | text-foreground |
text-on-surface-variant | text-muted-foreground |
bg-error-container | bg-destructive/10 |
text-on-error-container | text-destructive |
Rules:
globals.css; existing code keeps working during migration. Eventually the MD-era tokens will be removed, but not in a single sweep.bg-surface-variant/30. The dimmed/closed item surface (Section 2) has no Tailwind-semantic equivalent and is intentional design. Keep it.| Need | Use |
|---|---|
| Body text | text-foreground |
| Secondary / helper text | text-muted-foreground |
| Primary accent (links/CTAs) | text-primary |
| Error text | text-destructive |
| Primary CTA background | bg-primary |
| Subtle background | bg-muted |
| Destructive CTA background | bg-destructive |
| Destructive container bg | bg-destructive/10 |
| Card background | bg-card |
| Dimmed/closed item | bg-surface-variant/30 |
PinPoint's UI is built on Baseline Widely available (CORE-UI-005) — features that have been cross-browser stable for ~2.5 years. This is the support floor for every new component, layout, animation, and form pattern.
shadcn/ui and Radix remain the design system. The Baseline floor is the platform layer underneath — what we trust to "just work" in our users' browsers. We don't migrate components off Radix to chase native primitives; we layer Widely-available web platform features (:user-invalid, inert, container queries, :has(), fetchpriority, motion-reduce:, aspect-ratio, enterkeyhint, autocomplete tokens, semantic <table> markup, native required/pattern validation, etc.) onto our shadcn-based components so they get the full benefit of the platform.
| Capability | Where it shows up in PinPoint | Baseline since |
|---|---|---|
Container queries (@container) | IssueMetadata, IssueTimeline, AddCommentForm, ImageGallery | Feb 2023 |
:has() | DOM-state-driven styling, removes JS mirroring | Dec 2023 |
:user-valid / :user-invalid | Shared Input/Textarea primitives (CORE-FORM-003) | Nov 2023 |
inert attribute | Background regions when modals open (CORE-A11Y-006) | Mar 2022 |
aspect-ratio | ImageGallery, calendar day cells | Mar 2021 |
accent-color | Checkbox/radio/range accent matching | May 2022 |
fetchpriority (img/script/link) | LCP candidate images (Next/Image priority) | Sep 2023 |
| CSS subgrid | Multi-column form alignment | Sep 2023 |
gap on flexbox | Standard spacing everywhere | Apr 2021 |
prefers-reduced-motion (motion-reduce:) | Every animation utility (CORE-A11Y-002) | Jul 2020 |
focus-visible | All interactive primitives in src/components/ui/ | Mar 2022 |
Native form validation (required …) | Every form | (pre-Baseline) |
enterkeyhint | Multi-field forms (CORE-FORM-006) | Dec 2021 |
Logical properties (inline-start) | RTL-ready text alignment | Mar 2023 |
Native <dialog> | Narrow one-off cases — see §17 | Mar 2023 |
Native <details> / <summary> | Trivial disclosure where Accordion would be overkill | (pre-Baseline) |
These are not in PinPoint today. They require a per-feature opt-in here in §19 before adoption.
popover="auto" / popover="hint") — Radix Popover/DropdownMenu/Tooltip already cover the use cases.animation-timeline: scroll() and friends. Defer.text-wrap: balance — partially adopted (we use text-balance selectively per §9), but treat as Newly available and check support per use.interestfor attribute for tooltips — Chrome-only as of late 2025; defer.closedby attribute on <dialog> — Limited availability (no Safari).The Google Chrome modern-web-guidance catalog tags each guide with its Baseline status. Search it before adopting any pattern:
npx -y modern-web-guidance@latest search "<query>"
npx -y modern-web-guidance@latest retrieve "<id>"
If the guide says "Baseline Widely available" — use directly. If "Baseline Newly available" — follow the guide's documented fallback, or skip the recommendation and add it to the deferred list above.
If a Newly-available feature becomes load-bearing for a planned design:
@supports to feature-detect; fall back to existing pattern X").pinpoint-ui skill's relevant section.Don't sneak a Newly-available feature in without updating this section — it's the single source of truth for what the project considers safe.
Forms are the highest-leverage place to lean on the Widely-available web platform. The browser does post-interaction validation, autofill, mobile-keyboard hints, password-manager integration, and screen-reader announcement — opt in correctly and most "form polish" tickets disappear. Concrete rules and code in pinpoint-ui skill § "Form Correctness"; canonical rules in CORE-FORM-001..006.
| Attribute | When |
|---|---|
type | Always — email, tel, url, password, text per CORE-FORM-001 |
autocomplete | Every credential/identity input — per the token table below |
required | Every field the form will refuse to submit without |
enterkeyhint | Every field in a multi-field form (CORE-FORM-006) |
inputmode | Numeric/decimal/tel where type alone isn't enough |
pattern / minlength | When the validation can be expressed declaratively |
| Form / field | Token |
|---|---|
| Sign-in email | username |
| Sign-in password | current-password (id="current-password" too) |
| Sign-up email | username |
| Sign-up new password | new-password |
| Sign-up confirm password | off ← critical; do not autofill the confirm |
| Reset password (new) | new-password |
| Reset password (confirm) | off |
| First name | given-name |
| Last name | family-name |
| Email (general identity) | email |
| Phone | tel |
| Domain-specific picker | off (explicit — prevents browser from guessing/filling) |
Append <span aria-hidden="true">*</span> to the <Label> of every required field. For forms with many required fields, include a <p className="text-sm text-muted-foreground">* required</p> legend once near the top. Don't rely on the post-submit error to teach the user which fields are required.
:user-invalid styling on the shared <Input> primitive — fires only after the user has interacted (CORE-FORM-003).aria-invalid="true" synced on blur when checkValidity() fails (CORE-FORM-004). Implement once in the shared primitive, not per form.<Alert variant="destructive"> at the top of the form (per §13 Error State).<FormMessage> (react-hook-form) under the field, or inline <p className="text-sm text-destructive">.Disable a submit button after the user has attempted submission (to prevent double-posts), not preemptively while a CAPTCHA hasn't resolved or a field isn't yet filled. Preemptive disabling gives users no feedback about why the button is greyed out. The exception is the shadcn <Button loading> state during an in-flight submission.
Image loading sits at the intersection of LCP, layout stability, and bandwidth. Next.js <Image> handles the heavy lifting (srcset, WebP/AVIF negotiation, lazy loading); PinPoint must opt in correctly on a per-image basis.
priority is for the LCP candidate only (CORE-PERF-003)priority emits fetchpriority="high" (Baseline Widely available since Sep 2025) plus eager loading. The browser interprets this as "this image is critical to first paint." Every prioritized image deprioritizes every other resource — so adding priority to a non-LCP image actively hurts LCP.
| Place | Should priority? |
|---|---|
| The largest above-the-fold image | Yes — that's the LCP candidate |
| 32px header logo | No — too small to be the LCP, downloads fast |
| Sidebar logo on a wide-only column | No — never the LCP, often below the fold |
| Image inside a closed dialog/modal | No — not in the viewport at first paint |
| Avatars in a list | No — many, all small, none the LCP |
| Thumbnail in a gallery | No — lazy is correct |
sizes accompanies every responsive imageWithout sizes, the browser assumes 100vw and downloads the desktop-width variant on mobile. Always provide sizes for images that don't render at full viewport width:
<Image
src="/apc-logo.png"
alt="APC logo"
width={200}
height={149}
priority
sizes="(max-width: 768px) 80vw, 200px"
/>
Add <link rel="preconnect"> in the root layout for any third-party image origin used during initial render (e.g., the Vercel Blob bucket subdomain). This eliminates DNS + TLS handshake on the first user-uploaded image.
// src/app/layout.tsx <head>
<link
rel="preconnect"
href="https://<project>.public.blob.vercel-storage.com"
/>
priority images that render inside closed surfacesA Client-Component <Dialog> is mounted before it opens; an <Image priority> inside that mount is fetched eagerly even though the dialog hasn't been opened yet. Use priority on the gallery thumbnail's LCP candidate if there is one, not on the modal's full-size image.
The Google Chrome modern-web-guidance plugin is PinPoint's canonical lookup tool for "is there a Widely-available primitive for this?" Each guide is a prescriptive document with DOs/DON'Ts and a Baseline-status note. Use it at the start of any non-trivial UI work (CORE-UI-006).
npx -y modern-web-guidance@latest search "<query>" # find guides by intent
npx -y modern-web-guidance@latest retrieve "<id>,<id2>" # fetch full guide(s)
npx -y modern-web-guidance@latest list # browse the catalog
| Building... | MWG search/retrieve |
|---|---|
| Sign-in / sign-up form | forms, autofill-sign-in-form, autofill-sign-up-form |
| Address or anonymous reporter form | autofill-address-form, forms |
| Post-interaction validation | validate-input-after-interaction, required-field-feedback |
| Accessible error announcement | accessible-error-announcement |
| Modal / dialog / confirmation | html §4, light-dismiss-a-dialog, platform-controls-dismiss-dialog |
| Mobile drawer / slide-in | navigation-drawer |
| Tooltips on touch | interest-triggered-tooltips (most variants are Newly available) |
| Image priority / LCP | optimize-image-priority, optimize-preload-priority |
| Long-task / INP | break-up-long-tasks, identify-inp-causes |
| Container-internal layout | css-layout, size-aware-styling |
| Conditional styling via DOM state | style-parent-with-has |
| Hidden-but-findable content | search-hidden-content |
| Reduced-motion / animation | accessibility § Motion |
| Skip-link / landmarks / focus | accessibility, html §3 |
| Tables | accessibility § Tables |
Don't memorize the map — re-search per task. Plugin catalog updates more often than this document does.
When you build a mockup or prototype of a change for review, show enough of the surrounding page that the reviewer can judge how the change fits — not just the changed element in isolation.
This is a presentation rule for design exploration, not a constraint on the product UI itself.