How to write a component spec

How-To Write specs by level Intermediate 1051007HOWTO-1051007

HOWTO-1051007Write specs by levelIntermediate

This guide shows you how to write a SpecDD component spec for a spec-driven development workflow.

A component spec describes UI component behavior: inputs, rendered output, interactions, local state, events, and boundaries. It should keep UI responsibilities clear without turning the component into a full feature spec.

Short answer

Use a component spec for one UI component or small local component family. Define what the component owns, what props or state it accepts, what it renders or exposes, which interactions it handles, what it must not do, and which scenarios or checks prove important behavior.

When to use this guide

Use this guide when:

a component has meaningful behavior
props and state are misunderstood
UI changes keep leaking data or service logic into the component
interaction behavior needs review
agents overbuild component changes

Steps

1. Choose one component boundary

Examples:

itinerary-card.sdd
itinerary-card.component.sdd
TripDayList.sdd

Use suffixes only when they clarify the role.

2. Own the component and checks

Owns:
  ./itinerary-card.tsx
  ./itinerary-card.test.tsx

If visual fixtures or stories are writable, list them in Can modify or Owns deliberately.

3. Define accepted props or state

Accepts:
  itinerary item with place name and trip day
  selected state
  move-place callback

Use the project’s real prop names or symbols when useful.

4. Describe visible behavior

Must:
  Show the place name.
  Show the trip day.
  Call the move-place callback when the person chooses another day.

Keep component rules observable.

5. Block non-component responsibilities

Must not:
  Persist itinerary changes directly.
  Fetch destination search results.
  Decide booking availability.

Components can display or request actions without owning service and adapter behavior.

6. Add interaction scenarios

Scenario: move place
  Given the itinerary card shows "Louvre Museum"
  When the person moves it to June 13
  Then the move-place callback receives June 13

This guides implementation and tests.

Complete example

Spec: Itinerary Card

Purpose:
  Show one itinerary item and let the person request local item actions.

Owns:
  ./itinerary-card.tsx
  ./itinerary-card.test.tsx

Accepts:
  itinerary item with place name and trip day
  selected state
  move-place callback

Returns:
  visible itinerary card state

Must:
  Show the place name.
  Show the trip day.
  Call the move-place callback when the person chooses another day.

Must not:
  Persist itinerary changes directly.
  Fetch destination search results.
  Decide booking availability.

Scenario: move place
  Given the itinerary card shows "Louvre Museum"
  When the person moves it to June 13
  Then the move-place callback receives June 13

Common mistakes

Putting feature-wide behavior in one component spec.
Letting the component fetch or persist data directly when a service owns that.
Describing CSS implementation details instead of visible behavior.
Forgetting interaction scenarios for user actions.
Listing parent or child components as owned when they are only rendered or read.

How to verify the result

The component spec is useful when:

props or inputs are clear
visible behavior is reviewable
interactions have scenarios
service, storage, and feature responsibilities stay outside the component
component tests can trace to the spec

Language reference

← Write specs by level guides