Files
Marcos Paulo de3ec375ae
ci / ci (macos-latest) (push) Has been cancelled
ci / ci (ubuntu-latest) (push) Has been cancelled
ci / ci (windows-latest) (push) Has been cancelled
docs: specs and briefs for Tasks, Templater, Kanban and icons/banners
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21 06:06:54 -03:00

12 KiB

Icons and banners from properties (roadmap item 16)

Part of specs/plugins-parity/. Replaces the community plugins Iconize (2.27M downloads), Banners and the icon half of Pretty Properties. Research (2026-10-21):

  • Banners (github.com/noatpad/obsidian-banners README): frontmatter keys banner (URL or internal image link, quoted), banner_x, banner_y (0 to 1, centre of the visible window), banner_lock, banner_icon (emoji); solid and gradient banner styles; banners also in embeds and page previews; adjustable heights; drag to reposition.
  • Iconize (github.com/FlorianWoelki/obsidian-iconize, listing on community.obsidian.md): icons before file and folder names, icons in notes and above titles, icon packs plus custom SVG, icons in tabs, custom rules, frontmatter integration, per-icon colour. Maintenance has stopped upstream; forks (GlyphIt) and Iconic (rule-based by name, extension, parent folder, tags, properties) continue it.
  • The exact Iconize frontmatter spelling (icon, iconColor) was not confirmable from fetched pages; the spec adopts icon and iconColor as the contract and tests with real notes first (Open question Q1).

Problem

Users who tag notes with icon: LiRocket or banner: "[[cover.jpg]]" see none of it. The Explorer shows one generic file icon for every note, tabs likewise, and a note has no header image. The Bases Cards view already shows an image property as a cover (views/base_view/layouts/cover.rs) but nothing else uses image properties.

Goal

Two properties drive the look of a note, everywhere, with no extra file:

  • icon (and optional iconColor): shown in the Explorer row, the tab, the quick switcher and search rows, the Bases name column, and above the title in the note view.
  • banner (and banner_y): a header image at the top of the note view and on hover cards. Folders take their icon from their folder note (Folder/Folder.md or the configured folder-note name). Setting them is a context-menu action ("Set icon", "Set banner") that writes the property through the existing property commands. Properties are the single source of truth; Obsidian users keep their data.

Non-Goals (v1)

  • Custom icon packs download (Iconize packs from the network): offline only.
  • Rules ("all notes in Projects/ get icon X"): Feature ideas.
  • Remote banner URLs: the network policy of the roadmap forbids fetching without its own settings switch; banner: https://... shows a placeholder card with an "enable" notice, no fetch (same pattern as Maps).
  • Icons inside note text (:LiRocket:), banners in embeds and page previews, gradient banner style.
  • Animated icons for notes (the Lottie helpers stay for controls).

Design decisions

D1 - Property contract

Key Value Meaning
icon rocket, lucide-rocket, LiRocket (Lucide), an emoji (🚀), or a wikilink/path to an .svg/.png in the vault ([[icons/rocket.svg]]) the icon
iconColor #rrggbb, #rgb, a theme token name (accent, danger, success) tint for Lucide/SVG icons (emoji and PNG keep their colours)
banner wikilink [[cover.jpg]], ![[cover.jpg]], vault path, or https:// URL (placeholder only) header image
banner_y number 0..1 (default 0.5) vertical focus of the crop, 0 top, 1 bottom
banner_x number 0..1 (default 0.5) horizontal focus
banner_icon emoji used as icon when icon is absent (Banners compatibility)

Invalid values are ignored (no icon, no banner), never an error shown on every frame; a Properties-view warning chip is enough (Feature ideas). banner_y clamps ONLY for painting (input is hostile but a numeric focus, not a size); an out-of-range value is displayed as the nearest edge and flagged in the properties view.

D2 - Pure resolver in the index crate

crates/index/src/decor.rs (L1, pure):

