Icons

Two complete icon packs — Lucide (1711 glyphs) and Bootstrap Icons (2078) — are compiled into the wcl binary. Nothing is downloaded, nothing is read from disk at build time, and you declare nothing to use them. This chapter covers the three places an icon may go, the iconset block that renames a pack and styles it, the rules that turn a name into a glyph, the shared sprite the build emits, and what each of the three output targets does with an icon. It ends with both packs in full, every glyph drawn beside its name.

Every file and command below was run before it was written down. Type them and compare.

§ 1One file, every way in

Save this as icons.wcl. It uses all three ways to place an icon and declares one custom set:

# icons.wcl — every way to put an icon on a page.
import <wdoc.wcl>

iconset ui {
  pack  = "lucide"
  size  = "1.25em"
  color = "#88c0d0"
  icon_def "heart" { color = "#bf616a" }
}

site demo {
  title            = "Icon lab"
  default_template = :book
  toc { chapter "Icons" { page = lab } }
}

page lab {
  title = "Icon lab"

  h1 "Icon lab"

  p "Bare :heart:, prefixed :bootstrap.house:, and a time like 10:30 that stays prose."

  diagram {
    width = 240  height = 90
    icon "lucide.compass" { x = 20.0  y = 13.0  width = 64.0  height = 64.0 }
    process "Validate" {
      id = v  x = 110.0  y = 20.0  width = 110.0  height = 50.0
      icon = "lucide.shield-check"
    }
  }
}

$ wcl wdoc build icons.wcl --out site
wrote 1 page
$ ls site/_wdoc/icons.svg
site/_wdoc/icons.svg

The paragraph renders as prose with two glyphs in it, and the diagram draws a third and a fourth. Both are reproduced below — unstyled, because this book declares no ui set of its own:

Bare , prefixed , and a time like 10:30 that stays prose.

Four icons, three mechanisms. :heart: and :bootstrap.house: are the inline pattern — a :name: token inside any prose string. The compass is the icon block, a placeable shape inside a diagram. The shield on the Validate box is a badge: the icon field that every box-like shape carries. All four resolve through one registry, and all four end up in one file, site/_wdoc/icons.svg, holding exactly the four glyphs the build used.

Note the last clause of the paragraph too. 10:30 sits in prose that is scanned for icon tokens, and comes out untouched. Neither the pattern nor the lookup ever fails a build.

§ 2The two bundled packs

The packs are vendored into the repository and bundled by crates/wcl_wdoc/build.rs, which concatenates every *.svg in a pack directory into one blob and emits a name-sorted index into it. Looking an icon up is a binary search and a slice — there is no per-icon file and no runtime read.

An icon name is the file stem. house.svg is the icon house; alarm-clock-check.svg is alarm-clock-check. Names are lower-case, digits and hyphens only — which is what lets a set.name token be split on its dot without ambiguity. The two galleries at the end of this chapter list every name in both packs.

The two packs overlap in places and diverge in most. Both have house, heart, wrench and zoom-in; only Lucide has shield-check, only Bootstrap has windows. When both provide a name and you have not said which you mean, the resolution order decides.

§ 2.1Licensing

