Kwark. Design System
Open Kwark

Accessibility

WCAG 2.2 AA is the floor. This page gives Kwark's contrast per role, the keyboard map for the screenplay, timeline and boards, focus, screen readers, targets, motion, zoom, media and the checks every change must pass.

Foundations
Tabnext element⇧Tabprevious⌥↑move line up⌘Ggo to scene

The floor and the target

Kwark meets WCAG 2.2 level AA everywhere a person can go: the app, the published site, print and PDF, and this design system. That is the floor, not the goal. Where the thing on screen is the work (the script, the call sheet a crew reads at 6am), Kwark aims higher: 7:1 for the script’s ink, and a stronger-contrast switch in every writing room.

Accessibility here is not a checklist stage at the end. It is part of principle 11, Works for everyone, everywhere, and every screen runs the everyone test: phone, tablet, laptop; keyboard only; screen reader; slow or no network; a script in Tamil.

  • Must meet WCAG 2.2 AA in light, dark and all five writing rooms.
  • Must use native elements first: button, a, input, select, dialog, details.
  • Must give every icon-only control an accessible name that includes its object (“More for day 3”, not “More”).
  • Must offer a keyboard and a single-pointer way to do anything that can be dragged.
  • Never remove a focus outline without a visible replacement.
  • Never carry meaning by colour alone.

Contrast, role by role

Measured with the WCAG formula on the token values in kwark.css.

Pair Light Dark Needs Notes
--k-text on --k-surface 17.9:1 13.2:1 4.5:1 Body and titles
--k-text-2 on --k-surface 5.4:1 6.5:1 4.5:1 Meta, captions, placeholders
--k-text-2 on --k-bg 5.2:1 7.0:1 4.5:1 Quiet text on the page
--k-on-accent on --k-accent 5.0:1 10.2:1 4.5:1 Primary buttons with the default copper. A project accent recalculates --k-on-accent
--k-focus on --k-surface 17.9:1 15.0:1 3:1 The focus ring
--k-rev on --k-rev-bg 4.1:1 8.9:1 4.5:1 Revision label text. Below AA in light at 12px. Known gap
--k-line-strong on --k-surface 1.5:1 1.7:1 3:1 when it is the only boundary Known gap. Field borders must not be the only thing that identifies a field

Writing rooms, measured on the values in editorTheme.ts:

Room Ink on page Ink on desk Quiet text on chrome Pencil on page
Studio 13.9:1 15.4:1 7.2:1 project colour
Daylight 17.2:1 14.2:1 6.6:1 6.6:1
Paper 14.1:1 9.9:1 5.7:1 6.1:1
Lamplight 12.2:1 14.0:1 7.4:1 7.4:1
Midnight 13.3:1 15.0:1 7.6:1 7.7:1

The rooms do not rely on hand-picked values. Quiet ink is faded toward its ground only as far as the worst of the grounds it sits on allows (5.2:1 for muted text, 3.2:1 for faint marks, 7:1 and 4.6:1 with Stronger contrast on). See Writing rooms for the maths.

Stronger contrast

The room picker (View › Room…) has a switch, Stronger contrast: Fuller ink and firmer lines, in whichever room. It sets pure black or white ink, whichever measures better against all three grounds, and raises the quiet-text target to 7:1. It is the screen’s equivalent of a heavier pen, and it works in any room, including one a writer mixed themselves.

  • Must check text at 4.5:1 and icons, field borders and the focus ring at 3:1 against every ground they can sit on, not only the page.
  • Must test any new colour in the Paper room (warm, mid-light) and with Stronger contrast on.
  • Never fade text with opacity. Use --k-text-2; in the editor, the room’s settled muted ink.

Keyboard

Everything that works with a pointer works from the keyboard. Kwark’s keys come from one file in the screenplay (utils/editorShortcuts.ts): the menus show them beside each command, the shortcuts sheet (⌘/) lists them, and the keys do what the sheet says. Keys a browser keeps for itself (new tab, close, reload) are left alone. On Windows and Linux, ⌘ reads Ctrl and ⌥ reads Alt; labels are written for the platform (⌥⌘R on a Mac, Ctrl+Alt+R elsewhere).