pub enum IconRef { Lucide(String), Emoji(String), File(String) /* vault link target as written */ }
pub struct Decor { pub icon: Option<IconRef>, pub color: Option<ColorRef>, pub banner: Option<BannerRef> }
pub enum ColorRef { Rgb(u8, u8, u8), Token(String) }
pub struct BannerRef { pub target: BannerTarget, pub x: f32, pub y: f32 }
pub enum BannerTarget { File(String), Url(String) }
pub fn decor_from_props(props: &[(String, PropValue)]) -> Decor;
pub fn parse_icon(raw: &str) -> Option<IconRef>;

Rules: Lucide spellings LiRocket, lucide-rocket, rocket, Rocket normalise to kebab case rocket (LiArrowRight -> arrow-right); an emoji is one extended grapheme cluster that is not ASCII alphanumeric (use the scanner already used for emoji detection in the editor, grep is_emoji before writing one); a value ending .svg/.png/.webp, or wrapped in [[ ]], is File. Limits: value 1 KiB. The index already keeps all properties per note (Bases task 9), so no index change: Decor is derived from Index::note_props(path) on demand and cached by the engine (D3).

D3 - Engine

crates/engine/src/decor/ (mod.rs, commands.rs, resolve.rs):

id params result writes
decor.list {paths?: [..], prefix?: ".."} {items:{path:{icon?,color?,banner?:{path,x,y}}}, generation} no
decor.set {path, icon?, color?, banner?, banner_y?} (null removes) {path} yes

decor.list with no paths returns only notes that HAVE a decoration (fast: iterate the index once, cached per index generation, 15 000 notes < 20 ms warm); folders resolve through the folder note. banner links are resolved with the same link resolution as wiki links, so [[cover.jpg]] finds assets/cover.jpg. decor.set reuses crate::vault::properties::set (one undoable edit when the note is open, note.property_set semantics, .obsidian/types.json types honoured). Add ids to ai/assistant_gate.rs (list READ; set WRITE; the icon catalogue is UI-side, so there is no decor.icons) and CORE_IDS. Settings [appearance.decor]: icons_enabled (true), banners_enabled (true), banner_height (px at scale 1, default 180, range 80..400, validated and rejected out of range), property_icon (icon), property_color (iconColor), property_banner (banner): the property names are configurable because vaults differ (cover is common).

D4 - UI

  • crates/ui-egui/src/design/note_icon.rs: paint(ui, &IconRef, rect, tint, tokens) for Lucide (static icons::paint), Emoji (egui text, monochrome emoji font: see risk), File (SVG/PNG through the image loader behind a bounded texture cache of 256 entries, decoded off the UI thread).
  • Lucide catalogue: the app embeds 91 icons today (design/icons.rs). Add a curated set of about 250 common Lucide icons under assets/icons/lucide/ listed in design/icon_catalogue.rs (a &[(&str, &[u8])]); names outside the catalogue render the generic file icon and the picker never offers them.
  • Hook points (each a small edit, listed per task): Explorer row panels/tree.rs:~672 (replaces the file-text slot when a decor icon exists; folders use the folder-note icon), tab icon widgets/tabs/paint.rs:35,~204, note title area views/note_view/ (icon above the title, size 40), quick switcher and search rows (task 7), Bases name column views/base_view/table/cell.rs.
  • Banner: views/note_view/banner.rs paints the image full width at the top of the document, cropped with object-fit: cover and the x/y focus, height from settings, scrolls away with the note, rounded bottom corners on the surface card. Image decode reuses views/base_view/layouts/cover.rs (read it first: it already loads and caches vault images for Cards). A broken link shows no banner and a hover tooltip on the properties row, nothing on the page.
  • Picker: a popover (Dropdown/Modal library widgets) with tabs Icons (search the catalogue, grid, colour swatches from theme tokens), Emoji (a text field plus the OS picker hint), File (pick an image from the vault tree). Entry points: Explorer context menu "Set icon...", note menu "Set banner...", hover on the note icon, palette "Icon: Set / Remove". Everything calls decor.set.

