calm-ui — restrained product design system

This skill enforces a specific design philosophy when building product interfaces. It is not generic guidance — it is an opinionated constraint system.

Core constraints

Read these before writing any UI code. Every rule is testable — you should be able to look at a screen and answer yes/no.

Non-negotiables

1. Restraint over expression. Prefer reduction and clarity over visual novelty.
2. Minimal typography variance. Hierarchy comes from weight, spacing, placement, alignment, grouping, density, and contrast — not type size jumps.
3. Calm over busy. Interfaces feel quiet and easy to scan.
4. Structure over decoration. Layout, spacing, and rhythm before visual chrome.
5. System over one-offs. Repeated elements follow one consistent pattern.
6. Neutral first. The UI works in grayscale before accent color is added.
7. Shadcn is a foundation, not the final look. Never ship default-looking shadcn components. See "shadcn foundation" below for how to refine them.

Layout

• Start with spacing and grouping before reaching for cards
• Strong alignment throughout — architectural, not incidental
• Generous whitespace is structural, not decorative
• Fewer, stronger layout decisions; reduce unnecessary nesting
• No card-on-card-on-card; containment only when it adds clarity

Typography

• Tight type scale with minimal size variance
• Hierarchy from weight, spacing, placement — not dramatic scaling
• Headings restrained, body text readable and consistent, labels understated
• Prefer tighter tracking and line height while maintaining legibility

Components

• Light, quiet, precise, refined, consistent
• One strong pattern per component type
• Buttons: clear primary/secondary hierarchy, subtle treatment, calm states
• Inputs/forms: subtle field styling, aligned labels, strong spacing, clean focus states
• Cards: intentional, not automatic; prefer open composition
• Tables: clean structure, subtle row separation, readable spacing, minimal controls
• Navigation: predictable, quiet, understated
• Icons: one set, consistent sizing, restrained use

Color

• Neutral tones dominate — use shadcn's CSS variable system (bg-background, text-foreground, bg-muted, etc.)
• Never hardcode Tailwind color classes (bg-gray-*, bg-white) — this breaks dark mode
• Accent color sparingly and semantically
• Color for meaning, not decoration

Interaction

• Subtle hover/focus/selected/loading/disabled states
• Smooth transitions, never flashy
• Motion reinforces calmness

Anti-patterns

Do not produce any of the following:

• Generic SaaS dashboard energy
• Default shadcn demos shipped as-is
• Dense enterprise admin panel aesthetics
• Excessive borders, cards, badges, dividers, shadows
• Loud gradients, oversaturated surfaces, colorful widgets
• Crowded forms, dense layouts
• Decorative motion, flashy animation
• Large typography jumps for hierarchy
• Too many button styles or component variants
• Card-on-card nesting
• Generic table-heavy admin styling
• Overdesigned marketing energy inside an app

shadcn foundation

shadcn/ui is the component and color baseline. The job is to refine it into the restrained language — not replace it, not ignore it, and definitely not ship it looking stock.

Always use CSS variables for color

shadcn's theming runs through CSS variables in globals.css. This is the color system — and it's what makes dark mode work automatically. Always use the semantic color classes:

✅  bg-background  text-foreground  border-border
✅  bg-muted  text-muted-foreground  bg-primary  text-primary-foreground
✅  bg-card  bg-popover  bg-accent  bg-destructive

❌  bg-gray-100  text-gray-500  border-gray-200  bg-white  text-black

Hardcoded Tailwind color classes (like bg-gray-* or bg-white) break dark mode and bypass the design system. If you need a color, it should come from a CSS variable. The only exception is opacity modifiers on semantic colors when needed (e.g., border-border/50).

Customize the theme variables

The first lever for making shadcn not look like default shadcn is adjusting the CSS variables in globals.css:

• --radius: Reduce for a more restrained feel. 0.375rem or 0.5rem — not 0.75rem.
• --border: Slightly lower contrast than default. Borders should be felt, not seen.
• --primary: Keep it understated. It's an accent, not a shout.
• --muted: This is the workhorse for subtle backgrounds. Make sure it's actually subtle.

Refining components — what "not default" looks like

The second lever is how you compose and style the components themselves.

Card — default vs. refined:

Default shadcn wraps everything in <Card> with <CardHeader> and <CardContent>. Often the card is unnecessary — spacing and typography create the grouping on their own:

tsx
1// Default — card doing nothing structural
2<Card>
3  <CardHeader>
4    <CardTitle>Team Members</CardTitle>
5    <CardDescription>Manage your team and roles.</CardDescription>
6  </CardHeader>
7  <CardContent>...</CardContent>
8</Card>
9
10// Refined — open composition, card removed
11<div className="space-y-4">
12  <div>
13    <h2 className="text-sm font-medium">Team Members</h2>
14    <p className="text-sm text-muted-foreground">Manage your team and roles.</p>
15  </div>
16  <div className="space-y-2">...</div>
17</div>

Use <Card> only when you need explicit containment — a clickable surface, a draggable item, a visually distinct group inside a larger layout.

Button — refinement:

• Tighten padding: h-9 px-3 or h-8 px-3 text-sm feels more restrained than the default h-10 px-4 py-2
• Lean on variant="ghost" and variant="outline" for secondary actions — variant="default" (solid primary) is for the one main action on a screen
• Keep button labels short and sentence case

Table — refinement:

• Reduce row height from default padding — tighter rows read as more refined
• Use text-muted-foreground for secondary columns to create quiet hierarchy
• Subtle hover: hover:bg-muted/50 rather than hover:bg-muted
• Minimal header styling — don't bold everything, don't add background color to the header row

Design tokens

These are starting points for the restrained feel. The point isn't to be rigid — it's to have a baseline that produces consistent, calm output.

Workflow

When building or refining UI, follow this order:

1. Structure — layout, spacing, grouping, alignment
2. Typography — restrained hierarchy, weight over size
3. Component refinement — adapt shadcn into the calm design language
4. Unification — make repeated patterns feel cohesive
5. Noise reduction — strip anything that doesn't earn its place
6. Color — neutral system with semantic accents
7. Interaction — polish states subtly
8. Final check — run the self-review below

Self-review

Score 1–5 on each. Revise until all are 4+.

References

For task-specific copy-paste prompts (build, refinement passes, critiques, one-liners), read: → references/prompt-library.md

For the full system prompt version suitable for injecting into other tools or CLAUDE.md files: → references/system-prompt.md