--- title: "UI patterns" url: https://mdfy.app/wp12y7sM updated: 2026-05-16T14:17:17.723Z source: "demo-seed" --- # UI patterns ## Tailwind 4 conventions - Design tokens live in `globals.css` as CSS variables: `--background`, `--accent`, `--text-primary`, etc. - Use `var(--...)` everywhere. Don't hardcode hex. - Dark mode via `[data-theme="dark"]` on ``. Tokens get re-bound at the document root. ## Component organization ```text components/ ├── atoms/ # Button, Input, Badge — no state, no fetching ├── molecules/ # FormField, Card, Menu — local state OK ├── organisms/ # PageEditor, BlockToolbar — owns fetching └── primitives/ # shadcn/ui exports (rename to mark these as ours) ``` Rule: atoms can be used everywhere. Organisms can't be imported by atoms or molecules — only by pages. ## Form validation Zod schemas live next to the form. `useForm` from React Hook Form. Server validates the SAME schema. Don't trust client validation alone — the API enforces it again. ## Loading states Prefer `` boundaries with skeletons over conditional `isLoading` ternaries. Skeletons match the final layout so the viewport doesn't jump. ## Empty states Every list view has an empty state with: icon + 1-line copy + 1 CTA. Don't ship a blank screen — that's a bug. ## Accessibility - Every `