BoardUI's design rules for coding agents, kept in sync by npx boardui init.

BoardUI design rules

This project uses BoardUI (React + Tailwind CSS v4, source-owned components under components/). These rules always apply when writing UI code. MCP tools are on demand; these rules are not optional context.

Components first

• Before hand-building any UI element, check for an installed BoardUI component under components/base/ and components/application/, and prefer it.
• Missing a component? Install it (BoardUI MCP install_components, or npx boardui@latest add <name>) instead of writing a lookalike.
• Import through the @/ alias, e.g. import { Button } from "@/components/base/buttons/button".

Color: semantic tokens only

• Never use raw palette classes (text-gray-500, bg-white, border-neutral-200) or hex/oklch literals. Every color rides a BoardUI semantic token, which also makes dark mode automatic.
• Text: text-text-primary, text-text-secondary, text-text-tertiary, text-text-placeholder, errors text-text-error-primary.
• Surfaces: bg-background-primary-default, bg-background-secondary-default / -hover, bg-background-tertiary-default, page ground bg-background-full.
• Borders: border-border-button-default / -hover, hairlines border-separator-border, tables border-border-table, errors border-border-error-default.
• Icons: text-foreground-icon-primary through text-foreground-icon-quaternary.
• Charts: the chart-1 … chart-5 tokens (plus -active variants). CTAs and selection states: the accent-50 … accent-950 ramp.
• Dark mode flips tokens via the .dark class on <html>. Do not write dark: overrides with raw colors; if a token pair looks wrong in dark mode, pick a different token, not a literal.

Typography: composite utilities only

• Use BoardUI's composite type utilities: text-title-1-medium, text-title-2-medium, text-title-3-semibold, text-headline-medium, text-body-medium, text-body-regular, text-body-2-*, text-caption-1-semibold, and friends. Each sets size, weight, line-height, and letter-spacing together.
• Never rebuild type by stacking text-sm font-medium leading-5; if a style seems missing, look in styles/typography.css before inventing one.

Spacing and shape

• Stay on Tailwind's spacing scale (gap-2, p-4, mt-6); prefer flex/grid gap over per-child margins. Arbitrary values (p-[13px]) only when matching an existing BoardUI component exactly.
• Cards and panels: rounded-3xl with border-border-button-default. Inputs and menu rows: rounded-md to rounded-xl. Pills: rounded-full.

Mechanics

• Direction: wrap the app (or a mixed-language region) in DirectionProvider from @/components/foundations/direction/direction, with an explicit BCP 47 locale (ar, he, en-US, zh-CN). Set matching lang and dir on <html> for full-app RTL. CSS dir alone does not configure React Aria keyboard navigation or portal placement. Use useDirection() for custom interactions and put its value on custom portal roots.
• Use logical styles: ms/me, ps/pe, start/end, text-start/text-end, border-s/border-e, rounded-s/rounded-e, and inline logical CSS properties. Mirror navigation/disclosure glyphs and horizontal drawer motion in RTL. Preserve physical coordinates for measured geometry, charts, canvas, and decorative art. Keep code, OTP digits, email addresses and URLs in explicit LTR regions; isolate mixed text with <bdi> or dir="auto". Translating labels and formatting application data is separate from layout direction. See https://www.boardui.com/rtl.
• Internal vertical scroll regions must soften the top edge with a progressive blur and surface fade once scrolled, rather than sharply clipping content. Keep headers outside the scroll region. Use a stationary, pointer-events-none, aria-hidden overlay in a relative wrapper: a 24px masked 1px backdrop blur, a 16px masked 4px backdrop blur, and a gradient from the enclosing semantic surface token to transparent. Ramp each layer's opacity from 0 to 1 over the first 24px of scrolling; keep it invisible at scrollTop 0. Apply opacity to the individual layers, never the overlay parent (a translucent parent creates a backdrop root and can break blur at normal browser zoom). Verify top/reset, overflow, light/dark mode, and 100% zoom; preserve keyboard scrolling and do not blur the whole content area.
• Merge classes with cx() from @/utils/cx (tailwind-merge aware of BoardUI's composite text styles). No string concatenation, no plain clsx.
• Icons come from @remixicon/react, passed as component references (leadingIcon={RiAddLine}), not rendered elements.
• Form components build on react-aria-components; extend the installed BoardUI form components rather than raw <input>/<select>.
• Focus states: outline-none focus-visible:ring-2 focus-visible:ring-border-focus-ring.

When unsure about a token, a component's API, or working example code, ask the BoardUI MCP server: get_theme, get_component, get_usage_examples.