Skip to content

DESIGN.md

Latest commit

 

History

History
305 lines (241 loc) · 18.2 KB

DESIGN.md

File metadata and controls

305 lines (241 loc) · 18.2 KB
Raw
name FollowCursor
description An iOS-inspired Windows studio for recording and shaping cinematic product walkthroughs.
colors
brand brand-hover brand-active brand-translucent canvas-deep layer-1 layer-2 layer-3 layer-4 layer-5 foreground-primary foreground-secondary foreground-tertiary foreground-disabled stroke-default stroke-secondary light-canvas light-layer-2 light-layer-3 light-foreground-primary light-foreground-secondary light-stroke-default record-red success-green marker-amber info-blue timeline-teal
#8b5cf6
#9d74f7
#7c3aed
rgba(139, 92, 246, 0.18)
#000000
#141414
#1f1f1f
#292929
#333333
#3d3d3d
#ffffff
#d6d6d6
#adadad
#5c5c5c
#666666
#525252
#ffffff
#fafafa
#f5f5f5
#242424
#424242
#d1d1d1
#ef4444
#10b981
#f59e0b
#3b82f6
#14b8a6
typography
display headline title body label timecode
fontFamily fontSize fontWeight lineHeight letterSpacing
Segoe UI Variable, Segoe UI, sans-serif
68px
700
1.35
0
fontFamily fontSize fontWeight lineHeight letterSpacing
Segoe UI Variable, Segoe UI, sans-serif
24px
600
1.33
0
fontFamily fontSize fontWeight lineHeight letterSpacing
Segoe UI Variable, Segoe UI, sans-serif
20px
600
1.4
0
fontFamily fontSize fontWeight lineHeight letterSpacing
Segoe UI Variable, Segoe UI, sans-serif
14px
400
1.43
0
fontFamily fontSize fontWeight lineHeight letterSpacing
Segoe UI Variable, Segoe UI, sans-serif
12px
600
1.33
1px
fontFamily fontSize fontWeight lineHeight letterSpacing
Consolas, Courier New, monospace
14px
400
1.43
0
rounded
none small medium large xlarge circular
0px
6px
8px
12px
16px
9999px
spacing
xxs xs compact sm inset md lg section xl xxl major rail
2px
4px
6px
8px
10px
12px
16px
20px
24px
32px
48px
64px
components
button-secondary button-primary button-primary-hover button-primary-active button-record input-default source-card
backgroundColor textColor typography rounded padding height
{colors.layer-3}
{colors.foreground-primary}
{typography.body}
{rounded.small}
6px 12px
32px
backgroundColor textColor typography rounded padding height
{colors.brand}
{colors.foreground-primary}
{typography.body}
{rounded.small}
6px 12px
32px
backgroundColor textColor
{colors.brand-hover}
{colors.foreground-primary}
backgroundColor textColor
{colors.brand-active}
{colors.foreground-primary}
backgroundColor textColor rounded height width
{colors.record-red}
{colors.foreground-primary}
{rounded.medium}
48px
200px
backgroundColor textColor typography rounded padding height
{colors.layer-2}
{colors.foreground-primary}
{typography.body}
{rounded.small}
6px 8px
32px
backgroundColor textColor rounded padding
{colors.layer-4}
{colors.foreground-primary}
{rounded.medium}
8px

Design System: FollowCursor

Overview

Creative North Star: "The Precision Glass Studio"

FollowCursor is a focused, precise Windows editing environment with the calm material hierarchy and control clarity associated with iOS. It remains a native PySide6 desktop application: familiar under mouse and keyboard, dense enough for repeated editing work, and composed enough that the recording remains the visual subject.

The interface uses quiet translucent chrome, generous optical spacing, and confident actions. Neutral layers organize the workflow while Studio Violet marks primary actions, active navigation, selection, and focus. Record Red is reserved for capture and destructive urgency. Timeline Teal and Marker Amber give media and editing events stable identities without turning the whole shell colorful.

The adaptation borrows visual principles, not platform behavior. It does not introduce mobile navigation, touch-only gestures, safe-area layout, ReplayKit, or iPhone and iPad runtime assumptions. New work should extend the centralized tokens and existing component patterns before introducing a local visual treatment.

