The box model

Here is one of the nicest things about pdg: the box model is not a special element. It is a set of style: attributes that ride on any tag — a <text>, a <table>, a whole <vertical> column. If you know the CSS box model, you know this already. The full set is catalogued under Styles; this chapter is the working tour.

Padding and background

Put space inside an element's edge with style:padding, and fill behind it with style:background. Both use names you know — padding takes the same 1–4 value shorthand as CSS.

<text size="14" style:padding="16px" style:background="#faf6ed">
  A paragraph with 16px of padding and a warm background. The fill sits behind
  the padded box, just like in CSS.
</text>

Borders and rounded corners

style:border sets a border width (1–4 shorthand), style:border-color its colour, and style:border-radius rounds the corners.

<text size="14"
      style:padding="14px"
      style:border="1.5px"
      style:border-color="#c4341f"
      style:border-radius="10px"
      style:background="#fff">
  A bordered, rounded card — built entirely from style: attributes on a plain
  paragraph. No wrapper element required.
</text>

The per-side and per-corner forms exist too — style:border-bottom, style:border-top-left-radius, and so on — see style:border.

Margin vs padding (the usual distinction)

style:margin is space outside the element — it pushes neighbours away and does not get the background. style:padding is space inside — between the border and the content. Exactly as on the web.

<vertical style:background="#ece5d5">
  <text size="13" style:margin="14px" style:padding="10px" style:background="#fff">
    margin pushes me in from the grey; padding holds my white fill off my text.
  </text>
</vertical>

Shadows

style:box-shadow takes x y blur spread color, just like CSS. Pair it with a background and radius for a card that lifts off the page.

<text size="14"
      style:padding="16px"
      style:background="#ffffff"
      style:border-radius="8px"
      style:box-shadow="0 3px 12px #00000022">
  A floating card. The shadow is offset 3px down, blurred 12px, in a translucent
  black.
</text>

Sizing and alignment

Fix dimensions with style:width and style:height (and min-/max- variants). When a box is larger than its content, style:align and style:valign place the content within it — start, center, or end.

<text size="14"
      style:width="240px"
      style:height="90px"
      style:align="center"
      style:valign="center"
      style:background="#1b1a17"
      color="#faf6ed">
  Centred in a fixed 240×90 box.
</text>

Transparency and clipping

style:opacity (0–1) fades an element and everything inside it. style:clip crops content to the box on both axes — CSS overflow: hidden — so a fixed-size box never lets its contents spill past its edges. See style:opacity and style:clip.

<vertical gap="8px">
  <text size="16" style:padding="8px" style:background="#c4341f" color="#fff">
    Full strength
  </text>
  <text size="16" style:padding="8px" style:background="#c4341f" color="#fff"
        style:opacity="0.45">
    45% opacity — the fill and the text both fade together
  </text>
</vertical>

A note on pagination

A box does not stop content from flowing across a page break. If a padded, bordered block runs longer than the page, pdg splits it: the box is drawn around what fits, the cut edge carries no border or rounding, and a continuation box picks up the rest on the next page — so the two fragments read as one box severed by the break. Backgrounds, borders, and padding all come along on both sides. A bare <text> splits the same way, just without the chrome.

The exception is a fixed style:height: a box pinned to a height can't grow onto a second page, so content that overflows it is cut (with a warning) — that is what style:clip makes deliberate. And when you want a block to stay whole — a card or callout that should never straddle a break — add keep="true", which moves the whole block to the next page rather than letting it split. We lean on both in Chapter 9.

You now have boxes. Next we arrange them — the part where pdg feels most like flexbox.