Product Design
Designproduct-designProduct Design is an Agent Skill for design published in the chmonitor/chmonitor repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
chmonitor's product design system + UX conventions, so every new feature looks and behaves consistent with the rest of the dashboard. Use BEFORE building or reviewing any UI: new pages, charts, cards, dialogs, empty/error/loading states, badges, onboarding, settings. Covers design tokens (OKLCH theme, dark mode, radius, chart colors), shadcn/ui rules, the ChartCard/ChartContainer pattern, data-table system, EmptyState variants, graceful error handling, ?host routing + hooks-at-deepest-consumer, file/route organization, and brand. Triggers: "new page", "add a chart", "build UI", "design", "component", "empty state", "loading", "consistent", "follow-up feature", "match the design".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/chmonitor/chmonitor/blob/HEAD/.claude/skills/product-design/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/product-design, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
chmonitor product design system
The rulebook for keeping new features visually + behaviourally consistent. When
in doubt, COPY the closest existing component rather than inventing. Full token
values and file paths: docs/knowledge/product-design.md.
Non-negotiables
- Never edit
src/components/ui/*(shadcn primitives). Customise via theclassNameprop at the call site, or a wrapper insrc/components/— never inui/. Always merge classes withcn()(src/lib/utils.ts), never template-literal concatenation. - Tailwind v4, CSS-first. Tokens live in
src/styles.css@themeblocks — there is notailwind.config.ts. Use semantic tokens (bg-card,text-muted-foreground,border-border), not raw colors. Theme is OKLCH. - Dark mode is
class-based (next-themes,.dark). Every surface must read correctly in both themes — only use semantic tokens, which flip automatically. Don't hardcodebg-white/text-black. - Hooks at the deepest consumer. A component that needs data calls
useHostId()/useChartData()itself — do NOT prop-drillhostId. ?host=Nrouting, never dynamic/N/...segments. Preserve other search params withbuildUrl(pathname, { host }, searchParams).- No "AI slop" decoration — one clear signal per state, not several
redundant ones. No full-saturation accent bars/rails stacked on an
already-colored border; no gradient blobs/glow orbs behind icons. See
"Anti-patterns" in
docs/knowledge/product-design.md.
Tokens (semantic — use these names, not hex/oklch literals)
background foreground card card-foreground popover muted muted-foreground primary secondary accent destructive border input ring. Charts:
--chart-1..13 for series, plus named accents --chart-red (error series),
--chart-blue (info), --chart-green (success), --chart-yellow (warning) —
only pass tokens that exist in styles.css to a chart's colors prop; an
undefined var() renders the series black. Radius: rounded-md (9px) default,
rounded-lg (10px), rounded-xl (14px) for cards. Brand accents: orange
(metrics) + emerald (health/live) — see components/icons/chmonitor-logo.tsx.
Canonical idioms (match these class strings)
- Card surface:
rounded-xl border bg-card shadow-sm(premium variant addsbg-gradient-to-b from-card/80 to-card/40 dark:from-card/60 dark:to-card/30 backdrop-blur-xl). Seecomponents/charts/chart-card-styles.ts. - Icons:
lucide-react,size-4standard /size-3.5compact /strokeWidth={1.5}. - Dense text:
text-[13px]controls,text-smbody,text-xs text-muted-foregroundmeta,text-xl font-semibold tracking-tightpage/hero titles. - Spacing:
gap-1.5compact,gap-2standard,gap-4generous; card contentp-4 pt-0. - Pill/secondary button link:
inline-flex h-8 items-center gap-1.5 rounded-md border border-border px-3 text-[13px] font-medium hover:bg-muted. - Clickable card → detail dialog: whole card is the target (
role="button"+tabIndex={0}+onKeyDown={activateOnEnterOrSpace(open)}, never a nested<button>); inner linkse.stopPropagation()(notpreventDefault) so they still navigate. Drive drill-down from a per-item field, rendered viaResultTable. Seecomponents/health/{health-card-shell,health-detail-rows}.tsx. - Overflow strip (one row, no wrap):
scrollbar-hide overflow-x-auto+py-*(so shadows/accents/focus rings aren't clipped) with a chevron button + afrom-background→transparentedge fade per scrollable side, paging viascrollBy. Re-measure on scroll /ResizeObserver/ content-count change. Copycomponents/insights/insights-strip.tsx. - Paired page sections (e.g. AI-generated vs. plain-statistics content):
identical-weight header on both —
icon (size-4, muted-foreground) + <h2 className="text-sm font-medium text-foreground">. A genuinely empty section still gets the header, with anEmptyState variant="no-data" compactplaceholder card, rather than being omitted. See/insightsand/insights-settings(AI InsightsvsStatistics Insights— the latter is now a realStatsInsightsSettingsForm). - Preview / "Example" surfaces: render from deterministic mock data
parameterized by settings (seed-rotated, SSR-safe), never a live query/LLM
call — no "Couldn't generate" error for anon/read-only visitors. Label it
"Sample". See
components/insights/insights-preview.tsx. - Base UI primitives (
components/ui/*= shadcn Base UI, not Radix): style overlays offdata-open/data-closed/data-orientation(needs the@custom-variant data-horizontal|verticalinstyles.css) and Base UI CSS vars (--anchor-width,--available-height,--collapsible-panel-height), NOTdata-[state=…]/--radix-*. Use therenderprop, notasChild. Full detail in the knowledge doc's "Base UI backing" section.
Charts — always wrap state, never hand-roll it
Use ChartContainer (renders skeleton / ChartError / empty) + ChartCard
(title, SQL, metadata, stale indicator, retry). Fetch with useChartData({ chartName, hostId, interval }). Header icon order:
[StaleIndicator] [DateRange] [LogScaleToggle] [CardToolbar]. Copy an existing
chart in components/charts/ as the template — don't reinvent the wiring.
Loading / empty / error
- Loading: a
Skeletonthat matches the final layout (components/skeletons/) to avoid layout shift; gate withSuspensewhere used. - Empty:
EmptyState(components/ui/empty-state.tsx) with the rightvariant(no-data | no-results | error | table-missing | timeout | filtered-empty | offline | loading),icon,title,description, optionalaction/onRefresh. - Error (graceful): initial error (
error && !hasData) → fullChartErrorwith retry. Revalidation error (staleError) → KEEP showing data + subtle amberChartStaleIndicator(hover-revealed), auto-clears on next success. Never blank out good data on a refresh failure. - First run (zero hosts):
FirstRunGate→FirstRunEmptyState(3 modes: cloud signed-in / cloud anon / self-hosted). See thecloud-saas-modeskill.
Data tables
Use the components/data-table/ system (resizing, wrap toggle, sorting via
sorting-fns.ts, pagination, faceted filters, row actions, SQL display).
Synthetic column ids __expand, select, action are non-data — skip them in
filter/search/sort/card wiring.
User appearance settings
The Settings dialog (components/settings/settings-form.tsx) exposes units
(byteUnit, numberFormat), chart palette (chartPalette), table density
(tableDensity) and default time range on UserSettings. Every DEFAULT
reproduces the prior look byte-for-byte. Applied by AppearanceSettingsProvider
(lib/context/appearance-settings.tsx): units → module snapshot in
lib/format-settings.ts (read by the format-readable helpers); palette/density
→ data-chart-palette / data-density on <html> with --chart-* and
data-slot padding overrides in styles.css (never edit ui/table.tsx). For
2–3 choices use components/settings/segmented-control.tsx. Full detail:
docs/knowledge/product-design.md.
Adding a page
src/routes/(dashboard)/my-page.tsx('use client', usesuseHostId()).- Add a
QueryConfiginsrc/lib/query-config/if it needs data. - Register in
src/menu.ts(with feature gate /tableCheckif optional). - Compose
ChartContainer+ChartCard; reuse skeletons + empty/error states.
File & naming conventions
kebab-case files; PascalCase components; use* camelCase hooks; props as
interface XProps colocated; client components declare 'use client', server
components don't; shared types in src/types/ or src/lib/api/types.ts. Details
in docs/knowledge/conventions.md.
Keep this skill current
This skill is the source of truth for design consistency. When you introduce or
change a durable UI pattern (a new token, a reusable component, an
empty/error/onboarding convention), UPDATE this file + docs/knowledge/ product-design.md in the SAME change. See the "Auto-improve project skills"
note in the root CLAUDE.md.