Pixel‑Perfect Layout Adaptation for Mobile H5 Using vw Units and postcss-px-to-viewport

This article is the second part of the "H5 Must‑Know" series and discusses how to faithfully, pixel‑level restore design drafts when constructing page layouts for H5 (HTML5) embedded in mobile apps.

The author, Li Songfeng, is a senior front‑end engineer at 360 and a member of the W3C AC delegation.

Preface

In China, "H5" is commonly used to refer to web pages embedded inside mobile apps, not just the abbreviation for HTML5. Designers, product managers, Android/iOS developers, and back‑end engineers all understand this term.

Mobile web pages run inside a mobile browser or a WebView and can access device hardware (GPS, accelerometer, gyroscope) and host‑app JavaScript SDKs for features such as login, photo upload, and sharing.

Mobile layouts must follow native UI guidelines (Material Design, Human Interface Guidelines) and use the same components, fonts, colors, and interaction patterns as native apps, including touch‑based interactions.

Because mobile H5 pages are often part of hybrid apps, they need to interoperate with native code through well‑defined interfaces.

Adaptation and Restoration: Concept Explanation

Adaptation starts with two dimensions: pixel density and screen size.

Adapting to different pixel densities (e.g., @3x, @2x, @1x).

Adapting to different screen sizes.

For pixel density, a CSS pixel may correspond to multiple physical pixels. For example, iPhone Xs Max uses a 3× density (1 CSS pixel = 9 physical pixels), while iPhone XR uses a 2× density (1 CSS pixel = 4 physical pixels).

To avoid image distortion on high‑density screens, the image resolution should match the physical pixel count (e.g., [email protected] for @3x screens).

The key to restoring a design draft is to keep the layout measurements proportional to the screen width. Assuming a design width of 750 px, a component that is 690 px wide occupies 92 % of the screen, and a 30 px margin occupies 4 %.

By converting these pixel values to percentages (or a viewport‑relative unit) and letting the browser render them, the component will appear at the same proportion on any screen size.

A Global CSS Unit

Using plain percentages is not sufficient because most CSS properties reference the containing block, not the viewport width. A global unit that directly references the viewport is needed.

The rem unit equals the computed font‑size of the root html element. By dynamically setting the root font‑size based on screen width, rem can be used for proportional scaling.

A more straightforward unit is vw , which equals 1 % of the initial viewport width. Thus 92vw directly represents 92 % of the screen width, and 4vw represents a 4 % margin.

Both iOS 8+ and Android 4.4+ fully support vw , making it a reliable choice for mobile layout adaptation.

Using postcss-px-to-viewport

The postcss-px-to-viewport plugin can automatically convert px values in CSS to vw based on a configured design width (750 px in this article).

module.exports = {
  "plugins": {
    // ... other plugins
    "postcss-px-to-viewport": {
      viewportWidth: 750,
      viewportHeight: 1334,
      unitPrecision: 3,
      viewportUnit: 'vw',
      selectorBlackList: ['.usepixel'],
      minPixelValue: 1,
      mediaQuery: false
    }
    // ... other plugins
  }
};

Key configuration options:

viewportWidth : width of the design draft.

viewportHeight : arbitrary height.

unitPrecision : number of decimal places kept.

viewportUnit : target unit ( vw ).

selectorBlackList : selectors that should not be converted.

minPixelValue : minimum pixel value to convert.

mediaQuery : whether to convert pixels inside media queries.

Example component CSS before conversion:

section.card {
  margin: 0 auto;
  margin-bottom: 20px;
  background-color: #fff;
  border-radius: 10px;
  box-shadow: 0 6px 6px 0 rgba(0,0,0,0.02);
  text-align: center;
  padding: 38px 70px 46px;
  font-weight: 300;
}

After running the plugin, all px values become vw values that preserve the original design proportions.

Conclusion

The article covered two main aspects of achieving high‑fidelity design restoration for mobile H5: understanding adaptation (pixel density and screen size) and using a global CSS unit ( rem or, more conveniently, vw ) to scale layouts proportionally. It also introduced the postcss-px-to-viewport plugin to automate the px ‑to‑ vw conversion, completing the pixel‑perfect workflow.