Run any Skill in Manus with one click

mobile-ui-scaling

Stars17

Forks0

UpdatedJuly 23, 2026 at 10:56

How to correctly make UI scale on mobile in this project. The app scales every UI screen with the external ScalableContainer (@vibegameengine/ui-scaler): content is authored in a fixed logical `targetWidth` and shrunk by `transform: scale(min(1, innerWidth/targetWidth))`. On a phone a desktop-width target collapses the UI to ~30% (tiny, unreadable). The ONE correct fix is a DYNAMIC targetWidth per device via the shared `useResponsiveTargetWidth` hook — never remove the scaler, never patch it with per-element `transform: scale(N)` compensation, never invent a new scaling system. MANDATORY whenever a screen is "too small / doesn't scale / broken on mobile", when touching `targetWidth`, ScalableContainer, a HUD/menu/overlay on mobile, or any responsive UI work. Trigger on: "mobile UI", "doesn't scale on phone", "too small on mobile", "targetWidth", "ScalableContainer", "adaptive UI", "responsive", "portrait", "HUD too big/small on mobile", "меню не скейлится", "плашка на мобилке".

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

vibegameengine

vibegameengine/web-starter-kit

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Web and Digital Interface DesignersComputer and Mathematical Occupations·SOC 15-1255

SKILL.md

readonly

name

mobile-ui-scaling

description

Mobile UI scaling — dynamic targetWidth, verified by eye

The system (do NOT replace it)

Every UI screen is wrapped in ScalableContainer from @vibegameengine/ui-scaler. It renders one position:absolute; transform-origin:top-left div, sizes its logical canvas to targetWidth, and applies scale = min(1, window.innerWidth / targetWidth) (it only ever scales DOWN, never up). UI is authored in large logical px (menu 1448, HUD 1280) and shrunk to fit.

This is the project's scaling system. Keep it. Do not rip out ScalableContainer, do not rewrite screens as bespoke @media/rem layouts, do not add a second scaler.

The one correct fix

A screen that is "too small / doesn't scale" on a phone has a desktop targetWidth hardcoded. On a 390px phone scale = 390/1280 ≈ 0.30, so everything is 30% size. Fix it by making targetWidth dynamic per device — a smaller target on a narrow portrait phone keeps the on-screen scale near 1, so the UI fills the screen and stays legible.

Use the shared hook — never duplicate the logic, never hardcode:

import { useResponsiveTargetWidth } from '../../../shared/lib/ui-scale/useResponsiveTargetWidth'

const targetWidth = useResponsiveTargetWidth({ desktop: 1448, mobilePortrait: 640 })
// ...
<ScalableContainer targetWidth={targetWidth} zIndex={2}>

src/shared/lib/ui-scale/useResponsiveTargetWidth.ts picks mobilePortrait when innerWidth <= 720 && innerHeight >= innerWidth, else desktop, and reacts to resize / orientationchange.

Per-screen values

Only shrink the target where the screen is genuinely broken. A screen that already looks right on mobile keeps mobilePortrait === desktop (identical to before) — the hook stays for consistency but changes nothing.
Current production values: main menu { desktop: 1448, mobilePortrait: 640 } (was collapsing → now fills the screen); combat HUD { desktop: 1280, mobilePortrait: 1280 } (was already correct → left identical). See src/app/ui/main-menu/MainMenuScreen.tsx and src/features/combat/ui/GameHud/GameHud.tsx.
A screen with more elements (HUD) needs a larger mobile target than a sparse one (menu); tune the number by eye, not by formula.

Forbidden (these are the "костыли с обратным scale")

❌ Per-element compensation like .defeat { transform: scale(2) } to "un-shrink" one panel. If a panel is too small, the whole screen's targetWidth is wrong — fix the target, delete the hack.
❌ Removing ScalableContainer / replacing the transform-scale system.
❌ Duplicating computeMenuTargetWidth-style logic in a screen. Use the shared hook.

Runtime is scale-independent (no logic changes needed)

Touch/combat input does NOT depend on the scale factor: virtual sticks report unit direction vectors, and every world raycast / tap goes through the canvas rect, which is a full-window sibling of the scaler (outside the transform). Self-derived scale fields in InventoryGridPanel / MerchantStockGrid / VirtualStick collapse to 1 and stay correct. Changing targetWidth is a visual-only change.

MANDATORY verification — by eye, headed, both states

