From design system to frontend: define the component contract

Document the decision the component supports

Begin with purpose. A selectable scene card helps someone choose an object; a command button changes that object. Putting both behaviours into a clickable rectangle without distinguishing them makes the component harder to understand and test. Name the primary action and identify any independent secondary action before deciding on a reusable API.

This also helps determine what belongs outside the component. A card may show that an operation is pending without owning the request, permission rules or retry policy. Keep those decisions in the feature layer and give the visual component a small, explicit set of values and callbacks. Reuse is easier when responsibilities are visible.

Build a state table before adding variants

List meaningful states such as available, selected, processing and unavailable. For each, specify visible content, permitted actions and the transition that follows an action. Check whether combinations are valid. A card that appears selected and unavailable at the same time may be correct, but the design needs to explain what selection still means.

Do not model each visual difference as a separate boolean merely because that is convenient initially. Contradictory flags create combinations no one designed. React's state-structure guidance helps identify redundant state, while the product team must still define the valid transitions. A shared component cannot resolve an undefined product rule on its own.

Treat content as part of the layout contract

Use examples that stress the design: a long project title, a translated action, an empty thumbnail and a message spanning several lines. Specify what wraps, what truncates and where the full value remains available. A short English label is not a reliable proxy for all content the product will carry.

Decide which dimensions are fixed because of meaning and which should adapt. The aspect ratio of a media preview may be meaningful; the height of an explanatory paragraph usually is not. Document the narrow layout with the same real content used on desktop. Otherwise the implementation review becomes a negotiation over assumptions made in separate tools.

Include keyboard and focus in the handoff

For a control that opens a dialog, describe where focus goes, how the dialog closes and where focus returns. The W3C dialog pattern provides a foundation for these interactions. Starting with an established primitive can reduce implementation work, but the composed feature still needs verification with its real content and neighbouring controls.

Use semantic elements for their intended action. A link navigates; a button operates an interface. When a visual design makes them look similar, retain the distinction in the underlying markup. Specify an accessible name for icon-only controls and make the focus treatment part of the design, rather than a browser artefact to remove at the end.

Review the contract at its consumers

A component may pass an isolated demonstration and still fail inside a sticky toolbar or a translated settings panel. Review at least the contexts whose constraints differ materially. When changing an existing shared component, identify those consumers before editing its dimensions or interaction model.

A compact delivery note can contain purpose, valid states, content limits, keyboard behaviour and representative usages. This is often more useful than an exhaustive catalogue of visual variants. The result is a shared agreement about behaviour that can be checked in code review, design review and a real task.

• One clear primary responsibility.
• Valid state combinations and transitions.
• Long, empty and translated content examples.
• Keyboard behaviour and representative consumers.