Files
Chronos/docs/ui/DESIGN.md
T
Alby96andClaude Opus 5.5 f33bcac32e
CI / Build and test (push) Successful in 13m44s
CI / Windows tests and installer (push) Skipped
CI / YAML check (push) Successful in 16s
Release / Build, test and publish (push) Successful in 26m34s
CI / PostgreSQL 16 integration (push) Failing after 17m36s
CI / PostgreSQL 17 integration (push) Failing after 15m36s
CI / Docker image (push) Successful in 1m12s
Release / Server image (push) Failing after 15s
feat(copies): matches between this PC and the server, Integrate and merge (owner review 6, v1.2.0) (#74)
The same time-lapse on a server and on this PC under different ids, or twice on this PC, is recognised,
compared and settled as the owner asked in owner review 6.

Matches are found after each sync refresh, through the server's new photo lookup, and after the jobs that
change photos. The default is to ask every time. Server › Matches offers:
- Keep apart, which is remembered;
- Link only and Unlink;
- the Compare dialog: photos, details line by line, projects and the plan.

Integrate completes both sides. Photos default to Union, projects are copied across, and a losing version
goes to the trash only after a hash check. Afterwards new photos move by themselves, and deletions wait for
the user.

A merge of two local sequences verifies every photo before the other sequence goes to its archive's trash.
Upload all local skips suspected matches and flags them.

Migration 0012 adds the found_copies and copy_probes tables. Jobs 25 (Integrate) and 26 (MergeSequences) are
new, and so are the server capabilities photo-lookup and upload-into.

Refs #73

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
2026-11-18 15:20:29 +01:00

24 KiB
Raw Blame History

Chronos — Design reference for Claude Code

Companion to docs/BRIEF.md §12 (UI spec). Suggested repo placement: docs/ui/DESIGN.md (this file), docs/ui/mockups/*.html (open in any browser; each file is one screen at its natural size, Editor.html two steps and the crop states one below the other; links between screens work), branding/ (icon sources). The mockups are the visual target; where a mockup and the brief disagree on behaviour, the brief wins; where they disagree on looks, the mockup wins.

1. Tokens → WPF resource dictionary (Chronos.App/Themes/Dark.xaml, Light.xaml)

Key (SolidColorBrush) Dark Light Use
Brush.Bg #1F1F23 #F3F3F3 window background
Brush.Chrome #1A1A1E #FFFFFF title bar, rail, status bar, web sidebar
Brush.Surface #26262C #FFFFFF panels, toolbars, dialogs
Brush.Card #2F3038 #FFFFFF cards, inputs, buttons, hovered rows
Brush.Stroke #3E404A #E5E5E5 1 px borders and dividers
Brush.Text #F2F3F5 #1A1A1A primary text
Brush.TextMuted #A9AEB9 #616161 secondary text, labels
Brush.TextFaint #7B818E #9E9E9E hints, column headers, disabled
Brush.Accent #4CC2FF #0067C0 primary button, active rail edge, links, Auto
Brush.OnAccent #0B1B24 #FFFFFF text on accent
Brush.AccentSelected rgba(76,194,255,.25) #E8F1FA selection glow / selected nav
Brush.Sun #F5A524 #E08A1E manual slider track, uploader accent, icon sun
Brush.Success #35C48F #0F7B4F analysed, in sync, done
Brush.Warning #E8B339 #9A6700 warnings, destructive outline
Brush.Error #F0625D #C42B1C errors, failed
Brush.Region #5AD1C8 #1A9E95 sky/landscape region masks only

Dark is the client default; Light follows the OS setting; the web admin follows the browser's colour scheme, with a Light/Dark toggle in its header. Never use colour alone to carry state: pair it with a glyph (● ○ ◐ ▲ ✕ ▶) or a word.

2. Type (Segoe UI Variable, fallback Segoe UI; FontSize keys)

Text.PageTitle 18/600 · Text.Title 16/600 · Text.Section 14/600 · Text.Body 13/400 · Text.Secondary 12/400 muted · Text.Chip 11/400. Line heights 24/22/20/18/16/14. Numbers in tables use tabular figures (Typography.NumeralAlignment="Tabular"). Layout must survive +40 % text width (de, fi): no fixed-width labels, MinWidth only.

3. Spacing, radii, sizes

Spacing scale 4 · 8 · 12 · 16 · 20 (Thickness keys Space.1…Space.5). Radii: 6 controls · 8 cards/panels · 12 pills · 12 modal dialogs. Controls 32 px tall, 44 px minimum width, 12 px horizontal padding; compact row buttons 26–28 px. Rail 200 px (collapses to 48 px icons with ≡ or Ctrl+B, the tooltips then naming each section; the choice is kept; owner review 1); title bar 34; job bar 40; toolbar 56; status bar 30; table rows 36–40 (52 in the web admin); side panels 320 px; settings section list 200 px. Label column left of controls: 116 px in panels, 180 px in Settings.

4. Controls and states (see Components.html)

  • Button: Card fill, Stroke border. Hover +6 % lightness, pressed −6 %, focus = 2 px Accent ring outside. Primary (Accent fill, OnAccent text, 600) — one per screen. Destructive = Warning outline, transparent fill, never a primary. Subtle = no border until hover. Toggled = Accent text + Accent border. Disabled = 40 % opacity and the tooltip says why. Icon-only buttons carry AutomationProperties.Name and a tooltip.
  • Inputs: Card fill, Stroke border, Accent border on focus, Error border when invalid with the message in the tooltip (never a line of text under the field). Enter commits, Esc reverts.
  • Slider — Auto/manual (brief §10.4): Auto state = Accent track, dimmed thumb, an Auto · 41 pill at the right whose tooltip gives the advisor's reason; touching it turns the track Sun (manual), shows the value, and a ⟲ reset button returns to Auto. Not applicable = greyed value "n/a" with the reason in its tooltip.
  • Setting rows (side panels, label on the left, value or control on the right; owner review 1, R5/R6): number = label, value in TextMuted with tabular figures, the slider on the line below (Straighten −15…15° by 0.1, −1.2°; Crop size 85 %, Crop X/Y +0.40 · Centred); switch = label and a 36 × 20 switch at the right (off = TextMuted outline and knob, on = Accent fill, OnAccent knob; role="switch"), one toggle is one undo step; icon actions = label, the value (Rotation 90°), then 28 px icon-only buttons (a quarter turn per press, as the user sees the picture: the direction swaps while exactly one of Mirror and Flip is on); info = label and a read-only value (Output size). A row that does not apply shows "n/a" in TextFaint with the reason in its tooltip (Crop X when the crop fills the width, Strength when the filter is None). A group inside a panel is a 1 px Stroke divider, then its name in Text.Body 600 with the group's tooltip (Look on Exposure).
  • Collapsible group (Export's Output panel, the preset table's groups; owner review 1, R3): a 28 px header button, transparent (Card on hover, focus ring), a 14 px TextMuted chevron (down when open, toward the reading direction when closed), the name in Text.Body 600 and, only while collapsed, a muted one-line summary of its values after it, ellipsed ("Variable · 40 Mb/s · 1 s · B 2 · High"). The header's tooltip names the group and says what it holds. Open or closed is the user's choice, kept by the app (never in the project); Export opens Output and File, closes Encoding and Playback. Groups scroll; a fixed footer under them (1 px Stroke top border, 10 px above) holds the result line in Text.Secondary muted (two lines at most), the primary button (36 px), then a row of secondary buttons and a row of links.
  • Preset table (Export's measuring area; owner review 1, R3): 28 px rows, transparent, Card on hover; the preset in use has the AccentSubtle wash and a 3 px Accent bar at the start edge. Columns: batch check box 28, Name (fills, with the Recommended chip), Size 92, Codec 104, fps 44, Est. size 76, Est. time 96, numbers tabular and right-aligned; each group is a collapsible group header with its count. A click on a row selects it; the check box only ticks.
  • Structured menu entries (the Render ▾ menu; owner review 1, R3): a menu entry has two lines, the label and a muted Text.Secondary details line with tabular figures ("3840×2160 · HEVC Main10 · 24 fps"), each at most 320 px with an ellipsis; a header is a small muted semibold title; separators split the presets from the commands; a submenu has the ▸ arrow (Other presets ›, Save frame ›); the current preset carries the check mark. Every entry has a tooltip, a disabled one the reason.
  • Videos (owner review 1, R9): the section's cards are Library cards (DESIGN §4 Cards: the sequence's cover or the still itself, the duration as the badge) with the preset, size, codec and bytes as subtitle and state chips (Here, On server, Copied, Missing, Not sent) as status glyphs with words; the list is a table (Title, Preset, Format, Length, Size, Date, State; Preset, Format and Date drop while the player is open). The player is a 420 px pane at the end side: Preview background, the picture or video fitted (a left-to-right island), its title and facts, Show in folder and ✕; Cannot play here is an EmptyState inside it.
  • Matches (owner review 6, #73; brief §12.7): no new colours or controls, only the kit above.
    • Matches list: a Matches · n chip after Conflicts in the Server section (warning colours while a match needs attention); while selected it replaces the sync table with the same row style: Sequence, This side, Other side (counts first, "{archive} · {n} photos"), State as glyph and word (match found ▲ Warning, kept apart ○ faint, linked ● Accent, integrating · x of y and merging ● Accent with the job's share, integrated ● green, deleted there · n, deleted on server ▲, kept here ○), then the state's 26 px row actions, three at most (a linked pair with photos deleted there: Compare…, Unlink, Review). Columns: Sequence *, the two sides 1.4* (180 px at least), State 160 px, Actions 1.4* (280 px at least); an archive or server name longer than 24 characters is cut in its middle ("ChronosArch…Studio NAS"), the whole text in the tooltip. Attention first. Toolbar Find matches; empty state "No matches found." with Find matches.
    • Compare dialog: an in-window dialog over the section's scrim, 920 px wide, at most 600 px high, its parts scrolling inside. Header: each side's place, photos, size and time span; a SegmentedControl Photos · Details · Projects · Plan. Photos: the policy ComboBox, a class table of 28 px rows (glyph and class, count here, count there, size, a tooltip per class that follows the policy) and the selected class's virtualised photo list with column headings (Bring check box, the Keep both / This PC's / Server's / Leave ComboBox, Drop…, To trash…); the last column's heading reads Version while the rows offer a choice, the version Main uses reads In Main in Text.Secondary, and a choice not made is read Not chosen by a screen reader. The policy ComboBox (here and in Settings › Server) is 240 px and the version ComboBox 185 px, sized by a test over every shipped language; a longer label trims with an ellipsis. The photo and Details lists always show their vertical scroll bar and their headings keep its width, so the headings stay over their columns. Details: one row per setting, both values ellipsed (full in the tooltip, wrapping at 480 px) and a This PC | Server SegmentedControl, nothing preselected, each segment's tooltip naming the value it takes ("Take the value of Studio NAS: 33"); All this PC / All server links above. Projects: Copy across | Leave them and two lists with the target name ("→ Vertical (STUDIO-PC)"), rows trimmed with the whole row in the tooltip, the headings over their lists, both lists scrolling together when they do not fit. Plan: two columns of lines in Text, last copies first with the Warning glyph, Link only as a secondary row button, each block as a Status.DialogError line with at most one action. Two buttons: Cancel (safe, Esc) and Integrate (primary).
    • Merge dialog: the same dialog titled Merge sequences, Kept and Other in place of this PC and the server (from the first plan, made on opening), the kept-sequence radio rows first in the Plan, the projects choice fixed to Copy across (disabled, with its tooltip), primary Merge. Its one-sided classes are named by role (Only in kept, Deleted in other); under Choose each a differing photo offers Keep both / Kept / Other (no Leave).
    • Confirmations: Replace photos? (the losing versions under the side that loses them, last copies first) and Merge sequences? (the photo count typed without separators; the prompt names the number) as destructive ConfirmDialogs; every line of a trash or replace confirmation carries its prefix (Only copy:, Replaced:, Held elsewhere:). Unlink and Keep apart use a toast with Undo instead.
    • Library card status: Also elsewhere or Deleted there as a Warning status glyph with its word, second on the card, in the list too; Compare… in the context menu and the row actions. A server card in a match offers Compare… alone.
    • Two versions… (a local card's and row's context menu; a merge job's Open): an in-window dialog 640 px wide, at most 520 px high, titled with the sequence; a list of 48 px rows, one per version (file name in SemiBold, its detail in Text.Secondary with tabular figures, In Main where Main uses it, Drop… as the row button); an empty list reads a muted line; Close (default and Esc) with the dialog's Status.DialogError line beside it.
    • Edit picker twin: a muted Twin chip right after the project name of a Workspace row; its tooltip names the other home and project. Only a project whose sibling is at the other home carries it.
  • Crop overlay (preview, Camera step; owner review 1, R5): the box is drawn over the whole view frame (oriented, straightened) and is always locked to the output aspect. States (tiles under the Camera screen in Editor.html):
    • Shown: Crop mask on, any step: Scrim (#99000000 dark, #66000000 light) outside, 1 px TextMuted outline. In "how it will look" mode the outside is hidden instead, as today; handles and outline still draw.
    • Editable: Camera step, mask on (its default there) and the project editable: 1.5 px Accent outline and 8 handles (4 corners, 4 edge midpoints), 8 × 8 screen px whatever the zoom, Card fill, 1.5 px Accent stroke. The preview tooltip becomes "Drag to move · drag a handle to resize…" (Tooltips.Editor.Preview.CropEdit).
    • Dragging: rule-of-thirds lines inside the box (1 px Text at 50 %); only the overlay moves until mouse up, which commits one undo step; Esc cancels. Corners anchor the opposite corner, edges the opposite edge (centred on the other axis), Alt resizes about the centre; the minimum is 10 % of the largest box.
    • Straightening: while the Straighten slider is dragged or focused, a fine 8 × 8 grid over the whole view (1 px Text at 30 %).
    • Locked (read-only, newer format, busy): drawn as Shown, no handles, drag pans. Hit-test order: a handle within 6 screen px, the wipe divider, inside the box (move, SizeAll cursor), outside (pan); inside a box that spans the view both ways a press pans while the view is zoomed, and the middle button always pans. Cursors SizeNWSE/SizeNESW on corners, SizeWE/SizeNS on edges. Keyboard: a press on the box or Enter selects it (2 px Accent ring outside the handles), Esc gives the arrows back to the frames; while selected, arrows move 1 %, Shift+arrows 10 %, + and − resize 2 % about the centre. Double-click keeps Fit / 1:1.
  • Status glyphs: ● green Analysed · ○ faint Not analysed · ● Proxies · ▶ n rendered · ● accent Synced/Remote · ◐ amber Analysing · ▲ n warnings · ✕ n errors.
  • Chips: 24 px pills, Card fill, Stroke border; selected/recommended = Accent border and text.
  • Progress: 6 px bar, Accent fill, text to the right; indeterminate = sliding highlight.
  • Tooltip: light on dark (#F2F3F5 on dark, #1A1A1A text), 12 px, one line: action + cost + shortcut ("Read every frame again · about 6 min · Ctrl+Shift+A"); 400 ms delay; ≤ 200 chars. Every interactive element has one. There is no other explanatory text in the UI.
  • Dialog: Surface fill, Stroke border, radius 12, 24 px shadow, two buttons maximum, safe action left and default, destructive on the right with typed confirmation for formatting.
  • Toast: bottom-right, 420 px, Card fill with a 3 px Accent left edge, one action button, 8 s, hover pauses. Used for card insertion, render done, server messages.
  • Job bar: 40 px strip under the title bar in every client screen: current job, progress, time left, pause; hidden when idle only in the editor (it shows "Ready" elsewhere).
  • Rail item: 36 px; active = Card fill + 3 px Accent left edge; badge = Accent pill with the count of things needing attention. Library, Import, Edit, Videos (owner review 1, R9), Archive, Jobs and Server at the top (Ctrl+1…7), Settings alone at the bottom: no ⓘ About entry, About is the last Settings section (owner review 2, R5).
  • Step bar (Edit, owner review 1): one row of equal 36 px cells under the editor's header, one per step, 4 px padding: a 22 px badge, the name (about 82 px at the 1200 px minimum, an ellipsis beyond) and a 1 px Stroke connector to the next step. Badge = the number in a Stroke ring (to do), ✓ Success (done), ▲ Warning (attention), ◐ Warning (running), ○ faint (waiting): each status has its own glyph, so colour never carries it alone. Current step = 2 px Accent underline and a semibold name; visited steps' names in Text, the others muted. The tooltip names the step, then what it is for, its state and its shortcut (Alt+n). Previous · n / m · Next sit under the settings column: both buttons whole, the counter giving way.
  • Cards (Library): 236 px wide, thumbnail 16:9, count badge top-right, checkbox top-left on hover/selection, selected = Accent border + AccentSelected glow; hover scrubs the thumbnail.
  • Tables: header 11 px faint, sortable; rows Card fill on hover; numbers right-aligned, tabular; virtualised beyond 200 rows; row actions are 26 px buttons revealed on the row.

5. Icons

16 px, 1.5 px strokes, round caps and joins, currentColor, drawn as PathGeometry / DrawingImage resources in Chronos.App/Icons/Icons.xaml (source SVGs in branding/ui-icons/ if generated by a tool). No icon fonts, no emoji in shipped UI (the mockups use a few glyphs only as placeholders: replace ⟳ ▾ ✕ ■ ❚❚ ≡ with drawn icons). Directional icons mirror in RTL: IconData.IsDirectional marks the glyphs that point along the reading direction (back/forward, chevrons left/right, external link, start-aligned lines); ui:Bidi.IsDirectional overrides it for a subtree (a ▶ used as "next", a chevron on a left-to-right time axis). Every other glyph (clocks, media controls, the ▶ rendered status) and the brand mark keep their drawn orientation. Photos, previews, charts, numbers, paths and templates are left-to-right islands (FlowDirection="LeftToRight" on the smallest element holding them). Category charts without a time axis (horizontal bars, stacked bars) still lay out from the reading side inside their island: labels on the reading side, bars growing away from it; time axes and month grids never flip. branding/ui-icons/icons.py is the one source: it writes Icons.xaml and the web admin's icons.js. Settings is a toothed gear (8 teeth, outer radius 6.5, valleys on 4.6, centre hole 1.7: gear() in icons.py); a circle with rays is the Sun icon only. The Camera step's orientation icons (owner review 1, R6): RotateLeft / RotateRight = a rounded picture under a quarter-circle arrow (turn_arrow()), Mirror / Flip = an outline triangle and a filled one across a dashed axis, Straighten = a tilted line over a level one with its angle arc. They describe the picture, not the reading direction, so they never mirror in RTL. Owner review 1, phase 5: Videos = a clip with a play triangle in front of the stack of the others, CopyToFolder = the folder with a down arrow, StillFrame = one frame held out of the filmstrip, Fade = a ramp from black inside a frame, Boomerang = a line that goes and comes back; the admin panel's icons.js also gains the desktop's Play triangle.

6. App icon (branding/)

chronos.svg is the master: 256 plate radius 56 #1A1A1E, ring r 92, 12 ticks of 12° with 18° gaps, stroke 20 round caps, opacity 0.14 → 1.0 clockwise from 12 o'clock, sun disc at (152,104) r 30 #F5A524. Variants: chronos-server.svg (rack badge), chronos-uploader.svg (up-arrow badge), chronos-mono.svg (white, no plate, for the tray). PNG renders at 16/32/48/64/128/256 are reference output; Chronos.Tools make-icon must regenerate ICO/PNG from the SVG geometry (no raster assets checked in as sources). Badges only at ≥ 48 px.

7. Screen-by-screen notes (mockup → brief section)

Mockup Brief Notes
Main.html §12.2 Library grid/list, year·camera·status filters, selection panel; the match statuses and Two versions… (owner review 6) have no mockup: built from §4 Matches; the statuses are checked against the library-copies-* captures, the Two versions… dialog has no capture scene yet
Editor.html §12.3 Edit three parts, one below the other. Exposure step: step bar, title ▾ (Change sequence), wipe compare (the corrected side carries the look), curves, advisor Auto pills, the Look group (Filter, Strength) at the end of the panel, Previous · n / m · Next. Camera step (#camera): the whole view frame with a 9:16 crop being edited (handles), the zoom-keyframe curve under the filmstrip, rows Aspect · Rotation (Rotate left/right and the value) · Mirror · Flip · Straighten · Crop size · Crop X · Crop Y, the keyframes line, then Reset framing on its own line (three buttons do not fit the 292 px panel) above Optimise section · Reset (Reset framing disabled, with ResetFramingNone, when nothing is set). Crop overlay states: Shown, Editable, Dragging, Straightening, Locked
Export.html §12.3 / §11.4 the Export step (owner review 1, R3, phase 5): step bar with Export current, the header's fixed-width Render ▾, the grouped preset table (28 px rows, Recommended chip, batch ticks, a folded group), the Output panel's four collapsible groups (Output open, Encoding and Playback folded with their summaries, File open) and its fixed footer (result line, Render now, Add to queue · Batch (2), Videos (3) · Reveal), Previous · 8 / 8 · Next sequence; under it the Render menu open with Other presets › expanded. Resolution offers the standard boxes and Custom shows the preset's box; the Output size row under it shows what is rendered: the chosen proportions fitted in the box (4K at 9:16 = 2160 × 3840; "source" keeps the preset), the preset name unchanged; when the encoder caps it, the value reads "1296 × 2304 (capped)" with Tooltips.Editor.Export.OutputCapped. The preview mask is the output's footprint in the view frame
Videos.html §12.10 the Videos section (owner review 1, R9): toolbar (search, Kind, Codec, Year, Source, Order, cards/list, Refresh), the sequence chip, the selection bar (Play, Show in folder, Copy to folder, Copy on server, Open in Edit, Delete…), cards with state chips, the player pane open on the right; under it the list view and the Delete… confirmation
AdminVideos.html §14.8 the admin panel's Videos page (owner review 1, R9): sidebar with Videos after Library, filters, cards with a selection, the selection bar (Download, Copy to folder, Delete…), and the Play dialog with <video controls>
Import.html §12.4 / §13 card profile, sessions, plan, verification, after-import actions
Archive.html §12.5 tree, mass operations, stats, verify/rebuild, maintenance
Jobs.html §12.6 filters, queue order, expandable log, retry/open/folder; a Queue · Scheduled segmented control first in the toolbar (owner review 2, R10): Scheduled is a table (on switch, name, action, when, next run, last result, Run now · Edit · Reset or Delete), the selected schedule's last runs under it (Show in queue), New schedule at the toolbar's end and the editor as an in-window dialog; jobs a schedule queued carry an Accent Scheduled pill after their target
Server.html §12.7 / §14 connection with TOFU fingerprint, account and quota, render node, sync table, conflicts; the Matches list and the Compare/merge dialog (owner review 6) have no mockup: built from §4 Matches and checked against the server-copies-* captures
Settings.html §12.8 section list (About last, §12.9), Rendering section, encoder table, self-test
Welcome.html §12.1 first run: local archive / adopt folder / connect; Continue; card toast
Admin.html §14.7 dashboard; sidebar: pages from the top, Settings docked at its foot above the account, no About (the last group of Settings)
AdminUsers.html §14.7 users table, roles, quotas, temporary password, render-node right
Uploader.html §15 single window, watch folder, queue, tray
Components.html §12.1 the control kit above, with hex values and state rules
Icon.html §17 construction, sizes, variants, wordmark

Missing on purpose (build from the brief and this kit): the Settings › About page, Login dialog, Jobs › Scheduled and its editor, the Edit picker and the other steps (Analysis, Frames, Motion, Time, Stack), Import "Show plan", Archive rebuild dialog, the admin Archive/Jobs/Settings/Logs pages. Reuse the shell and the kit; do not invent new colours.