From ff5a2c8a038f336ad325d9771cbad1bef13a1b9d Mon Sep 17 00:00:00 2001
From: HerbertJulio <herbert.julio@azion.com>
Date: Thu, 25 Jun 2026 15:13:40 -0300
Subject: [PATCH 1/2] feat(flow): add Flow component (ENG-46487)

---
 .specs/flow.md                                | 172 ++++++++++++++++
 .../components/data/flow/Flow.stories.js      | 191 ++++++++++++++++++
 packages/webkit/package.json                  |   5 +
 .../src/components/data/flow/connectors.ts    | 146 +++++++++++++
 .../data/flow/flow-anchor/flow-anchor.vue     |  45 +++++
 .../data/flow/flow-anchor/package.json        |  11 +
 .../data/flow/flow-list/flow-list.vue         |  71 +++++++
 .../data/flow/flow-list/package.json          |  11 +
 .../data/flow/flow-node/flow-node.vue         |  53 +++++
 .../data/flow/flow-node/package.json          |  11 +
 .../data/flow/flow-parallel/flow-parallel.vue |  82 ++++++++
 .../data/flow/flow-parallel/package.json      |  11 +
 .../webkit/src/components/data/flow/flow.vue  |  84 ++++++++
 .../src/components/data/flow/injection-key.ts |  12 ++
 .../src/components/data/flow/package.json     |  11 +
 15 files changed, 916 insertions(+)
 create mode 100644 .specs/flow.md
 create mode 100644 apps/storybook/src/stories/components/data/flow/Flow.stories.js
 create mode 100644 packages/webkit/src/components/data/flow/connectors.ts
 create mode 100644 packages/webkit/src/components/data/flow/flow-anchor/flow-anchor.vue
 create mode 100644 packages/webkit/src/components/data/flow/flow-anchor/package.json
 create mode 100644 packages/webkit/src/components/data/flow/flow-list/flow-list.vue
 create mode 100644 packages/webkit/src/components/data/flow/flow-list/package.json
 create mode 100644 packages/webkit/src/components/data/flow/flow-node/flow-node.vue
 create mode 100644 packages/webkit/src/components/data/flow/flow-node/package.json
 create mode 100644 packages/webkit/src/components/data/flow/flow-parallel/flow-parallel.vue
 create mode 100644 packages/webkit/src/components/data/flow/flow-parallel/package.json
 create mode 100644 packages/webkit/src/components/data/flow/flow.vue
 create mode 100644 packages/webkit/src/components/data/flow/injection-key.ts
 create mode 100644 packages/webkit/src/components/data/flow/package.json