Per AGENTS.md #1, never claim a mobile layout "looks right" from tsc/build/code.

Capture a reference BEFORE you change anything. Screenshot the current (correct or broken) screen on a mobile viewport first, so you can compare after. Skipping this is the #1 mistake — you cannot match "identical to before" without it.
Drive a headed browser (chromium.launch({ headless: false }), never headless) against the already-running dev server on :5173 (never kill/restart it — see never-kill-dev-server). Mobile viewport, e.g. { width: 390, height: 844 }, isMobile: true, hasTouch: true.
Reach the real screen:
- Menu: http://localhost:5173/
- Combat HUD: http://localhost:5173/play?class=ember (bare /play renders nothing — it needs ?class=). Wait for canvas + ~12s for the dungeon + HUD.
- The death plaque (!alive && encounterStatus === 'defeat') only draws after a real defeat; confirm on device or force the state for one dev frame.
Screenshot into docs/shots/, open the image and look. Compare against the reference. Verify mobile fills/reads correctly AND desktop (e.g. 1440×900) is unchanged.

Save artifacts in-repo

Verification shots → docs/shots/. Throwaway Playwright scripts run from the repo root (so node_modules resolves) and are deleted after.

Related: memory mobile-scale-dynamic-targetwidth; skills patch9-ui (box-driven chrome already follows element size), ui-kit-architecture, fsd-ecs-architecture.

More from this repository

same repository

visual-verification-gate

vibegameengine/web-starter-kit

Define and execute visual acceptance before, during, and after any task that can change rendered UI, game scenes, 3D assets, animation, responsive layout, or browser behavior. Use before editing a visual surface, for redesigns that must be proven in an isolated lab before integration, after visual feedback, and before claiming a visual result complete.

2026-07-2317

alpha-atlas-semantic-slicing

vibegameengine/web-starter-kit

Slice transparent UI atlases into production PNGs through alpha connected-components, geometric clustering, and an explicit semantic review. Use when an atlas has a keyed/transparent background, when manual crop coordinates are unreliable, when UI parts must be identified before slicing, or when an agent needs to inventory every atlas element before building UI.

2026-07-2317

asset-optimization-pipeline

vibegameengine/web-starter-kit

How build-time asset optimization works in this project and how to extend it. Every asset (image, audio, 3D model) is shrunk at build time by a dedicated Vite plugin in `vite/`, and every asset reachable from the entry graph is auto-collected into `virtual:bootstrap-assets` and preloaded by the bootstrap gate — no hand-written manifest. Enforces the shared plugin shape (resolveId tag → load repack → emit/serve, per-import `?…` query opt-out/tuning, closeBundle savings report) and the registry wiring (ASSET_EXTENSIONS + kind). MANDATORY before: adding/importing a `.glb`/`.gltf`/image/audio asset, adding a new asset TYPE, changing texture/audio/image compression, touching the preloader weighting, or writing a new `vite/*OptimizerPlugin.ts`. Trigger on: "optimize assets", "compress texture/model/audio", "GLB import", "glTF", "gltf-transform", "reduce bundle/asset size", "preloader", "loading bar", "virtual:bootstrap-assets", "why is my asset not preloaded", "add asset type", "assetsInclude", "asset pipeline", "?

2026-07-2317

fixed-tick-gameplay

vibegameengine/web-starter-kit

Keep all gameplay logic independent from render FPS. Use for any work on player input, movement, combat, abilities, cooldowns, enemy AI, projectiles, damage, loot, encounter state, animation timing, cameras, `useFrame`, frame-rate caps, fixed ticks, simulation clocks, replay, interpolation, or multiplayer snapshots in this project. Applies to system designers and programmers.

2026-07-2317

fsd-ecs-architecture

vibegameengine/web-starter-kit

Where every file goes in this project's src/ and how to work in it. The codebase is Feature-Sliced Design (FSD) layers + a Unity-style ECS. ECS mapping: an ENTITY is a React component that IS a game being (features/slice/entities/*.tsx); a COMPONENT is a React hook you attach to any entity (features/slice/components/use*.ts); a SYSTEM is pure framework-free logic (features/slice/systems/*.ts). MANDATORY before adding, moving, or renaming any file under src/ — new entity, hook, system, screen, scene, feature, shared util, asset, or route. Enforces: correct layer placement, relative imports (no path aliases), deep cross-slice imports (barrels only for a feature's public screen), the app/scenes/features/shared layering, and DEV-only debug routes for lab/dead code. Trigger on: "where do I put", "add a feature", "add an entity / component / system", "new screen", "new scene", "new route", "folder structure", "FSD", "ECS", "how is src organized", "import from another feature", "where does this hook go".

