The docs are binding, so where Phase 4 diverged from them the divergence has to be written down rather than left as an undocumented difference between spec and code. Three owner decisions recorded: six settings rows (markdownStyle was persisted but only editable as a transient #export control), all five donate handles in About, and a three-way segmented theme control rather than a cycling glyph. One genuine conflict resolved: docs/06 §3 called the Legal Gate "a full overlay" while docs/14 §2 -- echoed in docs/03 §4 and the decision log -- requires #settings and #about to stay reachable while it is up. Those cannot both be satisfied literally, so docs/06 now says the gate fills the content region and explains why. Also: docs/02's directory tree had been stale since Phase 2 (it predated lib/edit, lib/export and lib/import entirely); docs/03 §4 documented a five-field Settings shape that had six fields in code; docs/07 §3 now names where the Intl helpers live and, more usefully, the three sites that deliberately do NOT use them; docs/11 §5 gains the QA items Phase 4 created. The decision log gains fifteen rows, including the cross-tab sync limitation, recorded as a known limitation rather than left to be rediscovered in review. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
11 KiB
06 — UI Specification
Two surfaces: Popup (launcher) and Manager (full-tab SPA, 5 tabs). Svelte 5 runes, scoped styles, CSS custom properties for theming. No CSS framework.
1. Design tokens — src/styles/tokens.css
:root {
--bg: #ffffff; --bg-raised: #f6f7f9; --border: #e2e5ea;
--fg: #1b1e24; --fg-muted: #5b6472;
--accent: #6d4aff; --accent-fg: #ffffff; /* violet — "magic" identity */
--danger: #d8384a; --success: #1f9d55; --warn: #b7791f;
--radius: 10px; --radius-sm: 6px;
--font: system-ui, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
--fs-0: 12px; --fs-1: 13.5px; --fs-2: 15px; --fs-3: 18px; --fs-4: 24px;
--sp-1: 4px; --sp-2: 8px; --sp-3: 12px; --sp-4: 16px; --sp-5: 24px; --sp-6: 32px;
}
[data-theme="dark"] {
--bg: #16181d; --bg-raised: #1e2128; --border: #2b3039;
--fg: #e8eaee; --fg-muted: #9aa3b0;
--accent: #8b6dff; --danger: #ff6b7d; --success: #3ecf8e; --warn: #e2b93b;
}
Theme: data-theme on <html>; default follows prefers-color-scheme,
manual override persisted in Settings. Focus rings always visible
(:focus-visible outline in accent).
2. Popup (~320 × auto px)
┌──────────────────────────────┐
│ ◆ BookmarkMagic v1.0 │ header: icon + name + version
├──────────────────────────────┤
│ [⬆ Import bookmarks… ] │ → manager#import
│ [⬇ Export bookmarks… ] │ → manager#export
│ [🗂 Open manager ] │ → manager#edit
├──────────────────────────────┤
│ 1 284 bookmarks · 96 folders │ footer: live count (getTree stats) + ⚙ → #settings
└──────────────────────────────┘
Legal not yet accepted → buttons still open the Manager (the gate lives there). No heavy work in the popup, ever.
3. Manager layout
┌────────────────────────────────────────────────────────────┐
│ ◆ BookmarkMagic [Import][Export][Edit] 🌐 ◐ │ header: brand · TabBar · lang · theme
├────────────────────────────────────────────────────────────┤
│ <active tab content> │
├────────────────────────────────────────────────────────────┤
│ v1.0.0 · GPL-3.0 · GitHub ↗ Settings · About │ slim footer
└────────────────────────────────────────────────────────────┘
Max content width 960px, centered. Settings/About open as tabs too (footer
links = same routes, and both are disabled while an import is writing — see
03 §5). The version in the footer is read from the manifest at runtime
(browser/app-info.ts), never hardcoded.
The header's theme control is a three-way segmented control
(System · Light · Dark), not the single ◐ glyph the sketch above draws.
Rationale: one code path shared with the #settings row, and the current
choice is visible rather than inferred — a cycling button conflates "what am I"
with "what will I become", which fights §5.
<LegalGate> fills the content region, not the viewport. docs/14 §2
(echoed in 03 §4 and the 15 decision log) requires #settings and #about
to stay reachable while the gate is up, and a literal inset: 0 scrim would
bury the footer links that get you there. So: a full-bleed panel inside
<main>, with the header and footer still live and the three blocked tabs
disabled via TabBar's blocked prop. A side effect worth keeping — the
Import/Export/Edit tabs never mount before acceptance, so nothing touches
chrome.bookmarks until the user has agreed to the terms.
3.1 #import
- Idle:
<DropZone>(dashed border, accent on dragover) — "Drop a bookmark file or browse — .html, .json, .csv · max 25 MB". - Parsed: two-column: left
<TreePreview>(read-only tree, badgesnew/dup); right<StatsCard>(bookmarks / folders / depth / duplicates) +<WarningList>(collapsible) +<ImportOptions>:- Merge mode radio (New folder ▸ default · Merge · Replace all). Replace shows a danger callout: "Deletes ALL current bookmarks. A JSON safety backup will download first."
[x] Skip duplicates already in this browser (n found)— disabled and unchecked when Replace is selected, with the note "Existing bookmarks are being replaced". Skipping against a tree that is about to be deleted would silently drop everything (03 §1,05 §3).- Primary button
Import n bookmarks, where n isstats.bookmarkCount(bookmarks only). The progress bar usesstats.toCreate(folders included) — two different numbers by design (02 §4).
- Writing:
<ProgressBar>(determinate) + current path line +Cancel+ "Keep this tab open" notice. - Done:
<ResultCard>(created / skipped / warnings) +[Open Edit tab][Import another file]. Cancelled/error variants include copyable detail.
3.2 #export
Left: <FolderPickTree> with tri-state checkboxes under "Everything" master
toggle. Right: <FormatSelect> (radio cards HTML · JSON · CSV · Markdown,
one-line description each + per-format note, e.g. CSV: "empty folders not
preserved"), format options (CSV delimiter, MD style), then
Export n bookmarks ⬇. Success toast with filename.
3.3 #edit
Toolbar: <SearchInput> (⌘/Ctrl-F focuses) · New folder ·
Find duplicates · Expand all / Collapse all.
Body: <TreeView> (editable) — rows: disclosure ▸, favicon placeholder
(folder/link glyph — no remote favicons), title, muted domain, hover-actions
(rename ✎, delete 🗑, ⋯ menu: Move to…, Copy URL, Open).
Interactions: drag & drop with drop-line indicator (HTML5 DnD wrapped in a
Svelte action draggableNode); F2 rename; Del delete (confirm shows
descendant count for folders); Enter opens bookmark; full arrow-key tree
navigation (see §5). <DuplicatePanel> slides in from right: groups by URL,
per-item delete + "Keep first in each group" bulk (confirm dialog).
Empty state: friendly illustration + "Import some bookmarks →".
3.4 #settings
Single column of six <SettingRow>s: Language · Theme
(System/Light/Dark segmented) · Default export format · Default import mode ·
CSV delimiter · Markdown layout.
- The Language select offers four options, not three:
Settings.localeis'auto' | 'en' | 'vi' | 'ja'andDEFAULT_SETTINGS.locale === 'auto', so "Automatic (follow the browser)" has to be selectable or the default is unreachable. The three language labels are endonyms, identical in all three dictionaries — a Japanese user hunting for Vietnamese looks for "Tiếng Việt". - Markdown layout is the sixth row because
markdownStyleis a persisted field; without it the only place to change it was a transient#exportcontrol that never wrote back. - Four of the six rows reuse the Export/Import tabs' own i18n keys rather than inventing parallel wording, so the two surfaces cannot describe the same choice differently.
Auto-save + saved toast — the toast reports the resolved SaveOutcome, so a
failed write says so rather than claiming success. Footer: "Reset to defaults",
behind a <ConfirmDialog> (six preferences is enough to be worth a confirm).
3.5 #about
<AboutCard>: logo, name, version (from manifest at runtime), tagline;
links: GitHub repo ↗ · Report an issue ↗ · Changelog ↗;
Third-party dependencies: None 🎉 (statement, satisfies the requirement);
Donate: all five handles from 14 §5 / .github/FUNDING.yml — GitHub
Sponsors · Ko-fi · Buy Me a Coffee · Patreon · PayPal (platform names are brand
names and stay untranslated, 07 §4);
Legal block: EULA · License (GPL-3.0) · Disclaimer · Privacy Policy — each →
GitHub legal/ file; "Legal terms accepted on · version n" — where n
is the version the user accepted, from the stored record, not the current
LEGAL_VERSION constant. Reachable before acceptance (14 §2), so it also has
a not-yet-accepted state, and a dateless variant for a stored record whose
timestamp is missing or unparseable.
"Changelog" points at the repo's releases page until CHANGELOG.md exists
(Phase 5) — an empty releases page beats a 404 opened from a legal surface.
4. Component inventory (src/lib/components/)
TabBar · LanguageSwitcher · ThemeToggle · DropZone · TreePreview ·
TreeView · TreeNode (recursive, {#await}-free, lazy children) ·
FolderPickTree · StatsCard · WarningList · ImportOptions ·
FormatSelect · ProgressBar · ResultCard · SearchInput ·
DuplicatePanel · ConfirmDialog (native <dialog>) · Toast (queue,
auto-dismiss 4s, ARIA status) · SettingRow · AboutCard · LegalGate ·
Button · Callout.
Rule: components ≤ 300 lines; recursive tree logic isolated in TreeNode.
As built, some inventory names map differently — recorded so the list is not read as a list of missing files:
| Inventory name | Realized as |
|---|---|
AboutCard |
AboutTab.svelte, for symmetry with the other four tab shells |
TreeView |
inline in EditTab.svelte; the row is TreeRow.svelte and the flattening lives in edit/tree-keyboard.ts |
TreeNode |
TreePreviewNode.svelte (import preview) + FolderPickNode.svelte (export picker) |
ResultCard / SearchInput |
inline in ImportTab / EditTab |
| — | plus SettingsTab.svelte, the fifth tab shell |
Toast's queue and timers live in stores/toast.svelte.ts, not the component:
one <Toast> mounts at the App root while the route chain below it unmounts on
every navigation, so component-owned timers would leak by construction.
5. Accessibility & keyboard
- Tree uses
role="tree"/"treeitem",aria-expanded,aria-level; arrow keys per WAI-ARIA tree pattern (↑↓ move, → expand/first child, ← collapse/ parent, Home/End, type-ahead by first letter). - All actions reachable without a mouse; DnD has menu-based "Move to…" parity.
- Dialogs: native
<dialog>+ focus trap +Esc. - Progress announced via
aria-live="polite"every 10%. - Contrast ≥ 4.5:1 in both themes (tokens chosen accordingly).
6. Iconography
Inline SVG only (16/20px, currentColor), stored as tiny Svelte components in
components/icons/. No icon-font, no external icon package.