diff --git a/.specs/flow.md b/.specs/flow.md
new file mode 100644
index 000000000..beb09e741
--- /dev/null
+++ b/.specs/flow.md
@@ -0,0 +1,172 @@
+---
+name: flow
+category: data
+structure: composition
+status: approved
+spec_version: 1
+figma:
+  url:
+  node_id:
+checksum: 1639b821be408187cef9eb07bd4b08f9cf22f7b3e802b85f44f28f50284ba0d5
+created: 2026-06-25
+last_updated: 2026-06-25
+---
+
+# Flow — Component Spec
+
+## Purpose
+
+Flow renders a directed flow diagram: a vertical sequence of steps (`flow-node`) joined by decorative connectors, with optional parallel branches (`flow-parallel`) and custom attachment points (`flow-anchor`). Use it to visualize pipelines, workflows, and step-by-step processes inside a data view; unlike `data-table` it expresses ordered/branching relationships rather than tabular records. Design source (rewritten to our conventions, never inherited as-is): the kumo "Flow" component group at https://kumo-ui.com/components/flow/. Scope boundary: large diagrams pan via a native `overflow: auto` scroll container on the root — free 2D drag-pan is intentionally out of scope (it would require an external positioning library forbidden by `.claude/rules/dependencies.md`). There is no Figma frame for this component; tokens are inferred from intent and recorded in the Theme gaps table.
+
+## Usage
+
+```vue
+<script setup>
+import Flow from '@aziontech/webkit/flow'
+import FlowList from '@aziontech/webkit/flow-list'
+import FlowNode from '@aziontech/webkit/flow-node'
+import FlowParallel from '@aziontech/webkit/flow-parallel'
+import FlowAnchor from '@aziontech/webkit/flow-anchor'
+</script>
+
+<template>
+  <Flow align="center">
+    <FlowList>
+      <FlowNode>Source</FlowNode>
+      <FlowNode>
+        Transform
+        <FlowAnchor type="end" />
+      </FlowNode>
+      <FlowParallel align="start">
+        <FlowList>
+          <FlowNode>Cache</FlowNode>
+          <FlowNode disabled>Archive</FlowNode>
+        </FlowList>
+        <FlowList>
+          <FlowNode>Deliver</FlowNode>
+        </FlowList>
+      </FlowParallel>
+    </FlowList>
+  </Flow>
+</template>
+```
+
+## Sub-components
+
+- `flow-node/flow-node.vue` — A single step in the flow. Connectors that touch a disabled node render at reduced opacity (mirrored by `data-disabled`). Content via the `default` slot.
+- `flow-anchor/flow-anchor.vue` — Marks a custom connector attachment point inside a node. `type` restricts the anchor to the incoming (`start`) or outgoing (`end`) connector; omitted means both. Content via the `default` slot.
+- `flow-parallel/flow-parallel.vue` — Container that lays out parallel branches side by side with junction connectors. `align` controls the horizontal alignment of the branches.
+- `flow-list/flow-list.vue` — Container for a sequence of `flow-node` with automatic connectors drawn between consecutive nodes. Content via the `default` slot.
+
+<!-- Resulting layout (composition):
+
+  packages/webkit/src/components/data/flow/
+  ├── flow.vue
+  ├── package.json
+  ├── injection-key.ts            (shared by every sub-component; one directory up from each sub-component)
+  ├── flow-node/
+  │   ├── flow-node.vue
+  │   └── package.json
+  ├── flow-anchor/
+  │   ├── flow-anchor.vue
+  │   └── package.json
+  ├── flow-parallel/
+  │   ├── flow-parallel.vue
+  │   └── package.json
+  └── flow-list/
+      ├── flow-list.vue
+      └── package.json
+
+  Public exports in packages/webkit/package.json#exports stay flat
+  (`./flow`, `./flow-node`, `./flow-anchor`, `./flow-parallel`, `./flow-list`). -->
+
+## Props
+
+| Prop | Type | Default | Required | JSDoc |
+|---|---|---|---|---|
+| `align` | `'start' \\| 'center'` | `'start'` | no | Vertical alignment of nodes within the diagram. |
+
+## Events
+
+| _none_ | — | — |
+
+## Slots
+
+| Slot | Scope | Notes |
+|---|---|---|
+| `default` | — | Diagram content: `flow-list`, `flow-node`, `flow-parallel`. |
+
+## States
+
+- Visual states: `default`, `focus-visible`, `disabled`
+- `data-disabled` mirrors the `disabled` prop on `flow-node`
+- `data-align` mirrors the `align` prop on `flow` and `flow-parallel`
+- `data-type` mirrors the `type` prop on `flow-anchor`
+
+## Motion & Animations
+
+_none_
+
+## Tokens
+
+| Region | Token (DESIGN.md) |
+|---|---|
+| typography (node label) | `.text-body-md` |
+| typography (compact label) | `.text-label-md` |
+| node surface | `var(--bg-surface)` |
+| node border | `var(--border-default)` |
+| node text | `var(--text-default)` |
+| connector stroke | `var(--border-default)` |
+| disabled text | `var(--text-disabled)` |
+| spacing | `var(--spacing-md)` |
+| shape | `var(--shape-button)` |
+| ring | `var(--ring-color)` |
+
+## Theme gaps
+
+| Figma variable | Temporary primitive | Follow-up |
+|---|---|---|
+| raised node surface (`bg-surface-raised`) | `var(--bg-surface)` | TODO: tokenizar `--bg-surface-raised` |
+
+## Accessibility (WCAG 2.1 AA)
+
+- Visible focus: `focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)]`
+- Keyboard map: `Tab` moves focus through focusable nodes in document order; no arrow-key roving (the diagram is a static list/group).
+- ARIA: root `flow` is `role="list"`; each `flow-node` is `role="listitem"` with accessible text content; `flow-parallel` is `role="group"`; connectors and anchors are decorative and carry `aria-hidden="true"`.
+- Contrast ≥4.5:1 (text) / ≥3:1 (large + icons), including the disabled state.
+- `motion-reduce:transition-none motion-reduce:transform-none` not required — the component is static (no motion).
+- Touch target ≥40×40 px where a node is interactive.
+
+## Stories (Storybook)
+
+Composite stories are justified below because Flow is a composition component whose value is in how parts compose, not in a single `kind`/`size` axis:
+
+- Default — a sequential `flow-list` of `flow-node` joined by connectors.
+- Parallel — a `flow-parallel` rendering parallel branches with junction connectors (demonstrates the composition that a single `kind`/`size` axis cannot).
+- Disabled — a `flow-node` with the `disabled` prop, showing the reduced-opacity connectors.
+
+## Constraints — DO NOT
+
+<!-- This block is injected VERBATIM into every sub-agent prompt.
+     spec-validator rejects the spec if this block is missing or shorter than the template. -->
+
+- Do not add props beyond the Props table above. If you need a prop that is not listed, emit `BLOCKED: missing prop <name>` and stop — do not invent.
+- Do not add events beyond the Events table above. Same rule for slots and sub-components.
+- Do not invent imports. Every `@aziontech/webkit/*` path must exist in `packages/webkit/package.json#exports`. Every relative import must resolve to a real file. Every npm package must be installed.
+- Do not use HEX/RGB/HSL colors, Tailwind palette names (e.g. `bg-blue-500`), raw typography classes (e.g. `text-sm`), `any`, `@ts-ignore`, or `class` inside `defineProps`.
+- Do not install or import positioning/animation libraries (`@floating-ui/*`, `popper.js`, `tippy.js`, `gsap`, `framer-motion`, `motion`, `@vueuse/motion`, `@formkit/auto-animate`, drag-drop runtimes, scroll virtualization libs). Use CSS + Vue primitives (`<Teleport>`, `<Transition>`). See `.claude/rules/dependencies.md`.
+- Do not improvise animations. Every `animate-*` / `transition-*` class must come from `packages/theme/src/tokens/semantic/animations.js`; every motion-bearing class pairs with `motion-reduce:*` on the same class string; no component-local `@keyframes`.
+- Do not create class presets in JavaScript (`const kindClasses = {...}`, `const sharedClasses = [...]`, `const sizeClasses = {...}`, `const rootClasses = computed(...)`). Variants live on `data-*` attributes consumed by Tailwind `data-[attr=value]:`. All utilities live inline on the root element's `class` attribute. No `<style>` block, no component-local `.css`/`.scss`. See `.claude/rules/styling.md`.
+- Do not inherit artifacts as-is from another design system, Figma file, library, or pre-existing `CONTRACT.md` / `README.md`. Rewrite to our conventions. See `.claude/rules/migration.md`.
+- Do not add Figma references to Storybook stories. No `parameters.design`, no `parameters.figma`, no Figma URLs in `docs.description.*`, no `@storybook/addon-designs` import. The Figma link is owned by `<name>.figma.ts` (Code Connect). See `.claude/docs/COMPONENT_REQUIREMENTS.md`.
+- Do not use `parameters.actions.argTypesRegex` (deprecated in Storybook 8 and silently misroutes Vue 3 emits) or `parameters.actions.handles` (DOM-only). Declare every event explicitly in `argTypes` with a camelCase `on<Event>` key and `{ action: '<emitted-name>' }`. Do not use the legacy CSF2 `Name.args = {...}` form — always object-style CSF3.
+- Do not add bespoke Storybook stories beyond Default + Types + Sizes + state stories (`Loading`, `Disabled`) for the props the component actually declares, unless the spec's "Stories (Storybook)" section explicitly justifies the addition. Do not split Types/Sizes into one-story-per-variant — the composite stories are the canonical pattern.
+- Do not duplicate the `## Usage` block from the spec inside the Storybook story body. The block is injected once into `parameters.docs.description.component` by the storybook-write skill; copy it nowhere else.
+- Do not edit `.claude/docs/DESIGN.md`, `.claude/docs/COMPONENT_REQUIREMENTS.md`, or `.claude/docs/PRIMEVUE_ABSTRACTION.md`.
+- Do not edit the root `package.json` or `.github/workflows/*`.
+- Do not change `structure` after `status: approved`. To change structure, bump `spec_version` and re-author the spec.
+- Do not create files outside the paths declared by your task (the orchestrator tells you exactly which files to write).
+- Do not run `git` commands, `pnpm install`, or any command that changes the lockfile.
+- If anything in the spec is ambiguous or contradicts the rules, emit `BLOCKED: <one-sentence reason>` and write nothing.
+</content>
+</invoke>
diff --git a/apps/storybook/src/stories/components/data/flow/Flow.stories.js b/apps/storybook/src/stories/components/data/flow/Flow.stories.js
new file mode 100644
index 000000000..94ec3f981
--- /dev/null
+++ b/apps/storybook/src/stories/components/data/flow/Flow.stories.js
@@ -0,0 +1,191 @@
+import Flow from '@aziontech/webkit/flow'
+import FlowAnchor from '@aziontech/webkit/flow-anchor'
+import FlowList from '@aziontech/webkit/flow-list'
+import FlowNode from '@aziontech/webkit/flow-node'
+import FlowParallel from '@aziontech/webkit/flow-parallel'
+
+const sfc = (imports, markup) =>
+  ['<script setup>', ...imports, '</script>', '', '<template>', markup, '</template>'].join('\n')
+
+const SEQUENTIAL_IMPORTS = [
+  "import Flow from '@aziontech/webkit/flow'",
+  "import FlowList from '@aziontech/webkit/flow-list'",
+  "import FlowNode from '@aziontech/webkit/flow-node'"
+]
+
+const DEFAULT_SOURCE = sfc(
+  SEQUENTIAL_IMPORTS,
+  [
+    '  <Flow align="center">',
+    '    <FlowList>',
+    '      <FlowNode>Source</FlowNode>',
+    '      <FlowNode>Transform</FlowNode>',
+    '      <FlowNode>Deliver</FlowNode>',
+    '    </FlowList>',
+    '  </Flow>'
+  ].join('\n')
+)
+
+const PARALLEL_SOURCE = sfc(
+  [...SEQUENTIAL_IMPORTS, "import FlowParallel from '@aziontech/webkit/flow-parallel'"],
+  [
+    '  <Flow align="center">',
+    '    <FlowList>',
+    '      <FlowNode>Start</FlowNode>',
+    '      <FlowParallel>',
+    '        <FlowNode>Validate</FlowNode>',
+    '        <FlowNode>Transform</FlowNode>',
+    '        <FlowNode>Cache</FlowNode>',
+    '        <FlowNode>Index</FlowNode>',
+    '      </FlowParallel>',
+    '      <FlowNode>End</FlowNode>',
+    '    </FlowList>',
+    '  </Flow>'
+  ].join('\n')
+)
+
+const DISABLED_SOURCE = sfc(
+  SEQUENTIAL_IMPORTS,
+  [
+    '  <Flow align="center">',
+    '    <FlowList>',
+    '      <FlowNode>Source</FlowNode>',
+    '      <FlowNode disabled>Archive</FlowNode>',
+    '      <FlowNode>Deliver</FlowNode>',
+    '    </FlowList>',
+    '  </Flow>'
+  ].join('\n')
+)
+
+/** @type {import('@storybook/vue3').Meta<typeof Flow>} */
+const meta = {
+  title: 'Components/Data/Flow',
+  component: Flow,
+  subcomponents: { FlowList, FlowNode, FlowParallel, FlowAnchor },
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    backgrounds: {
+      default: 'dark'
+    },
+    a11y: {
+      config: {
+        rules: [
+          { id: 'color-contrast', enabled: true },
+          { id: 'focus-order-semantics', enabled: true }
+        ]
+      }
+    },
+    docs: {
+      description: {
+        component:
+          'Flow renders a directed flow diagram: a vertical sequence of steps (`flow-node`) joined by decorative connectors, with optional parallel branches (`flow-parallel`) and custom attachment points (`flow-anchor`).'
+      },
+      canvas: {
+        sourceState: 'shown'
+      }
+    }
+  },
+  argTypes: {
+    align: {
+      control: 'inline-radio',
+      options: ['start', 'center'],
+      description: 'Vertical alignment of nodes within the diagram.',
+      table: {
+        category: 'props',
+        type: { summary: "'start' | 'center'" },
+        defaultValue: { summary: "'start'" }
+      }
+    },
+    default: {
+      control: false,
+      description: 'Diagram content: flow-list, flow-node, flow-parallel.',
+      table: { category: 'slots', type: { summary: 'VNode[]' } }
+    }
+  },
+  args: {
+    align: 'center'
+  }
+}
+
+export default meta
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Flow>} */
+export const Default = {
+  render: (args) => ({
+    components: { Flow, FlowList, FlowNode },
+    setup() {
+      return { args }
+    },
+    template: `
+      <Flow v-bind="args">
+        <FlowList>
+          <FlowNode>Source</FlowNode>
+          <FlowNode>Transform</FlowNode>
+          <FlowNode>Deliver</FlowNode>
+        </FlowList>
+      </Flow>
+    `
+  }),
+  parameters: {
+    docs: {
+      source: { code: DEFAULT_SOURCE },
+      description: { story: 'A sequential flow of nodes joined by connectors.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Flow>} */
+export const Parallel = {
+  render: (args) => ({
+    components: { Flow, FlowList, FlowNode, FlowParallel },
+    setup() {
+      return { args }
+    },
+    template: `
+      <Flow v-bind="args">
+        <FlowList>
+          <FlowNode>Start</FlowNode>
+          <FlowParallel>
+            <FlowNode>Validate</FlowNode>
+            <FlowNode>Transform</FlowNode>
+            <FlowNode>Cache</FlowNode>
+            <FlowNode>Index</FlowNode>
+          </FlowParallel>
+          <FlowNode>End</FlowNode>
+        </FlowList>
+      </Flow>
+    `
+  }),
+  parameters: {
+    docs: {
+      source: { code: PARALLEL_SOURCE },
+      description: { story: 'Parallel branches with junction connectors.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Flow>} */
+export const Disabled = {
+  render: (args) => ({
+    components: { Flow, FlowList, FlowNode },
+    setup() {
+      return { args }
+    },
+    template: `
+      <Flow v-bind="args">
+        <FlowList>
+          <FlowNode>Source</FlowNode>
+          <FlowNode disabled>Archive</FlowNode>
+          <FlowNode>Deliver</FlowNode>
+        </FlowList>
+      </Flow>
+    `
+  }),
+  parameters: {
+    docs: {
+      source: { code: DISABLED_SOURCE },
+      description: { story: 'A disabled node with reduced-opacity connectors.' }
+    }
+  }
+}
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index 038e706ba..20a34bc45 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -107,6 +107,11 @@
     "./field-textarea": "./src/components/inputs/field-textarea/field-textarea.vue",
     "./dropdown": "./src/components/inputs/dropdown/dropdown.vue",
     "./select": "./src/components/inputs/select/index.ts",
+    "./flow": "./src/components/data/flow/flow.vue",
+    "./flow-anchor": "./src/components/data/flow/flow-anchor/flow-anchor.vue",
+    "./flow-list": "./src/components/data/flow/flow-list/flow-list.vue",
+    "./flow-node": "./src/components/data/flow/flow-node/flow-node.vue",
+    "./flow-parallel": "./src/components/data/flow/flow-parallel/flow-parallel.vue",
     "./scroll-area": "./src/components/layout/scroll-area/scroll-area.vue",
     "./global-header": "./src/components/layout/global-header/index.js",
     "./sidebar": "./src/components/layout/sidebar/sidebar.vue",
diff --git a/packages/webkit/src/components/data/flow/connectors.ts b/packages/webkit/src/components/data/flow/connectors.ts
new file mode 100644
index 000000000..2db79fcee
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/connectors.ts
@@ -0,0 +1,146 @@
+import { useMutationObserver, useResizeObserver } from '@vueuse/core'
+import { onMounted, type Ref, ref } from 'vue'
+
+export interface FlowArrow {
+  x: number
+  y: number
+}
+
+export interface FlowPath {
+  /** SVG path `d` for the connector (straight when endpoints share a row, rounded elbow otherwise). */
+  d: string
+  /** Reduced opacity when either endpoint is a disabled node. */
+  faded: boolean
+  /** Arrowhead tip position, or null when the connector feeds a parallel junction. */
+  arrow: FlowArrow | null
+}
+
+interface FlowItem {
+  left: number
+  top: number
+  right: number
+  bottom: number
+  cx: number
+  cy: number
+  kind: string
+  disabled: boolean
+}
+
+const CORNER = 10
+
+/** Orthogonal H–V–H connector with rounded corners; straight when the row is shared.
+    `bus` pins the vertical leg to a shared x (so branches share one diverge/converge column). */
+const elbow = (fromX: number, fromY: number, toX: number, toY: number, bus?: number): string => {
+  if (Math.abs(fromY - toY) < 0.5) {
+    return `M${fromX},${fromY} L${toX},${toY}`
+  }
+
+  const midX = bus ?? (fromX + toX) / 2
+  const dir = toY > fromY ? 1 : -1
+  const radius = Math.max(
+    0,
+    Math.min(CORNER, Math.abs(toY - fromY) / 2, Math.abs(midX - fromX), Math.abs(toX - midX))
+  )
+
+  return [
+    `M${fromX},${fromY}`,
+    `H${midX - radius}`,
+    `Q${midX},${fromY} ${midX},${fromY + dir * radius}`,
+    `V${toY - dir * radius}`,
+    `Q${midX},${toY} ${midX + radius},${toY}`,
+    `H${toX}`
+  ].join(' ')
+}
+
+/** Read the direct flow items in layout coordinates (offset*, so the geometry is zoom-invariant). */
+const readItems = (container: HTMLElement): FlowItem[] =>
+  Array.from(container.querySelectorAll<HTMLElement>(':scope > [data-flow-kind]')).map((el) => ({
+    left: el.offsetLeft,
+    top: el.offsetTop,
+    right: el.offsetLeft + el.offsetWidth,
+    bottom: el.offsetTop + el.offsetHeight,
+    cx: el.offsetLeft + el.offsetWidth / 2,
+    cy: el.offsetTop + el.offsetHeight / 2,
+    kind: el.dataset['flowKind'] ?? 'node',
+    disabled: el.dataset['flowDisabled'] === 'true'
+  }))
+
+/**
+ * Measures a flow container's direct items and produces the SVG connector geometry.
+ * - `sequence`: links consecutive items left→right (Flow root and Flow.List).
+ * - `parallel`: diverges from the left-center to each branch and converges back to the right-center.
+ */
+export const useFlowConnectors = (
+  containerRef: Ref<HTMLElement | null>,
+  mode: 'sequence' | 'parallel'
+) => {
+  const paths = ref<FlowPath[]>([])
+  const viewBox = ref<string>('0 0 0 0')
+
+  const measure = () => {
+    const container = containerRef.value
+
+    if (!container) {
+      return
+    }
+
+    const width = container.clientWidth
+    const height = container.clientHeight
+    const items = readItems(container)
+    const out: FlowPath[] = []
+
+    if (mode === 'sequence') {
+      for (let i = 0; i < items.length - 1; i += 1) {
+        const from = items[i]
+        const to = items[i + 1]
+
+        out.push({
+          d: elbow(from.right, from.cy, to.left, to.cy),
+          faded: from.disabled || to.disabled,
+          arrow: to.kind === 'parallel' ? null : { x: to.left, y: to.cy }
+        })
+      }
+    } else if (items.length > 0) {
+      const centerY = height / 2
+      const minLeft = Math.min(...items.map((item) => item.left))
+      const maxRight = Math.max(...items.map((item) => item.right))
+      // Shared diverge / converge columns so every branch routes through one bus.
+      const busLeft = minLeft / 2
+      const busRight = maxRight + (width - maxRight) / 2
+
+      for (const item of items) {
+        out.push({
+          d: elbow(0, centerY, item.left, item.cy, busLeft),
+          faded: item.disabled,
+          arrow: item.kind === 'parallel' ? null : { x: item.left, y: item.cy }
+        })
+        out.push({
+          d: elbow(item.right, item.cy, width, centerY, busRight),
+          faded: item.disabled,
+          arrow: null
+        })
+      }
+    }
+
+    viewBox.value = `0 0 ${width} ${height}`
+    paths.value = out
+  }
+
+  onMounted(() => {
+    globalThis.requestAnimationFrame(measure)
+  })
+
+  useResizeObserver(() => containerRef.value, measure)
+  useMutationObserver(
+    () => containerRef.value,
+    () => measure(),
+    {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['data-flow-disabled']
+    }
+  )
+
+  return { paths, viewBox }
+}
diff --git a/packages/webkit/src/components/data/flow/flow-anchor/flow-anchor.vue b/packages/webkit/src/components/data/flow/flow-anchor/flow-anchor.vue
new file mode 100644
index 000000000..1dc36f240
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/flow-anchor/flow-anchor.vue
@@ -0,0 +1,45 @@
+<script setup lang="ts">
+  import { computed, inject, useAttrs } from 'vue'
+
+  import { cn } from '../../../../utils/cn'
+  import { FlowInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'FlowAnchor',
+    inheritAttrs: false
+  })
+
+  defineProps<{
+    /** Restricts the anchor to the incoming or outgoing connector; omitted marks both. */
+    type?: 'start' | 'end'
+  }>()
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const ctx = inject(FlowInjectionKey)
+
+  const testId = computed<string>(
+    () => (attrs['data-testid'] as string | undefined) ?? `${ctx?.testId ?? 'data-flow'}__anchor`
+  )
+
+  const rootClasses = computed(() =>
+    cn(
+      'inline-flex size-2 items-center justify-center rounded-[var(--shape-button)] bg-[var(--border-default)]',
+      attrs.class as string | undefined
+    )
+  )
+</script>
+
+<template>
+  <span
+    aria-hidden="true"
+    :data-type="type || null"
+    :data-testid="testId"
+    :class="rootClasses"
+  >
+    <slot />
+  </span>
+</template>
diff --git a/packages/webkit/src/components/data/flow/flow-anchor/package.json b/packages/webkit/src/components/data/flow/flow-anchor/package.json
new file mode 100644
index 000000000..b8dcd16c4
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/flow-anchor/package.json
@@ -0,0 +1,11 @@
+{
+  "main": "./flow-anchor.vue",
+  "module": "./flow-anchor.vue",
+  "types": "./flow-anchor.vue.d.ts",
+  "browser": {
+    "./sfc": "./flow-anchor.vue"
+  },
+  "sideEffects": [
+    "*.vue"
+  ]
+}
diff --git a/packages/webkit/src/components/data/flow/flow-list/flow-list.vue b/packages/webkit/src/components/data/flow/flow-list/flow-list.vue
new file mode 100644
index 000000000..9bac6616a
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/flow-list/flow-list.vue
@@ -0,0 +1,71 @@
+<script setup lang="ts">
+  import { computed, inject, ref, useAttrs } from 'vue'
+
+  import { cn } from '../../../../utils/cn'
+  import { useFlowConnectors } from '../connectors'
+  import { FlowInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'FlowList',
+    inheritAttrs: false
+  })
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const ctx = inject(FlowInjectionKey)
+
+  const testId = computed<string>(
+    () => (attrs['data-testid'] as string | undefined) ?? `${ctx?.testId ?? 'data-flow'}__list`
+  )
+
+  const containerRef = ref<HTMLElement | null>(null)
+  const { paths, viewBox } = useFlowConnectors(containerRef, 'sequence')
+
+  const rootClasses = computed(() =>
+    cn(
+      'relative flex flex-row items-center gap-[var(--spacing-xl)]',
+      attrs.class as string | undefined
+    )
+  )
+</script>
+
+<template>
+  <div
+    ref="containerRef"
+    role="presentation"
+    data-flow-kind="list"
+    :data-testid="testId"
+    :class="rootClasses"
+  >
+    <svg
+      v-if="paths.length"
+      :viewBox="viewBox"
+      preserveAspectRatio="none"
+      fill="none"
+      aria-hidden="true"
+      class="pointer-events-none absolute inset-0 h-full w-full overflow-visible"
+    >
+      <template
+        v-for="(path, index) in paths"
+        :key="index"
+      >
+        <path
+          :d="path.d"
+          stroke-width="1"
+          class="stroke-[var(--border-default)]"
+          :class="{ 'opacity-50': path.faded }"
+        />
+        <polygon
+          v-if="path.arrow"
+          :points="`${path.arrow.x - 7},${path.arrow.y - 4} ${path.arrow.x},${path.arrow.y} ${path.arrow.x - 7},${path.arrow.y + 4}`"
+          class="fill-[var(--border-default)]"
+          :class="{ 'opacity-50': path.faded }"
+        />
+      </template>
+    </svg>
+    <slot />
+  </div>
+</template>
diff --git a/packages/webkit/src/components/data/flow/flow-list/package.json b/packages/webkit/src/components/data/flow/flow-list/package.json
new file mode 100644
index 000000000..a4eeb0816
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/flow-list/package.json
@@ -0,0 +1,11 @@
+{
+  "main": "./flow-list.vue",
+  "module": "./flow-list.vue",
+  "types": "./flow-list.vue.d.ts",
+  "browser": {
+    "./sfc": "./flow-list.vue"
+  },
+  "sideEffects": [
+    "*.vue"
+  ]
+}
diff --git a/packages/webkit/src/components/data/flow/flow-node/flow-node.vue b/packages/webkit/src/components/data/flow/flow-node/flow-node.vue
new file mode 100644
index 000000000..91c66ff76
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/flow-node/flow-node.vue
@@ -0,0 +1,53 @@
+<script setup lang="ts">
+  import { computed, inject, useAttrs } from 'vue'
+
+  import { cn } from '../../../../utils/cn'
+  import { FlowInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'FlowNode',
+    inheritAttrs: false
+  })
+
+  withDefaults(
+    defineProps<{
+      /** Marks the step as disabled; adjacent connectors render at reduced opacity. */
+      disabled?: boolean
+    }>(),
+    {
+      disabled: false
+    }
+  )
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const ctx = inject(FlowInjectionKey)
+
+  const testId = computed<string>(
+    () => (attrs['data-testid'] as string | undefined) ?? `${ctx?.testId ?? 'data-flow'}__node`
+  )
+
+  const rootClasses = computed(() =>
+    cn(
+      'relative z-[1] inline-flex min-h-10 items-center justify-center whitespace-nowrap rounded-[var(--shape-button)] border border-[var(--border-default)] bg-[var(--bg-surface-raised)] px-[var(--spacing-md)] py-[var(--spacing-sm)] text-label-md text-[var(--text-default)] data-[disabled]:text-[var(--text-disabled)] data-[disabled]:opacity-60',
+      attrs.class as string | undefined
+    )
+  )
+</script>
+
+<template>
+  <div
+    role="listitem"
+    data-flow-kind="node"
+    :data-flow-disabled="disabled ? 'true' : null"
+    :data-disabled="disabled || null"
+    :aria-disabled="disabled || undefined"
+    :data-testid="testId"
+    :class="rootClasses"
+  >
+    <slot />
+  </div>
+</template>
diff --git a/packages/webkit/src/components/data/flow/flow-node/package.json b/packages/webkit/src/components/data/flow/flow-node/package.json
new file mode 100644
index 000000000..624a22ce2
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/flow-node/package.json
@@ -0,0 +1,11 @@
+{
+  "main": "./flow-node.vue",
+  "module": "./flow-node.vue",
+  "types": "./flow-node.vue.d.ts",
+  "browser": {
+    "./sfc": "./flow-node.vue"
+  },
+  "sideEffects": [
+    "*.vue"
+  ]
+}
diff --git a/packages/webkit/src/components/data/flow/flow-parallel/flow-parallel.vue b/packages/webkit/src/components/data/flow/flow-parallel/flow-parallel.vue
new file mode 100644
index 000000000..f24c593ad
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/flow-parallel/flow-parallel.vue
@@ -0,0 +1,82 @@
+<script setup lang="ts">
+  import { computed, inject, ref, useAttrs } from 'vue'
+
+  import { cn } from '../../../../utils/cn'
+  import { useFlowConnectors } from '../connectors'
+  import { FlowInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'FlowParallel',
+    inheritAttrs: false
+  })
+
+  withDefaults(
+    defineProps<{
+      /** Horizontal alignment of the parallel branches: `start` left-aligns, `end` right-aligns. */
+      align?: 'start' | 'end'
+    }>(),
+    {
+      align: 'start'
+    }
+  )
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const ctx = inject(FlowInjectionKey)
+
+  const testId = computed<string>(
+    () => (attrs['data-testid'] as string | undefined) ?? `${ctx?.testId ?? 'data-flow'}__parallel`
+  )
+
+  const containerRef = ref<HTMLElement | null>(null)
+  const { paths, viewBox } = useFlowConnectors(containerRef, 'parallel')
+
+  const rootClasses = computed(() =>
+    cn(
+      'relative flex flex-col gap-[var(--spacing-md)] px-[var(--spacing-xl)] data-[align=start]:items-start data-[align=end]:items-end',
+      attrs.class as string | undefined
+    )
+  )
+</script>
+
+<template>
+  <div
+    ref="containerRef"
+    role="group"
+    data-flow-kind="parallel"
+    :data-align="align"
+    :data-testid="testId"
+    :class="rootClasses"
+  >
+    <svg
+      v-if="paths.length"
+      :viewBox="viewBox"
+      preserveAspectRatio="none"
+      fill="none"
+      aria-hidden="true"
+      class="pointer-events-none absolute inset-0 h-full w-full overflow-visible"
+    >
+      <template
+        v-for="(path, index) in paths"
+        :key="index"
+      >
+        <path
+          :d="path.d"
+          stroke-width="1"
+          class="stroke-[var(--border-default)]"
+          :class="{ 'opacity-50': path.faded }"
+        />
+        <polygon
+          v-if="path.arrow"
+          :points="`${path.arrow.x - 7},${path.arrow.y - 4} ${path.arrow.x},${path.arrow.y} ${path.arrow.x - 7},${path.arrow.y + 4}`"
+          class="fill-[var(--border-default)]"
+          :class="{ 'opacity-50': path.faded }"
+        />
+      </template>
+    </svg>
+    <slot />
+  </div>
+</template>
diff --git a/packages/webkit/src/components/data/flow/flow-parallel/package.json b/packages/webkit/src/components/data/flow/flow-parallel/package.json
new file mode 100644
index 000000000..efc43c3fb
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/flow-parallel/package.json
@@ -0,0 +1,11 @@
+{
+  "main": "./flow-parallel.vue",
+  "module": "./flow-parallel.vue",
+  "types": "./flow-parallel.vue.d.ts",
+  "browser": {
+    "./sfc": "./flow-parallel.vue"
+  },
+  "sideEffects": [
+    "*.vue"
+  ]
+}
diff --git a/packages/webkit/src/components/data/flow/flow.vue b/packages/webkit/src/components/data/flow/flow.vue
new file mode 100644
index 000000000..4e7743385
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/flow.vue
@@ -0,0 +1,84 @@
+<script setup lang="ts">
+  import { computed, provide, ref, useAttrs } from 'vue'
+
+  import { cn } from '../../../utils/cn'
+  import { useFlowConnectors } from './connectors'
+  import { type FlowAlign, FlowInjectionKey } from './injection-key'
+
+  defineOptions({
+    name: 'Flow',
+    inheritAttrs: false
+  })
+
+  const props = withDefaults(
+    defineProps<{
+      /** Vertical alignment of nodes within the diagram. */
+      align?: FlowAlign
+    }>(),
+    {
+      align: 'start'
+    }
+  )
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+
+  const testId = computed<string>(() => (attrs['data-testid'] as string | undefined) ?? 'data-flow')
+
+  const containerRef = ref<HTMLElement | null>(null)
+  const { paths, viewBox } = useFlowConnectors(containerRef, 'sequence')
+
+  provide(FlowInjectionKey, {
+    testId: testId.value,
+    align: props.align
+  })
+
+  const outerClasses = computed(() =>
+    cn('w-full overflow-x-auto p-[var(--spacing-md)]', attrs.class as string | undefined)
+  )
+</script>
+
+<template>
+  <div
+    role="list"
+    :data-testid="testId"
+    :class="outerClasses"
+  >
+    <div
+      ref="containerRef"
+      :data-align="align"
+      class="relative flex w-fit flex-row gap-[var(--spacing-xl)] text-[var(--text-default)] data-[align=center]:items-center data-[align=start]:items-start"
+    >
+      <svg
+        v-if="paths.length"
+        :viewBox="viewBox"
+        preserveAspectRatio="none"
+        fill="none"
+        aria-hidden="true"
+        class="pointer-events-none absolute inset-0 h-full w-full overflow-visible"
+      >
+        <template
+          v-for="(path, index) in paths"
+          :key="index"
+        >
+          <path
+            :d="path.d"
+            stroke-width="1"
+            class="stroke-[var(--border-default)]"
+            :class="{ 'opacity-50': path.faded }"
+          />
+          <polygon
+            v-if="path.arrow"
+            :points="`${path.arrow.x - 7},${path.arrow.y - 4} ${path.arrow.x},${path.arrow.y} ${path.arrow.x - 7},${path.arrow.y + 4}`"
+            class="fill-[var(--border-default)]"
+            :class="{ 'opacity-50': path.faded }"
+          />
+        </template>
+      </svg>
+      <slot />
+    </div>
+  </div>
+</template>
diff --git a/packages/webkit/src/components/data/flow/injection-key.ts b/packages/webkit/src/components/data/flow/injection-key.ts
new file mode 100644
index 000000000..dd9616a21
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/injection-key.ts
@@ -0,0 +1,12 @@
+import type { InjectionKey } from 'vue'
+
+export type FlowAlign = 'start' | 'center'
+
+export interface FlowContext {
+  /** Base data-testid for BEM-derived sub-component ids. */
+  testId: string
+  /** Vertical alignment of nodes within the diagram. */
+  align: FlowAlign
+}
+
+export const FlowInjectionKey: InjectionKey<FlowContext> = Symbol('FlowContext')
diff --git a/packages/webkit/src/components/data/flow/package.json b/packages/webkit/src/components/data/flow/package.json
new file mode 100644
index 000000000..5078c3c52
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/package.json
@@ -0,0 +1,11 @@
+{
+  "main": "./flow.vue",
+  "module": "./flow.vue",
+  "types": "./flow.vue.d.ts",
+  "browser": {
+    "./sfc": "./flow.vue"
+  },
+  "sideEffects": [
+    "*.vue"
+  ]
+}

From 4d26d8a8b36493bc8a84c0ba172c14ec9a4cad0a Mon Sep 17 00:00:00 2001
From: HerbertJulio <herbert.julio@azion.com>
Date: Fri, 26 Jun 2026 03:05:25 -0300
Subject: [PATCH 2/2] [ENG-46487] feat(webkit): reshape Flow to compound API
 with custom nodes and anchors

Reshape the (unreleased) Flow component to a compound, slot-driven API:

- Public API is dot-notation now: import Flow and use Flow.Node /
  Flow.Parallel / Flow.Anchor. index.ts attaches them and is the single
  ./flow export (mirrors the select pattern).
- Nodes are direct children of Flow; remove the FlowList wrapper.
- flow-node gains an unstyled prop so the slot content defines the node
  (start dot, taller node, multi-row card); the default box is gated
  behind data-styled.
- flow-anchor wraps real content and marks where connectors attach
  (type end = incoming endpoint, type start = outgoing origin).
- Connector geometry is centralized in the root: one SVG draws every
  connector, so a leading/trailing flow-parallel fans in/out with no
  dangling stubs.
- Stories and spec updated to the new API; subcomponent autodocs tables
  populated via explicit docgen info.
---
 .specs/flow.md                                |  93 +++--
 .../components/data/flow/Flow.stories.js      | 325 ++++++++++++++----
 packages/webkit/package.json                  |   6 +-
 .../src/components/data/flow/connectors.ts    | 177 ++++++----
 .../data/flow/flow-anchor/flow-anchor.vue     |  18 +-
 .../data/flow/flow-list/flow-list.vue         |  71 ----
 .../data/flow/flow-list/package.json          |  11 -
 .../data/flow/flow-node/flow-node.vue         |  10 +-
 .../data/flow/flow-parallel/flow-parallel.vue |  50 +--
 .../webkit/src/components/data/flow/flow.vue  |   2 +-
 .../webkit/src/components/data/flow/index.ts  |  18 +
 .../src/components/data/flow/package.json     |   6 +-
 12 files changed, 460 insertions(+), 327 deletions(-)
 delete mode 100644 packages/webkit/src/components/data/flow/flow-list/flow-list.vue
 delete mode 100644 packages/webkit/src/components/data/flow/flow-list/package.json
 create mode 100644 packages/webkit/src/components/data/flow/index.ts

diff --git a/.specs/flow.md b/.specs/flow.md
index beb09e741..cef54dc7b 100644
--- a/.specs/flow.md
+++ b/.specs/flow.md
@@ -3,66 +3,66 @@ name: flow
 category: data
 structure: composition
 status: approved
-spec_version: 1
+spec_version: 2
 figma:
   url:
   node_id:
-checksum: 1639b821be408187cef9eb07bd4b08f9cf22f7b3e802b85f44f28f50284ba0d5
+checksum: bdd033850866837b20760c9154820d48ff57a1d28da13c2bb527b020235ab84f
 created: 2026-06-25
-last_updated: 2026-06-25
+last_updated: 2026-06-26
 ---
 
 # Flow — Component Spec
 
 ## Purpose
 
-Flow renders a directed flow diagram: a vertical sequence of steps (`flow-node`) joined by decorative connectors, with optional parallel branches (`flow-parallel`) and custom attachment points (`flow-anchor`). Use it to visualize pipelines, workflows, and step-by-step processes inside a data view; unlike `data-table` it expresses ordered/branching relationships rather than tabular records. Design source (rewritten to our conventions, never inherited as-is): the kumo "Flow" component group at https://kumo-ui.com/components/flow/. Scope boundary: large diagrams pan via a native `overflow: auto` scroll container on the root — free 2D drag-pan is intentionally out of scope (it would require an external positioning library forbidden by `.claude/rules/dependencies.md`). There is no Figma frame for this component; tokens are inferred from intent and recorded in the Theme gaps table.
+Flow renders a directed flow diagram: a horizontal sequence of steps (`flow-node`) joined by decorative connectors, with optional parallel branches (`flow-parallel`) and custom connector-attachment points (`flow-anchor`). Use it to visualize pipelines, workflows, and step-by-step processes inside a data view; unlike `data-table` it expresses ordered/branching relationships rather than tabular records. Steps are written as direct children of `flow`; a `flow-parallel` between two steps fans out from the previous step and fans back into the next, and a `flow-parallel` at the start/end fans only inward/outward (no dangling stubs). A node can be styled (the default box) or `unstyled` so its slot content defines the entire node — a dot, a tall card, a multi-row card — while connectors still attach correctly, optionally at `flow-anchor` points inside the node. Design source (rewritten to our conventions, never inherited as-is): the kumo "Flow" component group at https://kumo-ui.com/components/flow/. Scope boundary: large diagrams pan via a native `overflow: auto` scroll container on the root — free 2D drag-pan is intentionally out of scope (it would require an external positioning library forbidden by `.claude/rules/dependencies.md`). There is no Figma frame for this component; tokens are inferred from intent and recorded in the Theme gaps table.
 
 ## Usage
 
 ```vue
 <script setup>
 import Flow from '@aziontech/webkit/flow'
-import FlowList from '@aziontech/webkit/flow-list'
-import FlowNode from '@aziontech/webkit/flow-node'
-import FlowParallel from '@aziontech/webkit/flow-parallel'
-import FlowAnchor from '@aziontech/webkit/flow-anchor'
 </script>
 
 <template>
   <Flow align="center">
-    <FlowList>
-      <FlowNode>Source</FlowNode>
-      <FlowNode>
-        Transform
-        <FlowAnchor type="end" />
-      </FlowNode>
-      <FlowParallel align="start">
-        <FlowList>
-          <FlowNode>Cache</FlowNode>
-          <FlowNode disabled>Archive</FlowNode>
-        </FlowList>
-        <FlowList>
-          <FlowNode>Deliver</FlowNode>
-        </FlowList>
-      </FlowParallel>
-    </FlowList>
+    <Flow.Node>Load balancer</Flow.Node>
+    <Flow.Node unstyled>
+      <div class="rounded-[var(--shape-card)] border border-[var(--border-default)] bg-[var(--bg-surface-overlay)]">
+        <Flow.Anchor type="end">
+          <div class="flex h-10 items-center px-[var(--spacing-sm)] text-label-md text-[var(--text-muted)]">
+            my-worker
+          </div>
+        </Flow.Anchor>
+        <Flow.Anchor type="start">
+          <div class="m-[var(--spacing-xxs)] mt-0 rounded-[var(--shape-button)] border border-[var(--border-default)] bg-[var(--bg-surface)] px-[var(--spacing-sm)] py-[var(--spacing-xxs)] text-label-md text-[var(--text-default)]">
+            Bindings
+          </div>
+        </Flow.Anchor>
+      </div>
+    </Flow.Node>
+    <Flow.Parallel>
+      <Flow.Node>DATABASE</Flow.Node>
+      <Flow.Node>OTHER_SERVICE</Flow.Node>
+    </Flow.Parallel>
   </Flow>
 </template>
 ```
 
 ## Sub-components
 
-- `flow-node/flow-node.vue` — A single step in the flow. Connectors that touch a disabled node render at reduced opacity (mirrored by `data-disabled`). Content via the `default` slot.
-- `flow-anchor/flow-anchor.vue` — Marks a custom connector attachment point inside a node. `type` restricts the anchor to the incoming (`start`) or outgoing (`end`) connector; omitted means both. Content via the `default` slot.
-- `flow-parallel/flow-parallel.vue` — Container that lays out parallel branches side by side with junction connectors. `align` controls the horizontal alignment of the branches.
-- `flow-list/flow-list.vue` — Container for a sequence of `flow-node` with automatic connectors drawn between consecutive nodes. Content via the `default` slot.
+- `flow-node/flow-node.vue` — A single step in the flow. Renders the default node box; `unstyled` drops the box so the `default` slot defines the node's appearance (a dot, a card, a tall node). `disabled` marks the step disabled, rendering adjacent connectors at reduced opacity (mirrored by `data-disabled`). Content via the `default` slot.
+- `flow-anchor/flow-anchor.vue` — Marks a connector-attachment point inside a node and wraps the content that the connector should touch. `type="end"` is the incoming endpoint, `type="start"` the outgoing origin; omitted marks both. Content via the `default` slot.
+- `flow-parallel/flow-parallel.vue` — Container whose direct `flow-node` children are laid out as parallel branches stacked vertically; the `flow` root draws the fan-out/fan-in junction connectors. `align` controls the horizontal alignment of the branches.
 
 <!-- Resulting layout (composition):
 
   packages/webkit/src/components/data/flow/
   ├── flow.vue
+  ├── index.ts                    (entry: attaches Flow.Node / Flow.Parallel / Flow.Anchor)
   ├── package.json
+  ├── connectors.ts               (connector geometry composable, used by flow.vue)
   ├── injection-key.ts            (shared by every sub-component; one directory up from each sub-component)
   ├── flow-node/
   │   ├── flow-node.vue
@@ -70,15 +70,14 @@ import FlowAnchor from '@aziontech/webkit/flow-anchor'
   ├── flow-anchor/
   │   ├── flow-anchor.vue
   │   └── package.json
-  ├── flow-parallel/
-  │   ├── flow-parallel.vue
-  │   └── package.json
-  └── flow-list/
-      ├── flow-list.vue
+  └── flow-parallel/
+      ├── flow-parallel.vue
       └── package.json
 
-  Public exports in packages/webkit/package.json#exports stay flat
-  (`./flow`, `./flow-node`, `./flow-anchor`, `./flow-parallel`, `./flow-list`). -->
+  Public export is a single `./flow` entry (index.ts) that attaches the
+  sub-components for dot-notation (`Flow.Node`, `Flow.Parallel`, `Flow.Anchor`);
+  the same sub-components are also re-exported as named bindings from
+  `@aziontech/webkit/flow`. -->
 
 ## Props
 
@@ -94,14 +93,15 @@ import FlowAnchor from '@aziontech/webkit/flow-anchor'
 
 | Slot | Scope | Notes |
 |---|---|---|
-| `default` | — | Diagram content: `flow-list`, `flow-node`, `flow-parallel`. |
+| `default` | — | Diagram content: `flow-node` and `flow-parallel`, in flow order. |
 
 ## States
 
 - Visual states: `default`, `focus-visible`, `disabled`
 - `data-disabled` mirrors the `disabled` prop on `flow-node`
+- `data-styled` is present on `flow-node` unless `unstyled` (gates the default box utilities)
 - `data-align` mirrors the `align` prop on `flow` and `flow-parallel`
-- `data-type` mirrors the `type` prop on `flow-anchor`
+- `data-flow-anchor` mirrors the `type` prop on `flow-anchor` (`start` / `end` / `both`)
 
 ## Motion & Animations
 
@@ -111,14 +111,13 @@ _none_
 
 | Region | Token (DESIGN.md) |
 |---|---|
-| typography (node label) | `.text-body-md` |
-| typography (compact label) | `.text-label-md` |
-| node surface | `var(--bg-surface)` |
+| typography (node label) | `.text-label-md` |
+| node surface | `var(--bg-surface-raised)` |
 | node border | `var(--border-default)` |
 | node text | `var(--text-default)` |
 | connector stroke | `var(--border-default)` |
 | disabled text | `var(--text-disabled)` |
-| spacing | `var(--spacing-md)` |
+| spacing | `var(--spacing-md)`, `var(--spacing-sm)`, `var(--spacing-xl)` |
 | shape | `var(--shape-button)` |
 | ring | `var(--ring-color)` |
 
@@ -126,13 +125,13 @@ _none_
 
 | Figma variable | Temporary primitive | Follow-up |
 |---|---|---|
-| raised node surface (`bg-surface-raised`) | `var(--bg-surface)` | TODO: tokenizar `--bg-surface-raised` |
+| raised node surface (`bg-surface-raised`) | `var(--bg-surface-raised)` | TODO: confirm `--bg-surface-raised` is the canonical raised token |
 
 ## Accessibility (WCAG 2.1 AA)
 
 - Visible focus: `focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)]`
 - Keyboard map: `Tab` moves focus through focusable nodes in document order; no arrow-key roving (the diagram is a static list/group).
-- ARIA: root `flow` is `role="list"`; each `flow-node` is `role="listitem"` with accessible text content; `flow-parallel` is `role="group"`; connectors and anchors are decorative and carry `aria-hidden="true"`.
+- ARIA: root `flow` is `role="list"`; each `flow-node` is `role="listitem"` with accessible text content; `flow-parallel` is `role="group"`; the connector SVG is decorative and carries `aria-hidden="true"`. A `flow-anchor` wraps meaningful node content and is therefore not hidden.
 - Contrast ≥4.5:1 (text) / ≥3:1 (large + icons), including the disabled state.
 - `motion-reduce:transition-none motion-reduce:transform-none` not required — the component is static (no motion).
 - Touch target ≥40×40 px where a node is interactive.
@@ -141,8 +140,10 @@ _none_
 
 Composite stories are justified below because Flow is a composition component whose value is in how parts compose, not in a single `kind`/`size` axis:
 
-- Default — a sequential `flow-list` of `flow-node` joined by connectors.
-- Parallel — a `flow-parallel` rendering parallel branches with junction connectors (demonstrates the composition that a single `kind`/`size` axis cannot).
+- Default — a sequential flow of `flow-node` joined by connectors.
+- Parallel — a `flow-parallel` fanning out and back in between two nodes (demonstrates the composition that a single `kind`/`size` axis cannot).
+- Branches — leading and trailing `flow-parallel` (fan-in then fan-out), proving connectors route correctly at the edges of the sequence.
+- CustomNodes — `unstyled` nodes whose slot content defines the appearance (a start dot, a tall node, a multi-row card with `flow-anchor` attachment points).
 - Disabled — a `flow-node` with the `disabled` prop, showing the reduced-opacity connectors.
 
 ## Constraints — DO NOT
@@ -168,5 +169,3 @@ Composite stories are justified below because Flow is a composition component wh
 - Do not create files outside the paths declared by your task (the orchestrator tells you exactly which files to write).
 - Do not run `git` commands, `pnpm install`, or any command that changes the lockfile.
 - If anything in the spec is ambiguous or contradicts the rules, emit `BLOCKED: <one-sentence reason>` and write nothing.
-</content>
-</invoke>
diff --git a/apps/storybook/src/stories/components/data/flow/Flow.stories.js b/apps/storybook/src/stories/components/data/flow/Flow.stories.js
index 94ec3f981..fecfa3f8f 100644
--- a/apps/storybook/src/stories/components/data/flow/Flow.stories.js
+++ b/apps/storybook/src/stories/components/data/flow/Flow.stories.js
@@ -1,58 +1,157 @@
-import Flow from '@aziontech/webkit/flow'
-import FlowAnchor from '@aziontech/webkit/flow-anchor'
-import FlowList from '@aziontech/webkit/flow-list'
-import FlowNode from '@aziontech/webkit/flow-node'
-import FlowParallel from '@aziontech/webkit/flow-parallel'
+import Flow, { FlowAnchor, FlowNode, FlowParallel } from '@aziontech/webkit/flow'
 
-const sfc = (imports, markup) =>
-  ['<script setup>', ...imports, '</script>', '', '<template>', markup, '</template>'].join('\n')
+// Storybook's vue3-vite docgen does not run on the cross-package webkit SFCs, so the
+// autodocs subcomponent tabs have no props table. Attach the docgen info explicitly
+// (vue-docgen-api shape) so FlowNode / FlowParallel / FlowAnchor document their API.
+FlowNode.__docgenInfo = {
+  displayName: 'FlowNode',
+  props: [
+    {
+      name: 'disabled',
+      description: 'Marks the step as disabled; adjacent connectors render at reduced opacity.',
+      type: { name: 'boolean' },
+      defaultValue: { value: 'false' },
+      required: false
+    },
+    {
+      name: 'unstyled',
+      description: "Drops the default node box so the slot content defines the node's appearance.",
+      type: { name: 'boolean' },
+      defaultValue: { value: 'false' },
+      required: false
+    }
+  ],
+  slots: [{ name: 'default', description: 'Node content.' }]
+}
+
+FlowParallel.__docgenInfo = {
+  displayName: 'FlowParallel',
+  props: [
+    {
+      name: 'align',
+      description: 'Horizontal alignment of the parallel branches.',
+      type: { name: "'start' | 'end'" },
+      defaultValue: { value: "'start'" },
+      required: false
+    }
+  ],
+  slots: [{ name: 'default', description: 'Parallel branch nodes (one per branch).' }]
+}
 
-const SEQUENTIAL_IMPORTS = [
-  "import Flow from '@aziontech/webkit/flow'",
-  "import FlowList from '@aziontech/webkit/flow-list'",
-  "import FlowNode from '@aziontech/webkit/flow-node'"
-]
+FlowAnchor.__docgenInfo = {
+  displayName: 'FlowAnchor',
+  props: [
+    {
+      name: 'type',
+      description:
+        'Which connector attaches here: end is the incoming endpoint, start the outgoing origin; omitted marks both.',
+      type: { name: "'start' | 'end'" },
+      required: false
+    }
+  ],
+  slots: [{ name: 'default', description: 'The content the connector attaches to.' }]
+}
+
+const sfc = (markup) =>
+  [
+    '<script setup>',
+    "import Flow from '@aziontech/webkit/flow'",
+    '</script>',
+    '',
+    '<template>',
+    markup,
+    '</template>'
+  ].join('\n')
 
 const DEFAULT_SOURCE = sfc(
-  SEQUENTIAL_IMPORTS,
   [
     '  <Flow align="center">',
-    '    <FlowList>',
-    '      <FlowNode>Source</FlowNode>',
-    '      <FlowNode>Transform</FlowNode>',
-    '      <FlowNode>Deliver</FlowNode>',
-    '    </FlowList>',
+    '    <Flow.Node>Source</Flow.Node>',
+    '    <Flow.Node>Transform</Flow.Node>',
+    '    <Flow.Node>Deliver</Flow.Node>',
     '  </Flow>'
   ].join('\n')
 )
 
 const PARALLEL_SOURCE = sfc(
-  [...SEQUENTIAL_IMPORTS, "import FlowParallel from '@aziontech/webkit/flow-parallel'"],
   [
     '  <Flow align="center">',
-    '    <FlowList>',
-    '      <FlowNode>Start</FlowNode>',
-    '      <FlowParallel>',
-    '        <FlowNode>Validate</FlowNode>',
-    '        <FlowNode>Transform</FlowNode>',
-    '        <FlowNode>Cache</FlowNode>',
-    '        <FlowNode>Index</FlowNode>',
-    '      </FlowParallel>',
-    '      <FlowNode>End</FlowNode>',
-    '    </FlowList>',
+    '    <Flow.Node>Start</Flow.Node>',
+    '    <Flow.Parallel>',
+    '      <Flow.Node>Branch A</Flow.Node>',
+    '      <Flow.Node>Branch B</Flow.Node>',
+    '      <Flow.Node>Branch C</Flow.Node>',
+    '    </Flow.Parallel>',
+    '    <Flow.Node>End</Flow.Node>',
+    '  </Flow>'
+  ].join('\n')
+)
+
+const BRANCHES_SOURCE = sfc(
+  [
+    '  <Flow align="center">',
+    '    <Flow.Parallel>',
+    '      <Flow.Node>HTTP Trigger</Flow.Node>',
+    '      <Flow.Node>Cron Trigger</Flow.Node>',
+    '    </Flow.Parallel>',
+    '    <Flow.Node>Process Request</Flow.Node>',
+    '    <Flow.Parallel>',
+    '      <Flow.Node>Log Analytics</Flow.Node>',
+    '      <Flow.Node>Update Cache</Flow.Node>',
+    '      <Flow.Node>Send Notification</Flow.Node>',
+    '    </Flow.Parallel>',
+    '    <Flow.Node>Complete</Flow.Node>',
+    '  </Flow>'
+  ].join('\n')
+)
+
+const CUSTOM_NODES_SOURCE = sfc(
+  [
+    '  <Flow align="center">',
+    '    <Flow.Node unstyled class="size-4 rounded-full bg-[var(--border-default)]" />',
+    '    <Flow.Node>my-worker</Flow.Node>',
+    '    <Flow.Node',
+    '      unstyled',
+    '      class="rounded-[var(--shape-card)] border border-[var(--border-default)] bg-[var(--bg-surface-raised)] px-[var(--spacing-sm)] py-[var(--spacing-xl)] text-label-md text-[var(--text-default)]"',
+    '    >',
+    '      Taller node',
+    '    </Flow.Node>',
+    '  </Flow>'
+  ].join('\n')
+)
+
+const ANCHORED_SOURCE = sfc(
+  [
+    '  <Flow align="center">',
+    '    <Flow.Node>Load balancer</Flow.Node>',
+    '    <Flow.Node unstyled>',
+    '      <div class="rounded-[var(--shape-card)] border border-[var(--border-default)] bg-[var(--bg-surface-overlay)]">',
+    '        <Flow.Anchor type="end">',
+    '          <div class="flex h-10 items-center px-[var(--spacing-sm)] text-label-md text-[var(--text-muted)]">',
+    '            my-worker',
+    '          </div>',
+    '        </Flow.Anchor>',
+    '        <Flow.Anchor type="start">',
+    '          <div class="m-[var(--spacing-xxs)] mt-0 flex items-center gap-[var(--spacing-sm)] rounded-[var(--shape-button)] border border-[var(--border-default)] bg-[var(--bg-surface)] px-[var(--spacing-sm)] py-[var(--spacing-xxs)] text-label-md text-[var(--text-default)]">',
+    '            Bindings <span class="text-[var(--text-muted)]">2</span>',
+    '          </div>',
+    '        </Flow.Anchor>',
+    '      </div>',
+    '    </Flow.Node>',
+    '    <Flow.Parallel>',
+    '      <Flow.Node>DATABASE</Flow.Node>',
+    '      <Flow.Node>OTHER_SERVICE</Flow.Node>',
+    '    </Flow.Parallel>',
     '  </Flow>'
   ].join('\n')
 )
 
 const DISABLED_SOURCE = sfc(
-  SEQUENTIAL_IMPORTS,
   [
     '  <Flow align="center">',
-    '    <FlowList>',
-    '      <FlowNode>Source</FlowNode>',
-    '      <FlowNode disabled>Archive</FlowNode>',
-    '      <FlowNode>Deliver</FlowNode>',
-    '    </FlowList>',
+    '    <Flow.Node>Source</Flow.Node>',
+    '    <Flow.Node disabled>Archive</Flow.Node>',
+    '    <Flow.Node>Deliver</Flow.Node>',
     '  </Flow>'
   ].join('\n')
 )
@@ -61,7 +160,7 @@ const DISABLED_SOURCE = sfc(
 const meta = {
   title: 'Components/Data/Flow',
   component: Flow,
-  subcomponents: { FlowList, FlowNode, FlowParallel, FlowAnchor },
+  subcomponents: { FlowNode, FlowParallel, FlowAnchor },
   tags: ['autodocs'],
   parameters: {
     layout: 'padded',
@@ -79,7 +178,7 @@ const meta = {
     docs: {
       description: {
         component:
-          'Flow renders a directed flow diagram: a vertical sequence of steps (`flow-node`) joined by decorative connectors, with optional parallel branches (`flow-parallel`) and custom attachment points (`flow-anchor`).'
+          'Flow renders a directed flow diagram: a horizontal sequence of steps (`Flow.Node`) joined by decorative connectors, with optional parallel branches (`Flow.Parallel`) and custom connector-attachment points (`Flow.Anchor`). Steps are direct children of `Flow`; mark a node `unstyled` to let its slot content define the node entirely. Import only `Flow` and reach the parts via dot-notation.'
       },
       canvas: {
         sourceState: 'shown'
@@ -99,7 +198,7 @@ const meta = {
     },
     default: {
       control: false,
-      description: 'Diagram content: flow-list, flow-node, flow-parallel.',
+      description: 'Diagram content: Flow.Node and Flow.Parallel, in flow order.',
       table: { category: 'slots', type: { summary: 'VNode[]' } }
     }
   },
@@ -113,17 +212,15 @@ export default meta
 /** @type {import('@storybook/vue3').StoryObj<typeof Flow>} */
 export const Default = {
   render: (args) => ({
-    components: { Flow, FlowList, FlowNode },
+    components: { Flow, FlowNode },
     setup() {
       return { args }
     },
     template: `
       <Flow v-bind="args">
-        <FlowList>
-          <FlowNode>Source</FlowNode>
-          <FlowNode>Transform</FlowNode>
-          <FlowNode>Deliver</FlowNode>
-        </FlowList>
+        <FlowNode>Source</FlowNode>
+        <FlowNode>Transform</FlowNode>
+        <FlowNode>Deliver</FlowNode>
       </Flow>
     `
   }),
@@ -138,29 +235,135 @@ export const Default = {
 /** @type {import('@storybook/vue3').StoryObj<typeof Flow>} */
 export const Parallel = {
   render: (args) => ({
-    components: { Flow, FlowList, FlowNode, FlowParallel },
+    components: { Flow, FlowNode, FlowParallel },
     setup() {
       return { args }
     },
     template: `
       <Flow v-bind="args">
-        <FlowList>
-          <FlowNode>Start</FlowNode>
-          <FlowParallel>
-            <FlowNode>Validate</FlowNode>
-            <FlowNode>Transform</FlowNode>
-            <FlowNode>Cache</FlowNode>
-            <FlowNode>Index</FlowNode>
-          </FlowParallel>
-          <FlowNode>End</FlowNode>
-        </FlowList>
+        <FlowNode>Start</FlowNode>
+        <FlowParallel>
+          <FlowNode>Branch A</FlowNode>
+          <FlowNode>Branch B</FlowNode>
+          <FlowNode>Branch C</FlowNode>
+        </FlowParallel>
+        <FlowNode>End</FlowNode>
       </Flow>
     `
   }),
   parameters: {
     docs: {
       source: { code: PARALLEL_SOURCE },
-      description: { story: 'Parallel branches with junction connectors.' }
+      description: {
+        story: 'A parallel group fans out from the previous node and back into the next.'
+      }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Flow>} */
+export const Branches = {
+  render: (args) => ({
+    components: { Flow, FlowNode, FlowParallel },
+    setup() {
+      return { args }
+    },
+    template: `
+      <Flow v-bind="args">
+        <FlowParallel>
+          <FlowNode>HTTP Trigger</FlowNode>
+          <FlowNode>Cron Trigger</FlowNode>
+        </FlowParallel>
+        <FlowNode>Process Request</FlowNode>
+        <FlowParallel>
+          <FlowNode>Log Analytics</FlowNode>
+          <FlowNode>Update Cache</FlowNode>
+          <FlowNode>Send Notification</FlowNode>
+        </FlowParallel>
+        <FlowNode>Complete</FlowNode>
+      </Flow>
+    `
+  }),
+  parameters: {
+    docs: {
+      source: { code: BRANCHES_SOURCE },
+      description: {
+        story:
+          'A leading parallel fans in and a trailing parallel fans out — connectors route correctly at the edges of the sequence.'
+      }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Flow>} */
+export const CustomNodes = {
+  render: (args) => ({
+    components: { Flow, FlowNode },
+    setup() {
+      return { args }
+    },
+    template: `
+      <Flow v-bind="args">
+        <FlowNode unstyled class="size-4 rounded-full bg-[var(--border-default)]" />
+        <FlowNode>my-worker</FlowNode>
+        <FlowNode
+          unstyled
+          class="rounded-[var(--shape-card)] border border-[var(--border-default)] bg-[var(--bg-surface-raised)] px-[var(--spacing-sm)] py-[var(--spacing-xl)] text-label-md text-[var(--text-default)]"
+        >
+          Taller node
+        </FlowNode>
+      </Flow>
+    `
+  }),
+  parameters: {
+    docs: {
+      source: { code: CUSTOM_NODES_SOURCE },
+      description: {
+        story:
+          'Unstyled nodes whose slot content defines the appearance: a start dot, the default box, and a taller custom node.'
+      }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Flow>} */
+export const AnchoredNode = {
+  render: (args) => ({
+    components: { Flow, FlowNode, FlowParallel, FlowAnchor },
+    setup() {
+      return { args }
+    },
+    template: `
+      <Flow v-bind="args">
+        <FlowNode>Load balancer</FlowNode>
+        <FlowNode unstyled>
+          <div class="rounded-[var(--shape-card)] border border-[var(--border-default)] bg-[var(--bg-surface-overlay)]">
+            <FlowAnchor type="end">
+              <div class="flex h-10 items-center px-[var(--spacing-sm)] text-label-md text-[var(--text-muted)]">
+                my-worker
+              </div>
+            </FlowAnchor>
+            <FlowAnchor type="start">
+              <div class="m-[var(--spacing-xxs)] mt-0 flex items-center gap-[var(--spacing-sm)] rounded-[var(--shape-button)] border border-[var(--border-default)] bg-[var(--bg-surface)] px-[var(--spacing-sm)] py-[var(--spacing-xxs)] text-label-md text-[var(--text-default)]">
+                Bindings <span class="text-[var(--text-muted)]">2</span>
+              </div>
+            </FlowAnchor>
+          </div>
+        </FlowNode>
+        <FlowParallel>
+          <FlowNode>DATABASE</FlowNode>
+          <FlowNode>OTHER_SERVICE</FlowNode>
+        </FlowParallel>
+      </Flow>
+    `
+  }),
+  parameters: {
+    docs: {
+      source: { code: ANCHORED_SOURCE },
+      description: {
+        story:
+          'A multi-row card: the incoming connector attaches at the `end` anchor (my-worker) and the outgoing connectors leave from the `start` anchor (Bindings).'
+      }
     }
   }
 }
@@ -168,17 +371,15 @@ export const Parallel = {
 /** @type {import('@storybook/vue3').StoryObj<typeof Flow>} */
 export const Disabled = {
   render: (args) => ({
-    components: { Flow, FlowList, FlowNode },
+    components: { Flow, FlowNode },
     setup() {
       return { args }
     },
     template: `
       <Flow v-bind="args">
-        <FlowList>
-          <FlowNode>Source</FlowNode>
-          <FlowNode disabled>Archive</FlowNode>
-          <FlowNode>Deliver</FlowNode>
-        </FlowList>
+        <FlowNode>Source</FlowNode>
+        <FlowNode disabled>Archive</FlowNode>
+        <FlowNode>Deliver</FlowNode>
       </Flow>
     `
   }),
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index 20a34bc45..e67b1a1d8 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -107,11 +107,7 @@
     "./field-textarea": "./src/components/inputs/field-textarea/field-textarea.vue",
     "./dropdown": "./src/components/inputs/dropdown/dropdown.vue",
     "./select": "./src/components/inputs/select/index.ts",
-    "./flow": "./src/components/data/flow/flow.vue",
-    "./flow-anchor": "./src/components/data/flow/flow-anchor/flow-anchor.vue",
-    "./flow-list": "./src/components/data/flow/flow-list/flow-list.vue",
-    "./flow-node": "./src/components/data/flow/flow-node/flow-node.vue",
-    "./flow-parallel": "./src/components/data/flow/flow-parallel/flow-parallel.vue",
+    "./flow": "./src/components/data/flow/index.ts",
     "./scroll-area": "./src/components/layout/scroll-area/scroll-area.vue",
     "./global-header": "./src/components/layout/global-header/index.js",
     "./sidebar": "./src/components/layout/sidebar/sidebar.vue",
diff --git a/packages/webkit/src/components/data/flow/connectors.ts b/packages/webkit/src/components/data/flow/connectors.ts
index 2db79fcee..190442c24 100644
--- a/packages/webkit/src/components/data/flow/connectors.ts
+++ b/packages/webkit/src/components/data/flow/connectors.ts
@@ -1,7 +1,7 @@
 import { useMutationObserver, useResizeObserver } from '@vueuse/core'
 import { onMounted, type Ref, ref } from 'vue'
 
-export interface FlowArrow {
+export interface FlowPoint {
   x: number
   y: number
 }
@@ -11,118 +11,157 @@ export interface FlowPath {
   d: string
   /** Reduced opacity when either endpoint is a disabled node. */
   faded: boolean
-  /** Arrowhead tip position, or null when the connector feeds a parallel junction. */
-  arrow: FlowArrow | null
+  /** Arrowhead tip position, or null when the connector carries no head. */
+  arrow: FlowPoint | null
 }
 
-interface FlowItem {
+/** An attachment point on the left (incoming) or right (outgoing) edge of a node. */
+interface Endpoint {
+  x: number
+  y: number
+  disabled: boolean
+}
+
+/** Top-left origin of the measuring container, in viewport coordinates. */
+interface Origin {
   left: number
   top: number
-  right: number
-  bottom: number
-  cx: number
-  cy: number
-  kind: string
-  disabled: boolean
+}
+
+/** A direct child of the flow container: a single node or a group of parallel branches. */
+interface FlowChild {
+  /** Points where outgoing connectors originate (right edge / `start` anchors). */
+  exits: Endpoint[]
+  /** Points where incoming connectors terminate (left edge / `end` anchors). */
+  entries: Endpoint[]
 }
 
 const CORNER = 10
 
-/** Orthogonal H–V–H connector with rounded corners; straight when the row is shared.
-    `bus` pins the vertical leg to a shared x (so branches share one diverge/converge column). */
-const elbow = (fromX: number, fromY: number, toX: number, toY: number, bus?: number): string => {
+/** Orthogonal H–V–H connector with rounded corners; straight when endpoints share a row.
+    The vertical leg is pinned to `busX` so diverging/converging branches share one column. */
+const elbow = (fromX: number, fromY: number, toX: number, toY: number, busX: number): string => {
   if (Math.abs(fromY - toY) < 0.5) {
     return `M${fromX},${fromY} L${toX},${toY}`
   }
 
-  const midX = bus ?? (fromX + toX) / 2
   const dir = toY > fromY ? 1 : -1
   const radius = Math.max(
     0,
-    Math.min(CORNER, Math.abs(toY - fromY) / 2, Math.abs(midX - fromX), Math.abs(toX - midX))
+    Math.min(CORNER, Math.abs(toY - fromY) / 2, Math.abs(busX - fromX), Math.abs(toX - busX))
   )
 
   return [
     `M${fromX},${fromY}`,
-    `H${midX - radius}`,
-    `Q${midX},${fromY} ${midX},${fromY + dir * radius}`,
+    `H${busX - radius}`,
+    `Q${busX},${fromY} ${busX},${fromY + dir * radius}`,
     `V${toY - dir * radius}`,
-    `Q${midX},${toY} ${midX + radius},${toY}`,
+    `Q${busX},${toY} ${busX + radius},${toY}`,
     `H${toX}`
   ].join(' ')
 }
 
-/** Read the direct flow items in layout coordinates (offset*, so the geometry is zoom-invariant). */
-const readItems = (container: HTMLElement): FlowItem[] =>
-  Array.from(container.querySelectorAll<HTMLElement>(':scope > [data-flow-kind]')).map((el) => ({
-    left: el.offsetLeft,
-    top: el.offsetTop,
-    right: el.offsetLeft + el.offsetWidth,
-    bottom: el.offsetTop + el.offsetHeight,
-    cx: el.offsetLeft + el.offsetWidth / 2,
-    cy: el.offsetTop + el.offsetHeight / 2,
-    kind: el.dataset['flowKind'] ?? 'node',
-    disabled: el.dataset['flowDisabled'] === 'true'
-  }))
+/** Read an element's box in the container's coordinate space (scroll-invariant). */
+const measureRect = (el: HTMLElement, base: Origin) => {
+  const r = el.getBoundingClientRect()
+  return {
+    left: r.left - base.left,
+    right: r.right - base.left,
+    cy: (r.top + r.bottom) / 2 - base.top
+  }
+}
+
+/** Resolve a node's incoming (`end` anchor) and outgoing (`start` anchor) attachment points.
+    Falls back to the node's left/right edge when no matching anchor is present. */
+const readNode = (nodeEl: HTMLElement, base: Origin): { entry: Endpoint; exit: Endpoint } => {
+  const disabled = nodeEl.dataset['flowDisabled'] === 'true'
+  const endEl =
+    nodeEl.querySelector<HTMLElement>('[data-flow-anchor="end"], [data-flow-anchor="both"]') ??
+    nodeEl
+  const startEl =
+    nodeEl.querySelector<HTMLElement>('[data-flow-anchor="start"], [data-flow-anchor="both"]') ??
+    nodeEl
+  const endRect = measureRect(endEl, base)
+  const startRect = measureRect(startEl, base)
+
+  return {
+    entry: { x: endRect.left, y: endRect.cy, disabled },
+    exit: { x: startRect.right, y: startRect.cy, disabled }
+  }
+}
+
+/** Build a FlowChild from a direct container child (a node, or a parallel group of nodes). */
+const readChild = (el: HTMLElement, base: Origin): FlowChild => {
+  if (el.dataset['flowKind'] === 'parallel') {
+    const branches = Array.from(
+      el.querySelectorAll<HTMLElement>(':scope > [data-flow-kind="node"]')
+    ).map((branch) => readNode(branch, base))
+
+    return {
+      exits: branches.map((b) => b.exit),
+      entries: branches.map((b) => b.entry)
+    }
+  }
+
+  const { entry, exit } = readNode(el, base)
+  return { exits: [exit], entries: [entry] }
+}
+
+/** Pair the exits of one child with the entries of the next: 1→1, fan-out (1→N), fan-in (N→1), or zip (N→M). */
+const pairEndpoints = (exits: Endpoint[], entries: Endpoint[]): Array<[Endpoint, Endpoint]> => {
+  if (exits.length === 1) {
+    return entries.map((entry): [Endpoint, Endpoint] => [exits[0], entry])
+  }
+  if (entries.length === 1) {
+    return exits.map((exit): [Endpoint, Endpoint] => [exit, entries[0]])
+  }
+  const count = Math.min(exits.length, entries.length)
+  return Array.from({ length: count }, (_, i): [Endpoint, Endpoint] => [exits[i], entries[i]])
+}
 
 /**
- * Measures a flow container's direct items and produces the SVG connector geometry.
- * - `sequence`: links consecutive items left→right (Flow root and Flow.List).
- * - `parallel`: diverges from the left-center to each branch and converges back to the right-center.
+ * Measures a flow container's direct children and produces every connector in one SVG.
+ * Connectors are drawn only BETWEEN consecutive children, so a leading parallel fans in
+ * (no dangling left stubs) and a trailing parallel fans out, automatically.
  */
-export const useFlowConnectors = (
-  containerRef: Ref<HTMLElement | null>,
-  mode: 'sequence' | 'parallel'
-) => {
+export const useFlowConnectors = (containerRef: Ref<HTMLElement | null>) => {
   const paths = ref<FlowPath[]>([])
   const viewBox = ref<string>('0 0 0 0')
 
   const measure = () => {
     const container = containerRef.value
-
     if (!container) {
       return
     }
 
-    const width = container.clientWidth
-    const height = container.clientHeight
-    const items = readItems(container)
-    const out: FlowPath[] = []
+    const base = container.getBoundingClientRect()
+    const children = Array.from(
+      container.querySelectorAll<HTMLElement>(':scope > [data-flow-kind]')
+    ).map((el) => readChild(el, base))
 
-    if (mode === 'sequence') {
-      for (let i = 0; i < items.length - 1; i += 1) {
-        const from = items[i]
-        const to = items[i + 1]
+    const out: FlowPath[] = []
 
-        out.push({
-          d: elbow(from.right, from.cy, to.left, to.cy),
-          faded: from.disabled || to.disabled,
-          arrow: to.kind === 'parallel' ? null : { x: to.left, y: to.cy }
-        })
+    for (let i = 0; i < children.length - 1; i += 1) {
+      const from = children[i]
+      const to = children[i + 1]
+      if (!from.exits.length || !to.entries.length) {
+        continue
       }
-    } else if (items.length > 0) {
-      const centerY = height / 2
-      const minLeft = Math.min(...items.map((item) => item.left))
-      const maxRight = Math.max(...items.map((item) => item.right))
-      // Shared diverge / converge columns so every branch routes through one bus.
-      const busLeft = minLeft / 2
-      const busRight = maxRight + (width - maxRight) / 2
-
-      for (const item of items) {
-        out.push({
-          d: elbow(0, centerY, item.left, item.cy, busLeft),
-          faded: item.disabled,
-          arrow: item.kind === 'parallel' ? null : { x: item.left, y: item.cy }
-        })
+
+      const fromRight = Math.max(...from.exits.map((e) => e.x))
+      const toLeft = Math.min(...to.entries.map((e) => e.x))
+      const busX = fromRight + (toLeft - fromRight) / 2
+
+      for (const [exit, entry] of pairEndpoints(from.exits, to.entries)) {
         out.push({
-          d: elbow(item.right, item.cy, width, centerY, busRight),
-          faded: item.disabled,
-          arrow: null
+          d: elbow(exit.x, exit.y, entry.x, entry.y, busX),
+          faded: exit.disabled || entry.disabled,
+          arrow: { x: entry.x, y: entry.y }
         })
       }
     }
 
-    viewBox.value = `0 0 ${width} ${height}`
+    viewBox.value = `0 0 ${container.clientWidth} ${container.clientHeight}`
     paths.value = out
   }
 
diff --git a/packages/webkit/src/components/data/flow/flow-anchor/flow-anchor.vue b/packages/webkit/src/components/data/flow/flow-anchor/flow-anchor.vue
index 1dc36f240..624aaded3 100644
--- a/packages/webkit/src/components/data/flow/flow-anchor/flow-anchor.vue
+++ b/packages/webkit/src/components/data/flow/flow-anchor/flow-anchor.vue
@@ -9,8 +9,8 @@
     inheritAttrs: false
   })
 
-  defineProps<{
-    /** Restricts the anchor to the incoming or outgoing connector; omitted marks both. */
+  const props = defineProps<{
+    /** Which connector attaches here: `end` is the incoming endpoint, `start` the outgoing origin; omitted marks both. */
     type?: 'start' | 'end'
   }>()
 
@@ -25,21 +25,15 @@
     () => (attrs['data-testid'] as string | undefined) ?? `${ctx?.testId ?? 'data-flow'}__anchor`
   )
 
-  const rootClasses = computed(() =>
-    cn(
-      'inline-flex size-2 items-center justify-center rounded-[var(--shape-button)] bg-[var(--border-default)]',
-      attrs.class as string | undefined
-    )
-  )
+  const rootClasses = computed(() => cn('block', attrs.class as string | undefined))
 </script>
 
 <template>
-  <span
-    aria-hidden="true"
-    :data-type="type || null"
+  <div
+    :data-flow-anchor="props.type ?? 'both'"
     :data-testid="testId"
     :class="rootClasses"
   >
     <slot />
-  </span>
+  </div>
 </template>
diff --git a/packages/webkit/src/components/data/flow/flow-list/flow-list.vue b/packages/webkit/src/components/data/flow/flow-list/flow-list.vue
deleted file mode 100644
index 9bac6616a..000000000
--- a/packages/webkit/src/components/data/flow/flow-list/flow-list.vue
+++ /dev/null
@@ -1,71 +0,0 @@
-<script setup lang="ts">
-  import { computed, inject, ref, useAttrs } from 'vue'
-
-  import { cn } from '../../../../utils/cn'
-  import { useFlowConnectors } from '../connectors'
-  import { FlowInjectionKey } from '../injection-key'
-
-  defineOptions({
-    name: 'FlowList',
-    inheritAttrs: false
-  })
-
-  defineSlots<{
-    default(): unknown
-  }>()
-
-  const attrs = useAttrs()
-  const ctx = inject(FlowInjectionKey)
-
-  const testId = computed<string>(
-    () => (attrs['data-testid'] as string | undefined) ?? `${ctx?.testId ?? 'data-flow'}__list`
-  )
-
-  const containerRef = ref<HTMLElement | null>(null)
-  const { paths, viewBox } = useFlowConnectors(containerRef, 'sequence')
-
-  const rootClasses = computed(() =>
-    cn(
-      'relative flex flex-row items-center gap-[var(--spacing-xl)]',
-      attrs.class as string | undefined
-    )
-  )
-</script>
-
-<template>
-  <div
-    ref="containerRef"
-    role="presentation"
-    data-flow-kind="list"
-    :data-testid="testId"
-    :class="rootClasses"
-  >
-    <svg
-      v-if="paths.length"
-      :viewBox="viewBox"
-      preserveAspectRatio="none"
-      fill="none"
-      aria-hidden="true"
-      class="pointer-events-none absolute inset-0 h-full w-full overflow-visible"
-    >
-      <template
-        v-for="(path, index) in paths"
-        :key="index"
-      >
-        <path
-          :d="path.d"
-          stroke-width="1"
-          class="stroke-[var(--border-default)]"
-          :class="{ 'opacity-50': path.faded }"
-        />
-        <polygon
-          v-if="path.arrow"
-          :points="`${path.arrow.x - 7},${path.arrow.y - 4} ${path.arrow.x},${path.arrow.y} ${path.arrow.x - 7},${path.arrow.y + 4}`"
-          class="fill-[var(--border-default)]"
-          :class="{ 'opacity-50': path.faded }"
-        />
-      </template>
-    </svg>
-    <slot />
-  </div>
-</template>
diff --git a/packages/webkit/src/components/data/flow/flow-list/package.json b/packages/webkit/src/components/data/flow/flow-list/package.json
deleted file mode 100644
index a4eeb0816..000000000
--- a/packages/webkit/src/components/data/flow/flow-list/package.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "main": "./flow-list.vue",
-  "module": "./flow-list.vue",
-  "types": "./flow-list.vue.d.ts",
-  "browser": {
-    "./sfc": "./flow-list.vue"
-  },
-  "sideEffects": [
-    "*.vue"
-  ]
-}
diff --git a/packages/webkit/src/components/data/flow/flow-node/flow-node.vue b/packages/webkit/src/components/data/flow/flow-node/flow-node.vue
index 91c66ff76..96be6df74 100644
--- a/packages/webkit/src/components/data/flow/flow-node/flow-node.vue
+++ b/packages/webkit/src/components/data/flow/flow-node/flow-node.vue
@@ -9,13 +9,16 @@
     inheritAttrs: false
   })
 
-  withDefaults(
+  const props = withDefaults(
     defineProps<{
       /** Marks the step as disabled; adjacent connectors render at reduced opacity. */
       disabled?: boolean
+      /** Drops the default node box so the slot content defines the node's appearance. */
+      unstyled?: boolean
     }>(),
     {
-      disabled: false
+      disabled: false,
+      unstyled: false
     }
   )
 
@@ -32,7 +35,7 @@
 
   const rootClasses = computed(() =>
     cn(
-      'relative z-[1] inline-flex min-h-10 items-center justify-center whitespace-nowrap rounded-[var(--shape-button)] border border-[var(--border-default)] bg-[var(--bg-surface-raised)] px-[var(--spacing-md)] py-[var(--spacing-sm)] text-label-md text-[var(--text-default)] data-[disabled]:text-[var(--text-disabled)] data-[disabled]:opacity-60',
+      'relative z-[1] text-label-md text-[var(--text-default)] data-[styled]:inline-flex data-[styled]:min-h-10 data-[styled]:items-center data-[styled]:justify-center data-[styled]:whitespace-nowrap data-[styled]:rounded-[var(--shape-button)] data-[styled]:border data-[styled]:border-[var(--border-default)] data-[styled]:bg-[var(--bg-surface-raised)] data-[styled]:px-[var(--spacing-md)] data-[styled]:py-[var(--spacing-sm)] data-[disabled]:text-[var(--text-disabled)] data-[disabled]:opacity-60',
       attrs.class as string | undefined
     )
   )
@@ -44,6 +47,7 @@
     data-flow-kind="node"
     :data-flow-disabled="disabled ? 'true' : null"
     :data-disabled="disabled || null"
+    :data-styled="props.unstyled ? null : ''"
     :aria-disabled="disabled || undefined"
     :data-testid="testId"
     :class="rootClasses"
diff --git a/packages/webkit/src/components/data/flow/flow-parallel/flow-parallel.vue b/packages/webkit/src/components/data/flow/flow-parallel/flow-parallel.vue
index f24c593ad..cab6bc827 100644
--- a/packages/webkit/src/components/data/flow/flow-parallel/flow-parallel.vue
+++ b/packages/webkit/src/components/data/flow/flow-parallel/flow-parallel.vue
@@ -1,8 +1,7 @@
 <script setup lang="ts">
-  import { computed, inject, ref, useAttrs } from 'vue'
+  import { computed, inject, useAttrs } from 'vue'
 
   import { cn } from '../../../../utils/cn'
-  import { useFlowConnectors } from '../connectors'
   import { FlowInjectionKey } from '../injection-key'
 
   defineOptions({
@@ -10,15 +9,10 @@
     inheritAttrs: false
   })
 
-  withDefaults(
-    defineProps<{
-      /** Horizontal alignment of the parallel branches: `start` left-aligns, `end` right-aligns. */
-      align?: 'start' | 'end'
-    }>(),
-    {
-      align: 'start'
-    }
-  )
+  defineProps<{
+    /** Horizontal alignment of the parallel branches: `start` left-aligns, `end` right-aligns. */
+    align?: 'start' | 'end'
+  }>()
 
   defineSlots<{
     default(): unknown
@@ -31,12 +25,9 @@
     () => (attrs['data-testid'] as string | undefined) ?? `${ctx?.testId ?? 'data-flow'}__parallel`
   )
 
-  const containerRef = ref<HTMLElement | null>(null)
-  const { paths, viewBox } = useFlowConnectors(containerRef, 'parallel')
-
   const rootClasses = computed(() =>
     cn(
-      'relative flex flex-col gap-[var(--spacing-md)] px-[var(--spacing-xl)] data-[align=start]:items-start data-[align=end]:items-end',
+      'flex flex-col gap-[var(--spacing-md)] data-[align=start]:items-start data-[align=end]:items-end',
       attrs.class as string | undefined
     )
   )
@@ -44,39 +35,12 @@
 
 <template>
   <div
-    ref="containerRef"
     role="group"
     data-flow-kind="parallel"
-    :data-align="align"
+    :data-align="align ?? 'start'"
     :data-testid="testId"
     :class="rootClasses"
   >
-    <svg
-      v-if="paths.length"
-      :viewBox="viewBox"
-      preserveAspectRatio="none"
-      fill="none"
-      aria-hidden="true"
-      class="pointer-events-none absolute inset-0 h-full w-full overflow-visible"
-    >
-      <template
-        v-for="(path, index) in paths"
-        :key="index"
-      >
-        <path
-          :d="path.d"
-          stroke-width="1"
-          class="stroke-[var(--border-default)]"
-          :class="{ 'opacity-50': path.faded }"
-        />
-        <polygon
-          v-if="path.arrow"
-          :points="`${path.arrow.x - 7},${path.arrow.y - 4} ${path.arrow.x},${path.arrow.y} ${path.arrow.x - 7},${path.arrow.y + 4}`"
-          class="fill-[var(--border-default)]"
-          :class="{ 'opacity-50': path.faded }"
-        />
-      </template>
-    </svg>
     <slot />
   </div>
 </template>
diff --git a/packages/webkit/src/components/data/flow/flow.vue b/packages/webkit/src/components/data/flow/flow.vue
index 4e7743385..ff914e18d 100644
--- a/packages/webkit/src/components/data/flow/flow.vue
+++ b/packages/webkit/src/components/data/flow/flow.vue
@@ -29,7 +29,7 @@
   const testId = computed<string>(() => (attrs['data-testid'] as string | undefined) ?? 'data-flow')
 
   const containerRef = ref<HTMLElement | null>(null)
-  const { paths, viewBox } = useFlowConnectors(containerRef, 'sequence')
+  const { paths, viewBox } = useFlowConnectors(containerRef)
 
   provide(FlowInjectionKey, {
     testId: testId.value,
diff --git a/packages/webkit/src/components/data/flow/index.ts b/packages/webkit/src/components/data/flow/index.ts
new file mode 100644
index 000000000..43c9887d5
--- /dev/null
+++ b/packages/webkit/src/components/data/flow/index.ts
@@ -0,0 +1,18 @@
+import FlowRoot from './flow.vue'
+import FlowAnchor from './flow-anchor/flow-anchor.vue'
+import FlowNode from './flow-node/flow-node.vue'
+import FlowParallel from './flow-parallel/flow-parallel.vue'
+
+interface FlowStatic {
+  Node: typeof FlowNode
+  Parallel: typeof FlowParallel
+  Anchor: typeof FlowAnchor
+}
+
+const Flow = FlowRoot as typeof FlowRoot & FlowStatic
+Flow.Node = FlowNode
+Flow.Parallel = FlowParallel
+Flow.Anchor = FlowAnchor
+
+export default Flow
+export { FlowAnchor, FlowNode, FlowParallel }
diff --git a/packages/webkit/src/components/data/flow/package.json b/packages/webkit/src/components/data/flow/package.json
index 5078c3c52..309935a0a 100644
--- a/packages/webkit/src/components/data/flow/package.json
+++ b/packages/webkit/src/components/data/flow/package.json
@@ -1,7 +1,7 @@
 {
-  "main": "./flow.vue",
-  "module": "./flow.vue",
-  "types": "./flow.vue.d.ts",
+  "main": "./index.ts",
+  "module": "./index.ts",
+  "types": "./index.d.ts",
   "browser": {
     "./sfc": "./flow.vue"
   },