A mobile app design system should explain how reusable components behave, which states they represent and how those choices translate into the intended platforms. Start with the actions people need to perform, then document appearance, labels and interaction evidence together. A library of polished default screens leaves important decisions unfinished if errors, unavailable actions and accessibility semantics are missing.
What should a component contract describe?
Android’s Compose guide describes buttons as components that trigger a defined action. The Android Compose button guide offers a concrete component example for a broader design-system discussion. Keep the platform-specific implementation attached to its source rather than assuming another platform uses the same API.
For a hypothetical appointment app, define one reusable action called Confirm booking. Write down what the person intends, which information must be available and what the interface should show while the request is unresolved. This example is a proposed design exercise, not a report of an implemented booking service.
Give the component a purpose statement, a label rule and an owner. Add the context in which it may appear and the related action that allows the person to leave or revise the choice. Those details help a designer decide whether an existing component is appropriate for a new screen.
Keep visual tokens connected to meaning. If colour, spacing or emphasis changes, record which component decision it serves. The design-system record should help a colleague make a consistent choice instead of asking them to memorise a screenshot.
Which states need an explicit decision?
The Compose button guide identifies onClick as the function called when a button is pressed. Treat the press event as the beginning of the proposed booking request. Specify what the person should see until the application knows its outcome, and what evidence the implementation will use to present completion.
Setting enabled to false makes the documented Compose button unavailable and inactive. Ask the designer to explain when unavailability is appropriate and how the person learns what to do next. Include that explanation beside the state specimen. A greyed control alone does not answer the task question in the requirements brief.
Create specimens for a ready action, an action awaiting required information, an unresolved request and a recoverable error. Use realistic labels and messages in the design file. Ask the product owner to review the intended next step in each state before implementation begins.
When an error can be corrected, specify which input should remain available and where the explanation belongs. Use the same booking scenario throughout so the team can assess a coherent sequence rather than unrelated state samples.
How should action hierarchy work?
The Compose guide describes outlined buttons as medium-emphasis choices for secondary actions. The Compose guide describes text buttons as displaying text without a background or border. Use those documented distinctions to discuss the hierarchy in the Android implementation, then make an explicit choice for the actual task.
For Confirm booking, identify the main action and the route for changing details. Ask a reviewer to find both without receiving a verbal explanation. Keep the observation with the component record and use it to refine labels or emphasis where needed.
Do not make every action equally prominent merely because the component library offers several attractive variants. Write down the reason a variant is chosen and what relationship it expresses to the neighbouring controls. A shared rule makes future screens easier to assess.
For another platform, retain the task meaning and assess the appropriate native interaction separately. The system can document a common intent while allowing an implementation-specific presentation. Record deliberate differences, including the owner who approved them and the task conditions that justify them.
What accessibility information belongs with the specimen?
Android recommends a touch target of at least 48dp by 48dp for interactive touch elements. Android says custom interactive elements need their target size set by the developer. The Android accessibility guide gives the implementer a specific target-area question to assess rather than relying only on the visible icon size.
Android advises descriptions that communicate the purpose and result of an interaction. Put the intended accessible name beside the visual label in the component record. For an icon action, ask what the person should understand when the visual shape is unavailable. Assess the announced result in the implemented interface using the agreed assistive-technology method.
Android says Text composables do not need a contentDescription because accessibility services announce their text. Apply that guidance in its Android context and inspect the resulting announcement. Avoid adding redundant words simply to fill a specification field. The acceptance observation should describe what the user actually encounters.
Android recommends marking purely decorative elements so accessibility services can ignore them. Distinguish a decorative mark from an icon that performs an action or conveys necessary information. Have the reviewer assess that decision in context, including the surrounding text, rather than classifying all images the same way.
How can design and implementation stay connected?
Use this original component-state contract to prepare a handoff. It connects the task meaning to the visual specimen, implementation question and evidence needed for review.
| Contract element | Booking example | Evidence to inspect |
|---|---|---|
| Purpose | Confirm the selected booking request | Task description and chosen label |
| Readiness | Required information is available | State rule and implemented conditions |
| Pending work | Request outcome remains unresolved | Proposed feedback and observed sequence |
| Correction | Person can address a named issue | Error explanation and retained input |
| Hierarchy | Confirm or revise the details | Component variants in their screen context |
| Accessible meaning | Action is understandable without its visual shape | Announced label and interaction observation |
| Platform variation | Same intent with an appropriate implementation | Recorded reason for the deliberate difference |
Include one deliberately awkward label in the specimen set, such as a longer action translated for an intended audience. Ask the designer to show how the component preserves its meaning when the label wraps, rather than silently shortening away the important verb.
Give each released component example a revision reference. When a behaviour changes, ask which screens use that component and which state observations need repeating. Keep the old decision understandable so a developer investigating an earlier screen can see its basis.
Include a small working example in the development review, not only a static design specimen. Ask the reviewer to move through the booking states and record the observed labels, focus and feedback. Assign any discrepancy to a specific component rule or implementation issue.
The useful handoff is a shared account of what the component means and how that meaning is assessed. For the application scope, see web development or send Spout a representative task and its component states.
By Spout Team. AI-assisted drafting by Codex using the linked primary documentation.