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 · 4.0.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@4.0.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@4.0.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
Progress progress
A native progress element with a label and value; determinate fills with the primary colour, indeterminate shows static 45° stripes, never an animation.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
track.bg | color.interaction.pressed.bgobserveduse | #420f0c | Pressed fill. |
track.border | color.border.controlapproveduse | #c81a1a | D-041 owner correction: red control and floating-frame borders, distinct from rose text. |
value.bg | color.action.primary.bgapproveduse | #7d1310 | Primary button fill; D-026 darkened it off color12, which stays fixed as heritage ANSI 12. |
value.bg-error | color.status.danger.fillobserveduse | #dc282e | Danger fill. |
stripe.a | color.action.primary.bgapproveduse | #7d1310 | Primary button fill; D-026 darkened it off color12, which stays fixed as heritage ANSI 12. |
stripe.b | color.interaction.pressed.bgobserveduse | #420f0c | Pressed fill. |
label.text | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
value.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
detail.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
error.text | color.status.danger.textobserveduse | #f07178 | D-041 readable error text on neutral surfaces and native warning tints. |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Determinate | Indeterminate | With detail line |
|---|---|---|---|
default |
62%
|
14 of 67
Writing exports/components/date-picker.json | |
busy | |||
error | |||
reduced-motion |
Purpose
Shows how far a known task has gone, or that an unbounded one is running. It reports; it never blocks. A cancellable task has a button beside the bar. A short wait with no bar is the loading indicator.
Anatomy
Parts as listed in the anatomy.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | color.action.primary.bg fill on the track; the value text | the native value; the percentage text |
| busy | static 45° stripes of color.action.primary.bg on color.interaction.pressed.bg across the track; no value text | aria-busy; aria-valuetext; the stripe pattern; no animation |
| error | fill → color.status.danger.fill; the label gains ✕ 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; a cancel button beside the bar has its own tab stop.
Accessibility
The value is in the native value and repeated in text. Indeterminate bars
set aria-valuetext (“Preparing”); the container sets aria-busy for the
duration. Completion and failure are announced through a polite live region,
not by the bar. Text meets 4.5:1; the track boundary and error fill 3:1. The
primary fill against the track is waived because the value is stated in
text.
Portability
A toolkit with a native bar maps the fill to the primary colour and disables pulse animation; one without gradients draws the stripes with a hatched brush or alternating characters.
Non-examples
A spinner. Animated or barber-pole stripes. A shimmering skeleton instead of a bar. A circular ring. A rounded pill bar. Colour-only failure without the glyph and text. A bar with no label. A bar that blocks input.
Contrast report
9 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 1 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| progress default text | default | text | color.text.default #e99499 | color.surface.canvas #000000 | 9.16 | 4.5 | pass |
| progress default border | default | ui | color.border.control #c81a1a | color.surface.canvas #000000 | 3.62 | 3 | pass |
| progress error text | error | text | color.status.danger.text #f07178 | color.surface.canvas #000000 | 7.34 | 4.5 | pass |
| progress error border | error | ui | color.status.danger.border #e53935 | color.surface.canvas #000000 | 4.97 | 3 | pass |
| label on the canvas | — | text | color.text.bright #ffa2a7 | color.surface.canvas #000000 | 10.98 | 4.5 | pass |
| detail line on the canvas | — | text | color.text.muted #d4868b | color.surface.canvas #000000 | 7.58 | 4.5 | pass |
| value fill against the track | — | ui | color.action.primary.bg #7d1310 | color.interaction.pressed.bg #420f0c | 1.51 | 3 | waived: the fill falls below the floor against the track; the value is carried by the visible percentage text and the native value, and the track boundary (border.control) marks the full extent |
| stripes (decorative pattern) | busy | ui | color.action.primary.bg #7d1310 | color.interaction.pressed.bg #420f0c | 1.51 | 1 | pass |
| error fill against the track | error | ui | color.status.danger.fill #dc282e | color.interaction.pressed.bg #420f0c | 3.36 | 3 | pass |
Keys
| Key | Action |
|---|---|
| Tab | Nothing; progress is not focusable and never traps a person. |
| Escape | Nothing; cancelling is a separate button next to the bar. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: loading-indicator file-input wizard toast
Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-STATE-MATRIX