The audit and the adoption number
What each product uses from your design systems: the audit of a repo's UI, hand-typed values by file and line, and the adoption counts.
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 yours has it.
The audit shows what a product's code really uses: components from each design system, components from an old kit, native controls built by hand, and colours, sizes and spacing typed straight into the code. The same counts become the adoption number on each system's Consumers page.
Before you start:
- Your org needs the
designmodule and a code index (the knowledge scan). With the code index off, the audit reads "The code index is off, so there is nothing to audit". When staff turn off thedesignkill switch, the audit is unavailable. See kill switches and modules. - Members with a role on the product can read its audit. Guests can't.
- The product needs a linked repo. See products and repos.
Get the scan the audit needs
The audit reads the facts a knowledge scan extracts from your repos. The scan runs on a desktop app: it reads CSS, SCSS and Less files, Vue <style> blocks, and the components used in TSX and Vue templates.
Desktop app only
Scans run in the desktop app. A desktop app on the latest version rescans each repo it holds; an older one can't produce the facts the audit reads.
Until a repo is scanned, the audit reads "Not scanned since the audit existed". See set up knowledge to start scanning. Scanning the same commit again gives the same numbers.
Open a product's audit
Open the product and go to its Design system tab.
Scroll to the Audit section.
Read the line at the top. It says how many of the product's repos were counted and how old the oldest scan is. Repos you can't read on GitHub are counted as a number, never named, and left out of the totals.
If the product has no repo, the section says "Link a repo to audit this product".
Read the four counts
The audit always shows four counts side by side, never one percentage on its own:
- System uses: components from a current design system, by package or by UI files copied into the repo.
- Old kit uses: components from a system marked retiring.
- One-off uses: native controls, such as a hand-built button or input, outside the folder your copied-in UI lives in.
- Other uses: everything else.
Under them, Uses per system lists each system the product declares, with its count. A declared system with no uses shows 0, which tells you the code has not adopted it yet.
Find hand-typed values and old kits
Pick a list:
- Values: colours, font sizes, spacing, radii, shadows and fonts typed into the code. Filter by Category or search by value. A colour row shows a swatch.
- Tokens: tokens the repo defines itself, such as custom properties and Sass or Less variables.
- Components: each component used, with its bucket, its source and how often.
- Not read: what the scan could not read and why, such as CSS-in-JS, computed values or runtime themes.
Each list shows its first 200 rows; Show more loads the rest.
Press a row. A sheet lists every place it is used, as repo/path:line.
Press a place. GitHub opens at the scanned commit and that line.
Use this to find the hand-typed colours to replace with tokens, or every use of an old kit's component before you retire it.
Read the adoption number on Consumers
Each design system has a Consumers page listing the products that declare they use it. For each product you see how it takes the system, its theme, its declared pin, its found version, and four counts: System uses, Old-kit uses, One-offs and Other, with when they were counted.
The counts update after a scan of one of the product's repos. A product that has not been scanned reads "Not detectable yet", never 0.
Products you can't see are not named. A line at the bottom says how many there are, with their counts summed into one row.
For the found version on the same page, see found versions and update tasks.
Start from an empty page
The audit is useful before you have a design system on record:
- When your org has no design system yet, the Design systems page reads "No system to show yet. See what your products use today". Press Choose a product to audit, pick one, and press Open audit.
- A system's Overview with no sources offers the same choice.
Either way you land on that product's Audit section, where you can see which kits and hand-typed values are in use today.
Related
Something wrong or missing? Suggest a change
Review a design change on live frames
Review a pull request's design change on live frames: base beside the change, by theme and device, with comments through your own gh.
Found versions and update tasks
How EasyCode finds the design system version each product is on and keeps one update task per product and system.