Borders, outlines and shadows

The border shorthand

A border is a line drawn between the padding of a box and its margin. It has three parts: a width, a style and a color. The shorthand border takes all three in one string, in any order: "2px solid #0f766e". A bare number written without quotes, such as 6, means pixels. The style decides what is drawn: solid is a plain line, dashed and dotted are broken lines, double is two thin lines with a gap, and groove, ridge, inset and outset imitate a carved or raised edge by shading two sides lighter and two darker. none draws nothing and hidden does the same, but wins when two borders meet in a table.

component Sample(kind):
    box:
        border style = kind
        border width = 6
        border color = "#0f766e"
        padding = 12
        content = kind
    end
end

page:
    title = "Border styles"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        display = grid gap = 12 grid template columns = "repeat(auto-fit, minmax(110px, 1fr))" text align = center
        Sample: kind = "solid" end
        Sample: kind = "dashed" end
        Sample: kind = "dotted" end
        Sample: kind = "double" end
        Sample: kind = "groove" end
        Sample: kind = "ridge" end
        Sample: kind = "inset" end
        Sample: kind = "outset" end
    end
end

The example uses a small component, Sample, so each border style is one line. It passes the style name to border style and also shows it as text. The same three parts exist as separate properties: border width, border style and border color.

The three longhands take from one to four values, and the rule is the same for each of them. One value applies to all four sides. Two values are the top and bottom, then the left and right. Three values are the top, then the left and right, then the bottom. Four values go clockwise from the top: top, right, bottom, left. Padding and margin use the same rule, so you only learn it once.

A border is part of the box. With the default sizing a box of width = 200 and a border of 6px on each side becomes 212px wide. Many pages add a global rule box sizing = "border-box", which makes the width include padding and border, and the next lessons assume you know both ways.

One side at a time

Each side has its own shorthand and its own three longhands. border top, border right, border bottom and border left take the usual width, style and color. border top color and its twelve relatives change one part of one side. The example shows the most common uses: a thick stripe on the left of a warning, an underline under a heading, and two ways to give the four sides different widths and colors in a single line.

page:
    title = "Borders on one side"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        display = grid gap = 14
        box: border left = "6px solid #dc2626" background = "#fef2f2" padding = "10px 14px" content = "A warning: border left" end
        heading: size = 3 margin = 0 padding = "0 0 6px 0" border bottom = "3px solid #0f766e" content = "A heading: border bottom" end
        box: border style = "solid" border width = "2px 10px" border color = "#6366f1" padding = 12 content = "Two values: top and bottom, left and right" end
        box: border style = "solid" border width = 6 border color = "#ef4444 #22c55e #3b82f6 #eab308" padding = 12 content = "Four colors: top, right, bottom, left" end
    end
end

When a side has no border you can leave it out. The usual way to build a mixed border is to set border first and then overwrite the one side that must differ, for example border = "1px solid #cbd5e1" followed by border bottom color = "#0f766e". The later property wins, so the order of the lines matters.

Logical sides for any language

left and right are wrong for a page that is read from right to left: a stripe at the left of an English quotation belongs at the right of a Persian one. The logical properties name the sides by the direction of the text instead. The inline direction is the way a line of text runs. Inline start is where a line begins, which is the left in English and the right in Persian or Arabic, and inline end is the opposite side. The block direction is the way lines stack, so block start is the top and block end is the bottom in ordinary horizontal text.

That gives border inline start, border inline end, border block start and border block end, each with its width, style and color. The shorthand border inline sets both inline sides and border block sets both block sides, and their color, style and width forms take one or two values (start, then end). In the example the same line of code puts the stripe on the left of the English box and on the right of the Persian box, because the second box has dir = "rtl".

page:
    title = "Logical borders"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        dir = "ltr"
        border inline start = "6px solid #0f766e"
        padding = "10px 14px"
        margin = "0 0 14px 0"
        background = "#f0fdfa"
        content = "English text: the stripe is on the left."
    end
    box:
        dir = "rtl"
        border inline start = "6px solid #0f766e"
        padding = "10px 14px"
        background = "#f0fdfa"
        content = "متن فارسی: خط کنار راست است."
    end
end

Prefer the logical names in anything that may be shown in more than one language. In a Persian-only project the physical names are fine, and they are often what you want for something that is tied to the screen, such as a shadow.

