Skip to content
design
Components

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.

A useful update connects what changed, what we learned and the next decision. Give the reader one clear point to remember.
Example changes
18
Across the illustrative reporting week
Reviews
7
Example completed reviews
Next decisions
3
Questions to resolve before publication
  1. Collect
  2. Validate
  3. Review
  4. Publish

Decision record · Example 03

Start with a focused pilot

Proposed

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

  1. Complete

    Evidence gathered

    Source records are attached to the draft.

  2. In review

    Review the story

    Check the conclusion against the evidence and resolve open questions.

  3. After reviewPlanned

    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 progress

    Agree what the pilot must establish before wider access.

    Owner
    Example product team
    Due
    16 October 2026
  • Prepare the pilot invitation

    Waiting

    Depends on the distribution decision.

    Owner
    Unassigned
    Due
    After approval
  • Attach source records

    Complete
    Owner
    Example engineering team
    Due
    12 October 2026
A report on a large display: publication context across the header, a metric strip, then decisions, milestones and actions side by side. Use Desktop preview for a dedicated display.
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>
  );
}
01Evidence beside the claimValues include their unit, reporting window and source context. Missing observations stay explicit.
02Structure with purposeFacts, comparisons and processes use the smallest block that explains their relationship.
03One shared implementationThe reports site and this guide import the same Bosunkit components, typography and spacing.

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.

A useful update connects what changed, what we learned and the next decision. Give the reader one clear point to remember.
Example changes
18
Across the illustrative reporting week
Reviews
7
Example completed reviews
Next decisions
3
Questions to resolve before publication
  1. Collect
  2. Validate
  3. Review
  4. Publish
An illustrative weekly digest. Values describe this example, not measured Bosun results.
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.

  1. 01
    Find the signal

    Collect source material and identify the important change.

  2. 02
    Tell the story

    Connect the result to its consequence for the reader.

  3. 03
    Invite 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.
Illustrative editorial principleExample copy, not a customer testimonial

Example boundary

This composition demonstrates presentation. Its wording and values are illustrative.
An illustrative editorial composition: two perspectives, a short plan and an attributed pull quote.
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

Proposed

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

  1. Complete

    Evidence gathered

    Source records are attached to the draft.

  2. In review

    Review the story

    Check the conclusion against the evidence and resolve open questions.

  3. After reviewPlanned

    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 progress

    Agree what the pilot must establish before wider access.

    Owner
    Example product team
    Due
    16 October 2026
  • Prepare the pilot invitation

    Waiting

    Depends on the distribution decision.

    Owner
    Unassigned
    Due
    After approval
  • Attach source records

    Complete
    Owner
    Example engineering team
    Due
    12 October 2026
An illustrative release review connects a proposal, its checkpoints and the work still to do.
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 questionBlockInclude
What choice needs attention?ReportDecisionProposal or agreed choice, rationale, tradeoff, decision owner
What happened, and what comes next?ReportMilestonesDated checkpoints, current phase, dependencies for planned work
Who does what next?ReportActionsConcrete 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

Proposed

Keep the pilot small while reviewers confirm the evidence. Wider feedback waits for that decision.

Owner
Example review team

Example review checkpoints

  1. Draft phaseComplete

    Collect the evidence

  2. Review phaseIn review

    Resolve open questions

  3. After approvalPlanned

    Share the result

Example follow-up

  • Confirm distribution

    Open

    Agree 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.

Measurement boundary

The example describes the stated workload only. It does not establish performance on a different device.

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.

  1. Collect
  2. Validate
  3. Review
  4. Publish
  1. 1
    Collect

    Record the source and reporting window.

  2. 2
    Validate

    Check claims and comparable measurements.

  3. 3
    Review

    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 UTC
Documentation

Illustrative commit subject; replace with a real source record.

Props

PropTypeDefaultDescription
titlerequiredstring–The decision or question, phrased as a short heading.
statusrequiredstring–Explicit editorial state, such as Proposed or Agreed; never inferred from color.
eyebrowstring–Optional decision identifier or review context.
childrenrequiredReactNode–Rationale, alternatives, consequences and evidence.
detailsreadonly DescriptionListItem[]–Optional owner, review date or source, with caller-supplied labels.
accentReportAccent"03"Categorical emphasis with no success/failure meaning.
PropTypeDefaultDescription
titlerequiredstring–Visible heading and accessible name for this timeline.
itemsrequiredreadonly ReportMilestone[]–Checkpoints in chronological order. Planned dates remain visibly planned.
PropTypeDefaultDescription
titlerequiredstring–Visible heading and accessible name for the action list.
ownerLabelrequiredstring–Localized label for responsibility.
dueLabelrequiredstring–Localized label for the deadline.
itemsrequiredreadonly ReportAction[]–Actions as recorded at the report's publication time.
PropTypeDefaultDescription
titlerequiredstring–A short conclusion, outcome or question that anchors a report.
eyebrowstring–Optional context above the title, such as a reporting period.
childrenrequiredReactNode–Supporting explanation, evidence or next action.
iconReactNode–Optional decorative icon.
accentReportAccent"accent"Theme-aware editorial accent; defaults to the brand accent.
PropTypeDefaultDescription
childrenrequiredReactNode–Exact sourced words. Label fictional examples explicitly in surrounding prose.
attributionrequiredstring–Person, team or document credited for the quotation.
contextstring–Optional role, date or source context.
citestring–Optional verified source URL.
accentReportAccent"03"Theme-aware editorial accent.
PropTypeDefaultDescription
itemsrequiredreadonly DescriptionListItem[]–Named facts with caller-formatted values, hints and optional icons.
titlestring–Visible heading and accessible name for this group.
PropTypeDefaultDescription
itemsrequiredreadonly ReportMetric[]–Evidence-backed values, including units and reporting scope.
PropTypeDefaultDescription
childrenrequiredReactNode–Related panels or figures.
columns2 | 3 | 42Preferred column count; the grid wraps to fit its available width.
PropTypeDefaultDescription
iconReactNode–Optional decorative heading icon.
accentReportAccent–Optional editorial accent; omission keeps a neutral panel.
childrenrequiredReactNode–Explanation and supporting evidence.
titlestring–Optional panel heading.
PropTypeDefaultDescription
childrenrequiredReactNode–Limitation, assumption or interpretation.
titlerequiredstring–Short heading identifying the note.
PropTypeDefaultDescription
itemsrequiredreadonly ReportStep[]–Ordered stages with optional explanations.
PropTypeDefaultDescription
stepsrequiredreadonly string[]–A short linear process. Use Mermaid for branches and cycles.
PropTypeDefaultDescription
hashrequiredstring–Source revision, shortened by the caller when appropriate.
subjectrequiredstring–Complete commit subject.
timestring–Display time including timezone.
categorystring–Caller-supplied category label.
hrefstring–Verified destination of the source revision. Omit for plain text.
Do
Latency
Not measured
No timing run supplied
Keep a missing measurement explicit.
Don't

A zero without a measurement suggests a result that does not exist.

Do not substitute a reassuring number for missing evidence.