Icons

Two complete icon packs, Lucide (1711 glyphs) and Bootstrap Icons (2078), are compiled into the wcl binary. The build downloads nothing and reads nothing from disk, 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.

One 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. They are 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 the pattern engine scans for icon tokens, and comes out untouched. Neither the pattern nor the lookup ever fails a build.

The two bundled packs

The packs are vendored into the repository, and crates/wcl_wdoc/build.rs bundles them. It concatenates every *.svg in a pack directory into one blob and emits a name-sorted index into it. An icon lookup 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, so a set.name token splits 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, and only Bootstrap has windows. When both provide a name and you have not said which you mean, the resolution order decides.

Licensing

Both licences are permissive and both require the licence text to travel with the files. This repository already meets that obligation: 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.

Inline 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.

If a token matches but resolves to nothing, the build emits the literal text you wrote. That is the whole safety story for the pattern: prose that happens to look like an icon reference stays 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.

Iconsets

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:

Per-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 and nothing else: size, color, fill, background, class. 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"
  }
}

How 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 the lookup always tries a set of yours 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 build emits the literal :name: text. In a diagram, it draws nothing. A shape whose icon misses gets no badge.

The library declares iconset lucide {} and iconset bootstrap {} unconditionally, so 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, because the lookup reaches a root set 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 falls back to a compiled-in pack whose name matches the prefix. That value covers the icon(name, class) constructor, and so a callout's default glyph and a sidebar_footer button. 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 build emitted the literal text. Nor does a diagram icon block, nor a shape badge. Both resolve through the set list and stop there.

The placeable icon block

icon is also a shape. It extends SvgBlock, so it is a legal child of a diagram or a container. You place it 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, which is 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.

Icon badges on shapes

The third mechanism puts an icon on a shape rather than beside it. Every box-like shape carries four badge fields, and that means rect, circle, container, process, decision, terminator, and any custom SvgBlock shape that declares the same 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, as in icon = "ui.shield-check", when you want a set other than the first one that answers.

Sizing 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 does depends on where the icon is drawn, and the table below 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>.

The shared sprite

The build never copies a glyph 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. That file holds a <symbol> for each icon the build 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. The rewrite keeps viewBox. It also keeps the presentation attributes fill, stroke, stroke-width and stroke-linecap, because they are what makes the glyph draw. It drops width, height, xmlns, id, class, role, aria-hidden and focusable, 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 build writes the href relative, _wdoc/icons.svg, so it resolves both under the dev server and on a static host. And it is a fetch, so the icons appear when the output is served rather than when you open a page file directly from disk.

One registry, every caller

There is exactly one icon registry per build. The renderer threads it through as patterns.icons(), and every caller 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.

Icons 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. The PDF renderer embeds an inline icon 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 build icons.wcl --out md --type markdown
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: put @except(backends = [:markdown]) on the block that carries the decorative icon, and a plain-text block in its place. The axis is per block, though, and an inline :name: is not a block. A paragraph is the smallest thing you can hide.

Icons 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 icon() 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 the fallback 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.

The full galleries

Every glyph in both bundled packs — 1711 Lucide and 2078 Bootstrap, 3789 in all — is drawn out in Icon galleries, one page of nothing else. It is a lookup table rather than a chapter, so it sits beside this one instead of inside it: browser find over 3,789 names is the way to use it, and it is the only page in the book long enough to be worth loading on its own.

Where to go next

• Text and formatting. The inline pattern engine :name: belongs to, and the rest of what a prose string may carry.
• Styling rules. The class system an iconset's class and color hang off, and how currentColor reaches an icon.
• Callouts, footnotes and chapter headers. The block whose default glyphs a renamed lucide set moves.
• The diagram canvas. Placement, anchors and layout for the icon block and every shape that wears a badge.
• Output targets. HTML, PDF and Markdown, and what else differs between them.
• Writing your own blocks. Lowering to Html, where the icon(name, class) constructor lives.