Fonts and text styling

Choosing a font

You cannot know which fonts a visitor has installed. font family therefore takes a list, called a font stack: the browser tries the names from left to right and uses the first font that exists and has the letters it needs to draw. A name that contains spaces goes in single quotes inside the string. The last name should be a generic family, which every browser can always fill: serif (letters with small feet), sans-serif (without feet), monospace (equal width, for code), cursive and fantasy (decorative, and different on every system) and system-ui (the font of the operating system's own windows). ui-monospace is the system's code font.

page:
    title = "Font stacks"
    global: selector = "body" margin = "1.5rem" line height = 1.6 end
    paragraph: font family = "Georgia, 'Times New Roman', serif" content = "Serif: Georgia, then Times New Roman, then any serif font." end
    paragraph: font family = "system-ui, sans-serif" content = "Sans serif: the interface font of the system." end
    paragraph: font family = "ui-monospace, Consolas, monospace" content = "Monospace: every letter is equally wide." end
    paragraph: font family = "cursive" content = "Cursive: the look of handwriting." end
    paragraph: font family = "NoSuchFont, serif" content = "The first name does not exist, so the browser takes the next." end
end

Look at the last line of the preview. The first name does not exist, so the browser skips it silently and takes the next. This is also how a missing Persian glyph is handled: if the first font has no such letter, the browser asks the next font in the list for that single letter.

Put the rule on body with a global element, as the examples do, and every element inherits it. Only set font family on a single element when that element really needs a different font, such as code.

Size

font size accepts a bare number (pixels), or a string with a unit. The useful units are rem, which is relative to the font size of the whole page, em and %, which are relative to the parent element, and vw, which is a part of the window width. There are also keywords from xx-small to xx-large, and clamp(min, preferred, max), which grows with the window but never leaves the two limits. Prefer rem to pixels for text: people who raise the default size in their browser then get bigger text on your page too.

page:
    title = "Font sizes"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    paragraph: font size = 12 content = "12 means 12px" end
    paragraph: font size = 12 + 6 content = "An expression: 12 + 6 is 18px" end
    paragraph: font size = "1.5rem" content = "1.5rem is one and a half root sizes" end
    paragraph: font size = "150%" content = "150% of the parent size" end
    paragraph: font size = "x-large" content = "The keyword x-large" end
    paragraph: font size = "clamp(1rem, 4vw, 2rem)" content = "clamp() grows with the window, within limits" end
end

The second line is an expression. Any number or string that the compiler can compute is a valid value, so you can also use a constant declared above the page, such as font size = BASE * 2, and change one number to resize many elements.

Before the next sections, try the settings yourself. The slider and the list below run small functions that use the dom package, which is explained in its own page. Each time the slider moves, its function reads the value and sets the CSS property font-size of the sample. Inside such a function, CSS properties keep their original names with dashes.

import dom

page:
    title = "Type tester"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    paragraph: id = "label" content = "Size: 28px" end
    box: display = "flex" gap = 12
        input: id = "size" type = "range" min = 12 max = 64 value = 28
            input = ():
                size := dom.GetValue(dom.ById("size"))
                dom.SetStyle(dom.ById("sample"), "font-size", size + "px")
                dom.SetText(dom.ById("label"), "Size: " + size + "px")
            end
        end
        select: id = "family" change = (): dom.SetStyle(dom.ById("sample"), "font-family", dom.GetValue(dom.ById("family"))) end
            option: value = "Georgia, serif" content = "Serif" end
            option: value = "system-ui, sans-serif" content = "Sans serif" end
            option: value = "ui-monospace, monospace" content = "Monospace" end
        end
    end
    paragraph: id = "sample" font family = "Georgia, serif" font size = 28 content = "Sphinx of black quartz, judge my vow." end
end

Weight, style and width

font weight is a number from 1 to 1000: 400 is normal text, 700 is bold. normal and bold are the same as 400 and 700, and bolder and lighter move one step away from the parent. A font file has only the weights its designer drew. If you ask for 300 and the font has 400 and 700, the browser shows 400, so in the preview below the first lines may look equal. font style chooses upright, italic (a separate design) or oblique (the upright letters leaned over). font stretch and its newer name font width choose narrower or wider designs and only matter for fonts that have them.

page:
    title = "Weight, style and width"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" line height = 1.6 end
    paragraph: font weight = 300 content = "Weight 300, light" end
    paragraph: font weight = 400 content = "Weight 400, normal" end
    paragraph: font weight = 700 content = "Weight 700, bold" end
    paragraph: font weight = 900 content = "Weight 900, black" end
    paragraph: font style = "italic" content = "Italic: the italic design of the font" end
    paragraph: font style = "oblique" content = "Oblique: the upright letters slanted" end
    paragraph: font stretch = "condensed" content = "Condensed, if the font has a narrow design" end
    paragraph: font = "italic 700 1.25rem/1.4 Georgia, serif" content = "All of it in one shorthand" end
end

The last line uses the shorthand font. It sets style, weight, width, size, line height and family in one string, in this order, with the line height after a slash. Only the size and the family are required.

If a font has no bold or italic design, the browser fakes one by thickening or leaning the normal letters. The result is often a little ugly. font synthesis forbids this, and its parts font synthesis weight, font synthesis style, font synthesis small caps and font synthesis position forbid a single kind of faking.

Web fonts

To use a font that visitors do not have, ship the file with the page. The font element describes one file: name is the name you will use in font family, and url is the address of the file. Salam turns it into an @font-face rule, and the browser downloads the file only when some text uses the font. When one family has several files, write one font element per file with the same name and the weight or style that the file provides.

page:
    title = "A web font"
    font:
        name = "Course Serif"
        url = "/fonts/course-serif.woff2"
        weight = 400
        style = normal
        display = swap
    end
    font:
        name = "Course Serif"
        url = "/fonts/course-serif-bold.woff2"
        weight = 700
        display = swap
    end
    global: selector = "body" font family = "'Course Serif', Georgia, serif" margin = "1.5rem" line height = 1.7 end
    heading: size = 2 content = "Reading in comfort" end
    paragraph: content = "The font files are not part of this preview, so the browser shows the next name in the stack." end
    paragraph: font weight = 700 content = "This line asks for weight 700 and would use the second file." end
end

The two files of this example do not exist in the preview, so the page shows the next font of the stack. That is the right way to build a page: the fallback must always be good enough to read. On your own site, put the files in a folder that your server serves, and the page starts using them. Salam checks the address while compiling: an unsafe address is an error, and a relative file that cannot be found next to the program is a warning. If you leave out type, Salam finds out the format from the end of the address.

Three attributes shape the loading. display = swap shows the fallback font at once and swaps in the real one when it arrives, so the text is never invisible. range lists the Unicode ranges a file covers, so a Persian file is downloaded only by pages that contain Persian letters. weight can be a range such as "100 900" for a variable font.

Features, variants and variable fonts

A good font contains more than letters: small capitals, several kinds of digits, ligatures (shapes where two letters join, such as fi) and alternate forms. They are called OpenType features, and each has a four letter tag such as smcp or liga. The properties that start with font variant switch the common ones in words: font variant caps, font variant numeric, font variant ligatures, font variant position, font variant alternates, font variant east asian and font variant emoji. font feature settings is the raw version for the rest: "'smcp' 1" turns a feature on, and 0 turns it off. font kerning controls the pair spacing, which is on by default and should stay on.

page:
    title = "Font variants"
    global: selector = "body" font family = "Georgia, serif" margin = "1.5rem" line height = 1.8 end
    paragraph: font variant caps = "small-caps" content = "Small capitals for a book title" end
    paragraph: font variant numeric = "tabular-nums" content = "1111 and 8888 line up in tables" end
    paragraph: font variant numeric = "oldstyle-nums" content = "Old style figures 2026 sit in the line" end
    paragraph: font variant ligatures = "none" content = "office affinity: ligatures switched off" end
    paragraph: font kerning = "none" content = "AVATAR WAVE: kerning switched off" end
    paragraph: font feature settings = "'smcp' 1" content = "The same small capitals through the raw feature tag" end
    paragraph: font variation settings = "'wght' 650" content = "A variable font reads this axis; others ignore it" end
end

A variable font is one file that contains a whole range of designs along axes, such as weight (wght) or width (wdth). font variation settings sets the axes by their tag, and font optical sizing lets a font with an optical size axis change its shape with the text size. When an ordinary property exists, use it: font weight = 650 sets the weight axis and is easier to read. font palette picks one of the colour sets of a colour font.

Aligning and transforming text

text align places the lines of a block. Use start and end and not left and right: they follow the direction of the text, so the same rule is correct for English and for Persian. center centres every line and justify stretches every line but the last to the full width. text align last sets the last line separately, and text justify chooses whether the extra space goes between words or between letters. text indent pushes the first line in, the way books mark a new paragraph. text transform changes the case of the shown letters without changing the text, which is better than typing capitals because a screen reader and a search still see the real text.

page:
    title = "Aligning text"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" line height = 1.6 end
    box: text align = "start" content = "Start: the side where reading begins." border = "1px solid #cbd5e1" padding = 8 margin bottom = 8 end
    box: text align = "center" content = "Center: lines in the middle." border = "1px solid #cbd5e1" padding = 8 margin bottom = 8 end
    box: text align = "end" content = "End: the side where reading ends." border = "1px solid #cbd5e1" padding = 8 margin bottom = 8 end
    box:
        text align = "justify"
        text align last = "center"
        text indent = "2em"
        border = "1px solid #cbd5e1"
        padding = 8
        margin bottom = 8
        max width = 420
        content = "Justified text stretches every line to the same width, and the last line can be placed on its own. The first line is indented by two letters."
    end
    box: text transform = "uppercase" content = "uppercase letters" end
    box: text transform = "capitalize" content = "every word starts large" end
end

Justified text needs wide lines. In a narrow column the gaps between words become large and uneven, so use justify only for wide blocks.

Lines, shadows and outlines

text decoration draws lines on text. It is a shorthand of four properties: text decoration line (underline, overline, line-through), text decoration style (solid, double, dotted, dashed, wavy), text decoration color and text decoration thickness. Two more properties tune underlines: text underline offset moves the line away from the letters, and text decoration skip ink decides if the line jumps over the tails of letters like g and y. text shadow adds one or more shadows, each as horizontal offset, vertical offset, blur and colour; two shadows of the same colour make a glow. webkit text stroke and webkit text fill color outline letters; the name starts with webkit because browsers adopted the idea under that prefix, and all of them still use it.

page:
    title = "Decoration and shadow"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" line height = 1.8 font size = 20 end
    paragraph: text decoration line = "underline" text decoration style = "wavy" text decoration color = "crimson" text decoration thickness = 2 content = "A red wavy underline" end
    paragraph: text decoration line = "underline" text underline offset = 6 text decoration skip ink = "none" content = "An underline moved down from the letters" end
    paragraph: text decoration = "line-through 2px #64748b" content = "Crossed out in one shorthand" end
    paragraph: text decoration line = "overline underline" text decoration style = "double" content = "A line above and a double line below" end
    paragraph: text shadow = "2px 2px 4px #94a3b8" font size = 32 font weight = 700 content = "Soft shadow" end
    paragraph: text shadow = "0 0 8px #38bdf8, 0 0 16px #0ea5e9" color = "white" background = "#0f172a" padding = 8 content = "A glow made of two shadows" end
    paragraph: webkit text stroke = "1px #0f172a" webkit text fill color = "transparent" font size = 40 font weight = 700 content = "Outline" end
end

Line height and spacing

line height is the most important property for reading. Give it a plain number, without a unit: 1.6 means 1.6 times the font size of that element, and a child with a larger size gets a larger line height by itself. A length such as "24px" is passed to the children as a fixed result and makes big headings overlap. Around 1.5 suits English, and Persian needs about 1.9 because of its dots and marks above and below the line. letter spacing and word spacing add space between letters and between words. A small positive letter spacing is good for capitals, and a tiny negative one for very large headings. vertical align moves an inline element up or down within the line, as super and sub do for powers and indices. tab size sets the width of a tab character in preformatted text.

page:
    title = "Spacing"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box: width = 300 line height = 1 background = "#f1f5f9" margin bottom = 12 content = "line height 1: the lines of this paragraph are packed tightly together." end
    box: width = 300 line height = 1.6 background = "#f1f5f9" margin bottom = 12 content = "line height 1.6: comfortable for reading long text in a paragraph." end
    box: width = 300 line height = 2.2 background = "#f1f5f9" margin bottom = 12 content = "line height 2.2: so open that the lines start to fall apart." end
    box: letter spacing = "0.25em" text transform = "uppercase" font size = 14 margin bottom = 12 content = "Letter spacing for a label" end
    box: word spacing = "0.5em" content = "Words spread apart by half a letter" end
end

Wrapping and cutting

Normally the browser breaks a line at spaces. white space changes this: nowrap never breaks, pre keeps the text as typed, pre-wrap keeps it and still wraps, and pre-line keeps only the line breaks. white space collapse is the "what happens to spaces" half of it. When a single word is longer than its box, overflow wrap = "anywhere" lets it break so it does not stick out of the page, which is exactly what a long web address needs. word break = "break-all" breaks everywhere, even where the word would fit, and keep-all is for Chinese, Japanese and Korean, where it forbids breaks inside a word. hyphens = "auto" hyphenates words in languages the browser has a dictionary for, if the element has the right lang. text wrap = "balance" evens out the lines of a short heading, and pretty avoids a last line with one short word.

page:
    title = "Wrapping long text"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box: width = 180 white space = "nowrap" overflow = "hidden" text overflow = "ellipsis" background = "#f1f5f9" margin bottom = 12 content = "This sentence is far too long for its box" end
    box: width = 180 overflow wrap = "anywhere" background = "#e0f2fe" margin bottom = 12 content = "https://example.com/a/very/long/address/that-does-not-fit" end
    box: width = 180 word break = "break-all" background = "#fef9c3" margin bottom = 12 content = "Break-all cuts at any letter, even in short words." end
    box: width = 180 hyphens = "auto" lang = "en" background = "#dcfce7" margin bottom = 12 content = "Hyphenation helps incomprehensibilities fit narrow columns." end
    box: width = 180 white space = "pre-line" background = "#fae8ff" content = "Line breaks in the source\nare kept\nwith pre-line." end
end

To show only the first lines of a long text, you have two tools. text overflow = "ellipsis" replaces the cut-off end of one line with an ellipsis, and line clamp limits a block to a number of lines. Both are new or fussy, so build the example below the way it is written: with a max height and overflow = "hidden" as a safety net that works everywhere.

page:
    title = "Clamping lines"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        width = 260
        line height = 1.5
        line clamp = 3
        overflow = "hidden"
        max height = "4.5em"
        background = "#f1f5f9"
        padding = "0 10"
        content = "A card preview shows only the first lines of a long text, so every card in a list keeps the same height, however much the author wrote. Everything after the third line is cut off here."
    end
    heading: size = 3 text wrap = "balance" max width = 260 content = "A long headline that is split into two lines of similar length" end
end

Direction and vertical text

direction chooses ltr or rtl for the text of an element. In practice you set the direction with the dir attribute (see the lesson on the head and global attributes) because it tells screen readers too, and use the CSS property only for a rule that applies to many elements. unicode bidi controls how text of mixed directions is ordered, and bidi-override forces the order whatever the letters are; the elements isolate and direction override in the lesson on text elements do the same job.

writing mode goes further and turns the lines themselves: vertical-rl writes down the page and stacks the lines from right to left, as in Japanese and Chinese. text orientation decides whether the letters of other scripts stand up or lie down, and text combine upright squeezes a short run, such as a year, into the space of one character.

page:
    title = "Vertical writing"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box: display = "flex" gap = 32 font size = 22 height = 200
        box: writing mode = "vertical-rl" content = "Vertical lines run top to bottom" end
        box: writing mode = "vertical-rl" text orientation = "upright" content = "UPRIGHT" end
        box: writing mode = "vertical-rl"
            content = "In "
            span: text combine upright = "all" content = "2026" end
        end
    end
end

Ruby and emphasis marks

Ruby is a small annotation above or below a word, mostly the pronunciation of a Chinese or Japanese word, written with the ruby and ruby text elements. ruby position sets the side and ruby align how the annotation is spread over the word. East Asian text has no italics, so emphasis is drawn as small marks on each character, with text emphasis style, text emphasis color and text emphasis position. The shorthand is text emphasis.

page:
    title = "Ruby and emphasis"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" font size = 26 line height = 2.2 end
    paragraph:
        ruby: ruby position = "over" ruby align = "center"
            content = "東京"
            ruby parenthesis: content = "(" end
            ruby text: content = "とうきょう" end
            ruby parenthesis: content = ")" end
        end
    end
    paragraph: text emphasis style = "filled dot" text emphasis color = "crimson" content = "Dots mark the emphasis" end
    paragraph: text emphasis style = "open circle" text emphasis position = "under right" content = "Circles below the text" end
end

Persian and Arabic text

Everything above works for Persian, and a few points need care. A page in a Persian file already has lang = "fa" and the right-to-left direction. Then:

• Choose a font that has Persian letters, and put a safe one at the end of the stack, such as Tahoma. Many fonts made for English have no Persian letters, and the browser fills the gap letter by letter from another font, which looks uneven. A web font such as Vazirmatn or Estedad is the real fix: load it with the font element and the range of the Persian block.
• Set line height to about 1.9 for body text. Persian letters carry dots and marks that need space above and below.
• Use text align start and end, never left and right.
• Keep letter spacing at zero. Do not turn ligatures off either, because the joined forms are the script itself.
• Digits are characters, not a style. ۱۲۳ and 123 are different letters, and no CSS property converts one into the other. font variant numeric only changes the look of the digits a font has, such as the equal width form for columns.
• Browsers do not hyphenate Persian, and justify works well if the lines are long.
• Italics are rare in Persian type. A line that is only oblique looks slanted, which is fine for a short quotation but tiring for a paragraph. Use bold, or a different size, for emphasis.

page:
    title = "Persian text"
    global: selector = "body" font family = "Tahoma, system-ui, sans-serif" margin = "1.5rem" end
    box: dir = "rtl" lang = "fa" line height = 1.9 margin bottom = 16 border = "1px solid #cbd5e1" padding = 10 max width = 340
        content = "هر کتاب برای خواننده‌ای نوشته می‌شود. این بند ۳ سطر دارد و ارتفاع خطش ۱٫۹ است تا نقطه‌ها و کسره‌ها جا داشته باشند."
    end
    box: dir = "rtl" lang = "fa" line height = 1.2 margin bottom = 16 border = "1px solid #fecaca" padding = 10 max width = 340
        content = "همین متن با ارتفاع خط ۱٫۲ فشرده و خسته‌کننده می‌شود، چون سطرها به هم می‌چسبند و نقطه‌ها روی هم می‌افتند."
    end
    box: dir = "rtl" lang = "fa" line height = 1.9 text align = "justify" max width = 340 border = "1px solid #cbd5e1" padding = 10
        content = "ترازشدن دوطرفه در متن فارسی خوب کار می‌کند، به شرط آنکه خط‌ها به اندازه‌ی کافی بلند باشند."
    end
end

The example puts the same text three times. The first box has a comfortable line height, the second a tight one where the lines nearly touch, and the third is justified. The preview shows the page as the compiler built it, with Persian letters from the system.

Reference: every font and text property

Each entry shows the name in Salam, its name in CSS, the values it accepts and an example. The examples are checked by the compiler, so you can paste any of them inside a page: block. The colour of text, color, belongs to the lesson on colours and backgrounds, and the box around the text to the lessons that follow it. Persian names work in any file, and the Persian lessons use them.

Fonts: family, size, weight and style

These choose the font and its basic look.

Fonts: features, variants and variable fonts

These switch the extra forms and axes a font offers. The effect depends on the font.

Web font element

The font element goes directly inside the page.

font (Persian: قلم)

Declares a web font, which becomes an @font-face rule. name and url are required, and the element goes directly inside the page. Afterwards write the name in font family. Browsers download the file only when some text uses the font, and until then they show the next font of the stack.

font:
    name = "Course Serif"
    url = "/fonts/course-serif.woff2"
    weight = 400
    display = swap
end
box: font family = "Course Serif, Georgia, serif" content = "Set in the course font" end

Required: name, url · Only inside: page · Void element, it cannot have children

Text appearance: alignment, case, lines and shadows

These change how a line of text is placed and drawn.

Spacing and wrapping

These set the space between lines, letters and words, and decide where lines break or are cut.

Direction and writing modes

These set the direction of the text and turn lines upright.

Ruby, emphasis and East Asian typography

These are made for Chinese, Japanese and Korean, though most of them work with any text.

Try it yourself

• Take the type tester and add a second slider that sets line height between 1 and 3 on the sample. At what value does a paragraph start to feel loose?
• Write the front of a book: a title in small capitals with letter spacing, an author line in italics, and a paragraph that is justified with a text indent of 2em.
• Declare a font with a file that does not exist, use it in a font stack with a good fallback, and check that the page is still readable.
• Make a card that shows the first three lines of a long text and a headline with text wrap = "balance".