Library / SDK
Tencent/weui-wxss avatar
Tencent/weui-wxss

weui-wxss: pure styles, two builds, and a DIFF.md at the root

A UI library by WeChat official design team, includes the most useful widgets/modules.

15,274 stars5,126 forksLessNOASSERTION

At a glance

What is it?
The WeChat official design team's style library for WeChat Mini Programs, covering button, cell, dialog, progress, toast, article, actionsheet and icon. It ships no logic at all, only WXSS, in two builds: one in px under dist and one in rpx under dist-rpx-mode. Its manifest points at a different GitHub organisation than the repository it ships in, and the last push was on 2026-03-12.
Who is it for?
Adopt weui-wxss when you are building a WeChat Mini Program and want the native WeChat look without writing WXSS, and when you accept that you are adopting styles only. Do not expect behaviour from it, because the project points you to a separate component library for anything with logic.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Activity is slowing. The repository last received commits 8 months ago.
What is it written in?
Mainly Less, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Tencent/weui-wxss15,274 ★ · +0
Star history
Repository2026-09-222026-11-15
Tencent/weui-wxss15.3k15.3k

0 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

This is a style library with no logic in it

The overview describes WeUI as a base style library consistent with WeChat's native visual experience, designed by the official WeChat design team for WeChat web pages and WeChat Mini Programs, so that the user's perception is more consistent. The elements named are button, cell, dialog, progress, toast, article, actionsheet and icon.

Then comes the sentence that settles what this package is and is not. The content is a pure UI library; if you want the version with logic encapsulated, look at the Mini Program component library instead, which is linked to WeChat's developer documentation.

So what you install is WXSS and nothing else. There is no component with behaviour, no form validation, no event handling, and no JavaScript. What you get is the appearance, and you supply the markup and the behaviour yourself.

The usage section says so from the other direction. The style file can be referenced directly as dist/style/weui.wxss, or you can reference the wxss for individual components under dist/style/widget. And for the wxml structure of a component, you look at the components under dist/example.

That division matters more than it sounds. Reading dist/example tells you what markup a cell or a dialog is expected to have, which is the hard part to reconstruct from a stylesheet alone. So the package is styles plus reference markup, and the behaviour layer is a separate dependency you have to choose deliberately.

Two builds exist and the default is px, not rpx

There are two compiled outputs in the repository, and they differ in the unit they use.

The default build uses px. An alternative rpx version is also provided, with the files in the dist-rpx-mode directory. The compiled output in dist is what the manifest points at, with main set to dist/style/weui.wxss.

WXSS is the Mini Program stylesheet dialect, and rpx is its responsive unit, which scales against the device width. So the two builds are not two versions of the same thing; they are the same design expressed in a fixed unit or a scaling one.

Choosing wrongly here produces a layout that looks fine in the simulator and wrong on a real device, or the reverse, and the failure is quiet because the CSS is valid either way. The main field in package.json resolves to the px build, so a plain dependency install and then an import of the package main gives you the fixed-unit version.

The reference markup in dist/example belongs to the default build. If you switch to the rpx directory, you are keeping the same class names and the same structure, so the examples still describe what the markup should look like. That is the reason the split is safe to make, and also the reason it is easy to miss.

Dark mode is one attribute on the root node

The dark mode feature is described in two sentences. Add the attribute data-weui-theme="dark" to the root node. The example given is:

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

There is no separate stylesheet, no class to add, and no build step. The attribute is the whole mechanism, and the library's selectors are written so that a descendant of that node picks up the dark values.

The consequence is about scope rather than effort. The attribute is inherited by the subtree it sits on, so setting it on one view makes that region dark and leaves the rest of the page alone. If your Mini Program has separate pages, setting it on one page's root view does not darken the others, because each page is its own tree. A dark mode that should follow the system therefore needs the attribute applied per page, or on whatever common ancestor your page structure provides.

The same attribute name is the integration point for a manual toggle, which is the more likely use. Putting it on a root view and driving it from your own state is a few lines, and it means the library ships no mode-switching logic of its own, consistent with there being no logic in the package at all.

Preview the dist directory, and the README warns you twice about it

The preview section is short and contains the single most useful warning in the document.

Open the dist directory with the WeChat web developer tools. The parenthetical that follows is emphatic: note that it is the dist directory, not the entire project.

That emphasis tells you people get this wrong. The repository root contains src, which holds the Less sources, along with gulpfile.js, package.json and the project configuration files. None of that is what the developer tools need. The tool wants the compiled output, because what you preview is the result of the build, not the build inputs.

So if you open the project root and see nothing, the likely explanation is not a broken setup. It is that you are pointing the tool at a directory containing stylesheet sources rather than the compiled WXSS and the example markup.

Two files at the top level explain why. project.config.json is the developer tools project file that identifies the project, and project.private.config.json is its personal counterpart, which is the one that holds settings local to a machine.

The manifest points at weui, the repository ships from Tencent

The package metadata and the repository location do not agree, and it is the kind of detail that sends someone to the wrong place.

The repository field in package.json is set to git at https://github.com/weui/weui-wxss/. The repository you are reading, and the one the package is published from, is under the Tencent organisation at github.com/Tencent/weui-wxss.

The README's own link for the visual standard is the WeChat design repository at github.com/weui/weui-design, which is a different project, so the weui organisation name is not invented here. It points at a sibling repository rather than this one.

The practical consequence is narrow. If you follow the repository field, whether from a package page, a dependency report or a script that resolves the source URL, you arrive at a URL that is not this repository. Anything that ties an artefact back to its source, a supply chain inventory or an automated licence scan, will record the wrong origin.

