Tencent TDesign: a cross-framework design system with Vue, React and MiniProgram libraries

The problem TDesign solves is consistency across stacks, not component count

Most component libraries answer one question: what widgets do I get for my framework. TDesign answers a different one. The README frames the project as a comprehensive enterprise design system with implementations for Vue, React and WeChat MiniProgram, and it names two capabilities as the reason to pick it: consistent design and cross-platform, multi-tech stack support. That is the pitch. A product organisation with a Vue admin console, a React internal tool and a MiniProgram front end can point all three at one set of design values instead of maintaining three visual languages.

The README also gives the origin story, which explains the shape of the project. Before 2019 there were many internal design system and component library projects inside Tencent, described as product-focused decentralized rapid iterations. In 2019 Tencent established an Open Source Collaboration Committee, and TDesign is the consolidation that came out of it. That history matters for evaluation: this is not a weekend component set, it is an attempt to unify a large organisation's UI surface, and the repository structure reflects that ambition.

The audience is therefore narrower than the download numbers might suggest. If you are a solo developer building a landing page, the cross-stack argument does not apply to you and you are paying for coordination you will never use.

The main repository is documentation and tooling, not the components

This is the single most misread thing about Tencent/tdesign. The repository you are looking at is described in its own README as the TDesign main repository and documentation. The actual component libraries live elsewhere, in separate repositories listed in the README's tables: tdesign-vue-next, tdesign-react, tdesign-vue, tdesign-miniprogram, tdesign-mobile-vue, tdesign-mobile-react, tdesign-flutter and tdesign-uniapp. Shared code sits in tdesign-icons and tdesign-common.

The layout confirms it. The top level holds a pnpm workspace (pnpm-workspace.yaml, pnpm-lock.yaml), a packages/ directory, a services/ directory, a site/ directory and a docs/ directory. Linting and commit hygiene are wired in at the root: .commitlintrc.js, .eslintrc.js, .stylelintrc.js, .prettierrc.js and a .husky/ directory. The root package.json is marked private and declares packageManager [email protected] with an engines constraint of pnpm >=9.0.0. Its scripts are about building the site and the tooling, not about publishing components.

So the data flow for a consumer is: you install a component package from npm (for example tdesign-vue-next or tdesign-react), and this repository supplies the documentation site, the theme generator and the shared styles that those packages are built against. If you clone this repository expecting to patch a Button component, you are in the wrong place.

Installing TDesign Vue and rendering a first component

The README does not give install commands for the component packages. It points to the documentation site at tdesign.tencent.com with per-framework sections, and the npm package names are visible in the repository table's status badges, which query registry.npmjs.org for tdesign-vue-next, tdesign-react, tdesign-vue, tdesign-miniprogram, tdesign-mobile-vue, tdesign-mobile-react and @tdesign/uniapp. Those names are the ones to use; do not guess a scoped variant that is not in that list. Because the README stops at pointing you at the documentation, the exact install and registration lines belong to the per-framework docs rather than to this repository, and no command can be quoted from here.

What this repository does give you is the starter path. The README lists starter kits as separate repositories: tdesign-vue-next-starter, tdesign-react-starter, tdesign-vue-starter and tdesign-miniprogram-starter-retail, plus a CLI tool at tdesign-starter-cli. Those are the entry points for a new application. The library packages are for adding TDesign to something that already exists.

The one thing you can verify before installing anything is the package name itself. The badge URLs in the README's tables are the authoritative list, and they resolve against the npm registry. If a name you were given does not appear in those tables, it is not part of the set the project documents.

Working on the documentation monorepo itself needs pnpm and a specific Node version

If your goal is to contribute to the docs site or the theme generator rather than consume components, the root package.json defines the workflow. The package manager is pinned to [email protected] and the engines field requires pnpm >=9.0.0. There is also a .node-version file at the top level, which is where the expected Node release is recorded.

The scripts split into two families. Component and tooling builds run through pnpm filters, and the root package.json defines them as:

"dev:components": "pnpm run --filter @tdesign/site-components dev",
"dev:theme-generator": "pnpm run --filter @tdesign/theme-generator dev",
"build:components": "pnpm run --filter @tdesign/site-components build",
"build:theme-generator": "pnpm run --filter @tdesign/theme-generator build"

Site work is heavier because the site build depends on the components build first:

"dev:site": "pnpm run build:components && pnpm run --filter tdesign-site dev",
"site": "pnpm run build:components && pnpm run --filter tdesign-site build",
"site:preview": "pnpm run build:components && pnpm run --filter tdesign-site site:preview"

Because dev:site begins with build:components, a failure there will stop the site from starting. There is a prepare script that runs husky install, which means hooks are set up on install and a bare clone without a package install will not have them. Commit messages are validated by commitlint with the conventional config, and lint-staged runs eslint --fix and prettier --write on staged vue, js and html files, and stylelint --fix on less files. In practice that means a commit with a malformed message or an unformatted file will be rejected locally before it reaches review.

Where TDesign is the wrong choice, and what to use instead

The clearest limitation is stated by the project itself, in the status badges. tdesign-mobile-react, tdesign-flutter and @tdesign/uniapp are all labelled Alpha in the README tables, while the desktop Vue and React libraries and tdesign-miniprogram are labelled LTS. If your product is a mobile app and you were planning to standardise on TDesign across React Native or Flutter, you are adopting a library the project describes as Alpha. That is a material risk, not a footnote.

A second limitation is the multi-repository structure. Version numbers move independently across tdesign-vue-next, tdesign-react, tdesign-miniprogram and the rest. The README does not document a lockstep release train or a compatibility matrix between them, so keeping a Vue console and a MiniProgram on visually identical components is a coordination task you own. The weekly release notes visible in this repository (v2026.9.21, v2026.9.14, v2026.9.7) describe releases of the main repository, not of every component package.

For a single-framework team, the cross-stack argument evaporates and the relevant comparison is with the framework-native ecosystem. If you are building Vue 3 only, Element Plus covers much of the same enterprise admin ground with a single repository and a single release cadence. If you are building React only, Ant Design is the comparable choice, and it is also from a large Chinese vendor with an enterprise admin focus. The difference in approach is that both of those optimise for one framework and one release train, while TDesign optimises for parity across several. Parity costs you release independence. Pick based on which of those two you actually need.

Licence and the cost of tracking weekly releases

The repository declares MIT in the root package.json and ships a LICENSE file at the top level. The README's repository tables do not restate a licence per sub-repository, and this article cannot tell you whether every package under the TDesign umbrella carries the same terms. If you are vendoring or redistributing a component package, read the LICENSE in that specific repository rather than relying on the root declaration. That is a factual gap in the README, not a legal opinion.

Upgrade cost is the more practical concern. The release history shown here is weekly: v2026.9.7, v2026.9.14 and v2026.9.21, published on 2026-09-08, 2026-09-15 and 2026-09-22 respectively. The last push to the main branch was on 2026-09-23. A weekly cadence is good for fixes and bad for stability guarantees, because there is no long-term support branch described in the README for the main repository. If your organisation pins component versions and upgrades quarterly, you will be several weekly releases behind by the time you look, and the README does not document a migration guide or a rollback procedure for the main repository. Plan to read the release notes for each component package you actually depend on, not just this one.

Editorial conclusion

Adopt TDesign if you are building enterprise-facing products that must hold the same interaction patterns across Vue, React or WeChat MiniProgram, and if your team can absorb a pnpm workspace toolchain for the docs and site. Do not adopt it if you want one framework-agnostic package, or if you are shipping a single mobile app where tdesign-mobile-react and tdesign-flutter are still labelled Alpha in the README. Before committing, check which sub-repository matches your stack, confirm the npm package name, and read the licence file in that sub-repository rather than assuming the root MIT declaration covers every package.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Tencent/tdesign on GitHub