D5 - Performance and safety

Explorer paints thousands of rows: decorations come from ONE decor.list snapshot held in egui memory and refreshed on index generation change; no per-row engine call. Texture cache bounded; decode of one image capped at 8 MiB file / 4096 px (reject bigger, no downscale-on-read hack: show a placeholder). SVG icons from the vault are rendered with the existing craft-ui SVG path (no scripts run; reject files over 64 KiB). No network. Never write outside the property of the note.

Acceptance criteria

  1. A note with icon: LiRocket and iconColor: "#ff8800" shows a rocket tinted orange in the Explorer, its tab, and above its title; removing the property removes it on the next frame.
  2. icon: 🚀 shows the emoji; icon: "[[icons/star.svg]]" shows the vault SVG tinted by iconColor.
  3. banner: "[[cover.jpg]]" with banner_y: 0.2 shows the image cropped at 180 px height, focus near the top; a missing file shows no banner and no panic.
  4. banner: https://example.com/a.png makes ZERO network requests (stub server count) and shows the placeholder text.
  5. A folder with a folder note carrying icon shows that icon on the folder row; without a folder note it keeps the folder icon.
  6. "Set icon..." on a note writes icon: into the frontmatter as ONE undoable edit, body byte-identical.
  7. decor.list on a 15 000-note vault, 2 000 decorated: < 20 ms warm (ignored perf test); Explorer scroll does not call the engine per row (counter test).
  8. Properties keep working when a vault already uses Iconize/Banners keys; unknown spellings change nothing.
  9. Theme change retints Lucide icons that use a token colour.

Open questions

  • Q1: confirm the Iconize frontmatter key spelling with a real vault note (icon, iconColor) and add it to the fixture tests. Also confirm if Iconize stores folder icons in data.json, not in the notes: then an optional importer (reads .obsidian/plugins/obsidian-icon-folder/data.json) goes to Feature ideas.
  • Q2: emoji rendering: egui ships a monochrome emoji font. Acceptable for v1? (Color emoji = Twemoji pack, Feature ideas.)
  • Q3: bundle ~250 Lucide icons (about 250 KB) or the full set (1.5k, about 1.5 MB)?

Feature ideas (researched, ranked by value)

  1. Rules by folder / tag / property (Iconize custom rules, Iconic): a [appearance.decor.rules] list {match: folder|tag|property, value, icon, color}, evaluated once per index generation; makes a whole Projects/ tree pretty without editing 300 notes. Highest value after the properties themselves.
  2. Cover image for Bases Cards from banner: Cards view already supports a cover property; default it to the configured banner key, so Bases and notes share one image.
  3. Folder icons without a folder note through a .notescraft/icons.toml map (path -> icon), written by "Set icon" on a folder (a folder-note-less folder). Cheap, covers the common case of plain folders.
  4. Color emoji with a bundled Twemoji/Noto PNG sheet subset (about 3 000 glyphs, 1 MB): fixes Q2.
  5. Banner drag to reposition (Banners drag modifier): drag the image, release writes banner_y/banner_x (rounded to 2 decimals); lock with banner_lock: true.
  6. Banners in hover cards and embeds (![[note]] shows the banner small), and a card-size banner in the quick switcher preview.
  7. Import Iconize/Banners settings: read .obsidian/plugins/obsidian-icon-folder/data.json (folder and file icons stored outside notes) and offer to write them as properties; one-shot migration command.
  8. Gradient/solid banner style (no image): banner: "#336699" or a two-stop gradient string.
  9. Properties-view chips: an icon preview next to the icon row and a warning chip for invalid values (banner_y out of range, unknown Lucide name).
  10. Icon in graph nodes and calendar events from the same decor.list snapshot.