banner_studio/INTERACTION_STANDARDS.md

INTERACTION_STANDARDS.md

The canonical interaction reference for the banner production platform. These are non-negotiable. A developer who implements something different is fixing a bug, not making a design choice.

Conventions:

• Cmd on macOS = Ctrl on Windows/Linux. The shortcuts below are written with Cmd for brevity; the implementation must bind both.
• Shift, Alt, and Cmd modifiers compose as written.
• Every interaction is undoable except where explicitly noted.
• Behaviors apply across every editable surface in the app (template builder canvas, review grid edits, property panels) unless surface-specific overrides are called out.

---

Selection

Action	Result
Single click on a layer	Select the layer
Single click on empty canvas	Deselect everything
Double click on a text layer	Enter text edit mode, cursor at click position
Double click on a group	Drill into the group (select first child); deeper double-clicks descend further
Escape	Exit text edit mode → exit nested group → deselect (cascading)
Tab (with selection)	Cycle to next sibling in z-order
Shift + Tab	Cycle to previous sibling in z-order
Cmd + A	Select all layers in the active artboard
Click + drag on empty canvas	Marquee select (V2 — out of slice)
Shift + click	Add to selection (multi-select)
Cmd + click	Toggle inclusion in selection
Right-click	Context menu — always a duplicate of UI affordances, never the only path

Selection is always visible: every selected layer has a 1px outline in the system accent color, plus a bounding box for the multi-selection.

Multi-select and group operations

Action	Result
Drag any selected layer	All selected layers move together, preserving relative position
Arrow keys with multi-select	Nudge all selected layers by 1px
Property panel edit with multi-select	Applies to all selected layers; conflicting values show "Mixed" and editing replaces
Resize handle with multi-select	Scales the bounding box; children scale proportionally
Align actions (left/center/right/top/middle/bottom)	Align selected layers relative to the bounding box, or to the artboard if only one layer is selected
Distribute (horizontal/vertical)	Available with 3+ layers selected
Delete / Backspace	Delete all selected layers (undoable, no confirmation)
Cmd + G	Group selected layers into a new GroupLayer with group_behavior: 'fixed'
Cmd + Shift + G	Ungroup the selected group, lifting children to the parent
Cmd + L	Lock selected layers (BaseLayer.locked = true)
Cmd + Shift + L	Unlock
Cmd + ;	Toggle visibility (BaseLayer.visible)

Locked layers cannot be selected by click on the canvas — they must be selected via the layers panel. Hidden layers don't render and cannot be selected.

Movement

Action	Result
↑ / ↓ / ← / →	Nudge 1px
Shift + arrow	Nudge 10px
Drag	Free move
Shift + drag	Constrain to nearest axis (horizontal or vertical)
Alt + drag	Duplicate and move — standard creative-tool behavior
Cmd + drag	Disable snapping for this gesture

Snapping engages when the dragged element is within 4px of a snap target (artboard edge, safe zone, sibling edge or center, sibling baseline). Snap targets render a 1px guide before they engage. Cmd held during the drag suppresses all snapping.

Zoom

Action	Result
Cmd + scroll	Zoom to cursor
Cmd + =	Zoom in
Cmd + -	Zoom out
Cmd + 0	Fit all artboards in view
Cmd + 1	100% (1:1 pixel)
Cmd + 2	200%
Space + drag	Pan, even when a selection tool is active

Zoom is continuous, not stepped. Browser zoom is disabled inside the editor — Cmd + scroll is always canvas zoom.

History

Action	Result
Cmd + Z	Undo
Cmd + Shift + Z	Redo
Cmd + Y	Redo (alt)

Undo is unlimited within the session, including in text edit mode, in the property panel, and in the review grid. Undo never has exceptions. This is treated as a correctness property of the application, not a feature.

History persists across reloads via the version log for major changes (every state change is auto-saved). In-session undo is fine-grained; cross-session undo operates at version granularity.

Text editing

Action	Result
Double-click a text layer	Enter edit mode, cursor at click position
Cmd + B	Bold (toggles typography.font_weight within selection)
Cmd + I	Italic
Cmd + U	Underline
Cmd + A	Select all text in the layer
Cmd + arrow	Word-wise / line-wise cursor movement (standard OS behavior)
Shift + arrow	Extend selection
Escape	Commit edit and exit edit mode
Tab	Commit edit and select next layer in z-order
Enter (in single-line text)	Commit and exit
Shift + Enter	Line break within multi-line text
Cmd + Z in edit mode	Undo last text change (does not exit edit mode)

Live text fit happens as the user types: Dropflow recalculates layout on every change, the canvas updates within 100ms, push_siblings cascades visibly. If the content exceeds the character limit, the layer renders with a limit-exceeded badge but does not block typing — the user sees the consequence and decides.

Copy / paste

Action	Result
Cmd + C	Copy selected layer(s) with all properties
Cmd + V	Paste to the active artboard at the source layer's relative coordinates
Cmd + Shift + V	Paste in place — exact same coordinates as the source
Cmd + D	Duplicate in place, offset by (+10, +10) on the same artboard
Cmd + X	Cut (copy + delete)

Paste always:

