One box of a how-it-works diagram: its kind, its name and what it does, with the dots its arrows meet.A block is copied, not installed: take an example's code and the stylesheet at the foot of the page, and rename the site- prefix to your project's own.
Examples
Usage
A part of the system, with a dot on each side for the arrow that comes in and the one that goes out.
Token build
Writes the CSS and code tokens from the design file
Every kind
The five kinds, in the order data moves: an input, a part, a store, an output, and something outside the system, dashed. A node with nothing going out has no dot on that side.
Design file
The colors, sizes and type the designers set
Token build
Writes the CSS and code tokens from the design file
Token files
Every token, kept in the repository
Stylesheet
One file every page links
Font service
Serves the typefaces the pages name
Selected
Chosen: a thicker edge in the info color and the raised shadow, on any kind.
Token build
Writes the CSS and code tokens from the design file
Font service
Serves the typefaces the pages name
Built from
Guidelines
Purpose
Draws one box of a diagram that shows how a system works: what kind of thing it is, its name, a line on what it does, and a dot on each side where an arrow comes in or goes out. Five kinds: a part, an input, an output, a store and something outside the system, each chosen or not.
When to use
- In a diagram that explains how the parts of a system pass things to each other.
When not to use
- For a step in a process a reader follows. Use a stepper or a timeline.
- For an item a reader picks from a list. Use a card or a list.
Usage rules
Do
- Name each box with a noun a reader knows, and say what it does in a few words.
- Keep the arrows going one way, left to right or top to bottom.
Don't
- Make a box a button without its own focus and pressed looks.
- Show which box is chosen by color alone.
Anatomy
- The box: its own edge, small corners and tight room, on the default surface; a store sits sunken, and something outside has a dashed edge.
- The top line: the kind's icon, the Icon component, on a small tile in the kind's color, and the kind in the small code style, in capitals.
- The name in the medium label style.
- The line on what it does, in the extra small body style.
- The dots, one on each side the arrows meet. Leave out the dot on a side no arrow uses.
Behavior
The box takes no focus and does nothing when pressed: it is a drawing. The page draws the arrows between boxes, from one dot to the next, and chooses which box is selected, such as the one a reader is reading about.
Accessibility
What it does for you
- The kind is said in words, never by the tile's color alone.
- The dots and the icon are hidden from assistive technology.
- A selected box is marked as the current one, and shown by a thicker edge as well as its color.
What you must do
- Put a text version beside the diagram: a list of every arrow, such as "Design file goes to Token build". The boxes alone do not say what connects to what.
- Mark the selected box both ways, with its selected class and
aria-current="true", as the examples do.
How to test
- With a screen reader, each box reads its kind, its name and its line, and the selected one is read as current.
- In a forced-color mode, the selected box still stands out by its thicker edge.
Source
The diagram node's own layout, its classes under the site- prefix. The components inside it are drawn by the design system's stylesheet.
Stylesheet
/* site-diagram-node — Diagram node, a block: one box of a how-it-works diagram, its kind, its name and what it does,
* with the dots its arrows meet. Copy it into your project and rename site- to your project's own prefix. It is not
* built on the Card: its corners are smaller, its room tighter, and it has a dashed edge for what sits outside and
* a blue edge for the one chosen, so the block draws its own box from tokens. The icon is the Icon component. The
* lines between nodes are the page's to draw. */
.site-diagram-node {
position: relative;
display: flex;
flex-direction: column;
gap: var(--smbk-space-6);
box-sizing: border-box;
padding: var(--smbk-space-inset-md);
border: var(--smbk-border-width-hairline) solid var(--smbk-color-border-subtle);
border-radius: var(--smbk-radius-container-sm);
background: var(--smbk-color-surface-default);
color: var(--smbk-color-text-default);
}
.site-diagram-node__top {
display: flex;
align-items: center;
gap: var(--smbk-space-6);
}
/* The kind's icon on a small tile in the kind's color. */
.site-diagram-node__tile {
display: grid;
flex: none;
place-items: center;
box-sizing: border-box;
width: var(--smbk-size-20);
height: var(--smbk-size-20);
border-radius: var(--smbk-radius-control-xs);
background: var(--smbk-color-feedback-info-surface-subtle);
color: var(--smbk-color-icon-default);
}
.site-diagram-node__kind {
color: var(--smbk-color-text-subtle);
font-family: var(--smbk-typography-code-sm-font-family);
font-size: var(--smbk-typography-code-sm-font-size);
font-weight: var(--smbk-typography-code-sm-font-weight);
line-height: var(--smbk-typography-code-sm-line-height);
letter-spacing: var(--smbk-typography-code-sm-letter-spacing);
text-transform: uppercase;
}
.site-diagram-node__title {
margin: 0;
font-family: var(--smbk-typography-label-md-font-family);
font-size: var(--smbk-typography-label-md-font-size);
font-weight: var(--smbk-typography-label-md-font-weight);
line-height: var(--smbk-typography-label-md-line-height);
letter-spacing: var(--smbk-typography-label-md-letter-spacing);
}
.site-diagram-node__detail {
margin: 0;
color: var(--smbk-color-text-subtle);
font-family: var(--smbk-typography-body-xs-font-family);
font-size: var(--smbk-typography-body-xs-font-size);
font-weight: var(--smbk-typography-body-xs-font-weight);
line-height: var(--smbk-typography-body-xs-line-height);
letter-spacing: var(--smbk-typography-body-xs-letter-spacing);
}
/* The dots an arrow meets, half outside the box at the middle of each side. */
.site-diagram-node__port {
position: absolute;
inset-block-start: 50%;
box-sizing: border-box;
width: var(--smbk-size-8);
height: var(--smbk-size-8);
border: var(--smbk-border-width-hairline) solid var(--smbk-color-border-strong);
border-radius: var(--smbk-radius-full);
background: var(--smbk-color-surface-default);
translate: 0 -50%;
}
.site-diagram-node__port--in {
inset-inline-start: calc(var(--smbk-size-8) / -2 - var(--smbk-border-width-hairline));
}
.site-diagram-node__port--out {
inset-inline-end: calc(var(--smbk-size-8) / -2 - var(--smbk-border-width-hairline));
}
/* ---- kind ---- */
.site-diagram-node--kind-input .site-diagram-node__tile {
background: var(--smbk-color-feedback-success-surface-subtle);
}
.site-diagram-node--kind-output .site-diagram-node__tile {
background: var(--smbk-color-feedback-warning-surface-subtle);
}
/* A store, where something is kept, sits sunken. */
.site-diagram-node--kind-store {
background: var(--smbk-color-surface-sunken);
}
.site-diagram-node--kind-store .site-diagram-node__tile {
background: var(--smbk-color-surface-track-subtle);
}
/* What sits outside the system: a dashed edge, and its tile only outlined. */
.site-diagram-node--kind-external {
border-style: dashed;
border-color: var(--smbk-color-border-strong);
}
.site-diagram-node--kind-external .site-diagram-node__tile {
border: var(--smbk-border-width-hairline) solid var(--smbk-color-border-subtle);
background: none;
}
/* ---- selected: a thicker edge in the info color, and the raised shadow. The focus color is the brand's, so it
cannot mark a choice. ---- */
.site-diagram-node--selected {
border-width: var(--smbk-border-width-emphasis);
border-color: var(--smbk-color-feedback-info-border);
box-shadow: var(--smbk-elevation-raised);
}
.site-diagram-node--selected .site-diagram-node__port--in {
inset-inline-start: calc(var(--smbk-size-8) / -2 - var(--smbk-border-width-emphasis));
}
.site-diagram-node--selected .site-diagram-node__port--out {
inset-inline-end: calc(var(--smbk-size-8) / -2 - var(--smbk-border-width-emphasis));
}