X-ray and conformance
Label every element of a page in the desktop browser by design system, file a one-off as a request, and add a conformance block to a pull request.
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 X-ray shows which parts of a running page come from your design system and which don't. It reads the page in the session's browser and labels each element it recognises. The same rules give a pull request a conformance block, so a reviewer sees the numbers without opening the app.
Before you start:
- Your org needs the
designmodule and thebrowsermodule. When staff turn off thedesignkill switch, the X-ray is gone from the menu. See kill switches and modules. - The session needs a product. Without one, the X-ray says "This session has no product, so the X-ray has no rules to read."
Desktop app only
The X-ray lives in the session's browser pane, which is part of the desktop app.
What the labels mean
The X-ray counts only the systems the session's product uses. Each element it finds gets one of four labels:
| Label | What it means |
|---|---|
| System | Built from a current system's component, with its tokens and its slot. The pin names the component. |
| Old kit | Built from a component of a system that is retiring. The pin names the old kit and the component. |
| One-off | Hand-built on a system's tokens, with no component slot that system knows. |
| Unlabelled | Carries a slot a system knows, but none of that system's tokens. This is the X-ray's blind spot. |
An element with neither a token nor a known slot is not shown and not counted. A child that belongs to the same component folds into its parent, so one component counts once.
When a page names a component's version in a listed attribute and that version is one of the system's releases, the pin shows it, for example v1.4.0.
Set the identity attributes
The X-ray names a component only from attributes your org lists. Your pages might mark each part with data-slot="button", for example. Until the attribute is listed, the X-ray still counts system and old-kit parts, but it can't name the component or find one-offs. The panel then says to add the attribute to the identity attributes.
Every member can read the list. Only an org owner or admin can change it.
Open Settings, then Design.
Under Identity attributes, press Add attribute. You can have up to 8.
Type the attribute name, such as data-slot. Names that start with data-ec-, and data-cid, are reserved.
Pick the pattern: One name, Several names or Version. Set the max length, a whole number from 1 to 120.
Press Save attributes.
Scan a page
In a session on your product, open the page in the browser pane.
Open Tools in the pane's toolbar and turn on X-ray.
Read the counts at the top of the panel: System, Old kit, One-off and Unlabelled. Below them, the pins are grouped by label.
Press a pin to select its outline on the page. Each outline is numbered and coloured by label.
The page only gets boxes, colours and numbers. Names stay in the panel. The outlines never appear in screenshots, crops or recordings.
Moving to another page clears the X-ray. Press Rescan to read the page again, or Turn off to hide it.
When the panel shows a note
- "This product uses no design system." The product's systems are not declared. You can still file a bug, see below.
- "Northwind UI has no release, so its parts read unlabelled." A system needs a release and a render catalogue before the X-ray can name its parts.
- "Some parts of this page can't be read." Closed shadow roots and frames from another origin are skipped.
- "Showing 300 of 412." Long pages list the first pins only. The counts stay whole.
- "The X-ray couldn't read this page." Press Rescan.
File a one-off as a request
A one-off is a part someone built by hand that the system should probably cover. You can turn it into a design request in two clicks.
Find the pin under One-off and press File request.
Read the preview. It is a request on the system whose tokens the part uses, or on its replacement when that system is retiring. The title reads "One-off to replace with a Northwind UI component".
Press Create request. The request goes to the system's maintainers. Press Open request to see it.
The crop of the part stays in your session. The request does not carry it.
When there is no system to file on, the button reads Create bug instead and files a bug under the task you are testing. With no system and no task under test, the button is off and says why. To learn how requests move, see design requests.
Add a conformance block to a pull request
When a session proves a change in the browser, it runs proof_run. Ask it to pass conformance: true. The runner then takes a snapshot at the end of each flow, labels it with the same rules as the X-ray, and adds a Design conformance block beside the proof block in the pull request's body. Your own gh writes it, as it writes the proof.
The block holds:
- the systems and their versions, with "(retiring)" after an old kit,
- one row per flow with the System, Old kit, One-off and Unlabelled counts,
- the names of old-kit components still in use, with their counts.
It never holds a URL, page text or an attribute value. Each flow is listed by name, with any secret in the name redacted. Every name in the block is encoded so GitHub never turns it into a mention, an issue reference or a link. When a system's rules are missing, the block says so.
A reviewer reads the counts to see whether a change moved a page toward the system. For a team-wide view across products, see audit and adoption. To test in the browser pane, see browser testing.
Something wrong or missing? Suggest a change