design-system/docs/superpowers/plans/2026-03-24-documentation-updates.md

Documentation Updates Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Update COMPONENT_GUIDE.md and Inventory page with entries and demos for all new components: KpiStrip, SplitPane, EntityList, LogViewer, StatusText, and Card title extension.

Architecture: COMPONENT_GUIDE.md gets new decision tree entries and component index rows. Inventory page gets DemoCard sections with realistic sample data for each new component.

Tech Stack: React, TypeScript, CSS Modules

Spec: docs/superpowers/specs/2026-03-24-mock-deviations-design.md (Documentation Updates section)

---

Task 1: Update COMPONENT_GUIDE.md

File: COMPONENT_GUIDE.md

Steps

• 1a. In the "I need to show status" decision tree (line ~34), add StatusText entry after StatusDot:

- Inline colored status value → **StatusText** (success, warning, error, running, muted — with optional bold)

• 1b. In the "I need to display data" decision tree (line ~51), add three entries after the EventFeed line:

- Row of summary KPIs → **KpiStrip** (horizontal strip with colored borders, trends, sparklines)
- Scrollable log output → **LogViewer** (timestamped, severity-colored monospace entries)
- Searchable, selectable entity list → **EntityList** (search header, selection highlighting, pairs with SplitPane)

• 1c. In the "I need to organize content" decision tree (line ~62), add SplitPane entry after DetailPanel and update the Card entry:

After the - Side panel inspector → **DetailPanel** line, add:

- Master/detail split layout → **SplitPane** (list on left, detail on right, configurable ratio)

Update the existing Card line from:

- Grouped content box → **Card** (with optional accent)

to:

- Grouped content box → **Card** (with optional accent and title)

• 1d. In the "I need to display text" decision tree (line ~72), add StatusText cross-reference:

- Colored inline status text → **StatusText** (semantic color + optional bold, see also "I need to show status")

• 1e. Add a new composition pattern after the existing "KPI dashboard" pattern (line ~113):

### Master/detail management pattern

SplitPane + EntityList for CRUD list/detail screens (users, groups, roles) EntityList provides: search header, add button, selectable list SplitPane provides: responsive two-column layout with empty state

• 1f. Add five new rows to the Component Index table (maintaining alphabetical order):

After the EventFeed row:

| EntityList | composite | Searchable, selectable entity list with add button. Pair with SplitPane for CRUD management screens |

After the KeyboardHint row:

| KpiStrip | composite | Horizontal row of KPI cards with colored left border, trend, subtitle, optional sparkline |

After the LineChart row:

| LogViewer | composite | Scrollable log output with timestamped, severity-colored monospace entries |

After the Sparkline row:

| SplitPane | composite | Two-column master/detail layout with configurable ratio and empty state |
| StatusText | primitive | Inline colored status span (success, warning, error, running, muted) with optional bold |

• 1g. Update the existing Card row in the Component Index from:

| Card | primitive | Content container with optional accent border |

to:

| Card | primitive | Content container with optional accent border and title header |

---

Task 2: Add StatusText demo to PrimitivesSection

File: src/pages/Inventory/sections/PrimitivesSection.tsx

Steps

• 2a. Add StatusText to the import from '../../../design-system/primitives' (insert alphabetically after StatCard):

StatusText,

• 2b. Add a new DemoCard after the StatusDot demo (after line ~560, before the Tag demo). Insert this block:

      {/* 29. StatusText */}
      <DemoCard
        id="statustext"
        title="StatusText"
        description="Inline coloured text for status values — five semantic variants with optional bold."
      >
        <div className={styles.demoAreaColumn} style={{ width: '100%' }}>
          <div className={styles.demoAreaRow}>
            <StatusText variant="success">99.8% uptime</StatusText>
            <StatusText variant="warning">SLA at risk</StatusText>
            <StatusText variant="error">BREACH</StatusText>
            <StatusText variant="running">Processing</StatusText>
            <StatusText variant="muted">N/A</StatusText>
          </div>
          <div className={styles.demoAreaRow}>
            <StatusText variant="success" bold>99.8% uptime</StatusText>
            <StatusText variant="warning" bold>SLA at risk</StatusText>
            <StatusText variant="error" bold>BREACH</StatusText>
            <StatusText variant="running" bold>Processing</StatusText>
            <StatusText variant="muted" bold>N/A</StatusText>
          </div>
        </div>
      </DemoCard>

Note: Renumber subsequent demos (Tag becomes 30, Textarea becomes 31, Toggle becomes 32, Tooltip becomes 33).

---

Task 3: Update Card demo in PrimitivesSection

File: src/pages/Inventory/sections/PrimitivesSection.tsx

Steps

