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

This is the second article in the "H5 Must‑Know" series, focusing on how to faithfully reproduce design mockups when constructing page layouts for mobile H5 pages.

In China, "H5" refers to HTML5 pages embedded inside native apps, a term understood by product managers, designers, Android/iOS developers, and backend engineers alike.

Mobile web differs from desktop web in three main ways: it runs inside a mobile browser or WebView and can access device sensors and host‑app APIs; it must follow native UI guidelines (Material Design, Human Interface Guidelines); and it often forms part of a hybrid app, requiring coordinated interaction between H5 and native code.

Adaptation and Restoration

Adaptation has two dimensions: pixel‑density adaptation and screen‑size adaptation.

Pixel‑density adaptation ensures images look sharp on @2x, @3x, etc., screens by providing appropriately sized assets (e.g., 500×300 px → 1000×600 px for @2x, 1500×900 px for @3x).

Screen‑size adaptation keeps layout proportions consistent across devices of different widths.

Design drafts are usually 750 px wide. For a component that is 690 px wide with 30 px margins, the width ratio is 690/750 = 0.92 (92 %) and the margin ratio is 30/750 = 0.04 (4 %). By applying these percentages, the layout scales proportionally on any screen.

Global CSS Units

Using plain percentages is insufficient because most CSS properties reference the containing block, not the viewport width. A global unit is needed. Both rem (root‑element font size) and vw (1 % of the viewport width) can serve this purpose, but vw directly maps to screen width.

1 vw equals 1 % of the initial containing block (the html element). Therefore, the component width can be written as 92vw and the margins as 4vw , achieving true screen‑level adaptation.

Automating px‑to‑vw Conversion

The postcss-px-to-viewport plugin can automatically convert pixel values from the design draft into vw units during the build process. A typical .postcssrc.js configuration looks like this:

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

Key options:

viewportWidth : matches the design draft width.

viewportHeight : any reasonable value.

unitPrecision : number of decimal places.

viewportUnit : target unit ( vw ).

selectorBlackList : selectors to exclude from conversion.

minPixelValue : smallest pixel value to convert.

mediaQuery : whether to convert inside media queries.

For example, the CSS for a .card component written in pixels:

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 processing with the plugin, all pixel values become vw units, ensuring the component scales proportionally on any device.

Conclusion

The article covered the theory behind adapting and restoring design drafts for mobile H5, introduced global CSS units ( rem and vw ) for screen‑level adaptation, and demonstrated how to automate the pixel‑to‑viewport conversion with postcss-px-to-viewport . Future articles may explore H5’s interaction with native capabilities, deployment strategies, or front‑end engineering scaffolds.