# Block diagrams

Two parts: `BlockDiagram` is the canvas and `Block` is a node on it. A block
holds blocks, so the diagram nests as deep as the thing it describes without a
second component per level. Layout is CSS grid, the page ships no script, and
containment is the default relationship. Use `flow="sequence"` for a short
ordered process; its connectors turn downward when the stages stack on mobile.
Branches and loops belong in [Diagrams](https://ambiqai.github.io/helia-ui/diagrams/).

## A flat row

Five peers on one line. `flow="row"` is the default, and a row stacks to one
column below 42rem, which is where five labels stop fitting on a phone.

Capture path: Five stages, each one a peer of the others.

- Probe
- Sampler
- Decoder
- Aligner
- Report
```mdx
<BlockDiagram
  title="Capture path"
  caption="Five stages, each one a peer of the others."
>
  <Block label="Probe" />
  <Block label="Sampler" />
  <Block label="Decoder" />
  <Block label="Aligner" />
  <Block label="Report" />
</BlockDiagram>
```

## Nesting

A `Block` with children draws them in a set of its own. The children are more
`Block`s, so the whole diagram is one `<figure>` holding nested lists and a
screen reader walks the hierarchy the page draws. The ground steps at each
level, and the step is read off the markup rather than declared, so a subtree
moved a level in or out takes the ground of where it lands.

Pipeline with substeps: Two levels. Each stage names what it is made of.

- Ingest: Two sources
  - Reader
  - Validator
- Transform: Pure functions
  - Normalize
  - Resample
  - Window
- Publish: One writer
  - Encoder
  - Store
```mdx
<BlockDiagram title="Pipeline with substeps" flow="row">
  <Block label="Ingest" sublabel="Two sources">
    <Block label="Reader" emphasis="filled" />
    <Block label="Validator" emphasis="filled" />
  </Block>
</BlockDiagram>
```

### Plain ladder

Three levels with no tone and no emphasis. The ground steps with depth and the
second line keeps its contrast at the bottom of the ladder.

A plain ladder: Level one holds level two holds level three.

- System: Level one
  - Subsystem: Level two
    - Component: Level three
    - Component: Level three
  - Subsystem: Level two
- System: Level one

### A filled parent

A filled block can hold blocks. The children start the ladder again with their
own edge, so the filled ground is the parent's alone.

Filled parent

- Runtime
  - Scheduler
  - Allocator: arena
- Host

## Three levels, with links

The same part three deep. The labels here are this package, so every link goes
to the page that documents the block it names. `tone="accent"` takes the
product color of whatever subtree it sits in, which is the
`data-helia-accent` attribute a product site already sets.

helia-ui: System, subsystems, and what each one is made of.

- Style layers: Three sheets
  - [Tokens](https://ambiqai.github.io/helia-ui/foundations/tokens/)
  - [Semantic](https://ambiqai.github.io/helia-ui/foundations/)
  - [Recipes](https://ambiqai.github.io/helia-ui/primitives/)
- Astro parts: Ship no script
  - Primitives
    - Surface
    - Chip
  - Composites
    - [Cards](https://ambiqai.github.io/helia-ui/cards/)
    - [Layout](https://ambiqai.github.io/helia-ui/layout/)
- React islands: Hydrated on request
  - [Inputs](https://ambiqai.github.io/helia-ui/react/inputs/)
  - [Overlays](https://ambiqai.github.io/helia-ui/react/overlays/)
  - Proposed

## The variants

Each block below is labeled with the prop that draws it.

Tone

- Neutral: tone default
- Muted: tone="muted"
- Accent: tone="accent"

Emphasis

- Outline: emphasis default
- Filled: emphasis="filled"
- Dashed: emphasis="dashed"

Span and icons

- Wide: span=
- Plain
- Plain

Density and ground: density="compact" on a tone="muted" canvas.

- One
  - Inner
- Two
  - Inner
- Three
  - Inner

## What belongs in a label

One to three words. The box was drawn to be taken in at a glance, and a block
carrying a sentence is a card that has lost its frame. A qualifier that will
not fit in the name goes in `sublabel`, on its own line and in the muted ink,
where it stays out of the way of the shape.

## Ordered stages

`flow="sequence"` uses an ordered list and connects only its top-level stages.
Keep labels short; nested blocks still describe what each stage contains.

Build workflow

1. Input: Model and configuration
2. Compile: Plan and generate
3. [Output](https://ambiqai.github.io/helia-ui/getting-started/): Integrate generated code

## Diagrams within a section

Build stages

1. Input
2. Compile
3. OutputChoose an integration format.

- CMake
- CMSIS-Pack

A plain landing section keeps the same prose spacing.

- Source files
- Build files