# Covalent: a design system whose compatibility table documents its own history

> Teradata's design system tracks Angular one major version at a time, ten rows and counting. The README that explains this has a visible copy-paste scar in the middle of it, which is worth reading as a signal about how this repository is maintained.

**Teradata/covalent** — Covalent - A Design System for Teradata

- Repository: https://github.com/Teradata/covalent
- Website: https://design.teradata.com
- Stars: 2,222 · Forks: 352
- Language: TypeScript
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/teradata-covalent

## A design system defined by what it refuses to build

The README is short and the vision statement is the part worth quoting. Covalent is an atomic, reusable component platform for Teradata to consume, built in an open source model. Atomic is doing real work in that sentence. It means the unit of delivery is a component small enough to restyle without a rebuild of everything above it.

The current state is stated plainly: Angular support today, plus a comprehensive library of web components. That pairing is the interesting strategic choice. Angular is where a design system with a decade of history accumulates the most coupling, and web components are the escape hatch, so the web component library is what lets the same visual language leave Angular without a rewrite.

The documentation index reflects that split. Web components get three separate entries, a quickstart, a theming guide and a developer guide, and the theming guide and developer guide point at the same file. The Angular section gets a getting-started page plus StackBlitz and Plunker templates. Only web components get two documents, one of them duplicated, which suggests the newer path is where the documentation effort is going.

The project lives at design.teradata.com, the repository is MIT, the primary language is TypeScript, and the topics list both `angular` and `angular-material` alongside `teradata`. With 2,223 stars, 352 forks and 134 open issues, the fork count is the highest in this batch by a wide margin, which is what a corporate component library adopted by many internal teams looks like.

## The compatibility table and the scar next to it

The most informative page in the repository is the Angular support matrix, because it doubles as a release history. Ten rows, one per Covalent major, one Angular major each:

| Covalent |      Angular      |
| :------: | :---------------: |
|   2.X    |        8.X        |
|   3.X    | 9.X / 10.X / 11.x |
|   11.X   |       20.X        |

Read downward, it is a project that has followed every Angular major release since version 8 and published a Covalent major to match. The 3.X row is the exception and the interesting one, spanning Angular 9, 10 and 11, which is the shape of a release that absorbed three framework versions rather than tracking each one.

Directly below that table, the README contains visible damage. There is a literal `...existing code...` line, then a second `## Angular Support` heading, then `...existing code...` again, then a bare `| 11.X | 20.X |` row with no table around it, then a stray `---` and another `---`.

This is a copy-paste artifact that survived into the published README, and it is the single most useful thing in the file for calibrating trust. It does not tell you anything about the library's correctness, but it does tell you that the documentation is written by hand and can go stale between major releases, while the compatibility table itself is maintained carefully enough to track ten majors. Treat the prose in this repository as secondary and the tables and the code as primary.

## Flexbox as the stated platform requirement

The browser support section makes a dependency claim rather than a version claim. Covalent is built on a CSS Flexbox layout and all layouts and components heavily rely on that support, so the support table is short by design.

Chrome, Firefox, Safari and Edge are all marked supported with a check. Mobile Chrome and Mobile Safari are marked with a tilde, and the legend explains that the tilde means limited testing and lower priority. That is an unusual thing to publish plainly. Most design systems either claim mobile support or stay silent, and this one says it tests mobile less and considers it a lower priority, which is a commitment a team can be held to.

The header line says current version minus one for the listed browsers, so the policy is one behind on the newest release. For a library whose entire premise is consistency, that is a reasonable stance. Flexbox has been stable for years in all four engines, so the layout primitives underneath are not the risk, and the components built on them are.

The important caveat is what this section does not say. There is no Internet Explorer row and no legacy Edge row, which tells you the floor is somewhere well after both. Given the matrix starts at Angular 8 and the current pairing is Angular 20, the implied browser floor has been moving forward with the framework for over a decade without the README having to revise that part.

## Three releases in six hours, all about icons

The three most recent releases were published on the same day, 2026-09-09, roughly two hours apart, and every one of them is about the icon set.

v11.21.0 at 15:23 added and updated Covalent icons as a feature. v11.22.0 at 17:39 added product consumption icons to the icon list, also a feature. v11.22.1 at 21:34 added missing Ask AI icon ligatures as a bug fix, because a shipped set was missing glyphs. The last push to the repository was 2026-09-22.

Three patch-level releases in one afternoon, and the third is a fix for missing ligatures in an icon font. That is not a criticism so much as a description of where a design system spends its maintenance once the components are stable. The remaining work is adding glyphs to match new product surfaces, and a glyph added for one product reveals the ones that were forgotten, which becomes the next release.

It also means the versioning is doing two jobs at once. A consumer pinning to v11.22.1 gets the Ask AI ligature fix and implicitly the two preceding icon additions, and the major version 11 continues to track Angular 20 with patch releases carrying asset work. The naming convention visible in the release titles is the standard-release-please pattern, which is why each body is a generated changelog with commit links rather than a written summary.

## An Nx monorepo doing six jobs at once

The directory listing is where Covalent's real scope shows. Alongside the expected `libs/`, `apps/` and `docs/` there is `.storybook/`, `nx.json`, `migrations.json`, `decorate-angular-cli.js` and `monaco-webpack.config.js`, and each of those answers a question about how the project is built.

