baseline-ui

name	baseline-ui
description	Enforces an opinionated UI baseline to prevent AI-generated interface slop.

Baseline UI

Enforces an opinionated UI baseline to prevent AI-generated interface slop.

How to use

• /baseline-ui Apply these constraints to any UI work in this conversation.

• /baseline-ui <file> Review the file against all constraints below and output:

  • violations (quote the exact line/snippet)
  • why it matters (1 short sentence)
  • a concrete fix (code-level suggestion)

Stack

• MUST treat DESIGN.md in the repo root as the visual source of truth when it exists
• MUST prefer project design tokens from DESIGN.md over generic Tailwind defaults
• MUST use motion/react (formerly framer-motion) when JavaScript animation is required
• SHOULD use tw-animate-css for entrance and micro-animations in Tailwind CSS
• MUST use cn utility (clsx + tailwind-merge) for class logic

Components

• MUST use the project’s existing shadcn/ui components first (src/components/ui/*)
• MUST add missing primitives via shadcn component generation instead of hand-rolling keyboard/focus logic
• MUST use shadcn chart patterns for data visualization when charts are needed
• NEVER mix primitive systems within the same interaction surface
• NEVER introduce a second primitive library when a shadcn component is available
• MUST add an aria-label to icon-only buttons
• NEVER rebuild keyboard or focus behavior by hand unless explicitly requested

Interaction

• MUST use an AlertDialog for destructive or irreversible actions
• SHOULD use structural skeletons for loading states
• NEVER use h-screen, use h-dvh
• MUST respect safe-area-inset for fixed elements
• MUST show errors next to where the action happens
• NEVER block paste in input or textarea elements

Animation

• NEVER add animation unless it is explicitly requested
• MUST animate only compositor props (transform, opacity)
• NEVER animate layout properties (width, height, top, left, margin, padding)
• SHOULD avoid animating paint properties (background, color) except for small, local UI (text, icons)
• SHOULD use ease-out on entrance
• NEVER exceed 200ms for interaction feedback
• MUST pause looping animations when off-screen
• SHOULD respect prefers-reduced-motion
• NEVER introduce custom easing curves unless explicitly requested
• SHOULD avoid animating large images or full-screen surfaces

Typography

• MUST follow the typography system in DESIGN.md when present
• MUST use text-balance for headings and text-pretty for body/paragraphs
• MUST use tabular-nums for data
• SHOULD use truncate or line-clamp for dense UI
• NEVER modify letter-spacing (tracking-*) unless explicitly requested

Layout

• MUST use a fixed z-index scale (no arbitrary z-*)
• SHOULD use size-* for square elements instead of w-* + h-*

Performance

• NEVER animate large blur() or backdrop-filter surfaces
• NEVER apply will-change outside an active animation
• NEVER use useEffect for anything that can be expressed as render logic

Design

• MUST use the Chai design language from DESIGN.md when present: warm parchment canvas, bark text, border-first surfaces, IBM Plex Sans, and restrained orange emphasis
• MUST follow the theme model from DESIGN.md when present: Light, Dark, Chai, and System
• MUST treat Chai as a separate opt-in theme, not as the default meaning of dark
• MUST ensure System resolves to standard Light/Dark behavior and never silently maps to Chai
• MUST keep theme pickers in the order Light, Dark, Chai, System when all are exposed
• NEVER use gradients unless explicitly requested
• NEVER use purple or multicolor gradients
• NEVER use glow effects as primary affordances
• SHOULD use the shadow system defined in DESIGN.md when present instead of Tailwind default shadow assumptions
• MUST give empty states one clear next action
• SHOULD limit accent color usage to one per view
• SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones
• MUST ensure selected navigation states and text selection remain high-contrast and readable