J3W1 / DESIGN SYSTEM
Progress
A native progress element with a label and value; determinate fills with the primary colour, indeterminate shows static 45° stripes, never an animation.
stable · LIGHT DOM · 1.1.0
Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
determinate
<j3w1-progress id="example-progress-determinate"><div class="progress">
<div class="progress-header">
<label class="progress-label" for="example-progress-determinate-pg-upload">Uploading theme.json<span class="progress-error-glyph" aria-hidden="true"> ✕</span></label>
<span class="progress-value">62%</span>
</div>
<progress class="progress-bar" id="example-progress-determinate-pg-upload" max="100" value="62">62%</progress>
</div></j3w1-progress>indeterminate
<j3w1-progress id="example-progress-indeterminate"><div class="progress">
<div class="progress-header">
<label class="progress-label" for="example-progress-indeterminate-pg-scan">Scanning fonts<span class="progress-error-glyph" aria-hidden="true"> ✕</span></label>
</div>
<progress class="progress-bar" id="example-progress-indeterminate-pg-scan" aria-valuetext="In progress, total unknown">In progress</progress>
</div></j3w1-progress>with-label
Writing exports/components/date-picker.json
<j3w1-progress id="example-progress-with-label"><div class="progress">
<div class="progress-header">
<label class="progress-label" for="example-progress-with-label-pg-export">Exporting components<span class="progress-error-glyph" aria-hidden="true"> ✕</span></label>
<span class="progress-value">14 of 67</span>
</div>
<progress class="progress-bar" id="example-progress-with-label-pg-export" max="67" value="14">14 of 67</progress>
<p class="progress-detail">Writing exports/components/date-picker.json</p>
</div></j3w1-progress>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@1.1.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/progress.css';
import '@j3w1/ui/register/progress';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@1.1.0 j3w1-ui copy progress --out ./vendor/j3w1/progressThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
events
| Name | Type / signature | Meaning |
|---|
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Purpose
Shows how far a known task has gone, or that an unbounded one is running. It reports; it never blocks. A task that can be cancelled has a button beside the bar. A short wait with no bar is the loading indicator.
Anatomy
The header row with the label in color.text.bright and the value in
color.text.default; the bar, a native progress element whose track is
color.interaction.pressed.bg behind a 1px color.border.control and whose
fill is color.action.primary.bg; an optional detail line in
color.text.muted.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | fill color.action.primary.bg on the track; the value text | the native value; the percentage text |
| busy | the whole track shows static 45° stripes of color.action.primary.bg on color.interaction.pressed.bg; no value text | aria-busy; aria-valuetext; the stripe pattern; no animation |
| error | fill → color.status.danger.fill; the label gains the ✕ glyph in color.status.danger.text; the detail line says what failed | glyph; worded detail |
| reduced-motion | identical to default and busy: nothing animates in any state | prefers-reduced-motion |
Indeterminate work is the busy state; the determinate variant enters it while the total is unknown and leaves it once known.
Keyboard
None. The progress element is not focusable and receives no key. A cancel button next to the bar is an ordinary button with its own tab stop.
Accessibility
The label is a real <label for> on the progress element, so its name is
programmatic; the value is in the native value and repeated in text.
Indeterminate bars set aria-valuetext (“Preparing”), and the container sets
aria-busy for the duration. Completion and failure are announced through a
polite live region, not by the bar. Contrast: label 10.37:1, value 8.65:1,
detail 5.81:1, track boundary 4.45:1, error fill 3.36:1 against the track.
The primary fill against the track measures 1.51:1 and is waived because the
value is stated in text; a host that must meet 3:1 graphically raises the
track to color.surface.canvas.
Portability
A track, a fill and a hatched pattern. Toolkits with a native bar map the fill to the primary colour and disable pulse animation; toolkits without gradients draw the stripes with a hatched brush or alternating characters.
Non-examples
A spinner. Animated or “barber-pole” stripes. A shimmering skeleton in place of a bar. A circular ring. A rounded pill-shaped bar. Colour-only failure without the glyph and text. A bar with no label. A bar that blocks input.