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 once in tools/tailwind/theme.css as Tailwind v4 custom variants, which every Tailwind build in the workspace (the app, every lib's published utilities, the overlay sandbox, Storybook) imports:

/* tools/tailwind/theme.css */
@custom-variant mobile (@media (max-width: 1279px)); /* ≤1279 px — phones and tablets */
@custom-variant desktop (@media (min-width: 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: — Tailwind's default breakpoints still exist (they come with its default theme) but are out of scope for this project and should not be used.

Scoped menu and right-panel breakpoints

The existing layout boundary stays at 1280px. phone: (<768px), tablet: (768px <= width <1280px), and tablet-up: (>=768px) are approved only for menu presentation and bounded right overlays. Use useIsPhone for sheet versus anchored-menu decisions and useIsTablet for bounded overlays. Do not migrate navigation, conversation panels, forms, editors or page layout to these scoped hooks. Verify 767, 768, 1024, 1279 and 1280px, including an open surface crossing both boundaries.

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: useIsMobile from @epam/ai-dial-chat-shared. 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 builds

No lib carries a Tailwind or PostCSS config. Each publishable lib's vite.config.mts lists createLibTailwindUtilities from tools/vite-lib-tailwind-utilities.mjs, which compiles the classes the lib's own src/** uses against tools/tailwind/theme.css and appends them to dist/index.css. apps/chat scans libs/*/src from its own entry (apps/chat/src/tailwind.css), so a lib class works in the app with no per-lib setup. A new lib that ships Tailwind classes only needs the plugin in its Vite config.

Why one shared theme matters

Libs build their CSS in isolation, and that CSS is what consumers may ultimately ship. A build that did not read the shared theme would:

• compile mobile: / desktop: as unknown variants and silently drop them — responsive utilities authored in the lib disappear from the emitted CSS;
• lose every project token (bg-layer-base, text-primary, the control-* family, shadows), so classes referencing them would emit nothing in any context that does not also run the host app's Tailwind pass over the lib's source.

Re-declaring the theme per lib would duplicate ~150 lines of tokens and drift the next time someone adds a colour. The shared file keeps a single source of truth.

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

The Vite configs import tools/vite-lib-tailwind-utilities.mjs, and the theme is read from tools/tailwind/, outside any Nx project. The @nx/enforce-module-boundaries rule is scoped in eslint.config.mjs to source files only (**/src/**/*.{ts,tsx,js,jsx,…}). Project-root build configs (vite.config.mts, 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.

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 useIsMobile, 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

Verification

For any responsive change:

1. DevTools — exercise the feature at 360 and 900 (mobile/tablet) and 1280, 1920 (desktop)
2. Touch — verify interactive elements work without hover (use the DevTools touch simulator)
3. Unit tests — when a component branches on useIsMobile, add a test per branch by mocking the hook
4. Lint / typecheck — npm exec nx lint chat, npm exec nx test chat for the projects you touched
5. Note in the PR which breakpoints were exercised; a "verified desktop only" change is incomplete

Running a responsiveness check with MCP Playwright

Only run this when the user explicitly asks ("check responsiveness", "verify mobile", "go over screens", etc.). Do not run it proactively after every UI change.

Scope = what the user specifies. If the user names a page or feature, check only that. If they say "current feature", limit scope to the components touched by the current branch. Do not audit the whole app unprompted.

The app at http://localhost:4207 requires Keycloak auth — the MCP browser must log in before screenshots are useful.

Setup

Playwright MCP is pre-configured in .mcp.json — no manual setup needed. It starts automatically with the project.

Audit workflow

1. Navigate to http://localhost:4207 — the browser window opens visibly (Chrome, headed by default)
2. If redirected to Keycloak login, tell the user: "A Chrome window opened — please log in so I can proceed", then wait with mcp__playwright__browser_wait_for (textGone: "Sign in to dial", time: 120)
3. Navigate to the specific page/feature the user asked about (or the one touched by the current branch)
4. For each relevant viewport — 360 and 900 for mobile/tablet, 1280 and 1920 for desktop:
   • mcp__playwright__browser_resize to set width × height
   • Screenshot the specific screen/component under review
   • Run mcp__playwright__browser_evaluate to detect horizontal overflow:

     [...document.querySelectorAll('*')]
       .filter(
         (el) =>
           el.getBoundingClientRect().width >
           document.documentElement.clientWidth + 2,
       )
       .map((el) => ({
         tag: el.tagName,
         cls: el.className?.toString().slice(0, 60),
         w: Math.round(el.getBoundingClientRect().width),
       }))
       .slice(0, 10);

   • On mobile/tablet widths (≤1279), also check touch targets:

     [...document.querySelectorAll('button,a,[role="button"]')]
       .filter((el) => {
         const r = el.getBoundingClientRect();
         return r.width > 0 && (r.width < 44 || r.height < 44);
       })
       .map((el) => ({
         tag: el.tagName,
         text: el.textContent?.trim().slice(0, 30),
         w: Math.round(el.getBoundingClientRect().width),
         h: Math.round(el.getBoundingClientRect().height),
       }))
       .slice(0, 15);

5. Check each screenshot visually using the Read tool (it renders images inline)
6. Report findings grouped by viewport with screenshot paths

Key things to look for

• Horizontal scroll at 360px
• Text overflow / clipping
• Touch targets < 44×44px on mobile
• Sidebar visible on desktop but missing toggle on mobile
• Fixed/sticky elements obscuring content on small screens
• Modals fitting within the viewport

Anti-patterns

• className={isMobile ? 'flex-col' : 'flex-row'} — use flex-col desktop:flex-row instead
• Reading window.innerWidth in render or effects — use useIsMobile
• Hiding mobile UI with display:none while still mounting heavy subtrees — branch with the hook
• Authoring desktop-first and then trying to reset on mobile: — invert it
• Using sm: / md: / lg: / xl: — they are not configured here
• Using small_tablet:, large_tablet:, or large_desktop: — these prefixes do not exist and are silently ignored by Tailwind
• Adding min-[820px]: arbitrary queries — use the named breakpoints in the root config instead
• Implementing a Figma desktop frame without checking whether a mobile variant exists