Files
bookmarkmagic/docs/06_UI.md
T
poli0981andClaude Opus 5 c44c813aec docs: reconcile the spec with Phase 4
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>
2026-07-26 13:03:05 +07:00

11 KiB
Raw Blame History

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

  1. Idle: <DropZone> (dashed border, accent on dragover) — "Drop a bookmark file or browse — .html, .json, .csv · max 25 MB".
  2. Parsed: two-column: left <TreePreview> (read-only tree, badges new/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 is stats.bookmarkCount (bookmarks only). The progress bar uses stats.toCreate (folders included) — two different numbers by design (02 §4).
  3. Writing: <ProgressBar> (determinate) + current path line + Cancel + "Keep this tab open" notice.
  4. 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.locale is 'auto' | 'en' | 'vi' | 'ja' and DEFAULT_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 markdownStyle is a persisted field; without it the only place to change it was a transient #export control 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.