Skip to content

supercheck-io/supercheck / .agents/skills/ui

supercheck-ui

Verified

Build or change Supercheck UI or visual design, such as app pages, layouts, components, tables, forms, dialogs, charts, sidebar navigation, empty, loading and error states, dark mode, responsive layout, accessibility, colours, fonts, icons, or the look of the marketing landing page, pricing page and docs theme, and verify it visually. For data hooks see supercheck-architecture.

Supercheck UI

The app is Next.js 16 + React 19 with Tailwind 4 and shadcn-style components (app/components.json: style new-york, base color zinc, CSS variables, lucide icons). Reuse what exists before writing new UI. Read DESIGN.md (repo root) first: it defines the colour roles (black primary actions, area colours, violet for AI only, status colours for badges only), typography and the shared components below.

Start here

FileWhy
app/src/components/ui/Primitives (button, card, dialog, alert-dialog, form, field, table, data-table-*, chart, skeleton, tooltip, sidebar, ...)
DESIGN.mdColour roles, typography, layout and the agent checklist
app/src/app/globals.cssDesign tokens (oklch CSS variables incl. area tokens automate/monitor/respond/communicate/ai, @theme inline mappings, .dark overrides)
app/src/app/(main)/monitors/page.tsxReference page layout
app/src/components/app-sidebar.tsxSidebar navigation entries
app/src/hooks/React Query hooks the UI reads from

Page structure

  • Pages render <PageBreadcrumbs items={...} /> (components/page-breadcrumbs.tsx) followed by a Card with CardContent holding the feature component.
  • The title row is PageHeader (components/shared/page-header.tsx) with icon and tone set to the page's product area (automate, monitor, respond, communicate, ai; slate for settings and admin).
  • Keep page.tsx a Server Component and put interactive parts in a "use client" feature component.
  • Route-level loading uses app/(main)/loading.tsx (components/shared/supercheck-loading.tsx). Tables use ui/data-table-skeleton.tsx or ui/table-skeleton.tsx; generic placeholders use ui/skeleton.tsx.
  • Every list or panel needs explicit loading, empty, and error states. Reference empty state: components/dashboard/dashboard-empty-state.tsx. App-level errors: app/error.tsx, not-found.tsx.

Components and patterns

  • Tables: TanStack Table with the ui/data-table-* pieces (column header, faceted filter, view options). Reference: components/monitors/data-table.tsx.
  • Table footers use ui/data-table-pagination.tsx (DataTablePagination, label Total {n} {itemName}); never copy a pagination component into a feature folder.
  • Icon chips: ui/icon-chip.tsx (IconChip), one per page title or card header, never in table rows. Incident sections use SectionTitle from sre/incidents/incident-ui.tsx.
  • Buttons: Button variants only; never recolour a button with className (the Run buttons once did and drifted to blue).
  • List tables fit the window: use useFitPagination / useFitPageSize and pageSizeOptions from hooks/use-fit-page-size.ts (rows per page follow the viewport; a manual choice overrides). Pass a fixed size for tables embedded in sheets. Pages that must fill the viewport without scrolling put data-fit-viewport on their root (the layout reads it).
  • Forms: react-hook-form with zodResolver and the shared Zod schemas; use ui/form.tsx or ui/field.tsx as the neighboring form does.
  • Destructive actions confirm with ui/alert-dialog.tsx and name the object being deleted.
  • Feedback: toast from sonner (the <Toaster> is ui/sonner.tsx).
  • Long values: ui/truncated-text-with-tooltip.tsx; ids: ui/uuid-field.tsx; copy: ui/copy-button.tsx.
  • People: UserCell (avatar, name, email in a tooltip, "Unassigned"/"System" empty state) and UserAvatar from ui/user-cell.tsx. Never render "Name (email)" inline or hand-roll initials; select user.image in the query so the photo shows.
  • Icons from lucide-react only.

Tokens, theming, charts

  • Colors come from CSS variables in globals.css, which are oklch. Use Tailwind token classes (bg-primary, text-muted-foreground, border) or var(--token). Never hard-code hex/rgb, and never wrap a token in hsl(...): hsl(var(--chart-1)) is invalid CSS on oklch values and renders no color.
  • Chart colors: var(--chart-1) to var(--chart-5) (Tailwind --color-chart-* is mapped in @theme inline). Charts use recharts through ui/chart.tsx (ChartContainer).
  • Dark mode is the .dark class from next-themes (components/theme-provider.tsx). Check every change in both themes.
  • Fonts are Geist Sans and Geist Mono from the geist package (local font files, no download at build time), exposed as --font-geist-sans/--font-geist-mono and used through font-sans/font-mono.

Data in components

  • Read data through the hooks in app/src/hooks/; render cached data directly, do not copy it into state.
  • After a mutation, invalidate the affected *_QUERY_KEY arrays (scoped as [...KEY, projectId]).
  • Prefetch and mounted queries sharing a key must use the same normalized fetcher and bind requests to that key's project. Reset project-specific analytics state when the project changes.
  • Usage or limit numbers shown in UI must use the same counting as the server; label estimates as estimates.

Accessibility and responsiveness

  • Icon-only buttons need an aria-label and usually a Tooltip. Keep the visible focus-visible rings from ui/button.tsx; do not remove outlines.
  • Everything must be keyboard reachable; dialogs trap and restore focus (the primitives already do; do not replace them).
  • Layouts must not overflow at 390px width: wrap stat strips, let tables scroll inside their card, truncate long names with a tooltip.

Verify

  • Unit: colocated *.spec.tsx with React Testing Library for logic-bearing components.
  • Visual: run the app and screenshot the changed pages at 390px and 1440px in light and dark (Playwright, for example the playwright-cli skill). Check empty, loading, and error states, not only the happy path.
  • E2E selectors must survive hydration: interact after waitForHydration (app/e2e/utils/hydration.ts); components/hydration-ready.tsx sets the marker.
  • npm run lint (max warnings 0) and npx tsc --noEmit in app/.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall