app-design

# App Design Your job is to build cohesive, distinctive apps — not just correct ones. Add character through intentional design decisions — typography pairing, color emphasis, spatial rhythm, and a clear visual point of view. ## Aesthetic Direction Before building anything, decide the app's tone in one word and its signature detail — the one thing someone notices first. These two choices guide every decision that follows. Pick a tone that is specific and bold, not safe or generic. Examples like editorial, geometric, organic, industrial, playful, or minimal are starting points — don't limit yourself to these. Invent a direction that fits the app's purpose. Then match your execution to your direction — a maximalist direction needs layered effects and rich detail in the code; a minimalist direction needs precise spacing, restraint, and careful typography. Elegance comes from committing to the direction fully, not from adding more. ### Typography Pick fonts that set the app's character — this is one of the strongest signals of intentional design. At minimum choose a characterful `--font-heading` paired with a complementary `--font-base`, ideally from the same foundry or design family. Update `--font-monospace` and `--font-numeric` if necessary. Avoid generic defaults like Arial, Inter, or Roboto. Load fonts via Google Fonts (or another CDN) as `<link>` tags in `packages/frontend/index.html`, then update the font family tokens in the `@theme` block of `global.css`. ### Theming Workflow Start by customizing `packages/frontend/src/global.css` — this is the single source of truth for the app's visual identity. Every component uses these tokens, so setting them first means the entire UI shifts together. 1. **Colors**: Update the semantic color tokens (`--color-primary`, `--color-background`, `--color-card`, `--color-border`, etc.) in both the `@theme` block and the `.dark` override to match the aesthetic direction. The defaults are neutral blue/grey — make them yours. 2. **Radius**: Adjust `--radius` (the base radius) and the radius scale to match the tone — sharp/geometric (lower values), soft/rounded (higher values), or pill-shaped (`--radius-circular`). 3. **Fonts**: Update the font family tokens as described in the Typography section above. 4. **Then build components.** Focus component-level styling on layout, spacing, and element-specific details — not re-specifying colors and radii that the tokens already handle. 5. **Selective overrides last.** After the base theme is in place, inspect and adjust individual components that need to deviate — an accent-colored card border, a button with a unique hover effect, etc. --- Keep these principles in mind: - Use semantic color tokens so surfaces, text, and borders adapt correctly to light and dark mode. - Maintain sufficient contrast between text and backgrounds. - The recommended minimum text size is `text-200`. - Keep spacing consistent — use the spacing tokens from the theme rather than arbitrary values. - Ensure all interactive elements are keyboard-accessible with visible focus indicators and appropriate disabled states. Read these reference files — they include "Make it yours" prompts that tie back to the aesthetic direction above: - [UI Style Recipes](references/ui-style-recipes.md) — per-element styling guidance for buttons, cards, inputs, dialogs, tabs, tooltips, tables, and more. - [Visual Style Recipes](references/visual-style-recipes.md) — chart theming, Vega-Lite config, dark mode chart support, and mark-specific styling. --- ## Establish a runnable shell early Once the source and capabilities are selected, replace the starter/welcome view with an authenticated shell before exhaustive query discovery is complete. Keep the dynamic auth provider and gate intact so both standalone and embedded users sign in before reaching app content. Build the title, navigation, layout, final content regions, responsive behavior, and visual direction with loading states in the places where live content will appear. The shell must stay honest. Do not display invented figures, synthetic completion, or source-backed labels that have not been verified. As each real query or operation is validated, integrate its exact result shape into the corresponding region. ## App Layout These are good defaults for app structure. Adapt them to the specific app's needs. ### Page Structure - The app layout should fill the viewport. - On wide screens, constrain the content width so it doesn't stretch uncomfortably. Use responsive breakpoints or multi-column layouts to make good use of available space. Don't default to the same layout every time. The structure should serve the aesthetic direction — a sidebar + main content split, a full-width single column, a multi-panel master-detail, an asymmetric split, or something else entirely. These are starting points, not an exhaustive list. Invent a layout that fits the app's purpose and tone. The header/toolbar is part of the design language — not every app needs a traditional fixed header. Consider alternatives: a floating command bar, a compact inline toolbar, a branded banner, a collapsible drawer, a minimal top-right action cluster, or no header at all if the content speaks for itself. ### Container Sizing `VegaVisual` and other content components fill their container — the **container controls their dimensions**. Without constraints, charts and content stretch to the full viewport width, which produces squished, unreadable visuals on wide screens. - **Constrain the dashboard wrapper, not individual charts.** Apply a max-width to the outermost content wrapper that holds the dashboard. This single constraint keeps the entire layout proportional on wide monitors. If the app lacks an outer wrapper, create one. - **Do not constrain individual chart containers.** Let the wrapper width plus grid columns determine each chart's size naturally. - If the user explicitly requests full-width charts, confirm the design choice before proceeding. ### Dashboard Grid - Start mobile-first and scale up columns with responsive breakpoints. - Support mixed-size cards via span utilities. Avoid uniform grids where every card is the same size — they look like a spreadsheet. Vary card spans to create visual hierarchy: a wide chart spanning two columns next to a tall narrow KPI panel, or a full-width table below a row of smaller cards. Let the data importance guide which elements get more space. ### Loading, Empty & Error States Every component that depends on async data should handle all three states: | State | What to show | |---|---| | **Loading** | A skeleton matching the expected content, or a calm connecting state for a documented transient backend condition | | **Empty** | A centered muted message explaining no data is available | | **Error** | An actionable, sanitized error that does not expose provider internals | Do not leave authentication, permission, configuration, or query errors in loading. Retry only a known transient condition, use a bounded attempt count, and transition to the error state if it persists. ### Dark Mode Include a light/dark mode toggle in the app header or toolbar. Use the `useAppTheme` hook from `@/hooks/use-theme` to read and toggle the theme. --- ## Coding Conventions - **Styling**: Tailwind CSS v4 utility classes for all styling. Theme colors are defined as CSS custom properties in `packages/frontend/src/global.css` using `@theme`. Use Tailwind classes directly in JSX. - **Theming**: Light/dark color tokens defined in `packages/frontend/src/global.css` via CSS custom properties. Dark mode uses the `.dark` class on the root `html` element, auto-detected via `prefers-color-scheme`, `data-appearance` attribute, or `.dark` class. The `useAppTheme` hook in `packages/frontend/src/hooks/use-theme.ts` manages the toggle. - **CSS class merging**: Use `cn()` from `@/lib/utils` (powered by `clsx` + `tailwind-merge`) to conditionally combine Tailwind class names. - **Icons**: Lucide React for UI icons. - **UI Components**: Use Radix primitives with Tailwind CSS styling for all interactive elements — buttons, inputs, dialogs, menus, tabs, etc. ### UI Token Rules All styling must use the design tokens defined in `packages/frontend/src/global.css` via Tailwind utility classes. Never hardcode raw color values, pixel sizes, or font stacks — raw values are only permitted in `global.css` where the tokens are defined. Refer to `global.css` for available tokens, their values, and expected usage. Examples: - `bg-primary text-primary-foreground` — not `bg-blue-600 text-white` - `text-300` — not `text-sm` or `text-[14px]` - `p-400 gap-300` — not `p-4` or `gap-3` - `font-semibold` — not `font-[600]` - `rounded-xl` — not `rounded-[8px]` - `icon-size-200` — not `w-4 h-4` **`cn()` and tailwind-merge conflicts:** `tailwind-merge` treats `text-*` utilities as one conflict group. In `cn()`, combining text size and text color with ambiguous `text-*` classes can drop one class. Prefer explicit length syntax for font size (e.g., `text-[length:var(--text-300)]`) when combining with text color classes inside `cn()`. If classes are static and not merged, `text-300 text-foreground` is acceptable. **Form element font inheritance:** Native form controls may not inherit the page font family by default. Ensure base styles in `global.css` set `font-family: inherit` for `select`, `input`, `textarea`, and `button`. --- ## Final Audit After assembling a layout, audit each element in its actual context — not in isolation. A component may look correct on its own but break the visual rhythm of the page. Check: Is every text legible? Are labels proportional to their controls? Are toolbar rows aligned on a shared edge? Do charts fill their containers? Do repeated elements (badges in tables, icons in lists) maintain appropriate visual weight for their density? Fix anything that fails.