ds-galo/openspec/changes/archive/2026-10-10-material-icons-ui/design.md

Design

Context

Фронтенд — SvelteKit 2 + Svelte 5, adapter-static в режиме SPA (ssr=false), собирается в статику и вшивается в Go-бинарник через go:embed. Стили — Tailwind v4, семантические токены через CSS-переменные и data-theme на <html> (темы light/dark/neutral

• system). Внешние CDN-запросы нежелательны: приложение self-hosted и должно работать полностью автономно. Сейчас все «иконки» — эмодзи и юникод-глифы, рендерящиеся системным шрифтом (мотивация — в proposal.md).

Goals / Non-Goals

Goals:

• Единый набор векторных иконок, самодостаточный (без внешних запросов и без иконочных шрифтов).
• Иконки наследуют цвет текущей темы и не влияют на размеры/раскладку при переключении тем.
• Переиспользуемый компонентный API, спрайт для дедупликации повторяющихся иконок.
• Доступность: корректное поведение для декоративных и смысловых иконок и для тумблеров.

Non-Goals:

• Не менять доменную логику, API, БД и backend.
• Не вводить анимации/переходы иконок.
• Не добавлять внешние зависимости (иконочные пакеты, Vite-плагины).
• Не делать полный редизайн макета — только замена иконок и ведущие иконки контролов.

Decisions

1. Inline SVG через спрайт <symbol> + <use>

В +layout.svelte монтируется один скрытый <svg> со всеми <symbol id="i-...">; места использования рисуют <svg><use href="#i-..."/></svg>.

• Почему: нет внешних запросов, работает внутри статичного бандла, currentColor наследуется через <use>, а данные пути хранятся один раз в DOM (важно для сеток, где favorite/mode_comment повторяются на каждой плитке).
• Альтернативы (отклонены): иконочный шрифт через CDN — внешний запрос, FOUT, ломает автономность; внешний файл-спрайт <use href="/icons.svg#id"> — межфайловые <use> имеют ограничения в ряде браузеров; «иконка = компонент с полным inline-путём» — дублирование path-данных в DOM при массовом повторении.

2. Вендорим данные иконок в registry.ts, без зависимостей

Реестр — объект имя -> { path }, где path — сырая inner-разметка (<path d="..." .../>, иногда с fill-rule/clip-rule). Источник — Google Material Symbols (через Iconify, prefix material-symbols); базовые имена дают стиль filled, поэтому набор вендорится в filled-стиле, а для состояний-пар берутся отдельные ключи (favorite = filled, лайкнут; favorite-outline = контурный, не лайкнут). Примечание: контурного варианта для всех иконок в источнике нет, поэтому единый filled-набор согласованнее, чем смесь стилей.

• Почему: ноль зависимостей и supply-chain, малый бандл, полный контроль, согласуется с философией «один статичный бинарник».
• Альтернативы (отклонены): @mdi/js — готовые path-строки, но новая зависимость и другой визуальный набор; Iconify + unplugin-icons — мощный DX, но тяжёлый тулчейн ради ~25 иконок.
• Задел: при росте набора переход на @mdi/js не меняет компонентный API — только источник данных реестра.

3. Компонентный API

• Icon.svelte: пропсы name, необязательный label; размер и цвет задаются классами (size-4/5/6/16, text-*). По умолчанию aria-hidden="true" focusable="false"; при заданном label — role="img" + aria-label и aria-hidden снимается.
• IconSprite.svelte: рендерит все <symbol> из реестра один раз, монтируется в +layout.svelte.
• IconButton.svelte: иконочная кнопка с обязательным label (попадает в aria-label).
• Неизвестное имя: в dev — console.warn и пустой бокс (не падать); в prod — пусто.

4. Стиль и метрики

• fill="currentColor", шкала размеров: size-4 (в тексте/счётчиках), size-5 (кнопки/навигация), size-6 (панель лайтбокса), size-16 (плейсхолдеры).
• Пара состояний лайка: favorite-outline (не лайкнут) / favorite (залитая, лайкнут).

5. Маппинг иконок тем

light_mode, dark_mode, palette (нейтральная), brightness_auto (системная).

6. Доступность

• Декоративные иконки рядом с текстом/внутри кнопки с текстом — aria-hidden.
• Одиночные иконочные кнопки (тумблеры тем) — aria-label на <button> + aria-pressed.
• Счётчики лайков/комментариев: иконка декоративная, число несёт доступное имя (aria-label="12 лайков").

Risks / Trade-offs

• [Спрайт должен оставаться в DOM] → <use> ссылается на #id в том же документе; IconSprite живёт в +layout.svelte и не размонтируется.
• [{@html} в <symbol>] → данные статичны и вендорятся на этапе сборки, не приходят от пользователя; риск XSS отсутствует.
• [Рост DOM при больших сетках] → митигируется спрайтом (одна копия пути).
• [Визуальная регрессия/раскладка] → размеры задаём классами, иконки в квадратном viewBox 0 0 24 24; проверяем на трёх темах.
• [Лицензия/атрибуция] → Material Symbols под Apache 2.0; добавляем уведомление об источнике рядом с реестром.