Screenplay editor

Keys Does
Enter New line; the next element follows screenplay convention (after a cue, dialogue)
Tab · ⇧Tab Cycle the current element forward or back (action, character, dialogue…)
⌘⇧1 to ⌘⇧9 Make the line a scene heading, action, character, dialogue, parenthetical, transition, music, shot or lyrics. A writer can reassign the digits in Settings
( at the start of a dialogue line Starts a parenthetical
⇧Enter Break the line without changing the element
⌥↑ · ⌥↓ Carry the line past its neighbour; the caret goes with it
⌘Z · ⌘⇧Z Undo · Redo
⌘S Says Saved. Your script saves as you write. (Decision 0014)
⌘⇧S Make a restore point
⌘F · ⌘G Find · Go to scene
⌘\ Show or hide the scene navigator
⌥⌘R Read mode
⌘⇧F Distraction-free
⌘⇧D Dual dialogue
⌘⇧E Export
⌘, · ⌘/ Settings · Keyboard shortcuts

Typing in an Indian script. In a line whose speaker has a language, the word being typed is shown in that script just below the caret. Space, a punctuation mark or Enter writes it in; Esc keeps that word in Roman letters. The preview is zero width, so it never moves a line or a page break. See Writing systems.

Tab belongs to the script

In every screenplay tool, Tab cycles elements. Kwark keeps that convention, which means Tab cannot also move focus out of the page. WCAG 2.1.2 (No keyboard trap) allows this only if the way out is standard or is told to the person.

  • Must keep a documented key that moves focus from the page to the menu bar, and list it first on the shortcuts sheet.
  • Must announce, once, when the page takes focus, how to leave it (in the accessible description of the editor, not as a visible banner).
  • Status: the screenplay’s exit key has not been verified in this pass. Treat this as open, and do not ship a new editor surface that captures Tab without it.

Scenes, days and boards

Where Keys Does
Scene cards ← → ↑ ↓ Move focus between cards
Scene cards ⌥⇧ with an arrow Carry the scene one place along
Day planner (Schedule) Enter or Space Choose the block
Day planner ⌥↑ · ⌥↓ Move the block earlier or later in the day
Day planner ⇧↑ · ⇧↓ Shorten or lengthen the block by one step
Day planner Delete or Backspace Remove the block
Calendar C · T · W · X · D · M · A · L · B · [ · ] · ? · Esc Quick add, today, views, previous and next, shortcuts, close. Single keys are ignored while typing in a field or a dialog
Timeline (desktop) Tab, then Enter Each scene is a button named Scene 12, INT. EDIT SUITE – NIGHT, about 2:40
Timeline strip (phone) Enter or Space Opens the full timeline

Known gap. The phone timeline strip has role="slider" but answers only Enter and Space. A slider must also answer ← → (previous and next scene), Home and End. Until it does, the scene navigator and ⌘G are the keyboard routes.

  • Must read keys from the shared shortcut table, show them in menus with kbd, and list them on the shortcuts sheet.
  • Must ignore single-key shortcuts while focus is in a text field, the screenplay page or a dialog.
  • Never bind a key a browser or screen reader reserves (⌘T, ⌘W, ⌘R, Ctrl+Alt arrows on Windows readers).

Dragging always has another way

WCAG 2.2 adds 2.5.7, Dragging movements: anything that can be dragged must also work with a single pointer, without dragging. Kwark already has these routes; new work follows them.

Drag Single pointer Keyboard
Reorder scene cards Not verified in this pass ⌥⇧ with an arrow
Move a block in the day planner Not verified in this pass ⌥↑ · ⌥↓
Resize a block Not verified in this pass ⇧↑ · ⇧↓
Reorder episodes in a series ⋯ › Move earlier / Move later Through the menu
Arrange a character’s pages Move up / Move down Through the menu
Move a line of the script Cut and paste ⌥↑ · ⌥↓
Create an event by dragging the calendar grid Quick add, then the event inspector C

Where a row says Not verified, the keyboard route exists in the source; a single-pointer route (a Move earlier / Move later item in the thing’s ⋯ menu) is the rule to add if it is missing.

  • Must announce the result of a keyboard move in words (“Moved Scene 12 after Scene 13”) through a polite live region.
  • Must keep focus on the thing that moved.

Focus

  • Ring. 2px --k-focus, 2px offset, on :focus-visible. Inputs use a 1px offset and drop their border colour so the ring is the only edge.
  • Not hidden (2.4.11, new in 2.2). A focused control must not sit under the phone’s floating dial or a sticky header. Pages keep --k-fab-slot free at their foot, and scrolling a focused element into view must clear both.
  • Order follows reading order. Never use a positive tabindex.
  • Return. Every dialog, sheet and menu returns focus to the control that opened it. Escape closes the top-most layer only.
  • Into the work. A rule for every view: on opening, focus goes to the view’s heading, or in the screenplay to the caret where the writer left it.

Screen readers

Test with VoiceOver on macOS and iOS, TalkBack on Android, and NVDA on Windows for the core journey.

  • Landmarks. One main per view; the editor’s panels are regions with names (Estimated runtime, Top sheet, Shooting days).
  • The script. A screen reader user must be able to tell a cue from a line: each element’s type (scene heading, action, character, dialogue) must be exposed, not only drawn by indent. Verify this on every surface that renders the script.
  • Language of a line. A line written in Tamil or Hindi must carry lang (ta, hi) so the reader switches voice (3.1.2). Kwark stores the language per character and per line; exposing it as lang on the rendered line is a rule for every surface that shows the script.
  • Measures, in words. The timeline strip says Runs about 1 h 42 min and gives the current scene as its value text. The talk and action bar is role="img" named Talk 62 percent, action 38 percent.
  • Save state. The sync word is in a polite live region. Errors that block work (a change that could not be stored) use role="alert", once.
  • Toasts. Polite, never assertive. A toast with an action (Undo) stays until it is used or dismissed by keyboard, never only on a timer.
  • Revision marks. The label Suggested is read before the suggested words (aria-describedby), so the tint is never the only signal.
  • Decorative pieces. Icons beside a word are aria-hidden. Sprocket holes on Dailies film strips and paper grain are decoration.

Targets

Context Minimum Token
Phone and touch (≤767px, sideways phones) 44 × 44px --k-tap
Desktop controls 32px high --k-control-sm
WCAG 2.5.8 floor 24 × 24px, or 24px spacing none

Small marks that are not the only route are allowed under 2.5.8’s equivalent-control exception: a 3px-wide scene on a 120-minute timeline is reachable through the scene navigator and ⌘G. Rows on a phone have no inline buttons; the whole row is the target and secondary actions are in its ⋯ sheet (Decision 0016).

Motion

Motion answers an action; there is no ambient animation in the app. Durations are --k-dur-1 120ms, --k-dur-2 200ms, --k-dur-3 320ms. Under prefers-reduced-motion: reduce, transitions and animations collapse to 1ms and loops stop.

The timeline’s current scene used to pulse with a glow and six rising particles. They are gone (Decision 0041), and the scene is marked with a 2px ring and a pointer. Scrubbing the phone strip gives a 4ms haptic tick per scene where the phone supports it; it is a bonus, never the only feedback.

  • Never animate the script page, the caret or the page count.
  • Never auto-play an animatic or a table read.

Zoom and reflow

App zoom. Settings has a zoom from 80% to 200% in 5% steps, kept on the device. It sets --app-zoom (default 1.2), which scales the root font size, so everything sized in rem follows it. On phones (≤767px) the multiplier is switched off and the root is a standard 16px, because the phone’s own text size and pinch zoom do the job.

Page zoom. The screenplay page has its own zoom (Fit width, or a page zoom). It changes how large the page is drawn, never the page’s geometry: line breaks and page count are the same at every zoom.

Browser zoom. At 200% and at 320 CSS pixels wide (1.4.10 Reflow), nothing is cut off and nothing scrolls in two directions, except the parts that are two-dimensional by nature: the timeline, the stripboard, the calendar time grid and the printed page.

Text spacing. Line height 1.5, paragraph spacing 2×, letter spacing 0.12em and word spacing 0.16em (1.4.12) must not clip text. Use min-height, not height, on anything that holds words.

Media, captions and transcripts

  • Table reads. A table read speaks the script with the device’s voices. The script is its transcript. A rule for any reading view: show which line is being spoken, in text as well as by highlight.
  • Animatics. An animatic is built from the boards, so its frames and their descriptions are its text alternative. Any dialogue it plays must be shown as captions from the script.
  • Video a person uploads (research, references, audition tapes). Kwark does not support caption tracks on uploaded video yet. A rule for anything built: allow a .vtt file beside a video, and show No captions in words when there is none.
  • Images. A rule for anything built: every image a person uploads can carry a description, and boards and covers that carry the story say what they show.

Forms and sign-in

  • Labels are visible and above the field. Placeholder text is never the label.
  • Errors say what happened and how to fix it, next to the field, and move focus to the first one (3.3.1, 3.3.3).
  • Redundant entry (3.3.7). Kwark’s core idea is that one script feeds everything; never ask for what the project already knows. The call sheet takes cast from the breakdown and the budget takes fees from casting.
  • Accessible authentication (3.3.8). No puzzles or memory tests to sign in; password managers and paste must work.
  • Consistent help (3.2.6). Help sits in the same place in every view. In the screenplay it is the Help menu (Decision 0015); other views must keep it in one fixed place too.

Who is responsible for what

Component Must handle
Button, Icon button Native button; accessible name with its object; aria-pressed for toggles; disabled controls explain why
Menu, Dropdown Arrow keys, Home, End, type-ahead; Escape closes and returns focus; shortcuts shown with kbd
Dialog, Sheet dialog or role="dialog" with aria-modal; focus trapped while open and returned after; Escape closes
Toast Polite live region; actions reachable by keyboard; no timer while focused or hovered
Tabs, Segmented Arrow keys move between options; aria-selected or aria-pressed
Switch role="switch" with aria-checked; the label says what is on
Timeline Scenes as named buttons; strip as a real slider; measures in words
Screenplay page Element types exposed; lang per line; a documented way out of Tab
Revision mark Suggested in words before the text; Accept, Edit and Revert by keyboard
Charts A name with the numbers, or a table beside the chart. See Data visualisation

Checks before anything ships

  1. Keyboard only: reach, use and leave every control; focus always visible and never hidden.
  2. Screen reader: VoiceOver (macOS, iOS) and TalkBack on the changed journey; names, roles, states and live messages make sense alone.
  3. Contrast: every new pair in light, dark and the five rooms, and with Stronger contrast on.
  4. Zoom: 200% browser zoom, app zoom at 80% and 200%, and 320px wide.
  5. Touch: a real phone, not a resized desktop window. Targets 44px; nothing only on hover.
  6. Reduced motion on: nothing moves that does not have to.
  7. Drag: every drag has a single-pointer and a keyboard route.
  8. Language: a Tamil or Hindi line keeps its lang and does not clip its vowel signs.

These checks are the agreed method. Recording which screens have passed them is part of the launch readiness work, not yet complete.

An icon button named More for day 3, a visible focus ring, and the same action in the row’s ⋯ sheet on a phone.

Do

A bare ⋯ with no name, outline: none, and an action that only appears on hover.

Don’t

A drag that also has Move earlier in the menu and ⌥⇧ with an arrow on the keyboard.

Do

A board that can only be rearranged by dragging cards with a mouse.

Don’t

AI readiness test

Task. Add a “reorder shots” interaction to the shot list for Scene 12.

Give the agent. This page, the Menu and List row components, the Day planner key map above.

Constraint. Must meet WCAG 2.2 AA, including 2.5.7 Dragging movements and 2.4.11 Focus not obscured.

A reliable answer

  • Drag plus a single-pointer route (Move earlier, Move later in the ⋯ menu)
  • Keyboard route with ⌥ and an arrow, focus stays on the moved shot
  • Result announced in words through a polite live region
  • Focus ring visible and clear of the phone’s floating dial
  • No colour-only state

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…