Flow Diagram

Steps and decisions joined by arrows, with the path taken lit.

How a refund request is handled
  1. AgentRead the ticketNext: Order found?
  2. Order found?Next: Inside 30 days? (Yes), Ask for the order number (No)
  3. Inside 30 days?Next: Draft a refund (Yes), Offer store credit (No)
  4. AgentAsk for the order numberNext: Read the ticket (Reply)
  5. AgentDraft a refundNext: Approve the reply
  6. AgentOffer store creditNext: Approve the reply
  7. YouApprove the replyNothing is sent before this.Next: Send
  8. AgentSend
'use client';

import { useState } from 'react';
import { Button, FlowDiagram } from '@brand-studio/ui';
import type { FlowEdge, FlowNode } from '@brand-studio/ui';

const nodes: FlowNode[] = [
  { id: 'read', label: 'Read the ticket', tag: 'Agent' },
  { id: 'found', label: 'Order found?', kind: 'decision' },
  { id: 'window', label: 'Inside 30 days?', kind: 'decision' },
  { id: 'ask', label: 'Ask for the order number', tag: 'Agent' },
  { id: 'refund', label: 'Draft a refund', tag: 'Agent' },
  { id: 'credit', label: 'Offer store credit', tag: 'Agent' },
  { id: 'approve', label: 'Approve the reply', tag: 'You', note: 'Nothing is sent before this.' },
  { id: 'send', label: 'Send', tag: 'Agent' },
];
const edges: FlowEdge[] = [
  { from: 'read', to: 'found' },
  { from: 'found', to: 'window', label: 'Yes' },
  { from: 'found', to: 'ask', label: 'No' },
  { from: 'ask', to: 'read', label: 'Reply' },
  { from: 'window', to: 'refund', label: 'Yes' },
  { from: 'window', to: 'credit', label: 'No' },
  { from: 'refund', to: 'approve' },
  { from: 'credit', to: 'approve' },
  { from: 'approve', to: 'send' },
];
const tickets = [
  { name: 'Ticket 4812', path: ['read', 'found', 'window', 'refund', 'approve', 'send'] },
  { name: 'Ticket 4813', path: ['read', 'found', 'window', 'credit', 'approve', 'send'] },
  { name: 'Ticket 4814', path: ['read', 'found', 'ask'] },
];

export default function FlowDiagramDemo() {
  const [ticket, setTicket] = useState(0);
  return (
    <div style={{ width: '100%', maxWidth: 620, display: 'grid', gap: 16 }}>
      <div role="group" aria-label="Ticket" style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
        {tickets.map((item, index) => <Button key={item.name} tone={index === ticket ? 'primary' : 'secondary'} aria-pressed={index === ticket} onClick={() => setTicket(index)}>{item.name}</Button>)}
      </div>
      <FlowDiagram title="How a refund request is handled" nodes={nodes} edges={edges} lit={tickets[ticket].path} />
    </div>
  );
}

Installation

pnpm add @brand-studio/ui

Usage

import { FlowDiagram } from '@brand-studio/ui';
<FlowDiagram
  title="How a refund request is handled"
  nodes={[
    { id: 'read', label: 'Read the ticket', tag: 'Agent' },
    { id: 'found', label: 'Order found?', kind: 'decision' },
    { id: 'refund', label: 'Draft a refund', tag: 'Agent' },
    { id: 'ask', label: 'Ask for the order number', tag: 'Agent' },
  ]}
  edges={[
    { from: 'read', to: 'found' },
    { from: 'found', to: 'refund', label: 'Yes' },
    { from: 'found', to: 'ask', label: 'No' },
  ]}
  lit={['read', 'found', 'refund']}
/>

You give the nodes and the links between them; the component places them. A node sits one rank after the furthest step that leads to it, and a link that skips a rank gets a lane of its own so it never runs under a node. A link back to an earlier step is drawn dashed, against the flow.

Direction

The diagram runs top to bottom on a narrow screen and turns left to right when every rank has room for a readable node. A short flow turns sooner than a long one.

Where an answer comes from
  1. Your questionNext: Search the notes, Look up the order
  2. ToolSearch the notesNext: Write the answer
  3. ToolLook up the orderNext: Write the answer
  4. AgentWrite the answerEach claim cites its source.
import { FlowDiagram } from '@brand-studio/ui';

export default function FlowDiagramAcrossDemo() {
  return (
    <div style={{ width: '100%' }}>
      <FlowDiagram
        title="Where an answer comes from"
        nodes={[
          { id: 'ask', label: 'Your question' },
          { id: 'notes', label: 'Search the notes', tag: 'Tool' },
          { id: 'orders', label: 'Look up the order', tag: 'Tool' },
          { id: 'answer', label: 'Write the answer', tag: 'Agent', note: 'Each claim cites its source.' },
        ]}
        edges={[{ from: 'ask', to: 'notes' }, { from: 'ask', to: 'orders' }, { from: 'notes', to: 'answer' }, { from: 'orders', to: 'answer' }]}
        lit={['ask', 'notes', 'answer']}
      />
    </div>
  );
}

Nodes

  • kind: 'decision' draws a pill for a question. Label the links that leave it.
  • tag says who or what does the step, such as "Agent", "Tool" or "You".
  • note adds a second line.

The path taken

lit lists the ids of the nodes on one path. Those nodes and the links between them take the accent, which shows the route an agent took through its own rules.

Accessibility

  • The nodes are an ordered list in reading order, and each one says in words which steps come next, with the link's label.
  • The arrows are decoration for screen readers and are drawn once the nodes have a size, so the steps read before JavaScript runs.
  • A lit node has a heavier border as well as the accent, so the path does not depend on colour alone.

API Reference

PropTypeDefault
titlestring–
nodesFlowNode[]–
edgesFlowEdge[]–
lit?string[]–
nextLabel?string'Next'
hideTitle?booleanfalse
className?string''

Still, Deskhand and Hollis are fictional brands. The coffee photographs are original generated artwork. @brand-studio/ui is MIT licensed.