• 3a. Update the Card DemoCard description from:

        description="Surface container with optional left-border accent colour."

to:

        description="Surface container with optional left-border accent colour and title header."

• 3b. Add a title prop example to the Card demo. After the existing Card accent="error" line (~212), add:

        <Card title="Throughput (msg/s)">
          <div style={{ padding: '8px 12px', fontSize: 13 }}>Card with title header and separator</div>
        </Card>
        <Card accent="amber" title="Error Rate">
          <div style={{ padding: '8px 12px', fontSize: 13 }}>Title + accent combined</div>
        </Card>

---

Task 4: Add composite demos to CompositesSection

File: src/pages/Inventory/sections/CompositesSection.tsx

Steps

• 4a. Add new imports. Add KpiStrip, SplitPane, EntityList, LogViewer to the import from '../../../design-system/composites' (insert alphabetically):

  EntityList,
  KpiStrip,
  LogViewer,
  SplitPane,

Also add Badge and Avatar to the import from '../../../design-system/primitives' (needed for EntityList demo renderItem):

import { Avatar, Badge, Button } from '../../../design-system/primitives'

• 4b. Add sample data constants after the existing sample data section (before the CompositesSection function). Add:

// ── Sample data for new composites ───────────────────────────────────────────

const KPI_ITEMS = [
  {
    label: 'Exchanges',
    value: '12,847',
    trend: { label: '↑ +8.2%', variant: 'success' as const },
    subtitle: 'Last 24h',
    sparkline: [40, 55, 48, 62, 70, 65, 78],
    borderColor: 'var(--amber)',
  },
  {
    label: 'Error Rate',
    value: '0.34%',
    trend: { label: '↑ +0.12pp', variant: 'error' as const },
    subtitle: 'Above threshold',
    sparkline: [10, 12, 11, 15, 18, 22, 19],
    borderColor: 'var(--error)',
  },
  {
    label: 'Avg Latency',
    value: '142ms',
    trend: { label: '↓ -12ms', variant: 'success' as const },
    subtitle: 'P95: 380ms',
    borderColor: 'var(--success)',
  },
  {
    label: 'Active Routes',
    value: '37',
    trend: { label: '±0', variant: 'muted' as const },
    subtitle: '3 paused',
    borderColor: 'var(--running)',
  },
]

