Spacing, Sizing, Borders & Corner Radius

1. Component Overview

Definition

Spacing, sizing, borders, and corner radii form the geometric foundation of the design system.

• Spacing controls padding, margins, gaps, grouping, and layout rhythm.
• Sizing defines predictable dimensions for controls, icons, targets, and containers.
• Borders separate, contain, emphasize, or indicate interactive state.
• Corner radius defines surface shape without changing component semantics.

All values derive from a 4px baseline grid. The primary rhythm advances in 8px increments, while 4px values support compact alignment and optical adjustment.

Web implementations use rem values based on a user-configurable root size. Flutter implementations use density-independent logical pixels (dp).

Purpose

A governed scale prevents arbitrary geometry from accumulating across interfaces. It improves visual rhythm, responsive behavior, implementation consistency, design-to-development handoff, and automated validation.

The structural model uses one shared spacing scale for components, patterns, typography, and layouts. Smaller values establish relationships within components; larger values separate sections and layout regions. Existing tokens must be combined instead of creating arbitrary values.

2. Usage Guidelines (Dos and Don'ts)

3. Architectural Integration (Web & Flutter)

Token Architecture

The canonical progression is:

:root {
  --ds-space-3xs: 0.25rem;
  --ds-space-2xs: 0.5rem;
  --ds-space-xs: 0.75rem;
  --ds-space-sm: 1rem;
  --ds-space-md: 1.5rem;
  --ds-space-lg: 2rem;
  --ds-space-xl: 3rem;
  --ds-space-2xl: 4rem;
  --ds-space-3xl: 5rem;
  --ds-space-4xl: 6rem;
  --ds-size-target-minimum: 2.75rem;
  --ds-border-default: 0.0625rem;
  --ds-border-strong: 0.125rem;
  --ds-border-focus: 0.1875rem;
  --ds-radius-sm: 0.25rem;
  --ds-radius-md: 0.5rem;
  --ds-radius-lg: 0.75rem;
  --ds-radius-xl: 1rem;
  --ds-radius-full: 9999px;
}

The web root font size remains 100%. Do not force 16px on the root element because that can override user font preferences.

abstract final class DsSpace {
  static const double threeXs = 4;
  static const double twoXs = 8;
  static const double xs = 12;
  static const double sm = 16;
  static const double md = 24;
  static const double lg = 32;
  static const double xl = 48;
  static const double twoXl = 64;
  static const double threeXl = 80;
  static const double fourXl = 96;
}

Component API / Props Architecture

Web components expose semantic variants such as <ds-stack gap="md">, <ds-card padding="lg">, and <ds-button size="medium">. Spacing utility classes may support page composition, prototypes, and migration work, but must not override required component geometry.

Flutter components accept typed values such as DsSpace.md, DsInsets.lg, and DsControlSize.medium. Public APIs prefer semantic enums; raw numeric overrides remain private, deprecated, or explicitly marked as escape hatches.

Visual Examples

These rendered specimens use the same canonical variables exported by the Web package. Dimensions are shown at their actual CSS scale.

4. Specifications & Anatomy

Spacing Scale

Inner Padding

Outer Margins

Margins primarily control separation from external content. Components must not impose unpredictable outer margins.

Gap

Sizing

Compact controls use pseudo-elements, wrappers, padding, or layout containment to preserve the minimum hit area.

Icon Sizing

Icon size and hit-target size are separate contracts.

Border Width

Hairline borders must not be represented as fractional physical pixels in Flutter.

Corner Radius

Nested surfaces should generally use an inner radius equal to the outer radius minus the intervening padding or border thickness.

5. Accessibility (WCAG 2.2 AA)

Interactive Target Size

• A minimum target area of 44 × 44 CSS pixels on the web.
• A minimum target area of 48 × 48 dp in Flutter.
• At least space-2xs between adjacent targets where overlapping activation areas could cause errors.
• Compact visual controls retain a larger invisible or transparent activation area.
• Standalone icon buttons use the same minimum target as labeled controls.
• Inline text links preserve adequate line height and separation when a larger rectangular target is not practical.

These system requirements intentionally exceed the WCAG 2.2 AA minimum target-size threshold.

Focus Rings, Borders, and Radius

• Use border-focus for the standard keyboard focus indicator.
• Maintain at least 3:1 contrast between the focus indicator and adjacent colors.
• Place the focus ring outside the component border whenever possible.
• Use a minimum 2px focus offset.
• Match the focus-ring shape to the component radius.
• Calculate an external focus radius as the component radius plus the focus offset.
• Do not clip the focus ring with overflow rules.
• Do not replace the focus indicator with a border-color change alone.
• Preserve focus visibility in forced-colors and high-contrast modes.
• Keep error, selected, disabled, and focus states distinguishable when simultaneous.

Borders representing controls or essential boundaries must meet 3:1 non-text contrast against adjacent colors unless another visible cue provides the required distinction.

6. MCP Server Context

Agent Instructions

Use only registered spacing, sizing, border, and radius tokens; never generate arbitrary numeric values when a canonical token can express the relationship. Apply smaller tokens within related component content, larger tokens between independent layout regions, and preserve minimum targets of 44x44 CSS pixels on Web and 48x48 dp in Flutter. Component APIs must receive semantic variants, while focus rings remain visible, contrast-compliant, radius-aligned, and unclipped.