tdesign-flutter: Tencent's design system as a Flutter component library

One import brings both Material and TDesign

tdesign-flutter is a cross-platform UI component library based on Tencent's design system, built with the Flutter framework, and it supports iOS, Android and Web.

The feature list is short and specific. It provides a Flutter UI component library following the TDesign design specifications. It supports theme customization to match your app's design style. It includes a comprehensive icon library with custom replacement support. It defines colour groups according to the TDesign specifications, viewable in `TColors`. And it offers real-time preview of the default colour values through the colour declaration class.

The entry point is a single import:

import 'package:tdesign_flutter/tdesign_flutter.dart';

And the reason that one import is enough is stated explicitly. The TDesign entry point re-exports Flutter Material widgets, so the same import provides `MaterialApp`, `Scaffold`, `Text`, and TDesign components together. That is a deliberate design decision rather than an accident of packaging, and it is worth understanding before you adopt the library, because it means your dependency on Material is implicit.

The usage example is correspondingly short:

const TButton(child: Text('Button'))

The documentation notes that no additional initialization or theme configuration is required, and that omitting `onPressed` leaves the button disabled. So the library is usable with no setup at all, and the theme is opt-in rather than mandatory.

That last point is the one that makes this library different from a heavier design system. You can take a single component without adopting the whole visual language.

Version 1.0 is a breaking change, and it landed in a day

The version history is the first thing to read if you are coming from an earlier release, because the jump is not small.

The releases are 0.2.7 from 2026-01-21, 1.0.0-alpha.1 from 2026-07-31, and v1.0.0 from 2026-10-15, whose commit message is simply chore: release 1.0.0. The last push to the repository was on 2026-10-15, the same day, and the repository is not archived.

The README puts a warning at the top of the quick start. Upgrading from 0.2.7? Read the 1.0 migration guide before changing the dependency. Version 1.0 contains breaking API and behavior changes.

That is a significant break for a library that was at 0.2.7 in January. Seven months of alpha work, then a major version. The migration guide is at `tdesign-site/site/docs/migration-0.2.7-to-1.0.md` and is written in Chinese.

So the realistic picture for an adopter is a young library that has just stabilised its API, with a large jump from the pre-1.0 line and a migration path that exists but is not in English. If your project is on 0.2.7, the upgrade is a project rather than a dependency bump, and you should read the guide before planning around it.

The version requirement is explicit. It requires Flutter 3.32.0 or later and Dart 3.8.0 or later, and the dependency line to add is `tdesign_flutter: ^1.0.0` in `pubspec.yaml`, followed by `flutter pub get`.

The default branch is `develop`, and the published package lives on pub.dev as `tdesign_flutter`.

The documentation is Chinese first, and the code samples are not

The README says it directly: the detailed guides below are currently in Chinese. That covers getting started, custom themes, dark mode, internationalization and the FAQ, and the component documentation itself is hosted on the TDesign site.

The guides are all in the `tdesign-site/site/docs/` directory, and the dark mode page is a section of the custom theme document rather than a separate file, which is a small signal about how the material is organised.

What is in English is the code. The README's Dart snippets, the import path, the `TButton` example, the `TColors` reference and the `pubspec.yaml` line are all language-neutral, and the component reference site at tdesign.tencent.com/flutter/overview is the place to look for the API surface.

That split is workable for a developer who can read the code and use the API reference, and awkward for someone who needs the conceptual guidance, since the themes and internationalization guides are where the explanations live.

Internationalization gets its own guide, which is a meaningful inclusion for a component library that has to render text in more than one language, and the fact that it is documented at all suggests the library treats localisation as a first-class concern rather than something left to the consuming app.

The repository layout backs up the split between the library and its site. There is a `tdesign-component/` directory holding the components, a `tdesign-site/` directory for the documentation site, a `packages/` directory, a `specs/` directory, a `tool/` directory and a `scripts/` directory. There is also a `PUBLISH.md` documenting the release process, an `AGENTS.md` at the root, a `README_zh_CN.md` for Chinese readers, and a `.cnb.yml` alongside a `.cnb/` directory, which is CNB, the Chinese cloud build service used for CI.

Theming is the part TDesign actually owns

The design system's contribution to a component library is mostly the colour and type decisions, and the README is explicit that the colour groups are defined according to TDesign specifications and live in `TColors`, with real-time preview of the default colour values through the colour declaration class.

