# The design system record

Design systems as products in EasyCode: systems, releases, tokens and components read from the code, in step with every merge and tag.

> **In the pilot**
>
> The design system module is in the pilot: it is on for pilot orgs first. An org admin can tell you whether your org has it.

A design system is its own kind of product in EasyCode. It has a record: its sources, its components, its tokens and
its releases. EasyCode reads that record from the design files your repos declare, so it follows every merge and every
tag.

The pages sit behind the module `design`. With it off, the **Design systems** rail item and the system pages are
gone, and a design system shows as an ordinary product.

## Who can do what

- **Admins** make a design system, mark an existing product as one, import systems, and keep the approved hosts.
- **Maintainers** edit a system's identity and sources, and approve upgrade notes.
- **Contributors** draft upgrade notes and work on its tasks.
- **Every full member** sees every system. A guest sees one only through an explicit grant.

## Find a design system

**Design systems** in the rail lists every system you can see. The chips filter by status: draft, current or
retiring; press one again to clear it. Each row shows the system, its sources line, a status badge, **Required** when
teams must use it, and "Replaced by" and the new system's name on a retiring system. The right side counts consumers, such as "4 products,
2 more you can't see". With no systems, an admin sees **New design system**.

## Make a design system

There are three ways, all for admins:

- **New product**, with **Kind** set to **Design system**. A design system always has a base role of at least
  **Can view**, so every member sees it.
- **Mark as a design system**, in the **Kind** section of an existing product's settings. It makes a draft system.
- **The org import.** The bundle that `easycode org import` applies can hold `design_systems[]` (status, replaced by,
  required, traits and sources) and `uses[]` (which product uses which system, and how). Without `--apply` it prints
  what would change.

**Make it an ordinary product** undoes a mistake. It is refused while a product uses the system and once the system
has a release: a system with a history is retired, not unmarked.

## Describe the system

The **Overview** shows who the system is for. Maintainers press **Edit** to set:

- **Status**: draft, current or retiring. A retiring system names what replaces it, and the systems it replaces show
  "Replaces".
- **Required**: "Required: teams must use it", or optional.
- **Traits**: where tokens and components are edited first, how it is delivered, and its frameworks.
- **Where to ask**: one line that tells a team how to reach the system's people.

## Add a source

A source is where part of the system lives: a repo, a package, a registry, a Storybook, a design file, a base kit, a
docs site or authored content. Each has a role (such as `spec` or `tokens`) and says what it holds the truth for.

### Open Add a source

On the system's **Overview**, press **Add a source** and choose its type.

### Fill in its fields

For a repo, choose the repo and declare its design files: token files, spec files and a `registry.json`, as path
patterns. Set the tag pattern; it is `v*` when you leave it empty.

### Save

A repo source links the repo to the system. EasyCode reads the declared files at the repo's head straight away.

Token and spec files are JSON or YAML; tokens follow DTCG. The Overview lists each skipped file with its reason.

## Read the record

A system has these tabs: **Overview**, **Components**, **Tokens**, **Open changes**, **Releases**, **Consumers** and
**Requests**, then **Board** and **Knowledge**.

- **Components** lists each component with its status, a mark per library and its story count. A component page shows
  props, variants, slots, states and story links.
- **Tokens** has tabs for Primitive, Semantic and Component tokens, with one column per theme.
- **Consumers** lists the products that declare they use the system: how they take it, their theme, their declared pin
  and the found version. A product that EasyCode cannot measure yet reads "Declared, not detectable yet", never zero.

When the system has a release and newer work on its default branch, a switch in the header moves between
**Released v1.2.0** and **Unreleased**.

## Stay in step with the code

EasyCode reads a repo source when its default branch moves, when a tag is pushed, and when you add or edit the source.
An hourly check catches anything GitHub did not send. The Overview shows one line per source, such as "React v1.2.0 ·
3 changes unreleased", with **Last read**, **Commits behind** and **Why** (when a read failed) under it.

## Releases

A tag that matches a repo source's tag pattern and reads as a version (`v1.3.0`, `1.3.0-beta.1`) becomes a release.
**Releases** lists them per source, newest first, with the tag, the date and the level. A release page says what
changed in three blocks:

1. The structural change: components and tokens added, removed and changed.
2. The authors' words, from the GitHub Release body, or "No notes from the authors".
3. The upgrade note. A contributor or maintainer presses **Draft an upgrade note**, which makes a docs task; a session
   on that task writes the note, and a maintainer approves it.

When the version and the change disagree, the release says so, for example "This says patch, and a prop was removed:
Button.size". A deleted or moved tag withdraws its release, which shows **Withdrawn**.

## Who sees source details

File paths and line numbers come from repos, so a member who cannot read a repo on GitHub sees "Source hidden" in
their place, and the Overview shows the repo's name with "You can't read this repo". Consumers you cannot see are counted, never named: "2 more products you can't see".

## Approve the hosts

Story links, the story index and preview frames only open from hosts an admin approved. Admins list them in
**Settings → Design** under **Approved hosts**, one `https://host` or `https://*.host` per line. Members can read the
list.

## Next

- [Design in every session](/design-system/in-every-session)
- [Design requests](/design-system/design-requests)
- [Products and repos](/setup/products-and-repos)
