rules/ui-styling.md
When adding a brand mark for an AI provider (or any well-known SaaS brand), prefer official SVGs over hand-drawn or monogram fallbacks — users expect to see the real logo.
https://unpkg.com/@lobehub/icons-static-svg/icons/<name>.svg<name>-color.svg variant with full-color brand gradients (e.g. gemini-color.svg, qwen-color.svg, minimax-color.svg).https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/<name>.svg.Embed as inline React SVG components (see src/components/ProviderIcon.tsx for the pattern). For SVGs with <linearGradient> defs, hard-coded gradient IDs are fine — browsers resolve url(#id) to the first definition encountered, and multiple instances of the same icon use the same gradient definition, so there's no need to generate per-instance unique IDs.
Use the global .scrollbar-on-hover class (defined in src/styles/globals.css) for thin, hover-only scrollbars in dropdowns, submenus, and popovers. The OS default scrollbar (12px chrome) looks chunky inside small popups — .scrollbar-on-hover collapses to a transparent track and only reveals a thin thumb on hover/focus.
<DropdownMenuSubContent className="w-64 max-h-100 overflow-y-auto scrollbar-on-hover">
...
</DropdownMenuSubContent>
Use MoreHorizontal for compact preview-mode overflow and MoreVertical for
the right-most preview utility/actions menu. This keeps two ellipsis controls in
the same preview header visually distinct.
Version-diff mode replaces the normal preview modes with Preview and Diff. Keep its current-version context and exit action in shared preview chrome so users can leave the mode without first navigating to the Diff panel.
When using html-to-image to capture a scrolled viewport, do not translate or
transform the cloned document root. A transformed ancestor becomes the
containing block for fixed descendants and shifts headers, floating buttons,
and modals; use non-transform layout offsets so fixed UI remains viewport-bound.
Don't put an explicit min-w-* on a flex item whose children are flex-shrink-0 (icon buttons, etc.) if that value is smaller than the children's combined width. An explicit min-width overrides flexbox's content-based minimum, so the item gets squeezed below its content and the overflow paints over sibling elements — visually broken and it intercepts their pointer events (this broke the preview Restart button at narrow widths). Use min-w-fit to let the item refuse to shrink below its content.
The project uses Tailwind v4 (see tailwindcss: ^4.x in package.json). A few v4-specific affordances that don't work in v3:
bg-primary/8, text-muted-foreground/85 — any integer 0–100 works, not just the v3-canonical steps.w-[17rem], size-[3px] — use these for fine-grained tweaks instead of inventing config values.size-* shorthand sets both width and height.When reusing a setup component behind a persistent "Manage setup" entry point, make sure the component can render even after setup is complete. Components like setup banners often self-hide once isAnyProviderSetup() is true; add an explicit force/manage mode and a regression test that clicks the manage affordance and verifies dialog content appears.
To screenshot a redesigned component without driving the full Electron app (which may require onboarding/app state to reach the surface): build a standalone HTML harness using @tailwindcss/browser@4 (CDN) with the app's CSS variables copied from src/styles/globals.css (including the .dark block for dark-mode frames), then screenshot it with the repo's Playwright. Note: import Playwright by absolute path — import { chromium } from "file:///<repo>/node_modules/playwright/index.mjs" — because plain import "playwright" fails with ERR_MODULE_NOT_FOUND when the script lives outside the repo (ESM resolves from the script's location, not cwd); copying the script into the repo before running it works too.
For exact fidelity (real tokens, real utilities), compile the project's own CSS instead of the CDN build. The v4 CLI takes content globs via an @source directive in the CSS, not a --content flag (passing --content silently emits preflight only), and the input file must sit inside the repo so @import resolves:
printf '@import "./src/styles/globals.css";\n@source "/abs/path/harness.html";\n' > .tw-probe.css
npx @tailwindcss/cli -i .tw-probe.css -o /abs/path/out.css # then delete .tw-probe.css
The same probe doubles as a check that a utility actually exists before shipping it — grep the output for the generated rule rather than assuming a class name is valid. Use a fixed-string match so the leading . isn't read as a regex wildcard: grep -F '.-indent-5 {' /abs/path/out.css (the class -indent-5 compiles to the selector .-indent-5).
Related: npm run start:onboarding launches the real app with fresh userData and DYAD_DEV_NODEJS_STATUS=missing to reproduce first-run / Node-missing states.