diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 85fb9bb244..b2c3765d2f 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -2804,7 +2804,7 @@ In the case of multiple pages in a single browser, each page can have its own vi
 [`method: Browser.newContext`] allows to set viewport size (and more) for all pages in the context at once.
 
 `page.setViewportSize` will resize the page. A lot of websites don't expect phones to change size, so you should set the
-viewport size before navigating to the page.
+viewport size before navigating to the page. [`method: Page.setViewportSize`] will also reset `screen` size, use [`method: Browser.newContext`] with `screen` and `viewport` parameters if you need better control of these properties.
 
 ```js
 const page = await browser.newPage();
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 0f6966791a..d8f18e305c 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -3111,6 +3111,9 @@ export interface Page {
    *
    * `page.setViewportSize` will resize the page. A lot of websites don't expect phones to change size, so you should set the
    * viewport size before navigating to the page.
+   * [page.setViewportSize(viewportSize)](https://playwright.dev/docs/api/class-page#page-set-viewport-size) will also reset
+   * `screen` size, use [browser.newContext([options])](https://playwright.dev/docs/api/class-browser#browser-new-context)
+   * with `screen` and `viewport` parameters if you need better control of these properties.
    *
    * ```js
    * const page = await browser.newPage();