Icons in pages, dashboards and boards

Icons in pages, dashboards and boards

A Plank page cannot load anything from the internet when it is opened: the file viewer and canvas boards allow no CDN. So an icon font, an icon <script> or an <img src="https://…"> is simply blank for the person reading it. Icons go into the file, as inline SVG.

Every container has the Lucide set (≈2 100 icons, ISC licence) and a tool that prints any of them ready to paste:

python3 /opt/plank/design/icon.py search invoice        # English names and tags
python3 /opt/plank/design/icon.py search счёт           # common Russian business words work too
python3 /opt/plank/design/icon.py svg receipt-text
python3 /opt/plank/design/icon.py svg triangle-alert --size 16 --label "Просрочено"
python3 /opt/plank/design/icon.py info                  # version and count

svg prints one line:

<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" class="icon icon-receipt-text" aria-hidden="true">…</svg>

It draws in currentColor, so it takes the colour of the text around it and follows light and dark with no extra work. It carries no ids, no scripts and no links, so any number of copies can sit in one page. Lucide is also what the Plank app draws, so a page's icons look like the app's.

Options: --size (px, default 20), --stroke (default 1.75), --class (extra classes), --label (see below). An unknown name prints the closest matches.

When an icon earns its place

An icon helps when it is faster than the word or marks a kind the reader will see many times:

• Status, always with a word: circle-check Оплачено, triangle-alert Скоро срок, circle-x Просрочено. Colour from the status tokens in Charts; the icon is what keeps the status readable for a colour-blind reader and on a black-and-white printout.
• Kinds of things in a list or a diagram: a bank (landmark), a document (file-text), a person (user), a warehouse (warehouse).
• Actions on a button whose label is also there, or is universal (search, x for close, download).
• The leading mark of a KPI tile — one per tile, the same size in every tile.

It does not help as decoration beside a heading, as a bullet on every list item, or as the only label of a control whose meaning is not obvious.

An icon is not an illustration. An icon is a small symbol beside a label, up to about 48px. The picture that carries a slide's or a page's idea — a sun with rays, a leaf, a cell and its chloroplast, a process with arrows, the product itself — is an illustration or a diagram: draw it yourself as inline SVG, with filled shapes, several colours and labels in the drawing. That is encouraged, and a school or pitch deck should have several. Lucide does not replace an illustration, and a big outline icon is not one. Its colours are art direction, not chart series: they are free, within the contrast rules.

Never an emoji instead of an icon. An emoji is drawn by the reader's operating system — it is a different picture on Windows, iPhone and Android, ignores the theme, and reads as a chat message rather than a document.

Size, stroke and alignment

One size and one stroke per role across the whole page. Put an icon and its text in a flex row with align-items:center; gap:6px, and give the icon flex:none so a long label cannot squash it. In a diagram, place the printed <svg> as a nested <svg x="…" y="…" width="24" height="24"> inside the drawing.

Colour comes from the surrounding text (color: var(--ink-muted) on the row, or the status token on a status pill). Do not set fill — these are outline icons and a fill turns them into blobs.

Labelled or decorative

There are two states, as for any SVG (Diagrams, rule 2):

• Next to a word that says the same thing — the default, aria-hidden="true". A screen reader reads the word once instead of twice.
• On its own — an icon-only button, a status icon in a narrow table column: --label "…". The tool prints role="img" aria-label="…" instead. An icon-only <button> takes the aria-label on the button itself, and also a title so a mouse user can hover it.

On a canvas board, in a deck

Canvas boards (*.canvas.html) take the same inline SVG (Canvas). A .pptx deck draws its own shapes and cannot take an SVG; an HTML deck or a board slide can.

Icons never count as a slide's visual. A deck slide with only icons is still a text slide, and a deck of ≥ 6 slides where more than half carry no visual fails the canvas check (text-only-deck). The visual is a chart (chart.py), a diagram (diagram.py), a drawn illustration or a photo — which one per slide: /opt/plank/canvas/DECK.md.

Lucide's licence (ISC) is in /opt/plank/design/icons/lucide/LICENSE.