Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pbakaus/impeccable/llms.txt

Use this file to discover all available pages before exploring further.

Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis.

​
Spacing Systems

​
Use 4pt Base, Not 8pt

8pt systems are too coarse—you’ll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px. 
:root {
  --space-xs: 0.25rem;  /* 4px */
  --space-sm: 0.5rem;   /* 8px */
  --space-md: 0.75rem;  /* 12px */
  --space-lg: 1rem;     /* 16px */
  --space-xl: 1.5rem;   /* 24px */
  --space-2xl: 2rem;    /* 32px */
  --space-3xl: 3rem;    /* 48px */
  --space-4xl: 4rem;    /* 64px */
  --space-5xl: 6rem;    /* 96px */
}

​
Name Tokens Semantically

Name by relationship (--space-sm, --space-lg), not value (--spacing-8). Use gap instead of margins for sibling spacing—it eliminates margin collapse and cleanup hacks. 
/* Better: Use gap */
.card-grid {
  display: grid;
  gap: var(--space-lg);
}

/* Avoid: Margin cleanup */
.card + .card {
  margin-top: var(--space-lg);
}

​
Grid Systems

​
The Self-Adjusting Grid

Use repeat(auto-fit, minmax(280px, 1fr)) for responsive grids without breakpoints. Columns are at least 280px, as many as fit per row, leftovers stretch. 
.responsive-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: var(--space-lg);
}
For complex layouts, use named grid areas (grid-template-areas) and redefine them at breakpoints. 
.layout {
  display: grid;
  grid-template-areas:
    "header"
    "main"
    "sidebar"
    "footer";
}

@media (min-width: 768px) {
  .layout {
    grid-template-areas:
      "header header"
      "sidebar main"
      "footer footer";
    grid-template-columns: 250px 1fr;
  }
}

​
Visual Hierarchy

​
The Squint Test

Blur your eyes (or screenshot and blur). Can you still identify:
  • The most important element?
  • The second most important?
  • Clear groupings?
If everything looks the same weight blurred, you have a hierarchy problem.

​
Hierarchy Through Multiple Dimensions

Don’t rely on size alone. Combine:
ToolStrong HierarchyWeak Hierarchy
Size3:1 ratio or more<2:1 ratio
WeightBold vs RegularMedium vs Regular
ColorHigh contrastSimilar tones
PositionTop/left (primary)Bottom/right
SpaceSurrounded by white spaceCrowded
The best hierarchy uses 2-3 dimensions at once: A heading that’s larger, bolder, AND has more space above it.

​
Cards Are Not Required

Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when:
  • Content is truly distinct and actionable
  • Items need visual comparison in a grid
  • Content needs clear interaction boundaries
Never nest cards inside cards—use spacing, typography, and subtle dividers for hierarchy within a card.

​
Container Queries

Viewport queries are for page layouts. Container queries are for components: 
.card-container {
  container-type: inline-size;
}

.card {
  display: grid;
  gap: var(--space-md);
}

/* Card layout changes based on its container, not viewport */
@container (min-width: 400px) {
  .card {
    grid-template-columns: 120px 1fr;
  }
}
Why this matters: A card in a narrow sidebar stays compact, while the same card in a main content area expands—automatically, without viewport hacks.

​
Optical Adjustments

Mathematical centering doesn’t always look centered to the human eye.

​
Text Alignment

Text at margin-left: 0 looks indented due to letterform whitespace—use negative margin (-0.05em) to optically align. 
.heading {
  margin-left: -0.05em;  /* Optical alignment */
}

​
Icon Alignment

Geometrically centered icons often look off-center:
  • Play icons need to shift right
  • Arrows shift toward their direction
.play-button::before {
  transform: translateX(2px);  /* Optical centering */
}

​
Touch Targets vs Visual Size

Buttons can look small but need large touch targets (44px minimum). Use padding or pseudo-elements: 
.icon-button {
  width: 24px;  /* Visual size */
  height: 24px;
  position: relative;
}

.icon-button::before {
  content: '';
  position: absolute;
  inset: -10px;  /* Expand tap target to 44px */
}

​
Depth & Elevation

Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers. 
:root {
  --z-dropdown: 100;
  --z-sticky: 200;
  --z-modal-backdrop: 300;
  --z-modal: 400;
  --z-toast: 500;
  --z-tooltip: 600;
}
For shadows, create a consistent elevation scale (sm → md → lg → xl). 
:root {
  --shadow-sm: 0 1px 2px oklch(0% 0 0 / 0.05);
  --shadow-md: 0 4px 6px oklch(0% 0 0 / 0.07);
  --shadow-lg: 0 10px 15px oklch(0% 0 0 / 0.1);
  --shadow-xl: 0 20px 25px oklch(0% 0 0 / 0.15);
}
Key insight: Shadows should be subtle—if you can clearly see it, it’s probably too strong.

​
Guidelines

​
DO

  • Create visual rhythm through varied spacing—tight groupings, generous separations
  • Use fluid spacing with clamp() that breathes on larger screens
  • Use asymmetry and unexpected compositions; break the grid intentionally for emphasis
  • Use gap for sibling spacing instead of margins
  • Create semantic z-index scales

​
DON’T

  • Wrap everything in cards—not everything needs a container
  • Nest cards inside cards—visual noise, flatten the hierarchy
  • Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly
  • Use the hero metric layout template—big number, small label, supporting stats, gradient accent
  • Center everything—left-aligned text with asymmetric layouts feels more designed
  • Use the same spacing everywhere—without rhythm, layouts feel monotonous
  • Use arbitrary spacing values outside your scale

Build docs developers (and LLMs) love

Get started for freeTalk to us