Text

A line of interface copy from a translation key, with the key as its English fallback. Its tone, size, weight and wrapping work alike for a key and for text someone wrote.

An exhibition label

Display, heading, body and small text keep the square rhythm. The edition uses the mono face.

Different meanings, one baseline

Regular, strong, small, warning and danger text retain a consistent line.

Text and translation keys

Slot text is the translation key and the fallback.

Slot content is both the key and the fallback: <ds-text>Save</ds-text>. The text attribute is another way to provide the key. Configure languages and load words before displaying translated content.

Text a person wrote, such as a list’s name or an item, is literal: it is shown as it stands and never looked up.

AttributeTypeDefaultWhat it does
textstringEmptyTranslation key. Without it, slot text supplies the key.
literalbooleanfalseShow the text as written. Cut at its width, it fades over its last square, never an ellipsis; text that fits stays crisp.
tonemuted, title, warning, dangerNoneA quieter grey, the title grey, the warning colour (--ds-warning-color) for something that needs care, or the danger colour (--ds-danger-color) for a failure or a loss.
sizesmall, heading, displayNone10px; a 13px heading on one square; a 20px title on two squares.
strongbooleanfalseThe medium weight.
wrapbooleanfalseLet the text run over several lines, each one square.

Without attributes the element is one control high, so it sits in a row of one square. There is no variant attribute.

The element reads as plain text. For a heading, give it a role and a level:

<ds-text role="heading" aria-level="2" size="heading">Settings</ds-text>

A message that reports a failure is announced with role="alert":

<ds-text wrap tone="danger" role="alert">Could not save your changes</ds-text>

A warning that asks for care before something goes wrong takes the warning tone: Orange on dark paper, and Orange’s dim brown on light paper, where Orange itself is too light to read.

<ds-text wrap tone="warning">Your trial ends in three days</ds-text>

Like any element, a hidden one stays out of the page: <ds-text hidden> is not drawn.

Wherever Design system 1 cuts words that do not fit (a literal text, a row’s name, a menu entry, a calendar’s title), they fade out over their last square, never ending in an ellipsis. Words that fit stay crisp. The fade is a mask on the words, so it fades into whatever is behind them, and it runs to the left in a right-to-left page. It is drawn only while the words are marked data-cut="end"; the components measure and mark their own words as they resize, render or change.

A page without Lit marks the native classes (.ds-row__name, .ds-sidebar__label, .ds-menu__item, .ds-badge__label, .ds-notice__title, .ds-progress__label …) with one call from 0-face/cut-fade.ts (Sync 1 root "modules": ["cut-fade"]):

import { startCutFades } from "./0-face/cut-fade.ts";
const stop = startCutFades(); // marks them in the page, and keeps marking them as it changes

A component of your own owns a watcher: watchCuts() with select(root, selector), measure() after each render and disconnect(), or, in Lit, new CutFades(this, { selector: ".label" }), which measures after every update. Its stylesheet clips the words (text-overflow: clip) and fades them under the mark:

.label[data-cut="end"] { mask-image: linear-gradient(to right, #000 calc(100% - var(--ds-unit)), transparent); }
.label[data-cut="end"]:dir(rtl) { mask-image: linear-gradient(to left, #000 calc(100% - var(--ds-unit)), transparent); }

Put the words in an element of their own when their box has a fill, so the fill stays whole.

Copy in an application’s interface (labels, messages, titles) uses ds-text, or the .ds-text classes where the page has no scripts. Long-form and marketing writing stays in native headings, paragraphs and lists, drawn by the prose sheet. Both are Design system 1’s styles.

The component reads and replaces its slot text. Put an icon next to ds-text in a row rather than nesting markup inside it.

Languages · Prose · Row · Fonts

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.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>`.