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.

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.

BriefSketchReviewPrint
An item is four squares wide and one high, 80 by 20 apart, drawn 79 by 19: the last pixel is paper, so two items meet without touching.

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.

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.

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.
OverviewProjectsStarred
Rows stand edge to edge with nothing between them. The open row's layer is drawn over it, two pixels past what it holds, and reaches only into the next row's spare four: it stops two pixels short of the next row's words.

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.

Drag a block, or focus it and use the arrow keys. It follows the pointer, shows where it would collide in the danger colour, and lands on the nearest whole squares that are free.

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.

Monday12:30
Words, icons and controls take the lower sixteen pixels of their square, the spare four above. A 14px capital's top is then 7px below the square's top line and its baseline 3px above the next; the icon's foot is on that line.
WhereThe rule
A row, one square highalign-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 label4px above it and a 16px line, still one square
A square with a rule at its foot: a table cell, a tab bar3px above the sixteen, then the 1px rule; never a 19px line
Prose that wraps20px lines, one square a line: the one exception

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.

Notes12Calendar3Starred128
The icon takes the first sixteen pixels of its square, flush with its edge; the words begin on the next square, so the spare four stand between them. Counts end on the row's last square in tabular figures, so their digits line up.

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.

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.

HxgHxgHxgGT AmericaAs drawnAdjusted
GT Canon drawn as it comes stands half a pixel higher than the system's face. One descriptor in its @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 hhea table, or OS/2 typographic metrics when the face sets USE_TYPO_METRICS) and the cap height, each over the face’s units per em.
  • Match the baseline with ascent-override and descent-override so 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, top or a transform in each component: every component then sets the face right, and the system’s own faces are left alone.

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-face rules, 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.

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.

Button

button.visible-label
Button labels stay fully visible, never faded, gradient-masked or truncated; round the required width up to whole grid squares.The action must remain readable; a chosen width cannot cut off its label.

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.

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-owner on <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=on added to its address, and the browser remembers it for that site. ?ds-owner=off forgets it. The panel measures the page and shows nothing else, so a browser switched on shows no one anything private. A product whose package.json lists its sideEffects must name the copied 0-face/grid.ts and 0-face/constraint-panel.ts there, 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.

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:

Terminal window
vp run constraints:phone https://example.com
vp 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.

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.