Duolith docs

0030. A small built-in icon set, placed with <icon name="...">

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP7 (kit)

Context

Buttons, rows, fields and empty states all want icons (a chevron, a search glass, an alert). Without a built-in set every app would bring its own images, in its own style, and the kit could not show any. Icons must take the colour of the text around them so they follow the theme and dark mode, and must work on native later.

Decision

  • **<icon name="chevron-right" />** is an element. Its size comes from utilities (w-5 h-5), 1.25em square otherwise; its colour is the current text colour. It is hidden from assistive technology unless it has a label, which makes it an image with that name.
  • The set is data: spec/kit/icons.yaml, about fifty icons drawn on one 24-unit grid with 2-unit round strokes, as SVG shapes. A name written as text is checked when the page is built (E0125, with the nearest name as a suggestion); a name given as an expression, as kit parts do with their icon prop, is not.
  • On the web each icon becomes a CSS mask in the theme stylesheet: .st-icon[data-icon="check"] { --icon: url("data:image/svg+xml,...") }, filled with currentColor. So icons need no extra requests, no SVG namespace handling in the runtime, and recolour with the text. Native emitters will turn the same shapes into vector drawables and SF-style images.

Alternatives considered

OptionWhy not
An SVG sprite with <use href>The runtime would need namespaced element creation, and a separate file to load
An icon fontBlurry at some sizes, poor with screen readers, and a font per platform
Import a large third-party setThousands of icons to ship and a licence to track; a small set in one style is enough for the kit, and apps can still use images
Icons as image files per nameNo recolouring with the theme

Consequences

  • The theme stylesheet grows by about 20 KB, once per app, cached.
  • Adding an icon is a reviewed change to spec/kit/icons.yaml; names describe what the icon shows.
  • Apps that need a different icon use <image> until icon overrides are decided.