Skip to content

Design principles

Design around the task, make relationships clear and preserve familiar interaction.

Start with the task

Make the useful content or action easy to reach. A settings page should expose the settings; a component example should be ready to try. Keep supporting explanation close to the decision it helps, and put detailed reference material after the primary task.

Give related labels, rows and icons a common leading guide. Use indentation for real child relationships. Let the parent layout own spacing, and keep equivalent items on shared tracks. When a split leaves one side empty while the other grows long, rebalance it or stack the content.

Give surfaces clear roles

Use semantic page, group and control backgrounds. A grouped form paints one content surface; inner fields compose within it. Choose glass for a floating control or navigation role that needs visual separation. Typography and spacing should explain the hierarchy before another container is added.

Use the theme's semantic colors in both appearances. Keep selection, focus and error feedback distinct. These choices follow the intent of Apple's Layout, Color and Materials guidance, adapted to the Web.

Compose familiar controls

Use public component parts to keep controls, labels and overlays connected through their root. Preserve supplied props, refs, event handlers, state attributes and accessible relationships through the native render contract. Ordinary controls retain UI SDK behavior; date, time and color parts retain their native value-model context.

Keep native text selection, paste and editing. Keyboard users need a visible location cue, and errors need an associated explanation. Use motion to explain a transition or confirm an action while retaining a complete reduced-motion experience.

Verify the application

Try the primary task with pointer and keyboard. Check focus restoration, invalid content, both themes, narrow layouts and larger text in the rendered application. Measure alignment or contrast when the change depends on it. A source snippet, typecheck or DOM test alone does not prove a customized composition's appearance or usability.

Choose the field component

NeedComponent and responsibility
Edit short textInput supplies the editing control.
Edit longer textTextArea supplies multiline editing.
Label and validate one fieldTextField connects its label, control, description and error.
Group related settingsFieldset supplies the legend; Fieldset.Group paints the shared surface.
Place a non-text control in a settings rowFieldset.Row lays out a switch or selector with its label.
Submit and validate a set of fieldsForm owns submission and field errors.

Use a TextField directly inside Fieldset.Group; wrapping it in another Fieldset.Row duplicates row layout. See Form for a complete mixed-control example and TextField for individual fields.