{
  "title": "Files and uploads",
  "path": "/patterns/files",
  "url": "https://design.werklist.com/patterns/files",
  "text": "https://design.werklist.com/agent/patterns/files",
  "summary": "How people add a file, follow its upload, open it and share it, in Drive, on a board and in email.",
  "version": "2.1.2",
  "kind": "pattern",
  "name": "Files and uploads",
  "purpose": "Adding files to Drive, a board cell or an email, following their upload, opening them in place and sharing them at a stated access level.",
  "use": [
    "Any screen that accepts a file: a Drive folder, a file cell on a board, an email being written, a public application form.",
    "Moving items between Drive folders by drag, with Move in the item menu as the keyboard path."
  ],
  "avoid": [
    "A progress dialog that blocks the page. The tray reports progress while the page stays in use.",
    "A second progress display beside the tray."
  ],
  "anatomy": [
    {
      "part": "Upload button",
      "measure": "secondary button, 36 px, in the toolbar; opens the file picker for several files at once",
      "token": "--surface-control"
    },
    {
      "part": "Drop target",
      "measure": "covers the folder or the email being written; radius 16 px; fill only, no border; the sentence Drop files to upload at 14/20 weight 500, centered",
      "token": "--nav-fill-active, --radius-2xl, --type-product-body, --brand-ink"
    },
    {
      "part": "Upload tray",
      "measure": "fixed at the bottom right, 16 px from the right edge, 24 px on windows 1024 px and wider, and above the phone's bottom bar; 320 px wide, or the window minus 32 px; radius 12 px; padding 12 px",
      "token": "--surface-1, --elevation-3, --radius-xl, --space-3, --layer-toast"
    },
    {
      "part": "Progress bar",
      "measure": "38 by 19 px (30 by 15 px collapsed), radius 5 px, fill inset 1.5 px; a green gradient while running, the error fill on failure",
      "token": "--success, --success-deep, --error, --surface-control"
    },
    {
      "part": "Summary line",
      "measure": "13/18 weight 500; percent and size 12/16 in tabular digits",
      "token": "--type-product-dense, --type-product-caption"
    },
    {
      "part": "File row",
      "measure": "status glyph 20 px; name 12/16, cut in the middle so the extension stays in view; percent in tabular digits; a 24 px glyph button, 44 px to touch on touch screens",
      "token": "--type-product-caption, --text, --text-muted"
    },
    {
      "part": "Collapsed tray",
      "measure": "one row with the bar and the summary, radius 12 px",
      "token": "--radius-xl"
    }
  ],
  "states": [
    {
      "name": "Drag over",
      "change": "The drop target tint and sentence appear, and leave when the files leave or drop",
      "tokens": [
        "--nav-fill-active"
      ]
    },
    {
      "name": "Item dragged over a folder",
      "change": "The folder row takes the hover fill and full ink",
      "tokens": [
        "--glass-fill-hover",
        "--text"
      ]
    },
    {
      "name": "Queued",
      "change": "A row with the name and 0 percent",
      "tokens": [
        "--text-muted"
      ]
    },
    {
      "name": "Uploading",
      "change": "The bar fills with the total percent; each row shows its own percent and Cancel",
      "tokens": [
        "--success"
      ]
    },
    {
      "name": "Done",
      "change": "A check glyph; the rows clear once every upload has finished",
      "tokens": [
        "--success-ink"
      ]
    },
    {
      "name": "Failed",
      "change": "The bar takes the error fill; the row keeps the reason and Retry",
      "tokens": [
        "--error",
        "--error-ink"
      ]
    },
    {
      "name": "Refused before start",
      "change": "The row shows the limit sentence, and nothing is sent",
      "tokens": [
        "--error-ink"
      ]
    },
    {
      "name": "Collapsed",
      "change": "One row with the bar and the summary; a click expands it",
      "tokens": [
        "--radius-xl"
      ]
    }
  ],
  "keys": [
    {
      "key": "Tab",
      "action": "Reaches Upload, then Collapse in the tray, then each row's Cancel, Retry or Dismiss"
    },
    {
      "key": "Enter or Space on Upload",
      "action": "Opens the file picker"
    },
    {
      "key": "Enter on an item",
      "action": "Opens the file in the editor or the preview"
    },
    {
      "key": "Escape",
      "action": "Closes the preview, the share dialog or the move dialog and returns focus to the item"
    }
  ],
  "accessibility": [
    "The summary line is announced when an upload starts, finishes or fails, not at each percent.",
    "Each file row is a progress bar named with the file name.",
    "The drop target is hidden from screen readers. The Upload button and Move are the accessible paths.",
    "Cancel, Retry and Dismiss carry the file name in their names, such as Cancel upload of cv-ana-kovac.pdf.",
    "Tray controls are 44 px to touch on touch screens."
  ],
  "content": [
    "Summary: Uploading 3 files, 2 files uploaded, 1 file failed.",
    "Drop target: Drop files to upload.",
    "Limit: Files up to 25 MB. That one is too large. The sentence names the limit of the place the file was dropped.",
    "Failure: Upload failed. Check your connection and try again. Refusal: Upload was refused. You may not have access to save here. Cancel: Upload canceled.",
    "Empty folder: Nothing here yet. Upload files or add a folder.",
    "Share levels: Private, only you and people you grant access; Team, every signed in member can view; Public link, anyone with the link can view. People: Viewer, Editor."
  ],
  "rules": [
    "A file lands where it was dropped or chosen.",
    "Uploads continue when the screen that started them closes.",
    "Drive accepts files up to 50 GB. Attachments on a board or an email are up to 25 MB.",
    "A file that is too large is refused before it starts, with the limit in the sentence.",
    "Every drag has a menu equivalent.",
    "The tray is the one place that reports an upload.",
    "Documents save as you type, with no Save button."
  ],
  "tokens": [
    "--nav-fill-active",
    "--brand-ink",
    "--surface-1",
    "--surface-control",
    "--elevation-3",
    "--radius-xl",
    "--radius-2xl",
    "--success",
    "--success-deep",
    "--success-ink",
    "--error",
    "--error-ink",
    "--text",
    "--text-muted",
    "--type-product-body",
    "--type-product-dense",
    "--type-product-caption",
    "--space-3",
    "--space-4",
    "--space-6",
    "--layer-toast",
    "--focus-ring"
  ]
}