Tencent/weui: the WeChat design team's CSS library for mobile web

What WeUI solves, and who it is actually for

WeUI is a stylesheet, not a JavaScript framework. The README describes it as an "WeChat-like UI framework officially designed by the WeChat Design Team, tailor-made for WeChat Web development", and the stated goal is to "improve and standardize the experience for WeChat users". That sentence is the whole scope. If your page runs inside the WeChat in-app browser and you want it to feel like the surrounding app, WeUI gives you the same visual vocabulary the platform uses.

The component list in the README is concrete: button, cell, dialog, progress, toast, article, actionsheet and icon. That is a mobile interaction set, not a general component library. There is no data grid, no date picker in that list, no form validation layer. The audience is a front-end or full-stack developer shipping a WeChat-facing page, plus designers who want to match the platform's own patterns instead of inventing them.

One detail matters for planning. The README points to sibling projects rather than folding them in: weui-wxss for WeChat Mini Programs, a WeCom (enterprise WeChat) variant, weui.js for the JavaScript behaviours, and react-weui for React bindings. Those are separate repositories. If you need dialog and toast behaviour rather than just their appearance, the CSS package alone will not give it to you.

How the package is structured: Less source in, CSS out

The repository layout is a classic two-tree split: src/ holds the Less sources, dist/ holds the built output. package.json points three fields at the result: "style" and "main" both resolve to dist/style/weui.css, and "less" resolves to src/style/weui.less. So a bundler that understands the style field picks up the compiled CSS, while a Less-based build can consume the variables and mixins directly.

The build is Gulp. The scripts are "build": "gulp build" and "test": "gulp build", meaning the test script is the build itself. There is no unit test runner in the dependency list. What runs instead is stylelint: "lint": "stylelint src" and "lint:fix": "stylelint src --fix", configured through .stylelintrc.js and .stylelintignore. For a CSS project that is a defensible choice, but it means correctness is enforced at the style level, not at the behaviour level.

The toolchain in devDependencies is worth reading before you fork. gulp-less compiles Less, autoprefixer adds vendor prefixes, gulp-cssnano minifies, gulp-sourcemaps emits source maps, and gulp-convert-css-var appears in the pipeline. Several of these are pinned to old major ranges (autoprefixer ^6.3.1, gulp-postcss ^6.0.1). If you plan to modify the source rather than consume the dist output, expect to spend time on the build before you spend it on styles.

Building weui from source and serving the demo

The README does not spell out install steps, but package.json names the package "weui", declares the repository, and defines the scripts the project is developed with. The commands below are copied from that scripts block. Run this in your project root:

npm run build

That runs "gulp build", which is also what "npm test" maps to. The output lands in dist/, alongside the committed dist/style/weui.css that package.json points its main, style and less fields at.

For local development the project uses a watch-and-serve task:

npm start

The script is "gulp -ws", the watch-and-serve variant, which is what the demo pages are developed against. The README hosts the live demo at weui.io, and also links legacy demos at weui.io/1.x and weui.io/0.4.x, which is the fastest way to compare a component's intended appearance against your own output.

If you would rather not run the build at all, the compiled stylesheet is already in the repository at dist/style/weui.css, and that is the file package.json names as both "main" and "style".

To check the source against the project's own style rules, the lint scripts are:

npm run lint
npm run lint:fix

The first runs "stylelint src". The second runs "stylelint src --fix". Both are configured through .stylelintrc.js.

Where WeUI stops being the right choice

The clearest limitation is scope. The README says the framework is "tailor-made for WeChat Web development". A product with its own brand identity, or one that must look consistent across iOS Safari, Android Chrome and a desktop browser, gains little from a stylesheet whose entire premise is matching one platform's conventions. You would be overriding more than you inherit.

The second limitation is that visual components and interactive components live in different repositories. The README lists weui.js and react-weui under Development rather than describing them as part of this package. The npm package you install is named weui and its main entry is a CSS file. If your requirement is "show a toast and dismiss it after two seconds", the CSS gives you the toast's appearance and nothing that schedules the dismissal. That is a real integration cost, and the README does not document a supported path for combining the two beyond linking to the sibling repositories.

The third is the build. If you want to change a colour or a spacing value at the Less level, you are running Gulp with a dependency set that includes autoprefixer ^6.3.1 and gulp-postcss ^6.0.1. Modern PostCSS setups will not drop into that pipeline without work. Consuming dist/style/weui.css and overriding with your own rules is the cheaper route, at the cost of specificity fights.

Finally, the licence field on the repository is reported as NOASSERTION, while both the README and package.json state MIT. That mismatch is a packaging artefact, not a legal position, but it is the kind of thing a compliance check will flag, so confirm it against LICENSE.txt before you ship.

WeUI against a general-purpose mobile CSS framework

The obvious comparison is Bootstrap or a similar general mobile stylesheet. The difference is not quality, it is premise. Bootstrap defines its own visual language and applies it consistently everywhere; WeUI reproduces an existing one. If you are building a page that opens inside WeChat and should feel like part of the app, a generic framework will look foreign no matter how well it is themed, because its defaults were not drawn from the WeChat design reference the README links to at weui/weui-design.

The second difference is the delivery model. A general framework ships components and behaviour together. WeUI splits them: CSS here, weui.js and react-weui elsewhere, and weui-wxss for Mini Programs. That is more moving parts, but it also means you can take the stylesheet without taking a JavaScript runtime, which suits server-rendered pages.

The third difference is maintenance shape. The last push to this repository was on 2026-03-12, and the most recent release is v2.6.26 on the same date. The release before it, v2.6.25, landed on 2025-09-12, and v2.6.24 on 2025-09-04. That is a slow, occasional cadence rather than a weekly one. A general framework with a faster release rhythm will give you fixes sooner; WeUI's advantage is that the target it imitates changes slowly too.

Frequently asked questions

The README answers some questions directly and is silent on others. The entries below cover what the repository material supports.

Is WeUI the same as weui.js? No. The README lists weui.js as a separate repository under Development, and the npm package named weui resolves its main entry to dist/style/weui.css. The stylesheet and the JavaScript behaviours ship separately.

Does WeUI work in WeChat Mini Programs? Not this package. The README points to weui-wxss, described as "WeUI for 小程序", as the Mini Program variant. The CSS in this repository targets mobile web pages.

What licence does WeUI use? Both the README and package.json state the MIT License, and LICENSE.txt is present at the repository root. The repository's reported licence field reads NOASSERTION, so verify against LICENSE.txt if your process depends on the metadata.

Editorial conclusion

Adopt WeUI if you are building a mobile page that must look native inside WeChat and you want the official component set rather than a hand-rolled stylesheet. Do not adopt it if your product needs a general-purpose design system for desktop or for a non-WeChat visual identity, because the project is explicitly scoped to WeChat web service. Before committing, check the wiki for the component list, confirm that dist/style/weui.css or the Less entry point at src/style/weui.less matches your build, and verify that the version you pin is the one whose changelog you have read.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. Tencent/weui on GitHub