Generate a comprehensive web design reference sheet (docs/design/design-reference.md) and its companion enforcement skill (.agents/skills/{project-slug}/SKILL.md) for any website project. Extracts tokens from CSS files, validates completeness against a JSON schema scratchpad, inspects existing components, and produces a 12-section living document covering colours, typography, spacing, layout, borders, shadows, motion, component patterns, accessibility, dark mode, and Figma sync notes. Use when starting a new project, onboarding a design system, creating a Figma reference sheet, porting design tokens, or auditing existing styles. Triggers on: "create a design reference", "generate a style guide", "document the design tokens", "make a brand reference sheet", "create design docs", "port design tokens", "audit existing styles".
97
100%
Does it follow best practices?
Impact
89%
2.61xAverage score across 3 eval scenarios
Passed
No known issues
Gestalt psychology (German: "shape" or "form") describes how the human brain organises visual information into unified wholes rather than perceiving individual parts in isolation. The core insight: the whole is different from the sum of its parts.
These principles are directly applicable to UI/UX layout because the browser renders a flat collection of HTML elements — Gestalt explains how users perceive those elements as meaningful groups, patterns, and structures.
Elements close together are perceived as belonging to the same group.
The brain interprets spatial closeness as a relationship signal — before colour, shape, or any other attribute is processed.
● ● ● ■ ■ ■
Three circles and three squares — perceived as two groups based on proximity,
despite the shape difference.UI application:
Practical rule: If two elements are related, move them closer. If they are separate, move them further apart. Never rely on labels or lines when spacing can do the work.
Elements that share visual attributes — colour, shape, size, orientation, texture — are perceived as belonging together.
Similarity creates implicit categorisation without borders, labels, or explicit grouping.
UI application:
Warning: Similarity works against you when unrelated elements accidentally share attributes. If your CTA button and your error message are both red, the error message inherits the "action" connotation of the button colour.
The brain separates visual input into a dominant "figure" (foreground) and a "ground" (background).
The figure is perceived as solid, in front, with definite shape. The ground is perceived as behind, shapeless, continuous.
Classic example: The Rubin vase — two face profiles or a vase, depending on which you perceive as figure vs ground.
UI application:
Ambiguous figure-ground: Sometimes intentional (logo design, optical illusion art), but in UI it creates confusion. Ensure your figure (interactive or important element) is always clearly distinct from its ground.
Elements arranged along a line, curve, or path are perceived as related and connected.
The brain follows the path and groups the elements along it.
UI application:
The brain completes incomplete shapes and fills in missing information.
Humans prefer complete, familiar shapes and will mentally "close" gaps to perceive them.
UI application:
The brain perceives ambiguous or complex images as the simplest possible form.
Given multiple possible interpretations, the simplest is preferred.
UI application:
Elements that move together are perceived as belonging together.
When multiple elements move in the same direction simultaneously, the brain groups them.
UI application:
Elements with an explicit visual connection (line, border, shared background) are perceived as more strongly related than elements grouped by proximity or similarity alone.
UI application:
When building a page layout, work through these questions:
Proximity check: Is every related pair of elements closer to each other than to unrelated elements?
Similarity check: Do all interactive elements share a visual attribute that marks them as interactive? Do all navigation items of the same level look the same?
Figure-ground check: Is the main content clearly distinct from the background? Do modals, dropdowns, and elevated panels have enough shadow/contrast to separate from the page?
Closure check: Are any elements cut off that should signal "more content available"? Is that cutoff intentional?
Continuity check: Are sequential or related items arranged along a common path or line?
Prägnanz check: Does the overall layout resolve to a simple structure (grid, columns, rows) that the brain can interpret quickly? Is there unnecessary complexity?
| Principle | Core idea | Primary UI use case |
|---|---|---|
| Proximity | Close = related | Label/input pairing, card layout, section spacing |
| Similarity | Shared attributes = same group | Button styles, nav items, interactive affordance |
| Figure-Ground | Foreground vs background | Modals, dropdowns, card elevation, text contrast |
| Continuity | Along a path = connected | Navigation bars, timelines, steppers, progress bars |
| Closure | Brain completes incomplete shapes | Icons, carousel truncation, lazy borders |
| Prägnanz | Simplest interpretation wins | Overall layout structure, reducing cognitive load |
| Common Fate | Moving together = related | Accordion, notifications, parallax layers |
| Connectedness | Explicit connection = stronger grouping | Cards, form sections, badges, breadcrumbs |