Report blocks
Compose evidence-backed reports with facts, metrics, decisions, milestones, actions and supporting evidence.
On this page
From evidence to a clear decision
An illustrative engineering review: source context, current progress and proposed next steps in one report.
Engineering digest · illustrative
Small steps. Clear progress.
- Example changes
- 18
- Across the illustrative reporting week
- Reviews
- 7
- Example completed reviews
- Next decisions
- 3
- Questions to resolve before publication
- 1Collect
- 2Validate
- 3Review
- 4Publish
Decision record · Example 03
Start with a focused pilot
Invite a small review group to try the report workflow before expanding access.
Tradeoff: feedback arrives sooner, while broader distribution waits for the review.
- Decision owner
- Example product team
- Review
- 16 October 2026
From first draft to shared result
Evidence gathered
Source records are attached to the draft.
Review the story
Check the conclusion against the evidence and resolve open questions.
Invite the pilot group
Timing depends on the review decision; no release date is confirmed.
Make the next step concrete
Confirm the review criteria
In progressAgree what the pilot must establish before wider access.
- Owner
- Example product team
- Due
- 16 October 2026
Prepare the pilot invitation
WaitingDepends on the distribution decision.
- Owner
- Unassigned
- Due
- After approval
Attach source records
Complete- Owner
- Example engineering team
- Due
- 12 October 2026
Code
import type { ReactElement } from "react";
import { Heading } from "@bosunkit/components/heading";
import { Text } from "@bosunkit/components/text";
import { Stack } from "@bosunkit/components/stack";
import PublicationDetails from "../report-metadata/showcase";
import ReportSummary from "./showcase";
import ReportPlanning from "./planning";
export const description: string =
"A desktop report canvas: full-width publication context, a metric strip, and three columns for decisions, milestones and next actions. All content is illustrative.";
export default function DesktopReport(): ReactElement {
return (
<div style={{ width: "100%" }}>
<div style={{ maxWidth: "var(--bk-report-width)" }}>
<Stack as="header" space="sm">
<Heading level={2} variant="heading-page">
From evidence to a clear decision
</Heading>
<Text variant="body-reading" color="text-dim">
An illustrative engineering review: source context, current progress and proposed next steps in one report.
</Text>
</Stack>
</div>
<PublicationDetails />
<ReportSummary />
<ReportPlanning />
</div>
);
}
All examples are illustrative. Supply verified display strings in real reports. These components are registered
in the MDX runtime of both documentation sites. React consumers import them from @bosunkit/components/report-blocks.
Designed for larger displays
The opening example fits the documentation column. Its Desktop preview uses a larger report canvas. Metadata spans the header; the metric strip allows comparison at a glance; decisions, milestones and actions share a three-column grid. Use the Desktop preview control above the example to inspect laptop and monitor sizes without the documentation navigation.
Use the extra width for related evidence and parallel workstreams. Keep narrative paragraphs within a reading measure; a wider display does not require larger text. Narrow layouts are a fallback: blocks stack in reading order and retain their labels, evidence and status.
Highlights and editorial accents
Engineering digest · illustrative
Small steps. Clear progress.
- Example changes
- 18
- Across the illustrative reporting week
- Reviews
- 7
- Example completed reviews
- Next decisions
- 3
- Questions to resolve before publication
- 1Collect
- 2Validate
- 3Review
- 4Publish
Code
import type { ReactElement } from "react";
import { FileCheck, GitCommitHorizontal, Rocket, Workflow } from "lucide-react";
import { ReportHighlight, ReportMetrics, ReportPipeline } from "@bosunkit/components/report-blocks";
export const description: string =
"An illustrative weekly digest. Values describe this example, not measured Bosun results.";
export default function ReportSummary(): ReactElement {
return (
<div>
<ReportHighlight
eyebrow="Engineering digest · illustrative"
title="Small steps. Clear progress."
icon={<Rocket />}
accent="02"
>
A useful update connects what changed, what we learned and the next decision. Give the reader one clear point to
remember.
</ReportHighlight>
<ReportMetrics
items={[
{
label: "Example changes",
value: "18",
note: "Across the illustrative reporting week",
icon: <GitCommitHorizontal />,
accent: "02",
},
{ label: "Reviews", value: "7", note: "Example completed reviews", icon: <FileCheck />, accent: "01" },
{
label: "Next decisions",
value: "3",
note: "Questions to resolve before publication",
icon: <Workflow />,
accent: "03",
},
]}
/>
<ReportPipeline steps={["Collect", "Validate", "Review", "Publish"]} />
</div>
);
}
ReportHighlight gives a conclusion, milestone or question a focal place. An optional eyebrow supplies context,
and a decorative icon makes the block easier to recognize. Keep the document’s title in the page header.
<ReportHighlight eyebrow="Review outcome" title="Ready for the next decision" accent="02">
State the supported conclusion and the evidence needed for the next step.
</ReportHighlight>Use accent for brand emphasis or categorical palette slots 01 through 09. Slots match the chart palette,
with hues chosen by each theme; they carry no alert priority or success/failure meaning. Metric cards and process steps
cycle through that palette by default. Set each item’s accent to keep a category consistent across a report.
Labels, values and explanations remain readable text in every theme.
Tell a report’s story
What we learned
Readers need the conclusion and the evidence in the same place. Make the connection explicit.
What we’ll explore
Keep open questions visible. Describe the next experiment and the decision it will support.
- 01Find the signal
Collect source material and identify the important change.
- 02Tell the story
Connect the result to its consequence for the reader.
- 03Invite a decision
End with one useful question or a concrete next step.
Make the important part easy to find, and the evidence easy to follow.
Code
import type { ReactElement } from "react";
import { BookOpen, FlaskConical, Search, Send } from "lucide-react";
import { ReportGrid, ReportPanel, ReportQuote, ReportSteps, ReportNote } from "@bosunkit/components/report-blocks";
export const description: string =
"An illustrative editorial composition: two perspectives, a short plan and an attributed pull quote.";
export default function ReportStory(): ReactElement {
return (
<div>
<ReportGrid>
<ReportPanel title="What we learned" icon={<BookOpen />} accent="01">
<p>Readers need the conclusion and the evidence in the same place. Make the connection explicit.</p>
</ReportPanel>
<ReportPanel title="What we’ll explore" icon={<FlaskConical />} accent="03">
<p>Keep open questions visible. Describe the next experiment and the decision it will support.</p>
</ReportPanel>
</ReportGrid>
<ReportSteps
items={[
{
label: "01",
title: "Find the signal",
description: "Collect source material and identify the important change.",
icon: <Search />,
accent: "02",
},
{
label: "02",
title: "Tell the story",
description: "Connect the result to its consequence for the reader.",
icon: <BookOpen />,
accent: "01",
},
{
label: "03",
title: "Invite a decision",
description: "End with one useful question or a concrete next step.",
icon: <Send />,
accent: "03",
},
]}
/>
<ReportQuote
attribution="Illustrative editorial principle"
context="Example copy, not a customer testimonial"
accent="05"
>
Make the important part easy to find, and the evidence easy to follow.
</ReportQuote>
<ReportNote title="Example boundary">
This composition demonstrates presentation. Its wording and values are illustrative.
</ReportNote>
</div>
);
}
ReportPanel accepts an icon and an optional accent for related perspectives. ReportQuote gives a sourced
observation space to breathe, with visible attribution, optional context and a verified cite URL. Label
fictional example quotes explicitly; never present illustrative copy as customer evidence.
<ReportQuote attribution="Source document" context="Review notes" cite="/docs/source">
Copy the exact, verified words from the cited source.
</ReportQuote>Decisions, milestones and follow-through
Decision record · Example 03
Start with a focused pilot
Invite a small review group to try the report workflow before expanding access.
Tradeoff: feedback arrives sooner, while broader distribution waits for the review.
- Decision owner
- Example product team
- Review
- 16 October 2026
From first draft to shared result
Evidence gathered
Source records are attached to the draft.
Review the story
Check the conclusion against the evidence and resolve open questions.
Invite the pilot group
Timing depends on the review decision; no release date is confirmed.
Make the next step concrete
Confirm the review criteria
In progressAgree what the pilot must establish before wider access.
- Owner
- Example product team
- Due
- 16 October 2026
Prepare the pilot invitation
WaitingDepends on the distribution decision.
- Owner
- Unassigned
- Due
- After approval
Attach source records
Complete- Owner
- Example engineering team
- Due
- 12 October 2026
Code
import type { ReactElement } from "react";
import { ReportActions, ReportDecision, ReportMilestones, ReportGrid } from "@bosunkit/components/report-blocks";
export const description: string =
"An illustrative release review connects a proposal, its checkpoints and the work still to do.";
export default function ReportPlanning(): ReactElement {
return (
<ReportGrid columns={3}>
<ReportDecision
title="Start with a focused pilot"
eyebrow="Decision record · Example 03"
status="Proposed"
accent="03"
details={[
{ term: "Decision owner", value: "Example product team" },
{ term: "Review", value: "16 October 2026" },
]}
>
<p>Invite a small review group to try the report workflow before expanding access.</p>
<p>
<strong>Tradeoff:</strong> feedback arrives sooner, while broader distribution waits for the review.
</p>
</ReportDecision>
<ReportMilestones
title="From first draft to shared result"
items={[
{
label: "12 October",
dateTime: "2026-10-12",
title: "Evidence gathered",
status: "Complete",
state: "complete",
description: "Source records are attached to the draft.",
},
{
label: "14 October",
dateTime: "2026-10-14",
title: "Review the story",
status: "In review",
state: "current",
description: "Check the conclusion against the evidence and resolve open questions.",
},
{
label: "After review",
title: "Invite the pilot group",
status: "Planned",
description: "Timing depends on the review decision; no release date is confirmed.",
},
]}
/>
<ReportActions
title="Make the next step concrete"
ownerLabel="Owner"
dueLabel="Due"
items={[
{
title: "Confirm the review criteria",
owner: "Example product team",
due: "16 October 2026",
status: "In progress",
state: "current",
description: "Agree what the pilot must establish before wider access.",
},
{
title: "Prepare the pilot invitation",
owner: "Unassigned",
due: "After approval",
status: "Waiting",
description: "Depends on the distribution decision.",
},
{
title: "Attach source records",
owner: "Example engineering team",
due: "12 October 2026",
status: "Complete",
state: "complete",
},
]}
/>
</ReportGrid>
);
}
ReportDecision records a choice with its explicit status, rationale and consequences. Use details for the
decision owner, review date and source. A “Proposed” card asks for a decision; it is not evidence of approval.
ReportMilestones connects dated outcomes or named phases. Completed checkpoints use a check mark, the current
checkpoint uses a distinct circular mark, and upcoming checkpoints have an open mark and dashed connector.
Every checkpoint also has a visible status. Keep at most one item current, and distinguish planned dates from
observed completion dates. Use dateTime only when the label represents a date, not “After review”.
ReportActions captures ownership, due dates and workflow status at publication time. These rows are read-only;
they do not pretend to be task checkboxes. Supply a verified href to link an action to its tracking record.
Unassigned owners, unknown deadlines and dependencies remain explicit. Completed work keeps its title readable.
| Reader’s question | Block | Include |
|---|---|---|
| What choice needs attention? | ReportDecision | Proposal or agreed choice, rationale, tradeoff, decision owner |
| What happened, and what comes next? | ReportMilestones | Dated checkpoints, current phase, dependencies for planned work |
| Who does what next? | ReportActions | Concrete action, owner, due date, status, source task when available |
Native MDX example
The following composition is also illustrative. Static props stay readable in search and copied Markdown.
Review before wider distribution
Keep the pilot small while reviewers confirm the evidence. Wider feedback waits for that decision.
- Owner
- Example review team
Example review checkpoints
Collect the evidence
Resolve open questions
Share the result
Example follow-up
Confirm distribution
OpenAgree the intended audience and record the decision.
- Owner
- Example review team
- Due
- Before publication
<ReportDecision title="A supported choice" status="Proposed">
Explain the rationale, alternatives and tradeoff.
</ReportDecision>
<ReportMilestones title="Checkpoints" items={[
{label: 'After review', title: 'Share the result', status: 'Planned'},
]} />
<ReportActions title="Next actions" ownerLabel="Owner" dueLabel="Due" items={[
{title: 'Confirm distribution', owner: 'Unassigned', due: 'Not agreed', status: 'Open'},
]} />Facts and capability records
Use ReportFacts for named facts such as scope, package, artifact, workload or source revision. Report metadata
already supplies audience, date, updated date, category, distribution and editorial status; do not repeat those fields.
Capability record
- Scope
- Offline document indexing
- Artifact
- example-index.dbIllustrative artifact name
- Verification
- State the source revision and checks
<ReportFacts title="Scope" items={[{term: 'Artifact', value: 'example-index.db'}]} />Metric strips
Use ReportMetrics for a short group of values. A value includes its unit. The note states its period, baseline
or uncertainty. An optional item icon is decorative; accent picks its theme-aware card color. Keep missing measurements explicit; leave them as “Not measured” rather than substituting zero.
- Example changes
- 18
- Illustrative reporting day
- Example checks
- 7
- A count, not evidence of completeness
- Latency
- Not measured
- No timing result supplied
<ReportMetrics items={[{label: 'Latency', value: 'Not measured', note: 'No timing result supplied'}]} />Panels and comparisons
ReportPanel groups a conclusion and its evidence using the shared Card. ReportGrid aligns related panels
and collapses them when the content area narrows. Keep the same questions and measurement basis on both sides.
Baseline
Explain the existing behavior and its measured limitations. Link the baseline revision.
Candidate
Explain the changed behavior under the same conditions. State remaining uncertainty.
<ReportGrid>
<ReportPanel title="Baseline">Comparable source evidence.</ReportPanel>
<ReportPanel title="Candidate">Comparable candidate evidence.</ReportPanel>
</ReportGrid>Notes and limitations
Use ReportNote for a bounded limitation, scope condition or interpretation the reader needs near the result.
It uses the shared SectionMessage. A report note is not a vessel alert and does not use alert priority colors.
Pipelines and process steps
ReportPipeline shows a short, ordered chain. Use ReportSteps when a stage needs an explanation. Use Mermaid
when there are branches, loops, sequence interactions or relationships that cannot be expressed as a linear process.
- 1Collect
- 2Validate
- 3Review
- 4Publish
- 1Collect
Record the source and reporting window.
- 2Validate
Check claims and comparable measurements.
- 3Review
Resolve distribution and known limitations.
<ReportPipeline steps={['Collect', 'Validate', 'Review']} />
<ReportSteps items={[{title: 'Collect', description: 'Record the source.'}]} />Commit records
ReportCommit keeps the source identifier, timestamp, category and subject aligned. Pass a verified href to make
the hash navigable; a source without a link remains plain text. Include the timezone in the timestamp.
example14:30 UTCIllustrative commit subject; replace with a real source record.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| titlerequired | string | – | The decision or question, phrased as a short heading. |
| statusrequired | string | – | Explicit editorial state, such as Proposed or Agreed; never inferred from color. |
| eyebrow | string | – | Optional decision identifier or review context. |
| childrenrequired | ReactNode | – | Rationale, alternatives, consequences and evidence. |
| details | readonly DescriptionListItem[] | – | Optional owner, review date or source, with caller-supplied labels. |
| accent | ReportAccent | "03" | Categorical emphasis with no success/failure meaning. |
| Prop | Type | Default | Description |
|---|---|---|---|
| titlerequired | string | – | Visible heading and accessible name for this timeline. |
| itemsrequired | readonly ReportMilestone[] | – | Checkpoints in chronological order. Planned dates remain visibly planned. |
| Prop | Type | Default | Description |
|---|---|---|---|
| titlerequired | string | – | Visible heading and accessible name for the action list. |
| ownerLabelrequired | string | – | Localized label for responsibility. |
| dueLabelrequired | string | – | Localized label for the deadline. |
| itemsrequired | readonly ReportAction[] | – | Actions as recorded at the report's publication time. |
| Prop | Type | Default | Description |
|---|---|---|---|
| titlerequired | string | – | A short conclusion, outcome or question that anchors a report. |
| eyebrow | string | – | Optional context above the title, such as a reporting period. |
| childrenrequired | ReactNode | – | Supporting explanation, evidence or next action. |
| icon | ReactNode | – | Optional decorative icon. |
| accent | ReportAccent | "accent" | Theme-aware editorial accent; defaults to the brand accent. |
| Prop | Type | Default | Description |
|---|---|---|---|
| childrenrequired | ReactNode | – | Exact sourced words. Label fictional examples explicitly in surrounding prose. |
| attributionrequired | string | – | Person, team or document credited for the quotation. |
| context | string | – | Optional role, date or source context. |
| cite | string | – | Optional verified source URL. |
| accent | ReportAccent | "03" | Theme-aware editorial accent. |
| Prop | Type | Default | Description |
|---|---|---|---|
| itemsrequired | readonly DescriptionListItem[] | – | Named facts with caller-formatted values, hints and optional icons. |
| title | string | – | Visible heading and accessible name for this group. |
| Prop | Type | Default | Description |
|---|---|---|---|
| itemsrequired | readonly ReportMetric[] | – | Evidence-backed values, including units and reporting scope. |
| Prop | Type | Default | Description |
|---|---|---|---|
| childrenrequired | ReactNode | – | Related panels or figures. |
| columns | 2 | 3 | 4 | 2 | Preferred column count; the grid wraps to fit its available width. |
| Prop | Type | Default | Description |
|---|---|---|---|
| icon | ReactNode | – | Optional decorative heading icon. |
| accent | ReportAccent | – | Optional editorial accent; omission keeps a neutral panel. |
| childrenrequired | ReactNode | – | Explanation and supporting evidence. |
| title | string | – | Optional panel heading. |
| Prop | Type | Default | Description |
|---|---|---|---|
| childrenrequired | ReactNode | – | Limitation, assumption or interpretation. |
| titlerequired | string | – | Short heading identifying the note. |
| Prop | Type | Default | Description |
|---|---|---|---|
| itemsrequired | readonly ReportStep[] | – | Ordered stages with optional explanations. |
| Prop | Type | Default | Description |
|---|---|---|---|
| stepsrequired | readonly string[] | – | A short linear process. Use Mermaid for branches and cycles. |
| Prop | Type | Default | Description |
|---|---|---|---|
| hashrequired | string | – | Source revision, shortened by the caller when appropriate. |
| subjectrequired | string | – | Complete commit subject. |
| time | string | – | Display time including timezone. |
| category | string | – | Caller-supplied category label. |
| href | string | – | Verified destination of the source revision. Omit for plain text. |
- Latency
- Not measured
- No timing run supplied
A zero without a measurement suggests a result that does not exist.
Related
- Report metadata: audience, publication details and distribution intent.
- Report types: editorial structure and MDX starters.
- Mermaid: branches, loops and sequence diagrams.
- Report figure: captioned artwork and source access.