Kanban component

KanbanBoard is the optional Folio Docs canvas for a Folio Board, with filtering, staged drag-and-drop, and a progressive public workspace.

API

Example

<KanbanBoard compact maxCardsPerColumn={2} />

The standalone CLI reads the board configured by board.source in agents.yaml. The optional Folio Docs adapter reads kanban.source in docs.yaml. Folio’s own operational board lives on its independent board branch, so this release documentation shows the invocation without coupling the code release to that board’s update cycle.

Progressive workspace

Filters start collapsed and open from the filter button. On wide screens, the public board places the selected card beside the canvas and its artifact after the card. Below 1536px wide or 480px high, the card opens over the board at the full viewport height. Its header stays visible while the card body and the artifact reader each scroll inside their own frame; the page itself does not scroll. The board behind the card cannot scroll or receive focus. Escape closes the reader first, then the card, and returns focus to the opener. Resizing preserves the open artifact and its scroll position.

Each hairline between surfaces is a resizer. Drag it, use its arrow keys, or double-click it to restore the default. Closing the artifact returns to the card; closing the card also closes its artifact. Filters close independently. The URL carries ?card= and ?artifact=, and a readable artifact can enter and leave the browser’s native full-screen mode.

Open context is reading space, not a preview. The card starts at 760px in its active dimension and the artifact at 1040px wide or 900px high. Resizing cannot reduce the card below 440px wide or 420px high, nor the artifact below 560px wide or 480px high. These sizes apply to inline surfaces; the full-screen card fits the current viewport. The inline artifact continues below through 2559px, and larger viewports use all surfaces in one row.

Boards embedded inside documentation keep the modal card and artifact drawer.

Card tiles show completed/total acceptance criteria when criteria exist. This counter describes the checklist, not the card status; completing every criterion does not move the card. Cards without criteria show no counter.

Folio components in card descriptions

The published board page and the generated Docs board compile component-bearing descriptions with the site’s MDX component registry. Tabs, callouts, before/after comparisons, diagrams, and project components registered in docs.yaml render inside the selected card. Client components retain their interactions.

Write the component directly in the card body before its acceptance criteria, comments, or trail:

Track the behavior change and its evidence here.
 
## Before and after
 
<Tabs>
<TabItem label="Before">
 
The current implementation rewrites every output.
 
</TabItem>
<TabItem label="After">
 
Only affected outputs change. Measurements are still pending.
 
</TabItem>
</Tabs>
 
## Acceptance criteria
- [ ] record comparable measurements

Folio compiles these descriptions during the site build; the browser receives React content rather than evaluating Markdown or copying an HTML snapshot. The raw card remains readable by folio-agents board, which needs neither a Docs build nor Node to load or edit it. Ordinary descriptions retain their existing renderer. ./ links keep their card-relative artifact behavior.

Editing a local source board during folio-agents serve refreshes compiled descriptions. An open reader for a card-owned Markdown artifact also refreshes after its compiled page changes. The adapter derives a revision from the generated MDX, so the reader does not refetch during the earlier source-change notification. If that refresh fails, the reader retains the last successfully loaded body for the same artifact; an initial load failure keeps the existing error state. Changing a custom component’s registration still requires restarting the server. Invalid MDX reports a build error, as it does in an ordinary Folio page.

The public/generated board composes rich descriptions on the server; a manually embedded client KanbanBoard or a compact preview keeps the lightweight Markdown renderer. Rich descriptions contribute to the board’s initial page payload, so large report collections are better kept as attached documents.

Mermaid blocks in fetched documents render as interactive SVG diagrams inside the board reader.

Theming

Every structural node carries a data-slot attribute for styling. Additional attributes mark dynamic state.

The staging card appears on a static board only. A live board, one whose docs.yaml sets kanban.api, commits each move and edit through the board server instead; see Edit the board in the browser. Its slots:

The board page renders on pure white in light mode. Dark mode and every preset keep their own background.