Styles and the box model

Style properties are attributes

A style property is written exactly like any other attribute: name = value inside the element. Property names have spaces where CSS has dashes, so max-width is max width and border-radius is border radius. A misspelled name is a compile error, and the message suggests the nearest real one.

The styles do not stay on the element. The compiler collects the styles of each element into one rule under a short generated class and puts the rules into the stylesheet. box: padding = 20 background = "#eef" end turns into <div class="a"> and the rule .a{padding:20px;background:#eef}. Elements whose styles are identical share one class, which keeps the page small.

Values

Most values are one of four things. A bare number is pixels where a length is expected: padding = 24 is 24px, and 1.5 is 1.5px. Properties that take a plain number, such as line height and aspect ratio, keep it as a number. A string holds anything else: units, colors with #, several words. A keyword can be written without quotes: display = flex, overflow = hidden, color = white. And a function with simple arguments can be unquoted too, as in background = rgb(37, 99, 235).

Several lengths in one string form a shorthand. padding = "8 40" is 8px 40px: the first number is for top and bottom, the second for left and right. Up to four values are allowed, and a number without a unit gets px while a number with a unit keeps it, so "1rem 2" is 1rem 2px.

page:
    title = "Style values"
    global: box sizing = "border-box" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = "p" margin = "0 0 10px" end
    paragraph: content = "padding = 24" padding = 24 background = "#e0f2fe" end
    paragraph: content = "padding = \"8 40\"" padding = "8 40" background = "#dcfce7" end
    paragraph: content = "border = \"3px dashed #0f766e\"" padding = 12 border = "3px dashed #0f766e" end
    paragraph: content = "width = \"60%\"" padding = 12 width = "60%" background = "#fef9c3" end
    paragraph:
        content = "background = \"linear-gradient(90deg, ...)\""
        padding = 12
        color = white
        background = "linear-gradient(90deg, #0f766e, #2563eb)"
    end
end

Values can also be computed while compiling: padding = GAP * 2 + "px" uses a constant (the section on reuse below shows how it is declared), and + joins a number and a unit into text.

Units

A length is a number and a unit. The ones you will use all the time:

• px: a CSS pixel. Good for borders and fine details.
• rem: the font size of the page, normally 16px. Sizes in rem grow when a reader raises the font size in the browser, so use it for text and spacing.
• em: the font size of the element itself, which makes a padding follow the text size of its own box.
• %: a share of the parent. For widths and horizontal padding and margin it is the parent's width, for a height it is the parent's height.
• vw and vh: one percent of the width or height of the window. vmin and vmax take the smaller or larger of the two.
• ch: the width of the digit 0 in the current font. max width = "65ch" keeps lines of text at a readable length.
• cm, mm and in: real-world lengths, meant for printing.

page:
    title = "Units"
    global: box sizing = "border-box" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = "p" margin = "0 0 8px" padding = "6px 10px" background = "#99f6e4" white space = nowrap end
    paragraph: content = "200px" width = "200px" end
    paragraph: content = "12rem" width = "12rem" end
    paragraph: content = "50%" width = "50%" end
    paragraph: content = "40vw" width = "40vw" end
    paragraph: content = "24ch" width = "24ch" end
    paragraph: content = "5cm" width = "5cm" end
end

The unit fr, a share of the free space in a grid, belongs to the layout lesson.

Colors

Wherever a color is expected you can write it in any CSS notation. The text color, the background and the fancy fills have their own lessons (backgrounds and colors); this is only the list of ways to write the value.

• A name: teal, crimson, white.
• Hex: "#0f766e", the short "#fa0", and with transparency "#0f766e80".
• rgb(37, 99, 235): red, green and blue from 0 to 255. With transparency write "rgb(37 99 235 / 50%)".
• hsl(160, 84%, 39%): hue as an angle on the color wheel, then saturation and lightness. Easy to adjust by hand.
• oklch(0.7 0.15 30): lightness, chroma and hue in a space where equal steps look equal.
• color-mix(in srgb, red 40%, white): a blend of two colors.
• transparent and currentColor. The second is the element's own text color, so a border written with it follows the text.

page:
    title = "Colors"
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = "p" margin = "0 0 6px" padding = "8px 12px" end
    paragraph: content = "teal" background = teal color = white end
    paragraph: content = "#f59e0b" background = "#f59e0b" end
    paragraph: content = "rgb(37, 99, 235)" background = rgb(37, 99, 235) color = white end
    paragraph: content = "hsl(160, 84%, 39%)" background = "hsl(160, 84%, 39%)" end
    paragraph: content = "oklch(0.7 0.15 30)" background = "oklch(0.7 0.15 30)" end
    paragraph: content = "color-mix(in srgb, red 40%, white)" background = "color-mix(in srgb, red 40%, white)" end
    box:
        background = "#fde68a"
        padding = 6
        paragraph: content = "transparent shows what is behind" background = transparent end
    end
    paragraph: content = "currentColor makes the border follow the text" color = "#7c3aed" border = "3px solid currentColor" end
end

The box model

Every element is a rectangular box made of four layers, from the inside out. The content is the text or the children. Padding is the room between the content and the border, and it shows the element's background. The border is the line around the padding. The margin is empty space outside the border that keeps other boxes away. Padding and margin both take one to four values, in the order top, right, bottom, left, and each side also has its own property: padding top, margin left and so on.

page:
    title = "The box model"
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    box:
        background = "#e5e7eb"
        width = 320
        box:
            margin = 24
            border = "8px solid #1d4ed8"
            padding = 24
            background = "#bfdbfe"
            box:
                background = "white"
                padding = 8
                content = "content"
            end
        end
    end
    paragraph: content = "Grey: the space around the box (margin). Blue line: the border. Light blue: the padding. White: the content." end
end

The next question is what width = 240 measures. By default (content-box) it measures only the content, so a box with 20px of padding and a 6px border on each side is really 240 + 40 + 12 = 292 pixels wide, and a layout of several such boxes never adds up the way you wrote it. With box sizing = "border-box" the width includes padding and border, and 240 means 240. Click the button to see the same box measured both ways.

import dom

page:
    title = "box sizing"
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = ".border" box sizing = "border-box" end
    box:
        id = "b"
        width = 240
        padding = 20
        border = "6px solid #0f766e"
        background = "#ccfbf1"
        content = "width = 240"
    end
    paragraph: id = "out" content = "The box is 292px wide" end
    button:
        content = "Switch box sizing"
        click = ():
            dom.ToggleClass(dom.ById("b"), "border")
            w := dom.GetNum(dom.ById("b"), "offsetWidth")
            dom.SetText(dom.ById("out"), "The box is now " + w + "px wide")
        end
    end
end

That is why nearly every page begins with the same line. A global element with no selector styles every element on the page:

global: box sizing = "border-box" end

Width, height and their limits

width and height set the size. By default a block is as wide as its parent and as tall as its content, and auto names that default. A percentage is a share of the parent, though a percentage height only works when the parent has a height of its own. Since a fixed size breaks when the window or the text changes, you will mostly set limits instead: min width and max width, min height and max height. A minimum beats a maximum, and a maximum beats the width. The sizes min-content, max-content and fit-content size a box by its text. aspect ratio keeps a box in shape ("16 / 9") when you give one side and leave the other free.

page:
    title = "Sizes"
    global: box sizing = "border-box" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = "p" margin = "0 0 8px" padding = 10 background = "#e0e7ff" end
    paragraph: content = "min width 12rem, max width 24rem, width 50%" width = "50%" min width = "12rem" max width = "24rem" end
    paragraph: content = "width = clamp(10rem, 40%, 20rem)" width = "clamp(10rem, 40%, 20rem)" end
    paragraph: content = "height = 4rem" height = "4rem" end
    box:
        width = 200
        aspect ratio = "16 / 9"
        background = "#c7d2fe"
        padding = 10
        content = "aspect ratio = 16 / 9"
    end
end

A very common recipe is width = "100%" with max width = "40rem", optionally with margin = "0 auto" to center it: a box that fills a phone and stops growing on a monitor.

Logical properties

Left and right are physical directions. A page in English starts its lines on the left, a Persian page on the right, and a layout built from margin left has to be rewritten for the other language. Logical properties name the sides by the flow of the text. The inline direction is the one the text runs in and the block direction is the one the lines stack in. In English and Persian that makes inline horizontal and block vertical, and start is where a line begins: left in English, right in Persian.

So inline size is the width and block size the height, margin inline start and padding inline end are the sides at the start and the end of a line, and margin block and padding block are top and bottom. The example gives two boxes the very same styles and sets dir on the wrappers: the indent and the stripe change sides on their own.

page:
    title = "Logical properties"
    global: box sizing = "border-box" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = "p" margin = "0 0 12px" end
    box:
        dir = ltr
        paragraph:
            inline size = "70%"
            margin inline start = 40
            padding inline = "24 8"
            padding block = 10
            border inline start = "6px solid #0f766e"
            background = "#ccfbf1"
            content = "dir = ltr: the start side is the left"
        end
    end
    box:
        dir = rtl
        paragraph:
            inline size = "70%"
            margin inline start = 40
            padding inline = "24 8"
            padding block = 10
            border inline start = "6px solid #0f766e"
            background = "#ccfbf1"
            content = "dir = rtl: the same styles, mirrored"
        end
    end
end

For a site in both languages, logical properties are usually the better choice. Use left and right when you really mean the screen: a shadow that must fall to the right, for instance.

Margins in practice

Four rules about margins explain most surprises.

• Centering. A block with a width and margin = "0 auto" is centered: auto splits the free space between the two sides. A block without a width fills the parent, so there is nothing to split.
• Collapsing. When two blocks are stacked, the margin between them is not the sum of the two but the larger one. A margin bottom = 40 above a margin top = 20 leaves 40. The same happens between a parent and its first or last child when nothing (padding, border, a height) separates them. Margins inside a flex or grid layout never collapse.
• Negative margins. A margin may be negative, which pulls the element toward its neighbour or out of its parent. Use it sparingly; it hides the real structure.
• Which one to use. Padding when the space should be part of the box and show its background, margin when it should push other boxes away.

page:
    title = "Margins"
    global: box sizing = "border-box" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = "p" margin = 0 padding = 10 background = "#fed7aa" end
    paragraph: content = "width = 240, margin = \"0 auto 30px\"" width = 240 margin = "0 auto 30px" end
    paragraph: content = "margin bottom = 40" margin bottom = 40 end
    paragraph: content = "margin top = 20 (the gap above is 40, not 60)" margin top = 20 background = "#fdba74" end
    paragraph: content = "margin top = -12 pulls this one up over the last" margin top = -12 margin left = 40 background = "#fb923c" end
end

Display and visibility

display decides how an element takes part in the layout. block starts a new line and fills the width, inline sits inside a line of text and ignores width and height, and inline-block sits in a line but obeys them. flex and grid turn the element into a container that lays out its children, which is the whole topic of the layout lesson. contents removes the element's own box and lets its children take part in the parent's layout as if it were not there, and flow-root makes a box that contains everything inside it, floats included. Every element starts with a default: a box is block and a span is inline.

page:
    title = "display"
    global: box sizing = "border-box" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = "span" width = 90 height = 40 padding = 6 margin = 2 background = "#bbf7d0" border = "1px solid #15803d" end
    heading: size = 3 content = "inline (the default for span)" end
    box:
        span: content = "one" end
        span: content = "two" end
        span: content = "three" end
    end
    heading: size = 3 content = "inline-block" end
    box:
        span: display = inline-block content = "one" end
        span: display = inline-block content = "two" end
        span: display = inline-block content = "three" end
    end
    heading: size = 3 content = "block" end
    box:
        span: display = block content = "one" end
        span: display = block content = "two" end
    end
end

To hide an element you have two choices that behave differently. display = none takes it out of the page completely: it has no box and the following elements move up. visibility = hidden only stops it being drawn: the gap stays. In both cases the element cannot be clicked, cannot receive keyboard focus and is skipped by screen readers. The two buttons below set the style from a script, so you can watch the paragraph that follows.

import dom

page:
    title = "Hiding"
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    button:
        content = "display: none"
        click = ():
            if dom.GetStyle(dom.ById("target"), "display") == "none":
                dom.SetStyle(dom.ById("target"), "display", "")
            else:
                dom.SetStyle(dom.ById("target"), "display", "none")
            end
        end
    end
    button:
        content = "visibility: hidden"
        click = ():
            if dom.GetStyle(dom.ById("target"), "visibility") == "hidden":
                dom.SetStyle(dom.ById("target"), "visibility", "")
            else:
                dom.SetStyle(dom.ById("target"), "visibility", "hidden")
            end
        end
    end
    paragraph: content = "Before" background = "#e5e7eb" end
    paragraph: id = "target" content = "The target" background = "#fca5a5" end
    paragraph: content = "After" background = "#e5e7eb" end
end

Overflow

What happens when the content is bigger than its box is the job of overflow. With visible, the default, it spills out and covers what is next to it. hidden cuts it at the border, scroll always shows scrollbars, and auto shows them only when there is something to scroll, which is nearly always what you want. clip cuts like hidden but never allows scrolling, even from a script, and it is the only value that works with overflow clip margin. overflow x and overflow y set one direction at a time, and overflow block and overflow inline are their logical forms, which fewer browsers know today.

page:
    title = "overflow"
    global: box sizing = "border-box" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    box:
        display = flex
        flex wrap = wrap
        gap = "40 24"
        box: width = 150 height = 90 padding = 8 border = "2px solid #6366f1" font size = 14 overflow = visible content = "visible: A text that is longer than the box it sits in, so it must go somewhere." end
        box: width = 150 height = 90 padding = 8 border = "2px solid #6366f1" font size = 14 overflow = hidden content = "hidden: A text that is longer than the box it sits in, so it must go somewhere." end
        box: width = 150 height = 90 padding = 8 border = "2px solid #6366f1" font size = 14 overflow = auto content = "auto: A text that is longer than the box it sits in, so it must go somewhere." end
        box: width = 150 height = 90 padding = 8 border = "2px solid #6366f1" font size = 14 overflow = scroll content = "scroll: A text that is longer than the box it sits in, so it must go somewhere." end
    end
end

calc, min, max, clamp and var

CSS can do arithmetic where a length goes. calc() mixes units: "calc(100% - 80px)" is everything but 80 pixels, and the spaces around + and - are required. min() picks the smallest of its arguments and max() the largest, so "min(100%, 20rem)" says "at most 20rem". clamp(least, ideal, most) is the pair in one: "clamp(1rem, 4vw, 2rem)" is a font size that scales with the window but stays between 1 and 2 rem.

var() reads a CSS custom property, a value you name yourself. They are declared in raw CSS, which you give to a style element at the top of the page. The name starts with two dashes, and it can be used anywhere below through "var(--brand)".

page:
    title = "CSS functions"
    style: content = ":root { --brand: #0f766e; --gap: 14px }" end
    global: box sizing = "border-box" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = "p" margin = "0 0 10px" padding = "var(--gap)" end
    paragraph: content = "width = calc(100% - 80px)" width = "calc(100% - 80px)" background = "#e0f2fe" end
    paragraph: content = "width = min(100%, 20rem)" width = "min(100%, 20rem)" background = "#dcfce7" end
    paragraph: content = "width = max(50%, 18rem)" width = "max(50%, 18rem)" background = "#fef9c3" end
    paragraph: content = "font size = clamp(1rem, 4vw, 2rem)" font size = "clamp(1rem, 4vw, 2rem)" background = "#fce7f3" end
    paragraph: content = "background = var(--brand)" background = "var(--brand)" color = white end
end

The difference from the constants of Salam is when the value is known. A constant is fixed while compiling. A custom property lives in the browser, so it can change with the window size, with a dark mode rule, or from a script.

Global rules

Styles on an element are the right tool for that element. The global element is for everything else: a rule for a whole kind of element, or for the page. Its selector is any CSS selector, written as text. A tag name styles every element of that kind, ".tip" every element with that class, "#lead" one element with that id, and "li:nth-child(odd)" or "nav a" pick by position or place. Leave the selector out and the rule applies to every element, which is how the box sizing line above works.

page:
    title = "Global rules"
    global: box sizing = "border-box" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 line height = 1.5 end
    global: selector = "h2" color = "#0f766e" margin = "0 0 8px" end
    global: selector = ".tip" background = "#fef3c7" border left = "4px solid #f59e0b" padding = "8px 12px" end
    global: selector = "#lead" font size = 20 end
    global: selector = "li:nth-child(odd)" background = "#f1f5f9" end
    heading: size = 2 content = "Three kinds of selector" end
    paragraph: id = "lead" content = "A tag, a class and an id, all styled once." end
    paragraph: class = "tip" content = "Every element with class tip gets this look." end
    list:
        item: content = "Odd rows are shaded" end
        item: content = "Even rows are not" end
        item: content = "Odd again" end
    end
end

Two details to know. The selector is passed to the stylesheet as written, so the compiler cannot tell you that it is misspelled. And when two rules reach the same element the more specific one wins: a class beats a tag, an id beats a class. Use global for defaults and shared classes, element styles for what is unique.

Constants and components

Write a number once and use it everywhere. A const above the page holds a value that is worked out while compiling, and style values may use it in expressions: padding = GAP * 2 + "px". A component does the same for a whole piece of page: it takes parameters, builds a styled element tree, and content: end marks where the children of each use go. Parameters work in styles too: a value such as overflow = mode reads the parameter mode. Uses with identical styles share one generated class, so a card used ten times adds one rule.

const GAP := 16
const BRAND := "#0f766e"

component Card(title, body, accent):
    box:
        padding = GAP
        margin = "0 0 " + GAP + "px"
        border = "2px solid " + accent
        border radius = GAP / 2 + "px"
        heading: size = 3 content = title color = accent margin = "0 0 6px" end
        paragraph: content = body margin = 0 end
        content: end
    end
end

page:
    title = "Reusable cards"
    global: selector = "body" font family = "system-ui, sans-serif" margin = GAP * 2 + "px" end
    Card: title = "Fast" body = "Built to machine code." accent = BRAND end
    Card: title = "Safe" body = "Checked while compiling." accent = "#2563eb"
        paragraph: content = "Even the page styles." color = "#64748b" end
    end
end

Skipping work for big pages

Three properties help a long page load and scroll faster, at the price of some promises. contain tells the browser that the inside of an element does not affect anything outside it, so a change inside never needs the whole page to be laid out again. content visibility = auto goes further: the browser does not draw or lay out the element while it is far off screen. Because a skipped element has no height, add contain intrinsic size with a guess, auto 600px meaning "use the real size once you have seen it, and 600px before". Use it on the sections of a page that is long, not on small pages, where it only adds risk.

section:
    content visibility = auto
    contain intrinsic size = "auto 600px"
    heading: size = 2 content = "Far down the page" end
    paragraph: content = "Drawn only when the reader scrolls near it." end
end

Reset and field sizing

all resets every property of an element at once. Only the keywords that work for any property are allowed: initial, inherit, unset and revert. Put it first and then add back the styles you want, the way the reference example turns a button into a plain box. field sizing = content lets a text box grow while the user types, with no script, in browsers that support it. The properties appearance, resize and zoom are in the responsive lesson.

page:
    title = "field sizing"
    global: selector = "body" font family = "system-ui, sans-serif" margin = 20 end
    global: selector = "p" margin = "0 0 8px" end
    paragraph: content = "Type in the box: it grows with the text." end
    input:
        id = "name"
        field sizing = content
        min width = "6ch"
        max width = "100%"
        padding = 6
        font size = 18
        placeholder = "Your name"
    end
    paragraph: content = "Without it, a text box keeps one fixed width:" margin top = 24 end
    input: padding = 6 font size = 18 placeholder = "Your name" end
end

Reference: sizing, space, display and overflow

Every property of this lesson is below with what it accepts and a short example that the compiler has checked. Persian names work in any file and are what the Persian lessons use. First the global element, then the properties in groups.

The global rule

global (Persian: سراسری)

Holds a style rule for the whole page instead of for one element. With no selector the rule applies to every element, which is the place for resets such as box sizing. With a selector it applies to everything the selector matches. It takes any style property, with the hover, focus and similar prefixes too.

global: selector = ".tip" background = "#fef3c7" padding = 12 hover background = "#fde68a" end

Width, height and shape

Each size has a physical form (width, height) and a logical form (inline size, block size), and a minimum and a maximum of each.

Margin

The space outside the border. margin sets all sides, the top, right, bottom and left forms set one physical side, and the block and inline forms follow the text direction.

Padding

The space inside the border. It has the same set of sides as margin, and it never takes auto or a negative value.

Overflow

What happens to content that does not fit.

Display and containment

How the element takes part in the layout, whether it is drawn, and what the browser may skip.

Reset and field size

Try it yourself

• Build a card with padding = 24, a border and max width = "24rem". Put five of them in a column and add margin = "0 auto 16px". Is the gap between two cards 16px or 32px?
• Take the box example and write global: box sizing = "border-box" end at the top. Which sizes change, and why does the box look smaller?
• Make a 150 by 100 box with a long sentence in it and try each value of overflow. Then replace height = 100 with min height = 100.
• Replace every margin left and margin right of a page with the logical forms, then add dir = rtl to the page and look at the result.