Key Characteristics:

  • Windows-native interaction patterns with iOS-inspired material restraint.
  • A fixed editing frame around a fluid, aspect-preserving preview.
  • Translucent tonal layers with restrained ambient lift and crisp separators.
  • Semantic accent color in the timeline and high-confidence actions.
  • Compact desktop typography with clear, calm hierarchy and optical spacing.
  • Equal design intent in dark and light themes.

Colors

The palette combines a neutral Fluent ramp with a violet brand voice and task-specific signal colors.

Primary

  • Studio Violet (#8b5cf6): Primary actions, selected navigation, focus, zoom activity, and direct-manipulation handles. Hover uses #9d74f7; pressed uses #7c3aed.

Secondary

  • Record Red (#ef4444): Recording, stop, destructive actions, and danger states. Keep it specific to urgency.
  • Timeline Teal (#14b8a6): Voice and clip media on the timeline. It distinguishes media content from camera motion.
  • Marker Amber (#f59e0b): Chapters, trim handles, pan points, progress cues, and other temporal markers.
  • Status Green (#10b981): Successful completion and healthy state.
  • Information Blue (#3b82f6): Informational status where violet would imply selection or action.

Neutral

  • Deep Canvas (#000000) and Layer 1 (#141414): The deepest application and preview surroundings.
  • Layers 2-5 (#1f1f1f, #292929, #333333, #3d3d3d): Panels, content, cards, menus, and transient surfaces in increasing visual prominence.
  • Primary, Secondary, and Tertiary Foreground (#ffffff, #d6d6d6, #adadad): The text and icon hierarchy on dark surfaces.
  • Default and Secondary Stroke (#666666, #525252): Control boundaries and dividers.
  • Light Canvas and Layers (#ffffff, #fafafa, #f5f5f5): Light-theme equivalents, paired with #242424 primary text and #424242 secondary text.

The Semantic Timeline Color Rule. Studio Violet means camera and cursor activity, Timeline Teal means media, and Marker Amber means temporal structure or attention. Preserve those meanings in custom-painted editing surfaces.

The Accent Economy Rule. Use Studio Violet to identify action, selection, or focus. Do not wash large passive surfaces in brand color.

Typography

Display Font: Segoe UI Variable, with Segoe UI and sans-serif fallbacks
Body Font: Segoe UI Variable, with Segoe UI and sans-serif fallbacks
Label/Mono Font: Segoe UI Variable for labels; Consolas with Courier New fallback for timecode

Character: The type system uses Windows-native Segoe UI Variable with the calm hierarchy of an iOS editing surface. Weight, foreground contrast, and breathing room carry hierarchy more often than large jumps in size. Do not depend on Apple-only fonts that are unavailable on customer systems.

Hierarchy

  • Display (700, 68px, 92px): Available in the token ramp for rare display moments; it is not standard editor chrome.
  • Headline (600, 24px, 32px): Dialog or major workflow headings.
  • Title (600, 20px, 28px): Prominent section and overlay titles.
  • Body (400, 14px, 20px): Default controls, labels, menus, and explanatory text. Semibold weight provides local emphasis.
  • Label (600, 12px, 16px, 1px letter spacing): Uppercase inspector headers and compact category labels.
  • Caption (400, 10-12px, 14-16px): Dense metadata, timeline labels, and secondary status.
  • Timecode (400, 14px, 20px): Stable-width playback and duration readouts.

The Operational Scale Rule. Keep persistent editor chrome within the caption-to-subtitle range. Large display type must not compete with the preview or timeline.

Layout

The application is a frameless Windows desktop shell with a fixed editing frame. The minimum window is 900 x 600; the initial window is 1200 x 800. A 46px runtime title bar and 28px status bar bound the vertical workspace. The main content uses a fixed 64px navigation rail, a fluid center column, and a fixed 320px inspector. The inspector is hidden in Record mode and returns with the timeline in Edit mode. Its three equal-width task tabs are Motion, Style, and Audio, with Motion selected by default. Each task owns an independent scrolling region while shared utilities remain fixed below it. Do not replace this structure with a mobile tab bar, stacked navigation, or sheet-led workflow.

The center column places the aspect-preserving preview first, a 56px playback bar second, and the timeline third. The preview has a 480 x 270 minimum. The custom timeline track is 160px high and uses stable row geometry so content and hover states do not shift the editor.

Use the 2px-based spacing scale with an 8-16px working rhythm. Controls commonly use 8-12px internal spacing; sections use 16-24px separation. Inspector bodies use 16px horizontal insets, 8px internal gaps, and 16px section gaps. Fixed action areas remain outside scrolling content.

The source picker is a focused selection surface with a 760 x 500 minimum and generous 32px horizontal margins. Source cards have a 200 x 155 minimum and use a thumbnail-first composition.

Custom-painted widgets must respond to theme changes through theme-aware token getters. Do not copy the remaining dark-only local colors into new work. Current code also contains 48px QSS versus 46px runtime title-bar values and 280px QSS versus 320px runtime inspector values; runtime geometry is the shipped evidence, while these mismatches remain implementation debt.

Elevation & Depth

Depth is layered, quiet, and material-led. Tonal surfaces and translucent overlays establish the base hierarchy; shadows clarify menus, dialogs, and transient overlays. On supported Windows 11 builds, native Mica supplies the glass-like host material. Older Windows uses opaque QSS layers with the same contrast hierarchy rather than simulated blur.

Shadow Vocabulary

  • Flat (0px blur, 0px Y offset): Base canvas and edge-aligned structure.
  • Control (2px blur, 1px Y offset, rgba(0, 0, 0, 0.28)): Minimal lift for controls at rest.
  • Card (4px blur, 2px Y offset, rgba(0, 0, 0, 0.28)): Source cards and the editor panel.
  • Command (8px blur, 4px Y offset, rgba(0, 0, 0, 0.28)): Menus, source picker, tooltips, and settings dialogs.
  • Dialog (16px blur, 8px Y offset, rgba(0, 0, 0, 0.28)): Modal and callout surfaces.

Qt's standard drop-shadow effect renders one key shadow. The ambient rgba(0, 0, 0, 0.24) companion tokens document Fluent intent but are not rendered by that helper. Focus glow and elevation also compete for Qt's single graphics-effect slot; choose the effect that communicates the component's most important state.

The Tonal Before Shadow Rule. Establish hierarchy with the neutral layer ramp first. Add elevation only where a surface must visibly detach from its parent.

Shapes

FollowCursor uses compact, softened geometry. Small controls and internal items use 6px corners. Cards and larger buttons use 8px. Dialogs and popovers use 12px; exceptional overlay containers can use 16px. Circles are reserved for status dots, slider handles, and other intrinsically round controls. Rounded geometry must not turn every command into a pill.

Borders are functional rather than decorative: 1px neutral strokes define resting controls, accessible strokes strengthen hover, and 2px Studio Violet identifies selection or focus. Tabs and edge-aligned navigation use square outer geometry with local indicators rather than floating pills.

Components

Controls are quiet chrome with confident actions. Every interactive component must communicate rest, hover, pressed or active, focus, and disabled states where applicable.

Buttons

  • Shape: 6px radius and 32px minimum height for standard actions; 8px for larger workflow actions.
  • Primary: Studio Violet with white semibold text. Export is 32px high; Save is 40px high.
  • Secondary: Layer 3 fill, primary foreground, 1px default stroke, and 6px 12px padding.
  • Record / Stop: Record is a 48px filled red action with a 200px minimum width. Stop is a 40px outlined danger action with a 140px minimum width.
  • Hover / Focus: Hover lightens or strengthens the role color. Pressed darkens it. Focus uses a 2px Studio Violet boundary or the shared 6px glow helper when Qt permits it.

Cards / Containers

  • Corner Style: 8px for source and preview cards; 12-16px for large transient surfaces.
  • Background: Layer 4 at rest and Layer 5 on hover.
  • Shadow Strategy: Card elevation uses 4px blur and 2px Y offset.
  • Border: 1px default stroke at rest; selected source cards use a 2px Studio Violet stroke.
  • Internal Padding: Usually 8px; source cards use 6px internal margins around thumbnail-first content.

Inputs / Fields

  • Style: Layer 2 fill, primary foreground, 1px default stroke, 6px radius, and 6px 8px padding at a 32px minimum height.
  • Focus: Studio Violet border plus the focus treatment supported by the specific Qt widget.
  • Error / Disabled: Semantic danger colors for errors. Disabled fields fall to Layer 1 with disabled foreground and secondary stroke.

Navigation

The left rail uses fixed 64 x 64 items with a 20px icon over a 12px label. Resting items are transparent, hover uses a subtle neutral fill, and active items use translucent Studio Violet with violet text. Tabs remain transparent and use a 2px violet bottom indicator for selection.

Inspector Sections

The fixed 320px post-recording inspector is organized by task rather than control type. Motion owns Smart Zoom and opens by default. Style owns Background, Device Frame, Click Effects, and Output Size; all four groups start collapsed so the tab remains a compact inventory until the creator chooses a customization. Audio owns Chapters and Voiceover; Chapters starts collapsed while the voiceover workflow remains immediately available. Style and Audio use exclusive disclosure: opening one section closes its sibling so the narrow inspector presents one decision context at a time.

Inspector sections use a fixed 32px disclosure header with an uppercase semibold label, a native Qt disclosure arrow, and a collapsible body. Section fills, strokes, labels, separators, inputs, hover states, and focus states must use centralized theme tokens so dark and light themes preserve the same hierarchy and readable contrast.

Within Motion, Generate locally is the sole violet primary action and Generate with AI is its paired neutral alternative. Audio uses the same compact action-row pattern for automatic and playhead-based creation. Optional AI and manual alternatives must not visually outrank the active task's primary workflow. Dynamic feedback occupies one bounded status line; full text remains available through the tooltip and accessible name. Clear utility commands remain text-only. The fixed footer stays outside all tab scroll regions and keeps Undo and Redo together, followed by the native Qt information icon and Settings.

The Inspector Task Ownership Rule. Motion controls camera movement, Style controls presentation, and Audio controls chapters and voice. Keep new inspector controls with the task they change rather than adding another top-level tab.

The Inspector Action Hierarchy Rule. Use one violet primary action within the active task. Optional, alternate, and utility actions remain neutral secondary controls.

Timeline

The 160px timeline is the signature editing surface. It combines a ruler with fixed Mouse, Clicks, Zoom, Voice, optional Clips, and Chapter rows. Zoom segments use rounded violet blocks, transition ramps, edge handles, speed labels, and numbered amber pan points. Voice segments use teal state variants; unavailable media becomes neutral and pending synthesis adds an amber progress arc. Trim handles stay at viewport edges and use Marker Amber until snapped to the playhead.

Preview

The preview preserves the target aspect ratio and letterboxes when necessary. It supports direct centroid and annotation manipulation, reason-coded debug markers, recording blur, and context actions for zoom and pan. Temporary mode banners use compact, centered, translucent brand treatment rather than permanent chrome.

Do's and Don'ts

Do:

  • Do use centralized tokens for spacing, type, color, shape, motion, and custom paint.
  • Do preserve the fixed rail, fluid preview, timeline, and inspector hierarchy for editor workflows.
  • Do maintain semantic timeline colors across default, hover, selected, generating, and unavailable states.
  • Do provide dark- and light-theme behavior for every new QSS rule, icon, and custom-painted element.
  • Do keep primary and destructive color rare enough that active choices remain obvious.
  • Do use tooltips and visible focus for icon-only or unfamiliar controls.
  • Do preserve the inspector's Motion, Style, and Audio task ownership, disclosure defaults, and fixed utility footer.
  • Do translate iOS inspiration through material, spacing, hierarchy, and motion while preserving Windows input conventions.

Don't:

  • Don't promote one-off dark violet-gray values from dialogs, overlays, or timeline paint code into new primitives.
  • Don't use Studio Violet as passive decoration or as a substitute for hierarchy.
  • Don't make cards float inside cards; use tonal panels, dividers, and collapsible sections for structure.
  • Don't use large display typography in persistent editor chrome.
  • Don't canonize glyph and emoji controls where the established icon pipeline provides a clear symbol.
  • Don't promote optional AI or footer utilities to violet primary actions inside the inspector.
  • Don't claim formal accessibility conformance; preserve keyboard access and focus treatment while documenting verified behavior only.
  • Don't introduce ReplayKit, safe-area constraints, edge-swipe navigation, mobile tab bars, or touch-only interactions.