The customisation path is a separate guide, `custom-theme.md`, which also carries the dark mode section. Dark mode is not a separate configuration system here, it is a mode of the same theme model, which is a sensible simplification.

The icon library comes with custom replacement support, which is the detail that matters for a product team. A design system whose icons cannot be swapped is a design system that dictates, and the ability to replace an icon lets a product keep its own asset set while using the standard components around it.

There is also a preview application, which is the fastest way to see what the components actually look like. For Android there is a QR code to download a preview app, and a direct download link for `tdesign-flutter-example.apk`. For iOS the instruction is to run the project, with the link pointing at the `tdesign-component` directory in the repository.

More usage examples live under `example/lib/page/` in the `tdesign-component` directory, linked from the README as the place to refer to for more usage examples.

The third-party dependencies are three, all from pub.dev: `easy_refresh`, `flutter_slidable` and `image_picker`. That is a small dependency list for a component library of this size, and the acknowledgements credit the authors of those packages.

One design system, seven implementations

The table of TDesign component libraries is the most useful thing in the README for anyone deciding whether this is the right choice, because it shows the scope of the design system rather than just this package.

There is a Vue 2.x library, `tdesign-vue`, a Vue 3.x library, `tdesign-vue-next`, a React library, `tdesign-react`, a Vue 3.x mobile library, `tdesign-mobile-vue`, a React mobile library, `tdesign-mobile-react`, and a WeChat Miniprogram library, `tdesign-miniprogram`. The Flutter package is the seventh.

That has two consequences. The first is favourable. A company that has a TDesign-based product on the web and a Flutter app, or a React Native or mini program client, has one design system expressed across all of them, and the Flutter package is not a one-off port that drifts from the others. The icon set, the colour groups and the component behaviour are shared across implementations, so a button looks like a button everywhere.

The second consequence is the cost of that coherence. The Flutter package follows a specification that is itself evolving and that is expressed first in other frameworks, so a Flutter-specific request may have to wait for the specification to settle, and the migration guide for 1.0 is an example of the size of those changes.

This is also what makes the TDesign Flutter package different from a generic Flutter component library. It is one implementation of a company design system, not a community library that happens to have a polished look. If your product already uses TDesign somewhere, that is the argument for it. If it does not, the coherence argument does not apply to you, and you are simply choosing one set of widgets over another.

Where the library does not fit

Three limits are worth naming before you add the dependency.

The first is the documentation language. The detailed guides are in Chinese, which is a real friction for a non-Chinese-speaking team, particularly for theme customisation, where the conceptual part of the task is exactly what the guide explains and the API reference does not.

The second is the 1.0 line itself. A library that spent seven months in alpha and then made a breaking change from 0.2.7 to 1.0 in a single release is a young library with a recent API break. It is more stable than it was, and it is still young, and the difference between those two statements is what you are betting on.

The third is the implicit Material dependency. Because the entry point re-exports Flutter Material widgets, the library does not give you a Flutter package that stands alone. It is a layer over Material with a TDesign skin and TDesign components, and that is what makes the single-import experience work, and also what means a project that wanted a non-Material foundation would be fighting it.

For contrast, a project that has no existing design system can use Flutter's own Material components with a theme file, which is less distinctive but requires no migration, no Chinese documentation and no commitment to a specification set by another company.

The licence is MIT, with the licence file at the repository root and the README stating the project is licensed under the MIT License, so there is no obligation here beyond attribution, which is a licensing observation rather than legal advice.

Editorial conclusion

tdesign-flutter fits a Flutter team that has to match an existing TDesign product, or that wants a coherent component set with theme customisation rather than assembling one from several libraries. It does not fit a team that needs a design system matching a different specification, and it does not fit a team that cannot work with documentation written in Chinese. Verify first that the components you need exist in the 1.0 API rather than only in the older 0.2.7 line, since version 1.0 contains breaking API and behaviour changes and a migration guide is provided, that your Flutter is 3.32.0 or newer and your Dart is 3.8.0 or newer, and that the theme customisation path documented in the custom theme and internationalisation guides produces the colours your product expects, since the design system's colour groups are defined in `TColors` and the defaults are fixed by the specification.

Frequently asked questions

Official sources

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