Component Anatomy and API Design

The tangible win

After this lesson, you should be able to design a component API that exposes product decisions, hides implementation details, and still allows real product work.

Component anatomy

Before naming props, map the anatomy. For a text field, the parts may be:

• Label — what the field means.
• Input — where the user enters data.
• Placeholder — optional example, not a replacement for label.
• Helper text — guidance before action.
• Error text — recovery message after validation fails.
• Affixes or icons — prefix, suffix, clear button, status icon.

Anatomy prevents random additions. If a requested feature has no place in the anatomy, pause and ask whether the component or the pattern is wrong.

Backend analogy: public API vs internals

A weak component exposes implementation:

<TextInput labelColor="#666" borderColor="red" marginBottom="12px" />

A stronger component exposes product meaning:

<TextInput
  label="Email"
  hint="Use your work email."
  error={emailError}
  required
/>

The system decides colors, spacing, focus rings, and error styling. The product team supplies meaning, validation, and content.

Four API design rules

Practice: choose the better prop

A designer asks for an input with an error message. Which API is better?

API smell tests

• If many props are raw colors, spacing, or CSS names, the API is leaking internals.
• If every product request creates a new boolean, the API is becoming boolean soup.
• If props can create inaccessible states, defaults are not protective enough.
• If usage requires reading source code, documentation is part of the missing API.

Read next

Skim Carbon and Material text input docs. Notice that strong systems document anatomy, states, behavior, and usage guidance—not just visual examples.