EditTab.svelte was 589 lines against the 500-line hard limit in docs/10 §1 -- the one place in the codebase that broke it. Now 459. Extracted, in each case because the thing was genuinely cohesive rather than to hit a number: - src/lib/edit/edit-node.ts -- toEditNode, flattenTree, isEditable, resolveNewFolderParent, countDescendants, extraCopyIds. All pure, all previously inline and therefore untestable. resolveNewFolderParent in particular encodes a fixed bug (a focused root resolving to the synthetic root "0", which every create rejects) that nothing was pinning. - src/lib/browser/open-url.ts -- the docs/09 T3 scheme allowlist, which is the only thing between a crafted `javascript:` bookmark in someone's import file and the browser acting on it. It had NO test. It does now, including the case-shouting dodge and data:/file:/chrome:. - EditToolbar.svelte and MoveToDialog.svelte -- presentational, with their styles copied verbatim. This is a move, not a redesign. The script block is still 279 lines against docs/10 §1's 150-line guidance. The remainder is the mutation layer (guardEdit and the six operations), which is coupled to reactive state and would need accessor indirection to move. Adding that indirection to the app's delete paths immediately before a release is a worse trade than the line count, so it stays and is recorded in CLAUDE.md rather than quietly ignored. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
12 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: #ce3547; --danger-fg: #ffffff;
--success: #198045; --warn: #99651a;
--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: #8f72ff; --accent-fg: #16181d;
--danger: #ff6b7d; --danger-fg: #16181d;
--success: #3ecf8e; --warn: #e2b93b;
}
⚠️ --accent-fg and --danger-fg must be redefined in the dark block, in the
opposite direction to the colour they sit on. Dark mode lightens --accent
and --danger for contrast against --bg, which is exactly what breaks white
ink on them — the original palette measured 3.67:1 and 2.74:1 there, against
the 4.5:1 §5 requires.
The light --danger/--success/--warn are darker than an eyeball would pick
because all three are rendered as text on --bg-raised (DuplicatePanel
counts, TreePreviewNode badges, WarningList's summary), where the original
values measured 4.27, 3.26 and 3.40.
None of these numbers is a matter of taste: tests/unit/styles/contrast.test.ts
parses tokens.css and fails the build if any text pair drops below 4.5:1, or
if the two dark blocks drift apart. Re-run it after changing a colour.
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 |
inline in ImportTab |
SearchInput |
inside EditToolbar.svelte |
| — | plus SettingsTab.svelte (the fifth tab shell), EditToolbar.svelte and MoveToDialog.svelte |
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.