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.
Design examples
Section titled “Design examples”Display, heading, body and small text keep the square rhythm. The edition uses the mono face.
<section class="specimen">
<ds-text literal size="display">Rooms of light</ds-text><ds-gap></ds-gap><ds-row class="line" ><ds-text literal strong>Photographs by Nia Vale</ds-text></ds-row><ds-row class="line" ><ds-text literal >Silver prints, made beside the coast.</ds-text></ds-row><ds-row class="line" ><ds-text literal class="mono" size="small" tone="muted">Edition 024 / 100</ds-text></ds-row>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style> Regular, strong, small, warning and danger text retain a consistent line.
<section class="specimen">
<ds-row class="line" ><span class="mark"><ds-icon type="page" size="large" aria-hidden="true"></ds-icon></span><ds-text literal strong>Field notes</ds-text></ds-row><ds-row class="line" ><span class="mark"><ds-icon type="check" size="large" aria-hidden="true"></ds-icon></span><ds-text literal >Proofs approved</ds-text></ds-row><ds-row class="line" ><span class="mark"><ds-icon type="calendar" size="large" aria-hidden="true"></ds-icon></span><ds-text literal tone="warning">Collection closes tomorrow</ds-text></ds-row><ds-row class="line" ><span class="mark"><ds-icon type="warning" size="large" aria-hidden="true"></ds-icon></span><ds-text literal tone="danger">One photograph is missing</ds-text></ds-row><ds-row class="line" ><span class="mark"><ds-icon type="info" size="large" aria-hidden="true"></ds-icon></span><ds-text literal size="small" tone="muted">Last edited this morning</ds-text></ds-row>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style> Try it
Section titled “Try it”Slot text is the translation key and the fallback.
<ds-text>Welcome to the app</ds-text>
<ds-text text="Save" strong></ds-text>
<ds-text tone="danger" wrap>Could not save your changes</ds-text> Translation keys
Section titled “Translation keys”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.
| Attribute | Type | Default | What it does |
|---|---|---|---|
text | string | Empty | Translation key. Without it, slot text supplies the key. |
literal | boolean | false | Show the text as written. Cut at its width, it fades over its last square, never an ellipsis; text that fits stays crisp. |
tone | muted, title, warning, danger | None | A 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. |
size | small, heading, display | None | 10px; a 13px heading on one square; a 20px title on two squares. |
strong | boolean | false | The medium weight. |
wrap | boolean | false | Let 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.
Headings and messages
Section titled “Headings and messages”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.
Cut words fade
Section titled “Cut words fade”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 changesA 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.
Interface copy and writing
Section titled “Interface copy and writing”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.
Keep markup outside the text
Section titled “Keep markup outside the text”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
Contrast
Section titled “Contrast”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>`.