Rounded corners

border radius rounds the corners. A single length makes circular corners of that radius. Two to four values follow the corner order: with two, the first is for the top left and bottom right corners and the second for the top right and bottom left; with four they go clockwise from the top left. A slash makes oval corners: 50% / 30% sets a horizontal radius of 50% and a vertical radius of 30%. A radius larger than the box can fit is reduced, so 999px is the usual way to make a pill, and 50% on a square makes a circle.

Each corner also has its own property: border top left radius, border top right radius, border bottom left radius and border bottom right radius, and the logical versions border start start radius, border start end radius, border end start radius and border end end radius. The first word after border is the block side and the second is the inline side, so border start end radius is the top right corner in English and the top left in Persian.

component Tile(label, corners):
    box:
        width = 100
        height = 70
        background = "#f59e0b"
        display = flex
        align items = center
        justify content = center
        font size = 13
        border radius = corners
        content = label
    end
end

page:
    title = "Rounded corners"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        display = flex gap = 14 flex wrap = wrap
        Tile: label = "12" corners = 12 end
        Tile: label = "30px 0" corners = "30px 0" end
        Tile: label = "pill" corners = "999px" end
        Tile: label = "50% / 30%" corners = "50% / 30%" end
        Tile: label = "4 values" corners = "40px 4px 40px 4px" end
        box: width = 70 height = 70 border radius = "50%" background = "#f59e0b" end
        box: width = 100 height = 70 border top left radius = 40 background = "#f59e0b" display = flex align items = center justify content = center font size = 13 content = "top left" end
        box: width = 100 height = 70 border start end radius = 35 background = "#f59e0b" display = flex align items = center justify content = center font size = 13 content = "start end" end
    end
end

Rounding shapes the background, the border and the shadow, but it does not clip the content. A child that is larger than the box still sticks out of its rounded corner unless the box has overflow = hidden.

Border images

A border does not have to be a line. border image source draws a picture or a gradient in the border area instead. The picture is cut into nine pieces by border image slice: four corners, four edges and a middle. The corners go into the corners of the border as they are, the edges are stretched or repeated along the sides, and the middle is thrown away unless you add fill. This is called a nine-slice frame, and it lets one small picture fit boxes of any size.

