Direct manipulation

Drag, drop, reorder — and the keyboard equivalent that is not optional.

Part of the Konjo design language. The laws in the spine apply here unless this chapter contradicts them.

Every other pattern in Konjo is a state machine over taps: press → navigate, press → validate, press-arm → press-fire. This one is not. A drag is a continuous gesture with a mid-flight state, a spatial target, a cancel, a rollback, and a second complete interaction — the keyboard path — that has to produce identical outcomes through a different modality.

The chapter exists because a completeness test specified a Studio board and found the entire specification of direct manipulation in this system was one clause in a screen inventory: "Drag-and-drop cards." Thirty-three of that round's decisions were the agent's and not the system's, twelve of them here. The shapes this covers: a pipeline board, a sortable list, the belt-ladder editor, a schedule grid, and anything else where the person moves the object rather than filling in a field about it.

Before anything else: is a drag allowed here?

A drag must be reversible, or it is not a drag.

Serious actions require the consequence stated before the commit, "in caption, next to the control that causes it". A drag has no control and no before-the-tap moment — by the time anything is stated, the thing has happened. So:

• Reversible move → a drag is legal, and the announcement after the drop is the notice.
• Irreversible, or it moves money, or someone is told → it is not a drag. It is a control with a confirm, and the object may still be draggable as a shortcut to the control, which opens the confirm rather than committing.

If you cannot say what undoes it, you are not ready to build it.

The three visual states, and why none of them is a shadow

The universal convention for a lifted object is a drop shadow, and L3 bans shadow, blur, glow and gradient outright. The system's one recipe for a floating surface — scrim behind plus a 1px hairline — cannot apply either: a scrim would hide the drop targets that are the entire point of the gesture. So the lift is built from what is left, and it is built from meaning rather than depth.

Focus and the drop target are the same thing, deliberately. A drag in flight has exactly one active region, and it is the one a drop would land in — whether the person is pointing at it or arrowed to it. Giving them separate treatments would put two rings on one screen meaning almost the same thing, and would make the pointer path and the keyboard path look like different features. While a drag is in flight, focus is the drop target.

Nothing here is dashed. borderWidth ships hairline 1 and emphasis 2 and there is no border-style token; a dashed edge is a fifth visual language nobody sanctioned.

Pointer

A whole object may be the drag source, or a handle may be. Use a handle when the object also contains controls — a card with a link and a menu inside it — because a drag that starts on a link is a link that sometimes does not work. Use the whole object when it contains only text. The handle is iconSize.inline 16, text.tertiary, and it is not the object's only affordance: the cursor and the keyboard path both work on the object itself.

Keyboard, which is a requirement and not a courtesy

WCAG SC 2.5.7 (Dragging Movements, 2.2 AA): every drag needs a single-pointer alternative that is not path-based. SC 2.1.1 additionally requires the whole thing be reachable by keyboard. These are not the same requirement and one control can satisfy both.

The best answer is usually not a keyboard drag. It is a plain control that sets the same value — a stage chip row, a "move to" select, a menu on the row. That serves keyboard users, switch users, screen-reader users and anyone on a tremor-affected hand at once, and it is derivable from sheet-picker and buttons with nothing invented. Build that first. If the collection is large enough that the control is unusable, add the grab-and-move path below as well, never instead.

A collection is one tab stop, and that is an exception worth stating, because accessibility otherwise says tab reaches every control. A 40-card column with every card a tab stop reproduces exactly the problem a skip link exists to solve. Roving tabindex — one 0, the rest -1 — is the mechanism. It applies to a composite widget: a board, a grid, a tree, a toolbar. It does not apply to a list of links.

What it says

A drag is invisible to a screen reader unless it is narrated. Two live regions for the whole collection — not one, and not one per group:

• polite carries progress — the grab, and the in-flight message on every arrow press.
• assertive carries the outcome — the drop, the cancel, the failure.

One region cannot do both: politeness is read when the region is created, not per message. A single polite region drops the message that matters (rapid arrow presses coalesce), and a single assertive one interrupts the screen reader on every keypress.

• The pointer path announces too. A screen-magnifier user drags with a mouse.
• In-flight messages are polite and will sometimes be dropped when arrows repeat quickly. That is correct — and the outcome is assertive for the same reason, because it is the one that must survive. It restates the whole result, not just the change.
• Never aria-grabbed/aria-dropeffect — deprecated since ARIA 1.1. State lives in the live region and in aria-roledescription on the object.
• Voice: plain, name the person, no first person, no exclamation. See voice.

Motion

Reduced motion, and the one exemption in the system. Movement is normally replaced, never deleted (WCAG 2.3.3). 1:1 pointer tracking is exempt: it is not a transition, it is the person's own hand, and removing it removes the interaction rather than its decoration. This is the only essential-motion exemption Konjo has, and it does not generalise — everything else in a drag still obeys the rule: the settle becomes an instant swap, auto-scroll steps instead of ramping.

States

• Optimistic by default. The object moves on drop; a failure rolls it back and says so in an inline block, never a toast — a toast disappears and this needs a decision.
• Rollback returns the object to its exact origin, not to the end of the origin group.
• A drop into a group that is full, closed, or not allowed shows no drop target at all. Never accept a drop and then reject it.
• Two people on one board is an ordinary Tuesday. If a move lands on stale state, the object goes where the server says and the announcement says what happened — never silently.

The self-check

• Can someone who cannot drag do the same thing, in the same number of steps, without one?
• Does the drop announce the outcome, not just the action?
• If the network fails mid-gesture, where does the object end up, and is that said out loud?
• Is the thing this moves reversible? If not, why is it a drag?