Responsive Design

Responsive design

Overview

The chat app must render correctly on mobile/tablet (≤1279px) and desktop (≥1280px). Desktop is the historical baseline — most existing code is desktop-only. Treat mobile-first as the authoring default for new and changed UI: write the base classes for the smallest supported viewport and add desktop overrides via desktop:.

Project breakpoints

Defined in tailwind.config.js (extend.screens) and inherited by all lib Tailwind configs via preset:

// tailwind.config.js — extend.screens
mobile: { max: '1279px' },  // ≤1279 px — phones and tablets
desktop: { min: '1280px' }, // ≥1280 px — laptops and monitors

desktop: is a min-width prefix — styles cascade upward to all wider viewports.

Do not use small_tablet:, large_tablet:, large_desktop: — these prefixes are not in the config and Tailwind will silently ignore any class that uses them.

Do not use sm: / md: / lg: / xl: — the default Tailwind breakpoints exist in the config (via extend) but are out of scope for this project and should not be used.

When to use Tailwind prefixes vs. a JS hook

Default: Tailwind utility prefixes. They are SSR-safe, avoid first-paint flicker, and keep layout decisions in markup.

<aside className="hidden desktop:block">…</aside>
<button className="h-12 mobile:h-14">…</button>

Escape hatch: useBreakpoint / useIsMobile from apps/chat/src/hooks/breakpoint/useBreakpoint.ts. Reach for these only when:

• A component must mount entirely different subtrees per breakpoint (e.g. drawer vs. persistent sidebar) and a CSS-only hidden/block swap would still mount both
• An effect or imperative handler needs to branch on viewport size (focus, autoplay, virtualisation row count)
• A third-party component accepts a prop that toggles its mobile layout

Never call window.matchMedia directly inside components — go through the hook so the SSR fallback, listener cleanup, and breakpoint names stay consistent.

Library Tailwind configs

apps/chat/tailwind.config.js presets the root config and so inherits the named breakpoints. The component libs (libs/conversation-input, libs/conversation-messages, and any future libs/* that ships Tailwind classes) must also presets: [require('../../tailwind.config.js')]:

module.exports = {
  presets: [require('../../tailwind.config.js')],
  content: [join(__dirname, 'src/**/*.{ts,tsx}')],
};

Why presetting matters

Libs build their own CSS in isolation (via vite build on the lib) and that CSS is what consumers may ultimately ship. Without the preset, an isolated lib build:

• compiles mobile: / desktop: as unknown prefixes and silently drops them — responsive utilities authored in the lib disappear from the emitted CSS;
• loses every project token (bg-layer-1, text-primary, the entire controls-* family, fonts, shadows) because those live on the root config's theme — classes referencing them fall back to Tailwind defaults, which means the lib ships visibly wrong colors in any context that does not also run the host app's Tailwind pass over the lib's source.

Re-declaring the theme inline per lib would duplicate ~150 lines of tokens and introduce silent drift the next time someone adds a colour to the root config. The preset keeps a single source of truth.

Why this is allowed by @nx/enforce-module-boundaries

The require('../../tailwind.config.js') import crosses the Nx project boundary into the workspace root — exactly the kind of import the @nx/enforce-module-boundaries rule normally rejects. We do not punch a per-path allow hole for it. Instead, the rule is scoped in eslint.config.mjs to source files only (**/src/**/*.{ts,tsx,js,jsx,…}). Project-root build configs (tailwind.config.js, vite.config.ts, eslint.config.mjs) are workspace-level tooling, not application source code, so the boundary rule does not police them — which matches what that rule was designed to enforce. If you add a new lib that ships Tailwind classes, just author its tailwind.config.js with the same preset; no eslint changes are needed.

This tooling exception does not weaken source-code isolation. Hand-authored files under libs/*/src must still avoid host-owned integration knowledge (API/server-api/generated-client/auth/session/env/ feature flags/routing/storage/analytics/telemetry/SDKs/platform bridges/etc.) and receive app behavior through props, callbacks, or resolved values. libs/chat-api-client/src/generated is the generated OpenAPI-client exception.

Mobile-first authoring checklist

When implementing or modifying a component:

• Base classes describe the mobile layout — overrides target larger breakpoints
• Touch targets are at least 44×44 CSS px on mobile (use mobile: to bump a desktop-sized control when needed)
• No horizontal scroll at 360px width (test in DevTools device emulation)
• Long text wraps (break-words / min-w-0 on flex children) rather than overflowing
• Modals, popovers, and dropdowns are reachable and dismissable on touch (no :hover-only affordances)
• Inputs use the correct inputmode / type so mobile keyboards show the right layout
• Sticky and fixed elements account for mobile browser chrome (dvh/svh over vh when relevant)
• Conditional layouts that swap components use useBreakpoint, not window.innerWidth reads
• If the change adds new strings, they fit at 360px without truncation in the supported locales

Figma alignment

When a Figma file has separate mobile and desktop frames:

1. Fetch both frames in the design context call — never implement one without inspecting the other
2. If the design provides only desktop, ask before deriving a mobile version; do not guess
3. Map Figma's responsive frame sizes to the closest named breakpoint (375/390/768/820/900 → mobile ≤1279px, 1280+ → desktop)
4. Capture the divergences (drawer vs. sidebar, vertical vs. horizontal toolbar, hidden sections) before writing code; these drive whether you need the hook