2026-07-2317

reference-to-3d

vibegameengine/web-starter-kit

Reconstruct Blender models from supplied reference sheets, branding templates, texture atlases, orthographic front/side/back/top views, or mascot/logo art where visual fidelity to the source is more important than a plausible generated object. Use when the user says the model must match a template, wireframe, texture pack, character sheet, mascot sheet, or brand asset exactly; also use after feedback like "does not look like the reference", "fit the texture 1:1", "wrong number of visible parts", or "compare against the template". Requires Blender MCP plus local Python with Pillow/OpenCV/numpy; pairs with blender-uv-texturing, wireframe-to-3d, blender-modeling, blender-materials, and blender-export.

2026-07-2317

name

mobile-ui-scaling

description

Mobile UI scaling — dynamic targetWidth, verified by eye

The system (do NOT replace it)

This is the project's scaling system. Keep it. Do not rip out ScalableContainer, do not rewrite screens as bespoke @media/rem layouts, do not add a second scaler.

The one correct fix

Use the shared hook — never duplicate the logic, never hardcode:

import { useResponsiveTargetWidth } from '../../../shared/lib/ui-scale/useResponsiveTargetWidth'

const targetWidth = useResponsiveTargetWidth({ desktop: 1448, mobilePortrait: 640 })
// ...
<ScalableContainer targetWidth={targetWidth} zIndex={2}>

src/shared/lib/ui-scale/useResponsiveTargetWidth.ts picks mobilePortrait when innerWidth <= 720 && innerHeight >= innerWidth, else desktop, and reacts to resize / orientationchange.

Per-screen values

Only shrink the target where the screen is genuinely broken. A screen that already looks right on mobile keeps mobilePortrait === desktop (identical to before) — the hook stays for consistency but changes nothing.
Current production values: main menu { desktop: 1448, mobilePortrait: 640 } (was collapsing → now fills the screen); combat HUD { desktop: 1280, mobilePortrait: 1280 } (was already correct → left identical). See src/app/ui/main-menu/MainMenuScreen.tsx and src/features/combat/ui/GameHud/GameHud.tsx.
A screen with more elements (HUD) needs a larger mobile target than a sparse one (menu); tune the number by eye, not by formula.

Forbidden (these are the "костыли с обратным scale")

❌ Per-element compensation like .defeat { transform: scale(2) } to "un-shrink" one panel. If a panel is too small, the whole screen's targetWidth is wrong — fix the target, delete the hack.
❌ Removing ScalableContainer / replacing the transform-scale system.
❌ Duplicating computeMenuTargetWidth-style logic in a screen. Use the shared hook.

Runtime is scale-independent (no logic changes needed)

MANDATORY verification — by eye, headed, both states

Per AGENTS.md #1, never claim a mobile layout "looks right" from tsc/build/code.

Capture a reference BEFORE you change anything. Screenshot the current (correct or broken) screen on a mobile viewport first, so you can compare after. Skipping this is the #1 mistake — you cannot match "identical to before" without it.
Drive a headed browser (chromium.launch({ headless: false }), never headless) against the already-running dev server on :5173 (never kill/restart it — see never-kill-dev-server). Mobile viewport, e.g. { width: 390, height: 844 }, isMobile: true, hasTouch: true.
Reach the real screen:
- Menu: http://localhost:5173/
- Combat HUD: http://localhost:5173/play?class=ember (bare /play renders nothing — it needs ?class=). Wait for canvas + ~12s for the dungeon + HUD.
- The death plaque (!alive && encounterStatus === 'defeat') only draws after a real defeat; confirm on device or force the state for one dev frame.
Screenshot into docs/shots/, open the image and look. Compare against the reference. Verify mobile fills/reads correctly AND desktop (e.g. 1440×900) is unchanged.

Save artifacts in-repo

Verification shots → docs/shots/. Throwaway Playwright scripts run from the repo root (so node_modules resolves) and are deleted after.

Related: memory mobile-scale-dynamic-targetwidth; skills patch9-ui (box-driven chrome already follows element size), ui-kit-architecture, fsd-ecs-architecture.