const ENTITY_LIST_ITEMS = [
  { id: '1', name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { id: '2', name: 'Bob Chen', email: 'bob@example.com', role: 'Editor' },
  { id: '3', name: 'Carol Smith', email: 'carol@example.com', role: 'Viewer' },
  { id: '4', name: 'David Park', email: 'david@example.com', role: 'Editor' },
  { id: '5', name: 'Eva Martinez', email: 'eva@example.com', role: 'Admin' },
]

const LOG_ENTRIES = [
  { timestamp: '2026-03-24T10:00:01Z', level: 'info' as const, message: 'Route timer-aggregator started successfully' },
  { timestamp: '2026-03-24T10:00:03Z', level: 'debug' as const, message: 'Polling endpoint https://api.internal/health — 200 OK' },
  { timestamp: '2026-03-24T10:00:15Z', level: 'warn' as const, message: 'Retry queue depth at 847 — approaching threshold (1000)' },
  { timestamp: '2026-03-24T10:00:22Z', level: 'error' as const, message: 'Exchange failed: Connection refused to jdbc:postgresql://db-primary:5432/orders' },
  { timestamp: '2026-03-24T10:00:23Z', level: 'info' as const, message: 'Failover activated — routing to db-secondary' },
  { timestamp: '2026-03-24T10:00:30Z', level: 'info' as const, message: 'Exchange completed in 142ms via fallback route' },
  { timestamp: '2026-03-24T10:00:45Z', level: 'debug' as const, message: 'Metrics flush: 328 data points written to InfluxDB' },
  { timestamp: '2026-03-24T10:01:00Z', level: 'warn' as const, message: 'Memory usage at 78% — GC scheduled' },
]

• 4c. Add state variables inside the CompositesSection function for EntityList demo:

  // EntityList state
  const [selectedEntityId, setSelectedEntityId] = useState<string | undefined>('1')
  const [entitySearch, setEntitySearch] = useState('')

• 4d. Add KpiStrip demo after the existing GroupCard demo. Insert a new DemoCard:

        {/* KpiStrip */}
        <DemoCard
          id="kpistrip"
          title="KpiStrip"
          description="Horizontal row of KPI cards with coloured left border, trend indicator, subtitle, and optional sparkline."
        >
          <div style={{ width: '100%' }}>
            <KpiStrip items={KPI_ITEMS} />
          </div>
        </DemoCard>

• 4e. Add SplitPane demo:

        {/* SplitPane */}
        <DemoCard
          id="splitpane"
          title="SplitPane"
          description="Two-column master/detail layout with configurable ratio and empty-state placeholder."
        >
          <div style={{ width: '100%', height: 200 }}>
            <SplitPane
              list={
                <div style={{ padding: 16, fontSize: 13 }}>
                  <div style={{ fontWeight: 600, marginBottom: 8 }}>Items</div>
                  <div>Item A</div>
                  <div>Item B</div>
                  <div>Item C</div>
                </div>
              }
              detail={
                <div style={{ padding: 16, fontSize: 13 }}>
                  <div style={{ fontWeight: 600, marginBottom: 8 }}>Detail View</div>
                  <div>Select an item on the left to see its details here.</div>
                </div>
              }
              ratio="1:2"
            />
          </div>
        </DemoCard>

• 4f. Add EntityList demo:

        {/* EntityList */}
        <DemoCard
          id="entitylist"
          title="EntityList"
          description="Searchable, selectable entity list with add button — designed to pair with SplitPane."
        >
          <div style={{ width: '100%', height: 260 }}>
            <EntityList
              items={ENTITY_LIST_ITEMS.filter(u =>
                u.name.toLowerCase().includes(entitySearch.toLowerCase())
              )}
              renderItem={(item, isSelected) => (
                <div style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
                  <Avatar name={item.name} size="sm" />
                  <div>
                    <div style={{ fontSize: 13, fontWeight: isSelected ? 600 : 400 }}>{item.name}</div>
                    <div style={{ fontSize: 11, color: 'var(--text-muted)' }}>{item.email}</div>
                  </div>
                  <Badge label={item.role} style={{ marginLeft: 'auto' }} />
                </div>
              )}
              getItemId={(item) => item.id}
              selectedId={selectedEntityId}
              onSelect={setSelectedEntityId}
              searchPlaceholder="Search users..."
              onSearch={setEntitySearch}
              addLabel="+ Add user"
              onAdd={() => {}}
            />
          </div>
        </DemoCard>

• 4g. Add LogViewer demo:

        {/* LogViewer */}
        <DemoCard
          id="logviewer"
          title="LogViewer"
          description="Scrollable log output with timestamped, severity-coloured monospace entries and auto-scroll."
        >
          <div style={{ width: '100%' }}>
            <LogViewer entries={LOG_ENTRIES} maxHeight={240} />
          </div>
        </DemoCard>

• 4h. Verify all four new DemoCards are placed in alphabetical order among existing demos — EntityList after EventFeed, KpiStrip after GroupCard, LogViewer after LoginForm, SplitPane after ShortcutsBar. Adjust comment numbering accordingly.

---

Task 5: Update Inventory nav

File: src/pages/Inventory/Inventory.tsx

Steps

• 5a. Add StatusText to the Primitives nav components array (insert alphabetically after StatusDot):

      { label: 'StatusText', href: '#statustext' },

• 5b. Add four entries to the Composites nav components array (insert alphabetically):

After EventFeed:

      { label: 'EntityList', href: '#entitylist' },

After GroupCard:

      { label: 'KpiStrip', href: '#kpistrip' },

After LoginForm:

      { label: 'LogViewer', href: '#logviewer' },

After ShortcutsBar:

      { label: 'SplitPane', href: '#splitpane' },

---

Task 6: Commit all documentation

Steps

• 6a. Run npx vitest run src/pages/Inventory to verify Inventory page has no import/type errors (if tests exist for it).
• 6b. Stage changed files:
  • COMPONENT_GUIDE.md
  • src/pages/Inventory/Inventory.tsx
  • src/pages/Inventory/sections/PrimitivesSection.tsx
  • src/pages/Inventory/sections/CompositesSection.tsx
• 6c. Commit with message: docs: add COMPONENT_GUIDE entries and Inventory demos for KpiStrip, SplitPane, EntityList, LogViewer, StatusText, Card title

---

Dependency Notes

• Tasks 1-5 are independent and can be worked in any order.
• Task 6 depends on Tasks 1-5 being complete.
• All tasks depend on the components already existing — StatusText, Card title extension, KpiStrip, SplitPane, EntityList, and LogViewer must be built and exported from their barrel files before the Inventory demos will compile.

Files Modified

File	Change
COMPONENT_GUIDE.md	Decision tree entries + component index rows
src/pages/Inventory/Inventory.tsx	5 new nav entries (1 primitive + 4 composites)
src/pages/Inventory/sections/PrimitivesSection.tsx	StatusText demo + Card title demo update
src/pages/Inventory/sections/CompositesSection.tsx	KpiStrip, SplitPane, EntityList, LogViewer demos with sample data