<work-item>
General-purpose work unit card for tasks, bugs, chores, spikes, and features — the engineering sibling of user-story.
Overview
A web component for engineering work units — tasks, bugs, chores, spikes, and features. While <user-story> captures product needs in agile format, <work-item> represents the implementation work: what needs to be built, fixed, researched, or maintained. A single story may decompose into multiple work items, and some work items exist independently of any story.
Basic usage
<work-item item-id="PROJ-42" type="task" status="in-progress" priority="high" assignee="Sarah Chen" estimate="5" story-ids="PROJ-101,PROJ-102"> <h3 slot="title">Implement search API endpoint</h3> <p slot="description">Build the /api/search endpoint with filters and pagination.</p> <ul slot="checklist"> <li>Database schema design</li> <li>Endpoint implementation</li> <li>Integration tests</li> </ul></work-item>Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
item-id | string | — | Unique identifier (also sets HTML id for cross-referencing) |
type | string | "task" | task, bug, chore, spike, or feature |
priority | string | "medium" | critical, high, medium, or low |
status | string | "backlog" | backlog, to-do, in-progress, review, done, or blocked |
estimate | string | — | Effort estimate (points, hours, t-shirt size) |
assignee | string | — | Assignee name (shown with auto-generated avatar) |
story-ids | string | — | Comma-separated linked <user-story> IDs |
detail | string | "full" | full, compact, or minimal |
compact | boolean | — | Alias for detail="compact" |
src | string (URL) | — | Path to JSON data file |
Slots
| Slot | Expected Content | Description |
|---|---|---|
title | <h3> or text | Work item title displayed in the card header. |
description | <p> | Work item description. Shows in the body section. |
checklist | <ul> or <ol> | Subtasks or checklist items. |
notes | <p> | Additional notes, context, or links. |
Item Types
Each type gets a distinct icon and color badge in the header. Types are semantic — they help teams categorize work without requiring a separate labeling system.
| Type | Use Case |
|---|---|
task | Engineering implementation work (default) |
bug | Defect that needs fixing |
chore | Tech debt, maintenance, or operational work |
spike | Research, investigation, or proof-of-concept |
feature | New user-facing capability |
Cross-Referencing
Work items connect to the broader UX Planning system through two mechanisms:
story-ids— links outward to<user-story>elements via fragment anchors. Rendered as clickable chips in the card body.item-id— auto-set as the HTMLid, enabling inbound references from<gantt-chart>rows viadata-task-idmatching.
Linked work item in a kanban board
<kanban-board> <section data-column="in-progress" data-column-label="In Progress"> <work-item draggable="true" data-id="PROJ-42" item-id="PROJ-42" type="task" status="in-progress" story-ids="PROJ-101" detail="minimal"> <h3 slot="title">Implement search API</h3> </work-item> </section></kanban-board>Events
| Event | Detail | When |
|---|---|---|
work-item:ready | { itemId, title, type, priority, status } | After render |
work-item:status | { status, itemId } | When updateStatus() is called |
work-item:priority | { priority, itemId } | When updatePriority() is called |
work-item:data-changed | { data, source: 'property' } | After .data is assigned |
Property API (JS-first)
The whole work item — state attributes and slotted content — can be set in one assignment. Useful when a reactive framework or kanban-board owns the data.
| Property | Type | Description |
|---|---|---|
.data | { itemId?, type?, priority?, status?, estimate?, assignee?, storyIds?, detail?, title?, description?, checklist?, notes? } | Sets state attributes and creates slotted children for any text fields not already present. Idempotent. |
.data assignment
const wi = document.createElement('work-item');wi.data = { itemId: 'PROJ-42', type: 'task', priority: 'high', status: 'in-progress', assignee: 'Sam', estimate: 5, title: 'Wire OAuth flow', description: 'Add the /auth callback and refresh-token rotation.', checklist: ['Endpoint', 'Tests', 'Telemetry'],};document.body.appendChild(wi);Reading .data back returns the current shape — handy for persistence or logging. See the Data API concepts guide.
Events
| Event | Detail | When |
|---|---|---|
work-item:upgraded |
— | Once after first connect. Wait for this before assigning .data from a framework. |
work-item:data-changed |
{ data, source: 'property' } |
After .data assignment. |
Reactive consumer (e.g. Montane)
const wi = document.querySelector('work-item');await new Promise(r => wi.addEventListener('work-item:upgraded', r, { once: true }));wi.data = { itemId: 'PROJ-42', type: 'task', priority: 'high', title: 'Wire OAuth' };CSS Custom Properties
| Variable | Default | Description |
|---|---|---|
--work-item-bg | #ffffff | Card background |
--work-item-text | #1a1a1a | Primary text |
--work-item-border | #e0e0e0 | Card border |
--work-item-accent | #0066cc | Interactive color |
--work-item-card-bg | #f8f9fa | Header background |
Accessibility
- Card is an
<article>witharia-label - Type badge uses colored background for visual distinction (not color-only)
- Story links are real
<a>elements with fragment hrefs - Respects
prefers-reduced-motion: reduce - Print styles remove shadows for clean output
Related
<user-story>— Agile story cards that work items implement<kanban-board>— Track work items through status columns<gantt-chart>— Schedule work items on a timeline<impact-effort>— Prioritize work items on impact vs effort<review-surface>— Annotate work item designs with review pins- UX Planning Pack — Loads all UX planning components together