WeUI for WeChat Mini Programs: A WXSS-Only Style Library from the WeChat Design Team

What weui-wxss actually ships, and who it is for

The README opens by calling WeUI a base style library that matches the native WeChat visual experience, designed by the WeChat official design team for pages inside WeChat and for WeChat mini programs. The stated goal is a consistent user perception across apps. The listed elements include button, cell, dialog, progress, toast, article, actionsheet and icon.

The repository is the mini program edition of that library. Its package.json main field points at dist/style/weui.wxss, so the published npm package resolves to a single stylesheet. The README is explicit that the contents are pure UI. If you want a version with logic already wrapped, it directs you to a separate mini program component library, WeUI, hosted on the WeChat developer documentation site. That sentence is the most important one in the README: it tells you this repository is the lower layer.

The audience follows from that. You are building a mini program, you want your screens to look like WeChat's own surfaces, and you are prepared to write the interaction code yourself. If you want a drop-in component with properties and events, this is the wrong layer.

Styles in dist, structure in dist/example

The README gives two ways to consume the library. You can reference the whole stylesheet at dist/style/weui.wxss, or reference individual component stylesheets under dist/style/widget. The second path matters when a mini program has a size budget or when you only need a couple of elements.

The WXML structure is not shipped as a component definition. The README says the component WXML structures can be found under dist/example. In other words, the repository demonstrates the markup rather than packaging it: you copy the class names and the element nesting from the examples into your own pages. That is the whole data flow. There is no runtime, no JavaScript entry point, no component registration.

The top-level layout matches this split. There is a src directory, a gulpfile.js, and two output directories: dist and dist-rpx-mode. The build scripts in package.json are gulp, gulp build, and a release script that tags and pushes. The devDependencies list gulp-less, autoprefixer, gulp-cssnano and stylelint, which is a Less-to-CSS pipeline with prefixing, minification and linting.

px by default, rpx in dist-rpx-mode

The README states that the default version uses px, and that an rpx version is also provided in the dist-rpx-mode directory. This is a real fork in the road rather than a cosmetic detail. px values do not scale with the device width the way rpx does, so the two directories produce different layout behaviour on screens of different sizes.

The choice is not documented beyond the directory name. The README does not explain when to pick one over the other, and it does not say whether the two builds are generated from the same Less sources with a unit substitution or maintained separately. The package.json devDependencies include miniprogram-elder-transform, which suggests at least one build variant is produced by a transform step, but the README does not describe that pipeline. If you need to know which build your design calls for, the examples under dist are the practical reference.

Previewing weui-wxss and wiring up a first page

The README does not give npm install instructions, and it does not print an import line. What it does give is the entry point and the preview step. The package.json main field is dist/style/weui.wxss, and the README says the style file can be referenced directly, either whole or as the individual component stylesheets under dist/style/widget.

The README's own instruction for previewing is to open the dist directory in WeChat DevTools. It stresses that you open dist, not the whole project:

npm install weui-wxss

After that, the stylesheet you reference is dist/style/weui.wxss, or the per-component files under dist/style/widget. The WXML structures to copy come from dist/example. The one complete markup example the README prints is the dark mode root attribute:

<view data-weui-theme="dark">
    ...
</view>

The README says the dark mode is enabled by adding data-weui-theme="dark" on the root node. What you should see after wiring these together is the WeChat-native styling on your elements, with the dark palette applied inside that view. If the styles do not appear, the most likely cause is the path you reference: the package's main field is dist/style/weui.wxss, so the path in your own stylesheet has to match where your bundler or the devtools resolves the package.

Dark mode is a root attribute, and that constrains your page tree

The dark mode mechanism is a single attribute on a view. The README shows data-weui-theme="dark" on a root node, which means the theme is inherited by everything inside that subtree. There is no documented JavaScript API for toggling it, no documented storage key, and no documented media query fallback for the system theme.

That is a design choice with consequences. If your page has more than one root, or if a modal is rendered outside the themed subtree, the attribute will not reach it. The README does not document a partial-theme strategy or a way to scope the dark palette to a single component. You can set the attribute per view, but the README does not state whether nested values override each other. For a mini program with a single page-level root view, the mechanism is simple. For anything with portals or detached overlays, verify it before you commit to the approach.

The logic is your problem, and that is the real limitation

The README's own sentence about the library being pure UI is the limitation. A dialog in this repository is a styled container. Opening it, closing it, trapping focus, deciding what the confirm button does: none of that is here. The same applies to toast, actionsheet and progress. You get the visual contract and the class names, and you write the state machine.

There is a second constraint. The README points readers who want the logic-wrapped version to the extended WeUI component library on the WeChat developer documentation site. That library is a different artifact with a different integration model, and the README does not describe how the two relate or whether the styles are interchangeable. If you start with weui-wxss and later decide you want components, migration is not documented.

The third constraint is the build. The package ships .wxss files and a Less source tree. If your team does not use Less and does not want to run gulp, you are consuming the generated output and treating the src directory as reference only. The README does not document how to extend or override the Less variables.

How it compares with component libraries like TDesign and Vant Weapp

The related searches around this project include TDesign miniprogram and Vant Weapp, which are the natural comparison points because they sit one layer up. The difference is architectural, not cosmetic. Those projects ship components: you register a component, pass properties, and listen for events. weui-wxss ships stylesheets and example markup, and the README says so directly.

That changes what you own. With a component library, the interaction behaviour is the library's responsibility and your code is configuration. With weui-wxss, the interaction behaviour is your code and the library's responsibility stops at the visual layer. For a small mini program with a handful of screens, writing that behaviour is often less work than adapting a component library's API to your design. For a large one, it is a running cost that compounds with every new element.

There is also a fidelity argument. The README describes the library as matching the native WeChat visual experience and being designed by the WeChat official design team, with the visual standard documented in a separate weui-design repository. If looking like WeChat itself is the requirement, that provenance is the reason to pick this over a third-party component set.

Maintenance, licensing and what the repository does not document

The repository is not archived. The most recent release listed is v2.6.26, published on 2026-03-12, and the last push to the default branch was on 2026-03-12 as well. Before that, v2.6.25 landed on 2025-09-12 and v2.6.22 on 2025-06-17. The cadence is irregular, with gaps of several months between tags, and the CHANGELOG.md and DIFF.md files at the top level are where the project records what moved between them. The README does not describe an upgrade procedure, so the changelog is the place to look before bumping the version.

Licensing needs a caveat. The README ends with an MIT License line pointing at opensource.org/licenses/MIT, and package.json declares "license": "MIT". The repository metadata reports the license as NOASSERTION, which means the automated classifier could not confirm a standard licence from the LICENSE.txt file. That is a discrepancy worth resolving with your own legal review rather than assuming either reading; this is not legal advice, and the two sources disagree.

The upgrade cost is mostly mechanical. Because the package is stylesheets, a version bump can change class output and therefore your layout. The dist-rpx-mode directory is regenerated alongside dist, so if you consume the rpx build you have to re-check your sizing after each upgrade. Neither the README nor the release metadata describes a compatibility policy for class names.

Editorial conclusion

weui-wxss suits teams building WeChat mini programs that want the native WeChat look and are willing to write their own event handling, because the package ships styles and WXML structure but no logic. Teams that want ready-made components with properties and methods should look at the extended WeUI component library the README points to instead. Before adopting it, open the dist directory in WeChat DevTools, check whether the px build or the dist-rpx-mode build matches your layout approach, and confirm the dark mode attribute works with your page structure.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. Tencent/weui-wxss on GitHub