02 — Visual Doctrine
Spatial Logic
Section Overview
What This Is
Visual Doctrine is the normative specification of IDL's perceptual constraint layer. It governs spatial rhythm, color semantics, typographic scale, density levels, and surface rendering contexts.
Why It Exists
Perceptual consistency across platform targets cannot be achieved through authoring convention alone. Machine-evaluable rules produce equivalent perceptual output regardless of who authored the IDL source.
How It Works
Each subsection declares a named ruleset enforced by the compiler. Non-conforming values are rejected at Parse or Transform. Surface declarations establish rendering context for token resolution.
raw px · hex · ad-hoc values
base-unit · semantic token · scale step
CSS · iOS · Android · Figma
Visual Doctrine normalises authoring-time diversity into a platform-portable perceptual model.
Spatial decisions in IDL are expressed as multiples of a base unit, defined as 8px by default. All spacing, sizing, and layout values declared in IDL source MUST resolve to the nearest base-unit multiple. Non-conforming values are rejected at Parse time — they are not rounded, clamped, or silently coerced.
Base Unit
The base unit is a system-level declaration, not a per-component setting. It is declared once in the IDL configuration and applies uniformly to all spatial token declarations in the system. Custom base units other than 8px are permitted through the configuration; changing the base unit is a breaking change that requires all spatial tokens to be revalidated.
Named Spatial Scale
| Token Name | Multiplier | Default Value |
|---|---|---|
| spacing.0 | 0× | 0px |
| spacing.1 | 0.5× | 4px |
| spacing.2 | 1× | 8px |
| spacing.3 | 1.5× | 12px |
| spacing.4 | 2× | 16px |
| spacing.6 | 3× | 24px |
| spacing.8 | 4× | 32px |
| spacing.12 | 6× | 48px |
| spacing.16 | 8× | 64px |
Spatial Values in Components
Component declarations MUST NOT reference raw pixel values for any spatial property. All padding, margin, gap, width, height, and border-radius values in component tokens MUST reference a named spacing or sizing token. The compiler validates this at Transform. A component token that resolves to a non-base-unit value after chain resolution is a Transform error, not a warning.