breadboarding

name: breadboarding description: Transform a workflow description into affordance tables showing UI and Code affordances with their wiring. Use to map existing Dialtone systems, design new features from shaped parts, or slice breadboards into vertical implementation increments. Tables are the truth; Mermaid diagrams are optional visualizations.

Breadboarding

Breadboarding transforms a workflow description into a complete map of affordances and their relationships. The output is always a set of tables showing numbered UI and Code affordances with their Wires Out and Returns To relationships. The tables are the truth. Mermaid diagrams are optional visualizations for humans.

Use Cases

1. Mapping an Existing Dialtone System

You don't understand how an existing Dialtone feature works in its concrete details. You have a workflow you're trying to understand.

Input:

• Dialtone source files to analyze
• Workflow description (from the perspective of a consumer or contributor trying to accomplish something)

Output:

• UI Affordances table (Vue components, props, slots, events, CSS classes)
• Code Affordances table (composables, validators, build scripts, token transforms)
• (Optional) Mermaid visualization

Dialtone-specific guidance: Trace through Dialtone's package layers:

DOCUMENTATION LAYER (VuePress pages, Storybook stories)
    |
COMPONENT LAYER (Vue 3 SFCs, composables, validators)
    |
CSS LAYER (Less utilities, component styles)
    |
TOKEN LAYER (JSON → CSS custom properties → platform outputs)

2. Designing from Shaped Parts

You have a new feature sketched as an assembly of parts (mechanisms) per /shaping. You need to detail out the concrete mechanism and show how those parts interact as a system.

Input:

• Parts list (mechanisms from shaping)
• The R (requirement/outcome) the parts are meant to achieve
• Existing Dialtone system (optional) — if the new parts must interoperate with existing code

Output:

• UI Affordances table
• Code Affordances table
• (Optional) Mermaid visualization

Mixtures

Often you have both: an existing Dialtone system that must remain as-is, plus new pieces or changes defined in a shape. In this case, breadboard both together — the existing affordances and the new ones — showing how they connect.

Core Concepts

Places

A Place is a bounded context of interaction. While you're in a Place:

• You have a specific set of affordances available to you
• You cannot interact with affordances outside that boundary
• You must take an action to leave

Place is perceptual, not technical. It's not about Vue routes or package boundaries — it's about what the user experiences as their current context.

The Blocking Test

The simplest test for whether something is a different Place: Can you interact with what's behind?

Dialtone-Specific Place Examples

Labeling Conventions

Place IDs

Each Place gets an ID:

Affordances

Things you can act upon:

• UI affordances (U): Vue component props, slots, events, CSS classes, Storybook controls
• Code affordances (N): Composables, validators, build scripts, token transforms, computed properties

Wiring

How affordances connect to each other:

Wires Out — What an affordance triggers or calls (control flow):

• Emit wires: component emits event to parent
• Build wires: token JSON feeds into CSS build
• Prop wires: parent passes prop to child component
• Slot wires: parent injects content into child slot

Returns To — Where an affordance's output flows (data flow):

• Computed wires: computed property returns to template
• Token wires: CSS custom property consumed by utility class
• Expose wires: component exposes method via defineExpose

The Output: Affordance Tables

The tables are the truth. Every breadboard produces these:

Places Table

UI Affordances Table

Code Affordances Table

Data Stores Table

Column Definitions

Procedures

For Mapping an Existing Dialtone System

Step 1: Identify the flow to analyze

Pick a specific journey:

• "Consumer adds DtButton to their app, sets size and kind props, handles click"
• "Contributor adds a new token, builds, sees it appear as a CSS variable and utility class"
• "User visits docs page, sees live component example, copies code snippet"

Step 2: List all places involved

Walk through the journey and identify each distinct Place.

Step 3: Trace through the code to find components

Starting from the entry point, trace through:

1. Vue component (template + script setup, props, emits)
2. Composables used by the component
3. CSS classes applied (from dialtone-css)
4. Tokens consumed (CSS custom properties)
5. Build pipeline steps (gulp, style-dictionary, Nx)

Step 4: For each component, list its affordances

Read the code. Identify:

• UI: What props, slots, and events does the component expose?
• Code: What composables, validators, computed properties are involved?

Step 5: Name the actual thing, not an abstraction

If you write "STYLE", stop. What's the actual class? (.d-btn--primary). Every affordance name must be something real you can point to in the code.

Step 6-8: Fill in Control, Wires Out, Returns To

For each affordance, trace the actual code paths.

Step 9: Add data stores as affordances

In Dialtone, data stores include:

• Token JSON files (source of truth)
• Generated CSS/Less variables
• Component documentation JSON (component-documentation.json)
• MCP server data (packages/dialtone-mcp-server/src/data.ts)

Step 10: Add framework mechanisms as affordances

Include Vue reactivity mechanisms that bridge code and UI:

• computed() properties that transform props
• watch() / watchEffect() that trigger side effects
• provide() / inject() that pass context down the tree

Step 11: Verify against the code

Read the code again. Confirm every affordance exists and the wiring matches reality.

