Constraints
Constraints are the rules every piece of Design system 1 keeps, so a page never has to be corrected by eye. They are measured in pixels and squares, not judged. Each picture below is drawn with the system’s own pieces and magnified under a glass, its pixels ruled in and the rule drawn in blue. Move the pointer over a picture and the glass follows it.
On the squares
Section titled “On the squares”Everything is counted in squares of 20 pixels, multiplied by --sf on phones and tablets (see Scaling). Widths are whole squares, heights are whole squares, and gaps are whole squares or half a square at most. Nothing takes a size of its own.
A piece that fills its squares is drawn one pixel short at its end and foot (--margin-correction), so two pieces side by side or one above the other meet on the grid line with a pixel of paper between them. Lines are one pixel. To see the squares behind a page while you build it, lay a Grid under it.
Fault lines
Section titled “Fault lines”Open Constraints (five presses of C, or ?constraints=1 for the owner) to draw Fault lines on the page. Dashed blue lines show the reference edges across the viewport; solid red segments show actual edges that drift, with actual and reference gap labels. Choose Lines to collapse the results panel and see the page unobstructed; Results brings it back. Narrow viewports start in Lines mode. The overlay follows scrolling and resizing, never intercepts clicks, and disappears when Constraints closes.
The CLI saves an annotated viewport screenshot whenever Fault lines finds drift or a review candidate, under test-results/constraints/ (override with --artifacts PATH). Each filename includes its viewport width and page; the screenshot centres the first affected group.
Fault lines are the continuous alignment lines made by related groups of cards and controls across a page. Their outer edges, column boundaries and gaps should continue from one section to the next. Two grids can each use valid spacing yet break those lines: a 20px gap in one and a 10px gap in the next shifts their inner edges.
Headings, paragraphs and text tabs that are direct siblings in a semantic content column (main, article, section or [data-ds-prose]) must share their leading visible text edge. The check follows open shadow roots and slots to the words: an intentional negative tab margin is valid only when its inner padding compensates for it. Nested columns are checked independently; centred text and hidden labels are excluded. Use data-ds-fault-column for another column container, or data-ds-fault-lines="off" for an intentional independent alignment. The overlay marks the expected column and the drifting text edge.
The page.fault-lines check measures actual rendered edges and gaps across separate sections, including open shadow roots. Give grids that share tracks the same data-ds-fault-lines="filters" value. Use data-ds-fault-axis="y" for horizontal alignment lines through related rows; the default compares columns. Groups are compared at their current track count so coordinated responsive reflow is valid. Different card heights are allowed; hidden content and differences of at most one CSS pixel are ignored.
<div data-ds-fault-lines="filters" class="view-cards">…</div><section> <div data-ds-fault-lines="filters" class="product-cards">…</div></section>Unlabelled card/button grids sharing outer edges are also compared, but uncertain relationships are reported for review rather than failing a release. Name a related family to enforce it. Use a different family or data-ds-fault-lines="off" for an intentional independent layout, not to hide a genuine fault. A one-column Signal list, for example, need not share the two-column filter grid.
Run the check across the whole page at each viewport, not once at desktop size. The Site inspector and CLI now default to 320, 375, 393, 430, 768, 1024 and 1440px. Add widths immediately before and after the product’s breakpoints with --widths; no finite sweep proves every possible width. Findings name the viewport and measured drift. The source regression reproduces mismatched 20px/10px card gaps, shifted edges, subpixel rounding and responsive reflow in Chromium and WebKit. Reach uses one family and one gap for its view, Product and Country cards.
Nothing collides
Section titled “Nothing collides”Two pieces never stand on the same pixels. Rows stack edge to edge with no gap and no overlap; columns stand whole squares apart; a menu stands half a square from the button that opens it. What a piece draws beyond itself goes only where nothing else is:
- a pressed row’s layer reaches two pixels past what the row holds, into the spare four above the next row’s words, never onto them;
- keyboard focus is ringed two pixels inside a row, so the rings of two rows stacked edge to edge never touch;
- words that do not fit fade over their last square where they are cut; they never run under the next column.
Anything a person can move lands on whole squares, and never on another piece. While it moves it follows the pointer freely; where it would collide is shown, and on release it lands on the nearest whole squares that are free.
The sixteen
Section titled “The sixteen”In a square, words, pictures and controls take the lower sixteen pixels, with the spare four above them. A 14px line of text is set on a 16px line box standing against the foot of its square; a 16px icon and a 16px control stand on the same sixteen. Centring in the twenty is wrong: the words would sit two pixels higher than in every other row.
| Where | The rule |
|---|---|
| A row, one square high | align-items: flex-end and a 16px line, so everything ends on the row’s bottom line |
| A line on its own: a heading, a date, a label | 4px above it and a 16px line, still one square |
| A square with a rule at its foot: a table cell, a tab bar | 3px above the sixteen, then the 1px rule; never a 19px line |
| Prose that wraps | 20px lines, one square a line: the one exception |
A list on the grid
Section titled “A list on the grid”A list is rows one square high, stacked edge to edge. Across a row, a picture takes the first sixteen of its square, flush with the square’s edge; the words begin on the next square, so the square’s spare four stand between them. Words without a picture begin on the square’s edge. Numbers end on the row’s last square in tabular figures, so a column of them lines up digit for digit.
Lists, rows and their headers stand on the paper with no fill of their own. Colour is for a meaningful state, such as the open or current row, never decoration across a list.
A face you add
Section titled “A face you add”The system’s faces stand on the sixteen as they are drawn. A face you add, for a library or a product, has its own ascent and descent, so at 14px on a 16px line its capitals stand a little higher or lower: often less than a pixel, which is enough to make every row look wrong.
@font-face puts it on the same baseline, so every component sets it right without a nudge of its own.Where a line box puts the baseline follows from the face’s vertical metrics: in a 16px line at 14px it stands 8 + 7 × (ascent − descent) pixels down, each as a fraction of the em. GT America’s ascent is 1 and its descent 0.258, which puts the baseline 13.2px down the line, 3px above the square’s foot; its capitals, 0.71 of the em, are 10px tall and stand 3px inside the sixteen at both ends.
To put an added face on the same line, give its @font-face the same difference between ascent and descent, and, if its capitals are taller or shorter, the size that makes them 10px:
@font-face { font-family: "My face"; src: url("my-face.woff2") format("woff2"); /* GT Canon: ascent 1, descent 0.37, capitals 0.705 of the em. Its descent set to 0.258 gives GT America's 0.742; its capitals are within a percent, so no size-adjust. */ ascent-override: 100%; descent-override: 25.8%;}- Read the face’s metrics from its file: the ascent and descent the browser uses (the
hheatable, orOS/2typographic metrics when the face setsUSE_TYPO_METRICS) and the cap height, each over the face’s units per em. - Match the baseline with
ascent-overrideanddescent-overrideso that ascent minus descent is 0.742. - Match the capitals with
size-adjust: 0.71 over the face’s cap height. It scales the overrides too, so divide them by the same factor. - Correct the face once, in its
@font-face. Never move its words with padding,topor a transform in each component: every component then sets the face right, and the system’s own faces are left alone.
Correcting a face with the system
Section titled “Correcting a face with the system”DS1/0-face/face-correction.ts does the arithmetic, so no product works it out by hand. Take it with Sync 1, "modules": ["face-correction"] in the root export; it comes with google-face-metrics.json, the measured metrics of the Google faces 0001’s products offer.
correctFaces(css, metrics)returns a stylesheet of@font-facerules, Google’s css2 answer for one, with every face corrected in its own rule. Run it where the page is built and write the result into the head, so the first paint is already on the sixteen. A face without metrics stops it rather than stand off the line.correctedGoogleFonts(href, metrics)reads a css2 address and corrects it, for a page that chooses its faces while it runs.faceCorrection(metrics)gives the four declarations for a rule you write yourself.readFaceMetrics(file)reads a TrueType or OpenType file.node scripts/face-metrics.mjs "Family"measures a Google face and adds it to the JSON.
Small rules
Section titled “Small rules”Under the big rules stand the small ones: a sentence each, kept by one component and measured by a test of its own. Each has a code that never changes, so a review can name the rule it finds broken. A component’s page lists the rules it keeps.
Overlay
overlay.escape-close- Escape always closes the top sheet, including while typing or with focus outside it; editors, disabled Escape options and close vetoes cannot block it, and unsent drafts are preserved.
Table
table.uniform-text- All table text uses the same default text size, including headers, names, tags, numbers, dates and times.
Page
page.fault-lines- Fault lines keep related card and control grids aligned across the whole page, with matching track edges and gaps. Headings, prose and text tabs in a content column share the leading visible text edge, including labels inside shadow roots and slots, at every checked viewport width.Compare separate sections in the same alignment family; responsive layouts may change together, while unrelated groups and intentional exceptions remain independent.
page.window-width- A page is never wider than its window: nothing reaches past either edge unless something it stands in cuts it off or scrolls it, so a phone never zooms the page out or slides it sideways.A phone widens a page that is too wide and zooms it out, words and all, so a piece one square too wide spoils every piece on the page; check it at every phone width from 320px up.
Select
select.hug- Select and date-picker triggers use hug sizing, never fill sizing or growing to occupy the available row.
Tag
tag.visible-label- Tags always show their complete label, never clipping, truncating or fading it; the surrounding layout gives the tag room or reflows.
Text
text.whole-words- Headings and table headers keep each word intact across lines; only a long word that cannot fit may split at a valid language-specific hyphenation point, with a visible hyphen.Wrap between words or give the heading more room; never leave a final letter on its own, use break-all or anywhere, or insert an arbitrary line break inside a word. Use the correct lang with automatic hyphenation, or a soft hyphen at an editorially verified break; scripts with other line-breaking conventions keep their own typesetting rules.
Color
color.text-contrast- Visible text, including muted labels, placeholders and avatar initials, has at least 4.5:1 contrast against the background it is drawn on.Measure resolved colours through slots and open shadow roots, including transparency and opacity; image backgrounds and effects that cannot be measured need a visual review. In products, contrast-watch.ts measures the theme in use after load and reports each failure as `contrast.<theme>.<component>`.
Avatar
avatar.initial-contrast- Avatar initials have at least 4.5:1 contrast against their rendered fill, including after a theme or identity colour changes.Check each initial inside the avatar’s shadow root and in overlapping groups; decorative initials still need to be readable. Explicit ink overrides must pass too.
Card
card.media-level- A card's picture stands on the card's foot, a square below the words at least, so the pictures of cards side by side stand on one level whatever the words above them.The room a taller card leaves goes above its picture, never below it, so pictures of one height side by side start on one line too. Pictures of different heights side by side take one room (`media-height`, `--ds-card-media-height`) and start on one line, the foot cutting the taller.
card.media-corners- A picture is never rounded where it meets the card's edge: the card cuts it square there, and only a corner standing free inside the card, towards the words, keeps a picture's corner.
Window
window.shape- A window with a computer's chrome keeps a computer window's shape whatever it holds, 16:10 and never taller than it is wide, and stands no taller than 4:5 on a phone's width.What a window holds comes to the window: its page is cut by the foot or zoomed out as one picture, and the window never grows to fit it or to fill a column beside it.
Carousel
carousel.sideways-scroll- Only a carousel scrolls pieces sideways: pieces wider than their column stand in a carousel strip or stack, and nothing else scrolls sideways but a table, a block of code or a matrix in its own frame.A box given overflow auto to keep a page in its window hides what is past its edge with nothing to say it is there, no snap and no controls, and a phone slides it where a finger meant to scroll down; make it a ds-carousel strip (slide-width="auto") or stack it.
Checking a page
Section titled “Checking a page”Every small rule is also a check that measures a page as it is drawn. On a page built on Design system 1, add ?constraints=1 to the address and a panel opens at the page’s side once it has loaded. It lists each place the page breaks a rule: the rule’s code, what is wrong in measured values, and the element ringed on the page. Press one to scroll to it, and Page to measure again after a change. Escape hides it. Under what is broken, Rules says what each rule measured and whether it kept, for example “Kept by 1,204 pieces measured on this page”, or that the page has nothing for it to measure. The page’s owner can also open it with C pressed five times.
Site checks the whole site the same way, at every phone width. Each page in the site’s sitemap opens once, out of sight, in a frame that is then made 320, 375, 393 and 430px wide in turn, the page drawn at each phone’s scale; three pages are checked at a time. Every rule is measured, and each one a page breaks is listed with its width, what is wrong, the element and a link to the page. When it ends, Rules counts what each rule measured over every page view, and Pages lists every page it checked, kept at every width or broken at which ones. ?constraints=site opens the panel on that check. The frames’ addresses carry ph=out, so analytics that honour it count no visits, and anything the pages store in the browser is put back afterwards.
The panel comes with the grid shortcut (0-face/grid, Sync 1’s root "modules": ["grid"]), or alone as "constraints" (0-face/constraint-panel) for a site that shows no grid, and starts itself when the page loads it. Unlike the grid, five presses of C answer the owner alone; for anyone else they do nothing. The address opens the panel for anyone, since it only measures:
- A site with sign-in sets
data-ds-owneron<html>once its server has said the person signed in owns it, and takes it off when they sign out. - A site without sign-in has no owner to ask, so the owner switches on each browser they check it in, once: open any page of the site with
?ds-owner=onadded to its address, and the browser remembers it for that site.?ds-owner=offforgets it. The panel measures the page and shows nothing else, so a browser switched on shows no one anything private. A product whosepackage.jsonlists itssideEffectsmust name the copied0-face/grid.tsand0-face/constraint-panel.tsthere, or a bundler drops a script imported for what it does and the panel never reaches the page.inspectConstraints()returns the same list to a script or a test.
On every phone
Section titled “On every phone”A page has to keep the rules at every phone width, not only on the phone in your hand. When anything on a page is wider than the window, a phone widens the whole page and zooms it out, so its words shrink and it slides sideways. A piece that fits at 393px can break at 320px. The phone check opens every page of a site, as its sitemap lists them, in WebKit as an iPhone 320, 375, 393 and 430px wide. It scrolls each page through, then runs every rule on it and lists what each page breaks at which width:
vp run constraints:phone https://example.comvp run constraints:phone https://example.com --widths 320,393 --pages /,/about/It only reads the site, without cookies, so it is safe to run against production. It fails while anything is broken, so run it before releasing a site built on a library. The scale (0-face/scaling) keeps a page that a phone has zoomed out from getting worse: it never takes the page’s width as wider than the screen’s, so the scale cannot grow and widen the page further.
A new small rule goes into DS1/0-face/constraints.ts with its inspect, which measures it on a page, and a source test that measures the component; the component keeps it in its own CSS, and vp run constraints:write copies the list into the design-system-1 skill.
Checking it
Section titled “Checking it”Measure in the browser rather than judging by eye:
- an element’s width and height are whole squares, less the one pixel of correction where it fills them;
- a 14px capital’s top is 7px below the row’s top grid line and its baseline 3px above the next;
- a 16px icon’s foot is on the row’s bottom line;
- no two elements’ boxes intersect, except a layer drawn over its own row.
The color.text-contrast rule checks actual rendered text, including component shadow roots, slots, input values and placeholders. It reports ratios below 4.5:1 and backgrounds or effects requiring visual review. See Text contrast for scope and state checks.