consistency-design-systems

Identical Components Must Be Identical -- Consistency Is the Fastest Path to Perceived Quality

Consistency is the most central aesthetic factor. The VisAWI (Visual Aesthetics of Websites Inventory) instrument identifies Craftsmanship as a primary dimension -- and the fastest way to score high on Craftsmanship is rigid consistency. Every time a user encounters the same component rendered two slightly different ways, trust erodes. The CRAP design framework (Contrast, Repetition, Alignment, Proximity) names Repetition as a core principle for exactly this reason.

Design Token Layers

Design tokens are the atomic values that encode visual decisions. Organize them in three layers, referencing downward only.

Layer	Naming Pattern	Example	Changes When
Primitive	--{category}-{scale}	--blue-500, --space-4, --radius-md	Brand overhaul
Semantic	--color-{purpose}	--color-primary, --color-bg-surface	Theme switch (light/dark)
Component	--{component}-{property}	--button-bg, --card-radius	Component redesign

Rule: Components reference semantic tokens. Semantic tokens reference primitives. Never skip a layer.

Token Categories

Define tokens for every visual property. Constrain each category to a finite set.

Category	Max Unique Values	Example Tokens
Color	<= 15	--color-primary, --color-bg-surface, --color-status-error
Spacing	<= 10	See whitespace-density skill for the full spacing scale
Typography	<= 6 sizes	--font-xs, --font-sm, --font-base, --font-lg, --font-xl, --font-2xl
Elevation	<= 5 levels	--shadow-0 through --shadow-4 (see craftsmanship-polish skill for definitions)
Border radius	<= 4 values	See craftsmanship-polish skill for reference values
Motion	<= 3 durations	--duration-fast (100ms), --duration-normal (200ms), --duration-slow (300ms)

The "10 Unique Values" Audit

Extract all unique values for any single property in the codebase. If there are more than 10 unique values for spacing, or more than 15 for color, the system has drifted. Run this audit periodically.

How to audit:

1. Search the codebase for all padding, margin, and gap declarations
2. List every unique value
3. Flag any value not in the token scale
4. Replace rogue values with the nearest token

Atomic Design Methodology

Build from the smallest constrained unit upward.

Level	Definition	Example
Atoms	Single elements, unsplittable	Button, input, label, icon
Molecules	Small groups of atoms with one function	Search bar (input + button), form field (label + input + error)
Organisms	Complex groups forming a section	Navigation bar, pricing card, data table
Templates	Page-level layout with placeholder content	Dashboard layout, settings page layout
Pages	Templates filled with real content	The actual rendered screen

Every atom uses tokens. Molecules compose atoms without overriding their tokens. If a molecule needs a different button color, create a semantic token variant -- never hard-code a value.

Cross-Screen Consistency Rule

The same component at the same level must share exact styles across every screen. A "Save" button on the settings page must be pixel-identical to a "Save" button on the profile page. If it is not, the user perceives lower quality even without consciously noticing the difference.

Audit by taking screenshots of the same component across different pages and overlaying them. Any variation is a bug.

Anti-Patterns

Anti-Pattern	Problem	Fix
Magic numbers (padding: 13px)	Breaks the spacing scale, impossible to maintain	Use nearest token (--space-3: 12px)
One-off styles	Inconsistency across pages, maintenance burden	Create a reusable token or component
Token sprawl (50+ colors)	Effectively no system at all	Constrain to <= 15 colors, audit and merge
Inconsistent naming (--btn-bg vs --button-background)	Developer confusion, duplication	Adopt one naming convention and enforce it
Skipping token layers (component referencing primitive)	Theme switching breaks	Always reference through semantic layer

Cross-Media Notes

• Presentations: Master slides and layouts are tokens -- consistent heading position, font sizes, and color palette across all slides
• CVs/Resumes: One font, one heading style, one bullet style, one date format -- any variation looks unprofessional
• Brand systems: The design system is the brand -- every touchpoint must reference the same token set

Examples

Working implementations in examples/:

• examples/design-tokens-system.md -- Complete token system in CSS custom properties with primitive/semantic/component layers, Tailwind config, and React theme provider

Review Checklist

When reviewing or building a design system:

• Three token layers implemented: primitive, semantic, component
• Components reference semantic tokens, never primitives directly
• <= 15 unique color tokens in the semantic layer
• <= 10 unique spacing values in the scale
• <= 4 border-radius values defined
• <= 5 elevation/shadow levels defined (see craftsmanship-polish for reference values)
• No magic numbers -- every value traces to a token
• The same component renders identically across all pages
• Token naming follows a consistent pattern (category-purpose)
• The "10 unique values" audit passes for spacing and color
• Atomic design levels are respected (atoms -> molecules -> organisms)
• Token changes propagate automatically (CSS custom properties or theme provider)