`nx.json` confirms the README's statement that Covalent uses Nx for monorepo builds and task running, and the README goes further by recommending the Nx Console extension for VS Code so you can run affected builds, generate libraries and schematics interactively, and inspect the project graph. That is the standard Nx workflow, and putting it in the README rather than assuming it is a sign the team expects outside contributors.

`decorate-angular-cli.js` is the compatibility shim. It exists to make the Angular CLI behave correctly for a library that ships Angular Material components, and it is the kind of file whose presence tells you the project has to support consumer build setups older than its own. `migrations.json` is the schematics migration manifest, which is how a component library updates consumer code across major versions. `monaco-webpack.config.js` exists because the documentation app embeds Monaco, the editor behind VS Code, to render live code samples.

The rest is ordinary discipline: `.eslintrc.json`, `.prettierrc`, `stylelint.config.js`, `commitlint.config.js`, `.husky/` with `.huskyrc.js`, and a `.releaserc`. Husky plus commitlint plus release-please is a conventional three-piece commit pipeline, and its presence in the listing is a reasonable signal that the release notes are generated from commit messages rather than written.

## What package.json says about running it

The manifest is more informative than the README about day-to-day work, because the scripts encode the actual pipeline.

The local start command is `nx serve docs-app`, so what you get from `npm run start` is the documentation site rather than a playground. The build is `nx run-many --target build --skip-nx-cache`, and skipping the cache on a full build is a deliberate choice that suggests build times are long enough to matter. Formatting is `nx format` and `nx format:write` rather than direct prettier calls, so Nx owns the file graph for style fixes too.

The token pipeline has its own commands. `style-dictionary` runs in `libs/tokens` and builds there, and `build:foundations` chains `nx build tokens` into `nx build foundations`, which is the foundations-then-components order. There is also `dev:foundations`, which serves `libs/foundations/public` over a plain `python3 -m http.server 8000`. Being able to look at design tokens in a browser with no build step is a small thing that tells you a lot about how the system is meant to be worked on.

Version 11.22.1 with every `@angular/*` dependency pinned to `20.x.x`, including `@angular/cdk`, `@angular/material`, forms and the router, so the manifest corroborates the last row of the compatibility matrix independently of the README.

Visual regression is handled through Chromatic rather than by screenshot comparison inside CI, and the README gives the invocation directly:

```bash
npx chromatic --project-token=${CHROMATIC_PROJECT_TOKEN}
```

The token comes from the environment rather than the repository, which is the right arrangement for a service that bills per snapshot. Storybook is configured per library rather than at the root, which keeps component-level and app-level previews separate. A `Procfile` and `app.json` sit at the root as well, which is Heroku deployment configuration surviving in a repository that otherwise publishes documentation through a version-stamped `ghpages:deploy` script.

## Conclusion

What Covalent actually is, once the branding is set aside, is an Nx monorepo that carries a component library, a documentation app, a Storybook, a Knapsack bundle and a design-token pipeline across Angular major versions one at a time. Ten releases in the compatibility table, one per Angular major, is the clearest statement of its maintenance model in the repository. The README's duplicated Angular Support heading and its stray `...existing code...` marker are real defects, and the honest read is that documentation is maintained alongside code rather than derived from it. If you are evaluating it, the `libs/tokens` style-dictionary build and the `decorate-angular-cli.js` shim are the two things worth understanding first, and if you only need the visual language, `libs/foundations/public` serves over a plain http server with no build at all.

## FAQ

### What Angular version does the current Covalent release support?

Covalent 11.x targets Angular 20.x, and package.json pins every @angular dependency to 20.x.x, including @angular/cdk and @angular/material. The README's compatibility matrix pairs Covalent 2.x with Angular 8 through 11.x with Angular 20, one Covalent major per Angular major, with the exception of 3.x, which covered Angular 9, 10 and 11 together.

### Can I use Covalent without Angular?

Yes, through the web components library, which the README describes as comprehensive and covers in three separate documents: a components quickstart, a theming guide and a developer guide. That is the path intended for consumers who need Teradata's visual language outside an Angular application, and it is the part of the repository with the most dedicated documentation.

### Does Covalent support mobile browsers?

Partially, and the project says so rather than implying otherwise. The README states Covalent is built on a Flexbox layout and relies heavily on it, marks Chrome, Firefox, Safari and Edge as supported, and marks Mobile Chrome and Mobile Safari with a tilde that the legend defines as limited testing and lower priority. The stated browser policy is the current version minus one.

### How do I run the Covalent documentation locally?

The setup section asks for Node 22.16.0 or newer, then `npm ci` to install packages, then `npm run start`, which resolves to `nx serve docs-app`. Design tokens alone need no build at all: `dev:foundations` serves libs/foundations/public on a python http server at port 8000, and `storybook` starts Storybook against the components library configuration.

## Sources

- [License: MIT](https://github.com/Teradata/covalent/blob/main/LICENSE)
- [Project website](https://design.teradata.com)
- [README](https://github.com/Teradata/covalent/blob/main/README.md)
- [Releases](https://github.com/Teradata/covalent/releases)
- [Teradata/covalent on GitHub](https://github.com/Teradata/covalent)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/teradata-covalent