Kwark. Design System
Open Kwark

Progress and loading

Shows how much of a known job is done, in a bar and in figures: pages exported, folders imported. Kwark’s is the 2px bar of the import toast, with each folder on its own line.

ComponentsFeedbackIn the app
Importing Blank Pages
  • Characters
  • Screenplay60%
  • Schedule–
3/5 folders · syncing Screenplay
Exporting the screenplay48 of 112 pages
Importing Blank Pages3 of 5 folders
Checking the cloud copyUsually a few seconds
Importing project
  • Characters
  • Outline
  • Screenplay60%
  • BreakdownQueued
  • Schedule–
2/5 folders · syncing Screenplay
Saved on this deviceCloud sync queued
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Exporting the screenplay</span><span>48 of 112 pages</span></div>
  <div class="kw-progress" role="progressbar" aria-valuenow="48" aria-valuemin="0" aria-valuemax="112" aria-valuetext="48 of 112 pages" aria-label="Exporting the screenplay"><span style="width:43%"></span></div>
</div>
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Importing Blank Pages</span><span>3 of 5 folders</span></div>
  <div class="kw-progress-segs" role="progressbar" aria-valuenow="3" aria-valuemin="0" aria-valuemax="5" aria-valuetext="3 of 5 folders, Screenplay at 60%, Schedule queued" aria-label="Importing Blank Pages"><span data-state="done"></span><span data-state="done"></span><span style="--kw-seg:60%"></span><span data-state="queued"></span><span></span></div>
</div>
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Checking the cloud copy</span><span>Usually a few seconds</span></div>
  <div class="kw-progress" data-state="working" role="progressbar" aria-label="Checking the cloud copy" aria-valuetext="Working"><span></span></div>
</div>
<div class="kw-upload" role="status">
  <div class="kw-upload__head"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3v12M17 8l-5-5-5 5M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/></svg><span>Importing project</span><button class="kw-icon-button" type="button" aria-label="Minimise import progress"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m18 15-6-6-6 6"/></svg></button></div>
  <div class="kw-progress" role="progressbar" aria-valuenow="64" aria-valuemin="0" aria-valuemax="100" aria-label="Importing Blank Pages: 64%"><span style="width:64%"></span></div>
  <ul class="kw-upload__list">
    <li data-state="done"><span>Characters</span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.8 10A10 10 0 1 1 17 3.3"/><path d="m9 11 3 3L22 4"/></svg></li>
    <li data-state="done"><span>Outline</span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.8 10A10 10 0 1 1 17 3.3"/><path d="m9 11 3 3L22 4"/></svg></li>
    <li data-state="uploading"><span>Screenplay</span><b>60%</b><div class="kw-progress"><span style="width:60%"></span></div></li>
    <li data-state="queued"><span>Breakdown</span><b>Queued</b></li>
    <li data-state="pending"><span>Schedule</span><b>–</b></li>
  </ul>
  <div class="kw-upload__foot">2/5 folders · syncing Screenplay</div>
</div>
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Saved on this device</span><span>Cloud sync queued</span></div>
  <div class="kw-progress" data-state="queued" role="progressbar" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100" aria-label="Import saved on this device, cloud sync queued"><span style="width:100%"></span></div>
</div>

What it is

A bar and a sentence for work that can be measured: pages exported, folders imported, frames rendered. The figures matter more than the bar. 48 of 112 pages tells a writer whether to wait or make tea; a bar alone does not.

Which one

Form Status Use
Bar with figures In the app (UploadProgressToast) One job with a known total: Exporting the screenplay · 48 of 112 pages
Import toast In the app A multi-part import: each folder on its line, its own percentage, a summary foot
Segmented bar Ready for Kwark A known number of parts that finish one by one: five folders, three reels
Working bar Ready for Kwark A step with no measurable amount inside a measured flow; prefer the spinner on its own
Queued In the app Saved here, cloud part waiting: the bar fills in --k-warn, the words say so

Saved here, sent later

Kwark saves to the device first. An import that is complete here but waiting for the cloud is not an error: the bar is full, in the warn colour, and says Saved on this device · Cloud sync queued (Decision 0013). Green means it is in the cloud too.

Timing

  • Under a second: nothing. One to four: a skeleton or spinner. Longer with a total: this.
  • Never block the screenplay. Exports and imports run in a toast while people keep writing.
  • When it finishes, the toast says what happened and offers the next step: Screenplay exported · Open.

Anatomy

  1. Bar: 2px (h-0.5), 3px in a standalone block, --k-line track, fill in --k-accent-soft; --k-ok when done; --k-warn when queued or partly failed; width eases over --k-dur-3.
  2. Label row: what is happening on the left (Poppins 500 12px), the figures on the right in tabular --k-text-2 (48 of 112 pages).
  3. Segments: 4px tall, 3px gaps, one per part; done parts in --k-ok, the active one filled to its percentage, queued at 55% --k-warn.
  4. Import toast: up to 320px, --k-surface, 1px line, 10px corners, --k-shadow-pop; head with a 14px glyph, the title and a 26px minimise; the overall bar across its full width; folder rows (12px) with a tick, a tabular percentage, Queued in warn, or a dash; a 12px foot.
  5. Working bar: a 32% fill that slides across in 1.4s; under reduced motion it holds full width at 45% opacity.