Both licences are permissive and both require the licence text to travel with the files. That obligation is already met inside this repository: each pack directory keeps its upstream LICENSE beside the SVGs, and the two files are vendored verbatim — only icons/*.svg and LICENSE are copied from upstream, nothing else.

§ 3Inline icons

Inside any prose string, :name: becomes an icon. The pattern is one of the built-in inline patterns, so it works everywhere the others do — a p, a text block's span, a li, a table cell, a callout body, a chart label. Text and formatting covers the pattern engine as a whole.

The token is deliberately narrow. It matches a colon, a character from a–z or 0–9, then any run of lower-case letters, digits, dots, hyphens and underscores, then a closing colon. Three consequences follow:

• :Home: does not match — the first character after the colon must be lower-case or a digit.
• 10:30 does not match — a token needs a closing colon and there is none. note: see below does not match either — the character after the colon must be a letter or a digit, and a space is neither.
• :lucide.compass: matches as one token, dot and all, and the dot is what separates the set name from the icon name.

A token that matches but resolves to nothing is emitted as the literal text you wrote. That is the whole safety story for the pattern: prose that happens to look like an icon reference is left as prose.

Write this:

p "Bare :heart:, prefixed :bootstrap.house:, and :not-an-icon: falls through."

…and the build emits this (line-broken here to fit):

<p>Bare
  <svg class="wdoc-icon" style="width:1.25em;height:1.25em;color:#bf616a;">
    <use href="_wdoc/icons.svg#lucide-heart"/>
  </svg>,
  prefixed
  <svg class="wdoc-icon"><use href="_wdoc/icons.svg#bootstrap-house"/></svg>,
  and :not-an-icon: falls through.
</p>

Two things to read out of that. First, each icon is a <use> of the shared sprite rather than a copy of the glyph — the sprite explains why. Second, the styling on the heart came from the ui iconset and its icon_def, while bootstrap.house names a set that declares no defaults and so carries no inline style at all.

§ 4Iconsets

An iconset is a named reference to a bundled pack plus the default styling for icons drawn from it:

iconset ui {
  pack       = "lucide"                 # which bundled pack to read
  size       = "1.25em"                 # default inline size
  color      = "var(--wdoc-accent)"     # default foreground
  class      = ["ui-glyph"]             # added to every icon in the set

  icon_def "heart"  { color = "#bf616a" }
  icon_def "circle-x" { color = "#bf616a"  class = ["shout"] }
}

Its fields:

§ 4.1Per-icon overrides

An icon_def child names one icon in the set and overrides the set's defaults for it. It carries the same five styling fields — size, color, fill, background, class — and nothing else. Sizing and colour has the layering rule that decides what an override replaces.

iconset ui {
  pack  = "lucide"
  color = "#88c0d0"          # everything in `ui` is blue …
  class = ["ui-glyph"]

  icon_def "heart" {         # … except the heart
    color = "#bf616a"
    class = ["shout"]        # ends up with class="wdoc-icon ui-glyph shout"
  }
}

§ 4.2How a name resolves

A name reaches a glyph through one registry, loaded once per build from those root iconset blocks. Four rules, in this order:

• A set.name token names the set. :ui.heart: looks only at the set called ui. If no set has that name, or that set's pack has no heart, the lookup fails — it does not try elsewhere. (One caller has a fallback after that failure; the example below is it.)
• A bare name tries every set in declaration order, and the first whose pack holds the icon wins. The document's own sets come before the two the library declares, so a set of yours is always consulted first.
• On a diagram icon, an explicit set = field beats a set. prefix on the name. icon "lucide.compass" { set = ui } reads from ui.
• A failed lookup is never a build error. Inline, the literal :name: text is emitted. In a diagram, nothing is drawn. A badge whose icon misses simply has no badge.

The library declares iconset lucide {} and iconset bootstrap {} unconditionally, which is why both packs work in a document that declares nothing. Because a set's pack defaults to its own name, those two declarations are the whole of their configuration.

Declaring a set with one of those names replaces it — a root set is found before a library one:

import <wdoc.wcl>

# `lucide` now means the bootstrap pack, everywhere in the document.
iconset lucide { pack = "bootstrap" }

site demo { title = "s"  default_template = :book
  toc { chapter "L" { page = lab } }
}

page lab {
  title = "L"
  h1 "L"
  callout "Careful" { class = ["warning"]  body = "text" }
  p "inline :lucide.triangle-alert: here"
}

Build that and the sprite holds one symbol, lucide-triangle-alert, while the paragraph renders the literal text :lucide.triangle-alert:. Both halves of that are worth understanding, because they are the one place the rules above are not the whole story.

The warning callout's default glyph is lucide.triangle-alert, and Bootstrap has no icon by that name, so the set lookup failed. One path has a second chance after that failure: an icon named through the Html::Icon value — the icon(name, class) constructor, and so a callout's default glyph and a sidebar_footer button — falls back to a compiled-in pack whose name matches the prefix. That is why the callout drew the real Lucide glyph.

Nothing else gets that fallback. The author's own inline token did not: rule 1 applied, the lookup failed, and the literal text was emitted. Nor does a diagram icon block, nor a shape badge — both resolve through the set list and stop there.

§ 5The placeable icon block

icon is also a shape. It extends SvgBlock, so it is a legal child of a diagram or a container, it is placed by x / y or by anchors, and an edge may attach to it exactly as to a rect. The diagram canvas covers placement and Connections and routing covers the edges.

diagram {
  width = 260  height = 100
  icon "lucide.database" { id = db  x = 20.0   y = 26.0  width = 48.0  height = 48.0 }
  icon "lucide.cloud"    { id = cl  x = 190.0  y = 26.0  width = 48.0  height = 48.0 }
  db -> cl
}

The name is the block's label, so icon "lucide.compass" { … } and icon { name = "lucide.compass" … } are the same block written two ways. Its fields:

A set on the block and a set prefix on the name do different jobs, and the difference shows up in the styling. icon "lucide.compass" reads from the lucide set — the library one, with no defaults — so it inherits no colour even if you have a beautifully styled set of your own. icon "compass" { set = ui } reads from ui, and picks up its color, background and classes.

§ 6Icon badges on shapes

The third mechanism puts an icon on a shape rather than beside it. Every box-like shape — rect, circle, container, process, decision, terminator, and any custom SvgBlock shape that declares the same fields — carries four badge fields:

IconPos is a symbol set with seven members. Corner and edge placements are inset from the box by a tenth of its shorter side; :center is not inset.

:left is the default for two reasons. The label-bearing flowchart shapes reserve a matching strip on their left, so the badge and the label sit side by side instead of on top of one another. And a corner badge pokes out of a rounded or oval outline. Compare the two:

process "Validate" {
  id = a  x = 10.0  y = 20.0  width = 180.0  height = 50.0
  icon = "lucide.shield-check"                      # :left, the default
}
process "Validate" {
  id = b  x = 230.0  y = 20.0  width = 180.0  height = 50.0
  icon = "lucide.shield-check"  icon_pos = :top_right
}

A badge takes no set field. Write the set into the name — icon = "ui.shield-check" — when you want a set other than the first one that answers.

§ 7Sizing and colour

Styling arrives in three layers, and each later layer wins field by field:

• The set's defaults — the size / color / fill / background / class on the iconset.
• The icon_def for this one icon, if the set declares one.
• The placement itself — the fields on the icon block, or icon_class on a badge.

Scalar fields replace; class lists concatenate, so an icon ends up wearing wdoc-icon, then the set's classes, then the icon's own.

What each field actually does depends on where the icon is drawn, and the table is the comparison worth having in one place:

The default inline size is not a hard-coded number in the renderer: the library ships a base "svg.wdoc-icon" rule setting width: 1em; height: 1em, so an inline icon is as tall as the text around it and moves with it. An iconset's size overrides that rule with an inline style. The selector is deliberately svg.wdoc-icon — element and class — so it cannot touch a diagram icon, which is a <use> and not an <svg>.

§ 8The shared sprite

No glyph is ever copied into a page. Each use emits a <use href="_wdoc/icons.svg#pack-name"/>, and after every page has rendered, the build writes one _wdoc/icons.svg holding a <symbol> for each icon that was actually used. A document that references four icons ships four symbols, out of the 3789 available.

The symbol is the pack's own SVG with its root tag rewritten. viewBox is kept; presentation attributes — fill, stroke, stroke-width, stroke-linecap — are kept, because they are what makes the glyph draw; width, height, xmlns, id, class, role, aria-hidden and focusable are dropped, because the <use> supplies the size and the rest is noise. The id is {pack}-{name}.

<svg xmlns="http://www.w3.org/2000/svg" style="display:none">
  <symbol id="lucide-heart" viewBox="0 0 24 24" fill="none"
          stroke="currentColor" stroke-width="2"
          stroke-linecap="round" stroke-linejoin="round">
    <path d="M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 …" />
  </symbol>
  …
</svg>

Three facts follow from the sprite being a separate file. A page with fifty repetitions of one icon carries fifty short <use> elements and one copy of the path data. The href is written relative, _wdoc/icons.svg, so it resolves both under the dev server and on a static host. And it is a fetch, which means the icons appear when the output is served rather than when a page file is opened directly from disk.

§ 8.1One registry, every surface

There is exactly one icon registry per build. The renderer threads it through as patterns.icons(), and every surface that can name an icon asks the same object: the inline pattern engine, the diagram shape renderer, the badge renderer, a callout's default glyph, a sidebar_footer button's icon, and the icon(name, class) constructor available to your own blocks. One consequence matters in practice — the sprite is complete because everything records its usage in the same place, so a glyph that only a callout asked for is still in the file.

§ 9Icons across the three output targets

Icons are one of the features where the three targets genuinely differ, so it is worth seeing all three at once. Output targets covers the targets themselves.

Two of those rows deserve a sentence each. In PDF there is no sprite file to fetch, so the glyph must travel inside the document. An inline icon is embedded as the raw pack glyph, so an iconset's size and color do not reach it: it is one em tall, and it is the page's text colour. In Markdown the inline pattern has nowhere to go, because GitHub-flavoured Markdown has no inline SVG. The token you wrote comes back out as text. Diagrams are unaffected either way, because a diagram was always going to be an image.

Build the file from the top of this chapter as Markdown and the difference is plain:

$ wcl wdoc markdown icons.wcl --out md
wrote 1 page
$ cat md/lab.md
# Icon lab

Bare :heart:, prefixed :bootstrap.house:, and a time like 10:30 that stays prose.

![diagram](_wdoc/lab-diagram-1.svg)

If an icon has to survive into Markdown, put it in a diagram, or use a text marker instead. Visibility is the other tool here — @except(backends = [:markdown]) on the block that carries the decorative icon, and a plain-text block in its place — but note that the axis is per block, and an inline :name: is not a block. A paragraph is the smallest thing you can hide.

§ 10Icons in your own blocks

A block you declare yourself lowers to the HTML vocabulary, and that vocabulary has an icon in it. The icon(name, class) constructor builds one:

@block("status")
type Status extends ContentBlock {
  @inline(0) label: utf8
  glyph: utf8?

  lower = fn(s: &Status) -> list<Html>
    [el("span", ["status"], [
      icon(s.glyph ?? "lucide.circle-check", ["status-glyph"]),
      inl(s.label),
    ])]
}

The name resolves through the same registry and by the same rules, and it records its usage, so a glyph only your block asks for is still in the sprite. icon() is also the constructor that carries the compiled-in pack fallback: a pack.name that no declared set covers still resolves, exactly as a callout's default glyph does. A name that even that cannot place emits nothing rather than failing. Writing your own blocks covers the lowering interface, and inl alongside icon in the el family.

The other route needs no lowering at all. Because Html::Inline and every prose string run through the inline pattern engine, a block that emits prose gets :name: support for nothing.

§ 11All Lucide icons

Every icon in the bundled Lucide pack (1711). Reference one inline as :lucide.<name>:, or as a shape badge / icon block with lucide.<name>.