Two other metadata entries are worth noting in the same pass. The description is the string weui-wxss, which is the package name repeated rather than a description. And the author is recorded as wechat ui team, which is the team rather than an individual. Neither is wrong, and neither tells you much when you are trying to work out who to contact about a style regression.

A directories field points at an example directory that is not at the root

The manifest carries a field that has not been relevant to npm for a long time:

code
"directories": {
    "example": "example"
}

It declares an example directory at the top level. There is no example/ directory in the repository listing. What exists is dist/example/, which is where the compiled example markup lives, nested inside the build output.

So the declaration is both legacy and wrong with respect to this tree. The directories field was never a resolution mechanism, it was metadata that older tooling would show as an install path. Nothing reads it when the package is installed, which is why it has gone stale without breaking anything.

It is worth noting alongside the main field, which is set to dist/style/weui.wxss. That one does matter: it is what you get if you import the package by name rather than by path, and it points into the build output rather than at src. So the two path declarations in this manifest point in different directions, one of which is live and one of which is not.

For anyone consuming this package, the practical advice is to reference the file you want explicitly, either dist/style/weui.wxss or the individual widget styles under dist/style/widget, rather than relying on the package entry point and the directories field to agree with each other.

stylelint is installed and no lint script calls it

The development dependencies include stylelint at ^13.0.0 and stylelint-config-standard at ^19.0.0. The scripts block has three entries and none of them is lint:

code
"start": "gulp",
"build": "gulp build",
"release": "gulp tag && git add -A . && git push && git push --tags"

So the style checker is present as a dependency and unused as a script. Nothing in package.json runs it directly.

The release script is the more interesting entry. It runs a gulp tag task, then stages everything with git add -A ., then pushes the branch and then pushes the tags. There is no test step and no lint step in that chain, so whatever is on disk when someone runs it goes to the repository and the release is cut in one command.

The rest of the toolchain is a gulp pipeline in a couple of generations. There is gulp at ^4.0.2 with gulp-less ^4.0.1, then autoprefixer at ^6.5.1, gulp-postcss ^6.0.1, gulp-cssnano ^2.0.0, gulp-header ^1.8.8, gulp-rename ^1.2.2 and gulp-replace ^1.0.0. Then one package at an exact version: miniprogram-elder-transform 0.0.2.

Several of those pins are old, which is not a problem for a project that builds a stable stylesheet and a reason to expect the build to need attention before it runs on a current Node.

DIFF.md at the root, and a release gap between v2.6.25 and v2.6.26

Two files at the top level record change: CHANGELOG.md and DIFF.md. Having both is unusual.

The release history is worth reading for what it says about pace. The three most recent releases are v2.6.26 on 2026-03-12, v2.6.25 on 2025-09-12, and v2.6.22 on 2025-06-17.

Two observations. The gap from v2.6.22 to v2.6.25 skips two patch numbers, so either two releases were cut without a tag or the numbering moved. And the gap from v2.6.25 to v2.6.26 is about six months, which is a long interval for a patch release of a style library.

The last push to the default branch master was on 2026-03-12, the same day as v2.6.26. So as of 2026-11-03 there has been no push to this repository for nearly eight months, and the newest release is the newest commit.

For someone depending on this package, the practical reading is that the newest version is also the final one for now. There is no release cadence to track; read CHANGELOG.md and DIFF.md when you are deciding whether an upgrade changes a component you use.

Editorial conclusion

Adopt weui-wxss when you are building a WeChat Mini Program and want the native WeChat look without writing WXSS, and when you accept that you are adopting styles only. Do not expect behaviour from it, because the project points you to a separate component library for anything with logic. Pick your build deliberately, since the default is px and an rpx variant sits in another directory. Check the DIFF.md and CHANGELOG.md before upgrading given the release gaps, and note the last push was on 2026-03-12 rather than assuming a current release cadence.

Frequently asked questions

What is weui-wxss?

A base style library from the official WeChat design team, consistent with WeChat's native visual experience, designed for WeChat web pages and WeChat Mini Programs. It includes elements such as button, cell, dialog, progress, toast, article, actionsheet and icon, and it is MIT licensed.

Does weui-wxss include any JavaScript or component logic?

No. The README states the content is a pure UI library, and points anyone wanting the version with logic encapsulated to the separate Mini Program component library on WeChat's developer documentation. What weui-wxss ships is WXSS, plus reference wxml markup under dist/example to show what structure each component expects.

How do I use dark mode with weui-wxss?

Add the attribute data-weui-theme="dark" to the root node, for example on a view element wrapping the content. There is no separate stylesheet and no build step, and the setting applies to that node's subtree, so each Mini Program page that should be dark needs the attribute applied to it.

Should I use the px or rpx version of weui-wxss?

The default build uses px and is what the package main field points at, as dist/style/weui.wxss. An rpx version is also provided with the files under dist-rpx-mode. Pick deliberately, because the class names and structure are the same and a mismatch produces a layout that compiles but scales wrongly.

How do I preview weui-wxss changes?

Open the dist directory with the WeChat web developer tools. The README is emphatic that it is the dist directory and not the entire project, because the repository root holds the Less sources in src along with the gulpfile and the project configuration files, none of which is what the developer tools need.

Official sources

  1. Issues
  2. README
  3. Releases
  4. Tencent/weui-wxss on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tencent-weui-wxss.svg)](https://hysenlabs.com/projects/tencent-weui-wxss)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tencent-weui-wxss.svg)](https://hysenlabs.com/projects/tencent-weui-wxss)

Was this useful?