Tokens

Token Light Dark
--k-line #e2e8f0 rgba(255, 255, 255, .1)
--k-accent-soft #e8b58b #e8b58b
--k-ok #2c6e49 #6cc08a
--k-warn #8a5a00 #d8a44a
--k-surface #ffffff #1a1a1a
--k-text #0f172a #e3e3e3
--k-text-2 #5b6779 #9ca3af
--k-shadow-pop 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55)
--k-radius-card 10px
--k-fs-meta 12px
--k-ease-in-out cubic-bezier(.65, 0, .35, 1)
--k-dur-3 320ms

React

Use the HTML below with kwark.css. The example shows the markup and styling. Supply any application behavior described on this page.

HTML and CSS

Works anywhere with kwark.css.

<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Exporting the screenplay</span><span>48 of 112 pages</span></div>
  <div class="kw-progress" role="progressbar" aria-valuenow="48" aria-valuemin="0" aria-valuemax="112" aria-valuetext="48 of 112 pages" aria-label="Exporting the screenplay"><span style="width:43%"></span></div>
</div>
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Importing Blank Pages</span><span>3 of 5 folders</span></div>
  <div class="kw-progress-segs" role="progressbar" aria-valuenow="3" aria-valuemin="0" aria-valuemax="5" aria-valuetext="3 of 5 folders, Screenplay at 60%, Schedule queued" aria-label="Importing Blank Pages"><span data-state="done"></span><span data-state="done"></span><span style="--kw-seg:60%"></span><span data-state="queued"></span><span></span></div>
</div>
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Checking the cloud copy</span><span>Usually a few seconds</span></div>
  <div class="kw-progress" data-state="working" role="progressbar" aria-label="Checking the cloud copy" aria-valuetext="Working"><span></span></div>
</div>
<div class="kw-upload" role="status">
  <div class="kw-upload__head"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3v12M17 8l-5-5-5 5M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/></svg><span>Importing project</span><button class="kw-icon-button" type="button" aria-label="Minimise import progress"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m18 15-6-6-6 6"/></svg></button></div>
  <div class="kw-progress" role="progressbar" aria-valuenow="64" aria-valuemin="0" aria-valuemax="100" aria-label="Importing Blank Pages: 64%"><span style="width:64%"></span></div>
  <ul class="kw-upload__list">
    <li data-state="done"><span>Characters</span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.8 10A10 10 0 1 1 17 3.3"/><path d="m9 11 3 3L22 4"/></svg></li>
    <li data-state="done"><span>Outline</span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.8 10A10 10 0 1 1 17 3.3"/><path d="m9 11 3 3L22 4"/></svg></li>
    <li data-state="uploading"><span>Screenplay</span><b>60%</b><div class="kw-progress"><span style="width:60%"></span></div></li>
    <li data-state="queued"><span>Breakdown</span><b>Queued</b></li>
    <li data-state="pending"><span>Schedule</span><b>–</b></li>
  </ul>
  <div class="kw-upload__foot">2/5 folders · syncing Screenplay</div>
</div>
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Saved on this device</span><span>Cloud sync queued</span></div>
  <div class="kw-progress" data-state="queued" role="progressbar" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100" aria-label="Import saved on this device, cloud sync queued"><span style="width:100%"></span></div>
</div>

The import toast in the app is components/ui/UploadProgressToast.tsx: a 2px overall bar (h-0.5), a folder list where each folder shows a dash while pending, a percentage while uploading (with its own 2px bar), Queued when the cloud part is waiting, and a tick when done; and a foot that reads 2/5 folders · syncing Screenplay. The segmented bar and the indeterminate bar on this page are Ready for Kwark additions on the same 2px language.

ARIA

  • role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax, and aria-valuetext in the same words as the label: 48 of 112 pages.
  • The working bar has no value; its aria-valuetext is Working.
  • The toast is role="status". Announce the start and the end, and at most every 25%, never every percent.

Keyboard

  • The minimise button is reachable and named; the toast never takes focus on its own.
  • When an import finishes with failures, the foot says how many and how to retry (1 failed. Reopen import to retry.), and that text is announced.

Rules

  • Must give progress in figures as well as a bar: “48 of 112 pages”, “2/5 folders”.
  • Never block the screenplay with progress; run it in a toast while people keep working.
  • Must show “saved on this device, cloud sync queued” in the warn colour with words, never as an error.
  • Never show progress for work under a second, and announce at most every quarter.
  • Always end with what happened and the next step (“Screenplay exported · Open”).

AI readiness test

Task. Show progress while 112 pages export to PDF.

Give the agent. This page, Print and export, Toast.

Constraint. The writer keeps typing; the export may finish offline.

A reliable answer

  • Non-blocking toast with “Exporting the screenplay · 48 of 112 pages”
  • aria-valuetext in the same words
  • Announces at most every 25%
  • Ends with “Screenplay exported” and Open
  • Not a full-screen spinner

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

Open .mdllms.txt
Loading…