For Designing from Shaped Parts

Step 1: List each part from the shape

Take each mechanism/part identified in /shaping and write it down.

Step 2: Translate parts into Dialtone affordances

For each part, identify:

• What Vue components does this part require? (new or existing)
• What composables implement this part?
• What CSS classes or tokens are needed?
• What documentation pages need to exist?

Step 3: Verify every U has a supporting N

For each UI affordance, check: what Code affordance provides its data or behavior? If none exists, add the missing N.

Step 4: Classify places as existing or new

For each affordance, determine whether it lives in an existing Dialtone package or requires new additions.

Step 5: Wire the affordances

Fill in Wires Out and Returns To. Trace the intended behavior through Dialtone's package layers.

Step 6: Connect to existing system

Identify existing Dialtone components and utilities the new affordances must connect to. Add those existing affordances to your tables.

Step 7: Check for completeness

• Every U should have an N that feeds it
• Every N should have either Wires Out or Returns To (or both)
• Every new token should flow through the build to a CSS variable
• Every new component should have corresponding docs and stories
• Cross-package dependencies should follow the dependency graph: tokens → CSS → Vue → docs

Key Principles

Never use memory — always check the data

When tracing a flow, scan the Wires Out column for ALL affordances that wire to your target. The tables are the source of truth.

Every affordance name must exist (when mapping)

When mapping existing Dialtone code, never invent abstractions. Every name must point to something real — a Vue component, a CSS class, a token name, a build script.

Mechanisms aren't affordances

An affordance is something you can act upon with meaningful identity. Skip:

• Layout wrappers (DtStack used purely for spacing)
• Internal build intermediaries (temporary generated files)
• Import/export boilerplate

Dialtone-Specific: The Build Pipeline Is the Bridge

The build pipeline (Nx tasks, gulp, style-dictionary) is the critical bridge between tokens and consumable output. Always show build steps explicitly — they're where token values become CSS custom properties and utility classes.

Two flows: Consumer and Contributor

Every component prop that renders needs a style source

A UI affordance that renders styled content must trace back to a CSS class or token. If a prop changes visual appearance but has no CSS backing, something is missing.

Visualization (Mermaid)

Line Conventions

ID Prefixes

Color Conventions

classDef ui fill:#ffb6c1,stroke:#d87093,color:#000
classDef nonui fill:#d3d3d3,stroke:#808080,color:#000
classDef store fill:#e6e6fa,stroke:#9370db,color:#000
classDef chunk fill:#b3e5fc,stroke:#0288d1,color:#000,stroke-width:2px

Slicing a Breadboard

Slicing takes a breadboard and groups its affordances into vertical implementation slices.

What is a Vertical Slice?

A vertical slice is a group of UI and Code affordances that does something demo-able. It cuts through all Dialtone layers (tokens, CSS, Vue component, docs) to deliver a working increment.

The opposite is a horizontal slice — doing work on one layer (e.g., "define all the tokens first") that isn't visible as a usable component.

The Key Constraint

Every slice must have visible UI that can be demoed. A slice without UI is a horizontal layer, not a vertical slice.

• Good: "Button renders with size variants in Storybook" (demo: open story, see sizes)
• Bad: "Add all token values" (no demo possible in isolation)

Slice Size

• Too small: Only 1-2 UI affordances, no meaningful demo -> merge with related slice
• Too big: 15+ affordances or multiple unrelated journeys -> split
• Right size: A coherent journey with a clear "watch me do this" demo
• Max 9 slices. If you need more, the shape may be too large for one cycle.

Procedure

Step 1: Identify the minimal demo-able increment

Ask: "What's the smallest subset that demonstrates the core mechanism working?"

Usually: basic component rendering with one key prop. No variants, no edge cases yet.

This becomes V1.

Step 2: Layer additional capabilities as slices

Each slice demonstrates a mechanism working:

• V2: Prop variants (demonstrates the configuration surface)
• V3: Interactive behavior (demonstrates event handling)
• V4: Accessibility (demonstrates keyboard/screen-reader support)
• V5: Documentation (demonstrates consumer guidance)
• etc.

Step 3: Assign affordances to slices

Go through every affordance and assign it to the slice where it's first needed.

Step 4: Create per-slice affordance tables

For each slice, extract just the affordances being added.

Step 5: Write a demo statement for each slice

Each slice needs a concrete demo:

• V1: "Component renders with default props in Storybook"
• V2: "All size and kind variants visible in stories"
• V3: "Click handler fires, keyboard navigation works"
• V4: "Screen reader announces component role and state"
• V5: "Docs page shows usage, props table, and live examples"

Mapping Slices to Dialtone PRs

Each slice should correspond to one PR:

Visualizing Slices in Mermaid

Show the complete breadboard in every slice diagram, but use styling to distinguish scope:

Dialtone Architecture Mapping Reference

When breadboarding Dialtone features, map affordances to these layers:

Component Layer (U + N affordances)

CSS Layer (N affordances)

Token Layer (N + S affordances)

Build Pipeline (N affordances)

Documentation Layer (U + S affordances)