--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/design_system/ICONS.md	Tue Aug 04 15:12:09 2026 -0700
@@ -0,0 +1,40 @@
+# Zenbu UI icons
+
+`zen-icon` is the only icon renderer used by Zenbu UI. It renders first-party
+SVG geometry in light DOM, inherits the current text color, and has no font,
+emoji, package, or network dependency.
+
+```html
+<zen-icon name="search"></zen-icon>
+<zen-icon name="archive" label="Archive repository" size="1.25rem"></zen-icon>
+```
+
+Icons without `label` are decorative and receive `aria-hidden="true"`. An icon
+with a label receives `role="img"` and the matching accessible name. Buttons
+that already have an accessible name should use an unlabeled icon.
+
+## Names
+
+The initial set contains:
+
+```text
+add alert archive arrow-down arrow-left arrow-right arrow-up
+branch calendar check chevron-down chevron-left chevron-right chevron-up
+close code copy download error external file folder history info
+menu moon more pause play repository retry search settings sun
+trash upload user
+```
+
+Unknown names render the `alert` fallback rather than inserting authored HTML.
+The catalog at `/icons` renders the authoritative runtime list.
+
+## Hard requirements
+
+- Do not use emoji or text glyphs as interface icons.
+- Do not add inline SVG outside `components/icon.js`.
+- Do not import an external icon package or icon font.
+- Use `currentColor` through `zen-icon`; the owning component must obtain that
+  color from a `--zen-color-*` token.
+- Add new geometry to the first-party icon registry and include a catalog test.
+
+`//design_system/test:design_system_policy_test` enforces these requirements.