Visual Hierarchy

Visual hierarchy (i.e., how important each element appears relative to the others) is the highest-leverage tool for making a feature feel designed. When everything competes for attention, nothing guides the eye and the screen feels busy no matter how clean each piece is. The work is always the same: decide what matters most, then use size, weight, color, and restraint to make it win. The sections below move in that order (e.g., choose the focal point, shape the content around it, then rank the actions on the page).

Give every view a single focal point

Before styling anything, name the one thing this view exists for (i.e., the primary task, or the piece of information the user came to find). That element earns the most visual weight; everything else is support and should defer to it. If you can't name the single most important thing on a view, the design isn't finished yet.

Hierarchy comes from contrast, so the fastest way to make a focal point win is usually to hold everything else back rather than pile more emphasis onto the target. When a key element still doesn't stand out, de-emphasize what competes with it (e.g. let a supporting panel sit on the page background instead of giving it its own surface). That restraint does more for perceived polish than any surface styling choice.

Build emphasis with weight and color, not size alone

Leaning on font size alone to signal importance pushes primary content too large and secondary content too small. Use weight and color instead, and keep both to a tight range (i.e., roughly two font weights and two or three text colors):

• Primary content: --t-text
• Secondary labels and supporting text: --t-textA (#4d4d4d at 77% opacity)
• Tertiary or muted content: --t-a11y-gray-color-AA (#949494)

To push something back, reach for a lighter color or a smaller size, never a thinner weight, which tends to read as disabled.

Treat labels as secondary to their values

A naive label: value layout gives every field equal weight, which flattens hierarchy. Drop the label entirely when format or context already carries the meaning (e.g., a currency amount needs no "Balance" label). When a label helps, fold it into the value ("12 left in stock" rather than "In stock: 12"). When you genuinely need a separate label, make it the quieter element, because the value is what the user came for. With q2-detail, a smaller size keeps the label subordinate to the value it names.

Style for visual hierarchy, not document structure

Choosing a semantic element and choosing its emphasis are independent decisions: pick the element for meaning, then style it for the hierarchy the layout needs. q2-section's label prop renders an <h2>, which is correct for document structure, but a section title usually behaves more like a quiet label than a headline, so style it down to frame the content without competing with it.

Rank actions: one primary, the rest recede

Every view has one true primary action, a few secondary ones, and some tertiary ones. Communicate that ranking through Tecton's button intents:

• Primary (only one per page, card, or modal): q2-btn intent="workflow-primary"
• Secondary: q2-btn intent="workflow-secondary"
• Tertiary: q2-btn intent="neutral-text"

A primary action only reads as primary when it's the exception. Promote exactly one, and let everything else step back. Keep an action group to buttons only; reserve a standalone q2-link for a navigational or contextual link elsewhere on the view rather than mixing it alongside q2-btn actions in the same group.

Scale destructive emphasis to the action's role

Being destructive doesn't automatically make an action loud. A destructive action that isn't the view's primary action should take a secondary or tertiary treatment. Reserve the emphatic q2-btn intent="workflow-destroy" for the confirmation step (e.g., inside a modal, where deleting is the primary action and the user has already chosen to proceed). A bold red button on every row of a list adds noise, not safety.

In practice

The card below puts the principles together. The balance is the focal point (i.e., large value, quiet label) and the supporting details sit beneath it at a smaller size. The action group promotes a single primary action while the secondary and tertiary actions recede.

<q2-card type="non-clickable">
  <q2-detail label="Available balance" stacked size="medium">
    <q2-currency amount="4820.55"></q2-currency>
  </q2-detail>
  <q2-grid columns="2" gap="comfortable">
    <q2-grid-area>
      <q2-detail label="Account" description="Family Checking ****9538" stacked size="small"></q2-detail>
    </q2-grid-area>
    <q2-grid-area>
      <q2-detail label="Routing number" description="****0021" stacked size="small"></q2-detail>
    </q2-grid-area>
  </q2-grid>
  <q2-action-group>
    <q2-btn intent="workflow-primary">Pay a bill</q2-btn>
    <q2-btn intent="workflow-secondary">Transfer</q2-btn>
    <q2-btn intent="neutral-text">View statements</q2-btn>
  </q2-action-group>
</q2-card>

<!-- Don't: equal-weight fields and three equally loud buttons -->
<q2-detail label="Available balance" description="$4,820.55"></q2-detail>
<q2-detail label="Account" description="Family Checking ****9538"></q2-detail>
<q2-detail label="Routing number" description="****0021"></q2-detail>
<q2-action-group>
  <q2-btn intent="workflow-primary">Pay a bill</q2-btn>
  <q2-btn intent="workflow-primary">Transfer</q2-btn>
  <q2-btn intent="workflow-primary">View statements</q2-btn>
</q2-action-group>