• Lands on the active artboard
• Preserves every visual property (typography, color, opacity, rotation, anchors)
• Preserves the layer's behavior rules (push_siblings, character constraints)
• Re-anchors push_siblings.layer_id references to copies of siblings if the siblings were copied too; otherwise the rule is preserved with the original target ID
• Is undoable

Pasting across artboards of different sizes preserves the layer's pixel dimensions, not its proportional position — designers think in pixels for ad layouts.

Layer manipulation

Action	Result
Cmd + ]	Bring forward one z-index
Cmd + Shift + ]	Bring to front
Cmd + [	Send backward one z-index
Cmd + Shift + [	Send to back
Drag in layers panel	Reorder z-index by dragging
Cmd + G	Group
Cmd + Shift + G	Ungroup
Cmd + L / Cmd + Shift + L	Lock / unlock
Cmd + ;	Toggle visibility
Cmd + R	Rename selected layer (focus name field in layers panel)

The layers panel mirrors the canvas selection bidirectionally. Selecting in the panel selects on canvas; selecting on canvas highlights in the panel and auto-scrolls if needed.

Review grid shortcuts

Action	Result
→ / ←	Next / previous banner
↓ / ↑	Next / previous row in the grid
Enter	Open the focused banner detail (full-size view + AI reasoning panel)
Escape	Close detail / return to grid
A	Approve the focused banner
R	Reject the focused banner (prompts for one-line reason)
G	Regenerate the focused banner (shows pre-flight: overrides preserved, conflicts likely)
E	Edit the focused field (or activate inline edit if a field is in focus)
Cmd + Enter	Approve all banners in the campaign (only if all have status in_review and no unresolved conflicts)
Space	Play / pause animation on the focused banner
?	Show this shortcut sheet as an overlay

Approval and rejection are bound to single keystrokes (A, R) because they are the most repeated actions in the review path. Regenerate is G deliberately — not Cmd+G, which is group — because regenerate is a single-banner action with a pre-flight modal that prevents accidental destruction.

The shortcut sheet (?) is the canonical onboarding aid for the review grid. Producers should not need a tutorial.

Touchpad and gesture

Gesture	Result
Two-finger scroll	Pan the canvas (no scroll bars are visible during; the canvas is the document)
Pinch	Zoom to pinch center, continuous
Two-finger horizontal scroll on review grid	Pan horizontally through banners
Three-finger swipe	OS-level navigation (do not capture)
Double-tap with two fingers	Fit to view (Cmd + 0 equivalent)

Browser-level pinch zoom is disabled in the editor and in the review grid — pinch is always canvas zoom. Two-finger scroll on the canvas pans, not page-scrolls. The canvas captures these gestures when the cursor is over it; outside the canvas, the page behaves normally.

Gesture conflict handling:

• If the cursor is over an inline text input or scrollable panel, two-finger scroll scrolls that element, not the canvas.
• Pinch over a scrollable panel still zooms the canvas (the page should never zoom; this is consistent everywhere in the editor).
• Space + drag (panning shortcut) wins over gesture-based pan when both fire — keyboard intent is explicit.

Property panel

Action	Result
Type in any numeric field	Live update on commit (blur or Enter)
Drag the field label	Scrub the numeric value (Photoshop-style)
Shift + scrub	10× speed
Alt + scrub	0.1× speed
Tab	Move to next field
Color swatch click	Open color picker; selection updates live as the picker moves
Escape in a field	Revert to the field's value before edit

All property panel edits are undoable. The panel never shows a "Save" or "Apply" button.

Asset library (V1)

Action	Result
Drag an asset onto a smart asset slot	Bind the asset's variant group to the slot
Drag an asset onto the canvas	Reject — assets must enter through smart asset slots, not free placement (anti-pattern #32)
Click an asset	Open asset detail (metadata, rights, approved crops)
Cmd + F in the library	Focus search
Filter pills (region, market, language, campaign type)	Multi-select OR within a pill, AND across pills

Conflicts to resolve before build

• Cmd + L for lock vs. layer-level locking. Anti-pattern document and FRUSTRATION_LIST.md both reference field-level locking (HumanOverride.locked). This document defines Cmd + L as layer-level lock (BaseLayer.locked). These are two different locks. Confirm naming and keybinding to avoid user confusion — likely: Cmd + L locks the layer; field-level lock is a toggle in the review grid's override pip menu, not a global keystroke.
• Marquee select. Listed as V2 (out of slice) consistently with the source document. Confirm V1 includes it; if not, surface in the V1 acceptance criteria.
• Browser zoom disabled in the editor. Disabling browser zoom is technically tricky (browsers don't fully let you). Document the chosen approach (e.g., a CSS touch-action: none on the canvas wrapper + intercepting Cmd + scroll) before implementation so behavior is consistent across Chrome/Safari/Firefox.
• Cmd + Y vs. Cmd + Shift + Z for redo. Both bound. Adobe convention is Cmd + Shift + Z; some users expect Cmd + Y. Both work; no conflict — but document that Cmd + Y is an alias, not a separate action.
• Tab cycles z-order vs. Tab in text edit. Tab exits text edit mode and selects the next layer. This means Tab cannot insert a tab character into text. For ad copy this is fine (ad copy has no tabs), but flag in case a future text feature needs literal tabs.