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 importapplies can holddesign_systems[](status, replaced by, required, traits and sources) anduses[](which product uses which system, and how). Without--applyit 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:
- The structural change: components and tokens added, removed and changed.
- The authors' words, from the GitHub Release body, or "No notes from the authors".
- 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
Something wrong or missing? Suggest a change