UI Design

Design the interface as a coherent product surface, not as a collection of technically valid widgets.

Before designing or reviewing

Read the existing interface, theme tokens, typography, layout primitives and nearby screens before choosing a new shape.
Find the repository's canonical owner of those tokens and the real target sizes. Extend source tokens or primitives; do not edit generated output or invent a viewport contract the product does not have.
Search the project's history for visual corrections and reuse the lessons that apply. Treat repeated fixes as requirements: alignment, surface contrast, spacing, text scaling, state clarity and calm degradation.
Name the primary question the screen answers. Keep the first viewport focused on that question; move investigation detail behind deliberate disclosure.

Design tokens are the visual source of truth. Put surfaces, text, borders, spacing, type scale, radii, breakpoints and motion values in the canonical token layer; UI code contains no unexplained design constants. Local numbers that belong to a component's layout algorithm remain local and named by their purpose.
Use the shared token set consistently. Do not scatter one-off values through widgets or styles, and do not edit generated token output.
Preserve the product's established visual language. When one does not exist, choose a restrained visual system that supports the product's audience and primary question, then express it through shared tokens.
Establish hierarchy before decoration. Align edges, bands, columns and repeated rows. Consistent gaps matter more than ornamental containers.
Let text, labels, shape and placement carry meaning. Color may reinforce a role or state but never carries it alone. Keep independent semantic dimensions—such as role, location and state—separate.
Show the smallest useful supporting detail beside the primary fact. Do not invent metrics, activity, controls or empty decorative panels to make a screen feel complete.