The properties that control it are border image slice (how far from each edge of the picture to cut, as a number of the picture's own pixels or a percentage), border image width (how thick the frame is drawn, a length or a multiple of the border width), border image outset (how far it reaches outside the box) and border image repeat (stretch, repeat, round or space). border image is the shorthand for all five, in the order source slice / width / outset repeat. The border itself must still have a width, and a transparent color is the usual choice so that nothing shows through under the picture.

const FRAME := "url('data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27 width=%2790%27 height=%2790%27%3E%3Crect x=%275%27 y=%275%27 width=%2780%27 height=%2780%27 rx=%2710%27 fill=%27none%27 stroke=%27%230f766e%27 stroke-width=%274%27/%3E%3Ccircle cx=%2715%27 cy=%2715%27 r=%2712%27 fill=%27%23f59e0b%27/%3E%3Ccircle cx=%2775%27 cy=%2715%27 r=%2712%27 fill=%27%23f59e0b%27/%3E%3Ccircle cx=%2715%27 cy=%2775%27 r=%2712%27 fill=%27%23f59e0b%27/%3E%3Ccircle cx=%2775%27 cy=%2775%27 r=%2712%27 fill=%27%23f59e0b%27/%3E%3C/svg%3E')"

page:
    title = "Border image"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        width = 260
        padding = 14
        border = "30px solid transparent"
        border image source = FRAME
        border image slice = 30
        border image width = "30px"
        border image repeat = "round"
        content = "The four corners come from the corners of the picture. The edges are stretched or repeated to fit the box."
    end
end

The frame in the example is a small SVG picture written as a data URL, with an amber circle in each corner. Because the corners are copied and never stretched, the circles stay round on a box of any size, and round repeats the edges a whole number of times so no piece is cut. A gradient works as a source too, and with a slice of 1 it makes the popular gradient border: border image = "linear-gradient(135deg, #f59e0b, #db2777) 1". The one thing a border image cannot do is follow border radius, because the image replaces the line that the radius would have curved.

Outlines and focus rings

outline looks like a border and takes the same width, style and color, but it is different in three ways. It is drawn outside the box and takes no room in the layout, so adding one never moves anything. It can be pushed away from the box with outline offset, or pulled inside with a negative offset. And it is the tool of the browser for showing keyboard focus. The longhands are outline color, outline style (the border styles and also auto, the browser's own ring) and outline width.

Focus is the element that receives the keyboard. A person who cannot use a mouse presses Tab to move from link to button to field, and the focus ring is the only thing that shows where they are. Write the state as a prefix: focus outline = "3px solid #2563eb" applies only while the element has focus. Click into the example and press Tab: the button gets a blue ring set three pixels away, and the input gets a pink one.

page:
    title = "Outlines and focus rings"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        display = flex gap = 24 flex wrap = wrap align items = center
        button:
            id = "go"
            content = "Tab to me"
            padding = "8px 16px"
            border = "2px solid #0f766e"
            background = "white"
            border radius = 6
            focus outline = "3px solid #2563eb"
            focus outline offset = 3
        end
        input: type = "text" placeholder = "Focus me" padding = 8 focus outline color = "#db2777" focus outline width = 3 focus outline style = solid end
        box: outline = "3px dashed #db2777" outline offset = 6 padding = 12 content = "outline offset 6" end
    end
end

Box shadows

box shadow draws a shadow behind the box, shaped like its rounded corners. One shadow is written as up to five parts: x y blur spread color. The first two numbers move the shadow right and down (negative numbers move it left and up). Blur softens the edge: 0 is sharp and a bigger number is softer. Spread makes the shadow bigger or, if negative, smaller than the box. The color is almost always a transparent black such as rgb(0 0 0 / 20%), because a shadow lets the page show through. Put inset first and the shadow is drawn inside the box, as if it were pressed in.

Separate several shadows with commas and the first one is on top. A pair of shadows, one close and tight and one far and soft, looks far more natural than a single one, which is how the "layered" card gets its depth. A shadow with no blur and a spread of 4px is a ring that follows the corners, and a blurry shadow with a bright color is a glow.

component Card(label, shadow):
    box:
        background = "white"
        width = 120
        height = 80
        display = flex
        align items = center
        justify content = center
        text align = center
        font size = 13
        border radius = 10
        box shadow = shadow
        content = label
    end
end

page:
    title = "Box shadows"
    global: selector = "body" font family = "system-ui, sans-serif" margin = 0 padding = "1.5rem" background = "#e2e8f0" end
    box:
        display = flex gap = 24 flex wrap = wrap
        Card: label = "soft" shadow = "0 4px 12px rgb(0 0 0 / 18%)" end
        Card: label = "hard offset" shadow = "6px 6px 0 #0f172a" end
        Card: label = "spread ring" shadow = "0 0 0 4px #60a5fa" end
        Card: label = "inset" shadow = "inset 0 3px 8px rgb(0 0 0 / 30%)" end
        Card: label = "glow" shadow = "0 0 24px #22d3ee" end
        Card: label = "layered" shadow = "0 1px 2px rgb(0 0 0 / 20%), 0 8px 24px rgb(0 0 0 / 18%)" end
    end
end

The next example lets you try the values. The sliders write a new box-shadow and border-radius to the card and print the CSS they made, so you can read how each number changes the look.

import dom

func update():
    x := dom.GetValue(dom.ById("x"))
    y := dom.GetValue(dom.ById("y"))
    blur := dom.GetValue(dom.ById("blur"))
    radius := dom.GetValue(dom.ById("radius"))
    shadow := x + "px " + y + "px " + blur + "px rgb(0 0 0 / 35%)"
    dom.SetStyle(dom.ById("card"), "box-shadow", shadow)
    dom.SetStyle(dom.ById("card"), "border-radius", radius + "px")
    dom.SetText(dom.ById("css"), "box-shadow: " + shadow + "; border-radius: " + radius + "px")
end

page:
    title = "Shadow lab"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box: id = "card" width = 180 height = 90 margin = "10px 0 20px" background = "white" border = "1px solid #cbd5e1" box shadow = "0px 4px 12px rgb(0 0 0 / 35%)" border radius = 12 end
    box: label: content = "x" width = 60 display = "inline-block" end input: type = "range" id = "x" min = "-20" max = "20" value = "0" input = update end end
    box: label: content = "y" width = 60 display = "inline-block" end input: type = "range" id = "y" min = "-20" max = "20" value = "4" input = update end end
    box: label: content = "blur" width = 60 display = "inline-block" end input: type = "range" id = "blur" min = "0" max = "40" value = "12" input = update end end
    box: label: content = "radius" width = 60 display = "inline-block" end input: type = "range" id = "radius" min = "0" max = "45" value = "12" input = update end end
    paragraph: id = "css" content = "box-shadow: 0px 4px 12px rgb(0 0 0 / 35%); border-radius: 12px" end
end

Broken boxes and new corner shapes

An inline element such as a span can wrap onto several lines, and then its padding, border and background have to be drawn on more than one piece. box decoration break chooses how. With slice, the default, the element is drawn as if it were one long box that has been cut with scissors, so the left edge appears only on the first piece and the right edge only on the last. With clone every piece is a complete box with its own edges, padding and corners. Use clone for highlights and tags that may wrap.

page:
    title = "Box decoration break"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" max width = "280px" line height = 2.2 end
    paragraph:
        content = "Slice (the default): "
        span: background = "#fde68a" padding = "2px 10px" border radius = 8 border = "2px solid #b45309" box decoration break = "slice" content = "one highlight cut into pieces where the line breaks" end
    end
    paragraph:
        content = "Clone: "
        span: background = "#fde68a" padding = "2px 10px" border radius = 8 border = "2px solid #b45309" box decoration break = "clone" content = "every piece gets its own padding, border and corners" end
    end
end

The corner shape properties change what a rounded corner looks like. Until now the curve was always a quarter circle. corner shape can make it a squircle (a softer, superelliptical curve, like app icons), a bevel (cut straight across), a scoop (curved inward) or a notch (a square cut inward), and each corner has its own property, such as corner top left shape. The shape is applied to the corners that border radius sets, so the radius is still needed to say how large the corner is.

component Tile(label, shape):
    box:
        width = 100
        height = 80
        background = "#7c3aed"
        color = "white"
        display = flex
        align items = center
        justify content = center
        border radius = 28
        font size = 13
        corner shape = shape
        content = label
    end
end

page:
    title = "Corner shapes"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        display = flex gap = 16 flex wrap = wrap
        Tile: label = "round" shape = "round" end
        Tile: label = "squircle" shape = "squircle" end
        Tile: label = "bevel" shape = "bevel" end
        Tile: label = "scoop" shape = "scoop" end
        Tile: label = "notch" shape = "notch" end
        Tile: label = "scoop bevel" shape = "scoop bevel" end
    end
end

How the compiler checks values

Every style value in a page is checked while the page is compiled, not in the browser. A browser silently ignores a CSS value it does not understand, and the page just looks wrong with no message. In Salam a bad value stops the build with error E018. The message names the property, shows the value you wrote and says what was expected. For example, writing a style of wobbly in border style reports invalid value for 'border style': 'wobbly' is not 'none', 'hidden', 'dotted', ... followed by the file, line and column where the value is. A radius of big reports that it is not a length or a percentage, and a border shorthand with parts that do not belong together says that it is not a valid combination for this property.

The check works on the shorthands as well. It splits border into its parts and checks each part against its own rules, so a typo in a color name inside "2px solid reed" is found too. Persian files accept the Persian value names such as یکپارچه and خط‌چین in the same places, and the messages are in Persian. The tables below show the values each property accepts.

Reference: borders, outlines and shadows

Every property of this lesson is listed below. Each one has a one-line description of what it accepts and an example that the compiler has checked. The groups follow the lesson: the shorthand and the four values rule, the four physical sides, the logical sides, the corners, the border image, and then outline, shadow and the corner shapes.

All sides

Top

Right

Bottom

Left

Block sides

Inline sides

Corners

Border image

Outline

Shadow, breaks and corner shapes

Try it yourself

• Make a notification box with a thick border inline start in red, then put it inside a box with dir = "rtl" and check that the stripe moves to the right by itself.
• Build a button with a pill shape, a box shadow that gets smaller on active, and a focus ring of a different color.
• Make a gradient border with border image and a slice of 1, and try to round its corners. What happens, and what can you use instead?
• Add a fourth slider to the shadow lab that changes the spread, and a checkbox that adds the word inset.