Skip to content

UI Density & Confidence Standards

Durable guidance for card structure, navigation rails, metadata exposure, and the visual confidence that defines SageOx product surfaces.

Card Structure & Density

Header-to-Content Spacing

The header must visually own the content beneath it. If a header floats above its content, spacing is too generous.

Region Padding Rationale
CardHeader 16px 20px 8px 20px Top breathes; bottom pulls toward content
CardContent 8px 20px 16px 20px Top binds to header; bottom closes the card

The gap between header bottom (8px) and content top (8px) yields 16px total, which is tight enough that the header claims its content without collision.

Card Height Expectations

A card should never feel taller than the information it contains.

  • Empty states: py-4 maximum. No oversized icons. One sentence.
  • Single-item lists: No extra padding. The card collapses naturally.
  • Full lists: Items set the rhythm; the card follows.

Spacing Between Cards

Cards in a space-y-6 stack (24px) is the standard inter-card gap. Do not reduce this. The breathing room between cards is earned; the tightness within cards is what makes it work.

Width Philosophy

A nav rail should feel like a tool, not a room. If the sidebar feels roomy, it is too wide.

State Width Padding Rationale
Expanded w-52 (208px) px-2.5 Labels breathe but do not float
Collapsed w-14 (56px) px-1.5 Icon centered with minimal air
Property Value Note
Icon-label gap gap-2.5 (10px) Tighter than body text spacing
Min height 34px Enough for touch; no wasted vertical
Horizontal padding px-2.5 expanded, px-1.5 collapsed Items fill available width
Font size 14px / leading-5 Matches body text hierarchy

When a Nav Is "Too Wide"

  • Labels have visible right-side dead space
  • The nav column competes with content for attention
  • Collapsing the nav feels like a relief rather than a compromise

Identifiers & Metadata

When Internal IDs May Be Shown

Almost never. Internal IDs are shown only when:

  1. The user needs to copy or reference the ID in another system
  2. The ID is the only available display name (no human-readable alternative)
  3. A debug or admin mode is explicitly active

When Technology Labels Should Be Implied

Redundant Better Why
"git" under a repo name (omit) The Repositories card implies git
"REST API" in an endpoint list (omit) Context makes protocol obvious
"JSON" next to a payload (omit) Code block formatting implies it
"PostgreSQL" in a migration "Migration" The system defines the DB

Rule: If the surrounding context (card title, section name, icon) already communicates the technology, the label adds noise.

Good vs Bad Metadata Exposure

Bad (repo card): 

my-service
repo_01JQ2X4K...
git

Good (repo card): 

my-service

Bad (member row): 

usr_01JQ2X4K... | Person A | admin | Jan 6, 2026

Good (member row): 

Person A | admin | Jan 6

Confidence & Restraint

How SageOx UI Expresses Confidence

Confidence is shown through restraint, not minimalism theater.

  • Tight spacing within cards says "this information belongs together."
  • Removing redundant labels says "we trust users to understand context."
  • Collapsing empty states says "we acknowledge absence without apologizing."
  • Narrow nav rails say "the content area is what matters."

Signs of Over-Politeness

Symptom Diagnosis Fix
Headers feel detached from content Padding is apologetic Reduce header bottom / content top
Cards feel tall with little content Padding fills the void Collapse padding when sparse
Sidebar feels spacious Width compensating for sparse items Tighten to content-fit
Labels restate the obvious UI explaining itself Remove; trust context
Empty states are dramatic Large icons, multiple paragraphs One line, modest icon

Restraint Principles

  1. Whitespace explains structure, not apologizes for it. Every pixel of padding should serve grouping or separation.

  2. Headers own their content. The gap between a header and its first item should feel like a breath, not a pause.

  3. Cards are as tall as their content. Never pad a card to fill a visual expectation.

  4. Navigation is a tool, not a room. If the nav feels comfortable, it is stealing focus from the work area.

  5. Obvious facts are implied. If the section title, icon, or context already communicates something, a label repeating it is noise.