Semantic Token Gap
Definition
The failure point in AI-generated UIs where primitive design tokens (blue-500, spacing-4, font-lg) undermine AI effectiveness because they carry no contextual meaning, while semantic tokens (color-button-background-brand, spacing-section-padding, font-heading-page) enable accurate generation by encoding intent. Identified as the largest design consistency failure point in Figma-to-code pipelines — not a limitation of tools but of upstream design system structure. The gap exists when a design system defines options (palette values) but not decisions (what those values mean in context). AI tools replicate whatever token structure exists; if the structure is primitive, the output is inconsistent.
Builder Context
The semantic token gap is the #1 thing to fix before giving your design system to an AI agent. Example: if your tokens define --blue-500 and --blue-600, the agent has to guess which blue to use for a button vs. a link vs. a badge. If your tokens define --color-button-primary-bg, --color-link-default, --color-badge-info, the agent has no decision to make. Action items: (1) audit your current tokens — if >50% are primitive names, you have a gap; (2) create a semantic layer that aliases primitives to contextual meanings; (3) expose ONLY the semantic layer to agents (keep primitives private to reduce the decision surface). The three-layer architecture (Option → Decision → Component) from Martin Fowler's token article is the canonical solution.