A Fundamental Design Specification for Interfaces
WHITE DIAMOND is not a UI kit. It is not a component library. It is not a framework. It is a design specification — a set of foundational principles that define the physics of space, the geometry of objects, the perception of motion, the psychology of interaction, the rules of composition, the behavior of components, the constraints of design, and the philosophy of architecture.
Any developer, designer, or AI system reading these documents would arrive at nearly the same architectural decisions — regardless of programming language, framework, platform, or design tool.
A specification that answers: What is an interface, and how does it work?
- Physics of space — How digital space behaves, how objects exist within it, how gravity, pressure, and density apply to layout
- Geometry of objects — How boundaries define existence, how the three-layer hierarchy (Physical Boundary → Inner Surface → Content) structures every element
- Perception of motion — How animation reveals spatial relationships, how objects enter and exit the viewport, how movement serves physics not decoration
- Psychology of interaction — How humans develop intuition about interfaces, how predictability creates control, how cognitive load constrains design
- Rules of composition — How elements relate spatially, how hierarchy is established, how layout follows architectural logic
- Behavior of components — How interactive elements contract with users, how states communicate availability, how feedback confirms action
- Constraints of design — What is forbidden and why, how constraints create coherence, how prohibition enables freedom
- Philosophy of architecture — Why interfaces should feel like constructions, not decorations, why monumentality matters, why permanence builds trust
| It is not | It is |
|---|---|
| A UI kit with pre-styled components | A specification for how components should behave |
| A component library you import | A contract you implement in any technology |
| A framework that enforces structure | A philosophy that informs decisions |
| A design tool or plugin | A set of principles independent of tools |
| A set of arbitrary rules | A system of reasoned axioms with explained motivations |
| Style guidance (colors, fonts) | Spatial reasoning about why colors and fonts exist where they do |
| A trend or aesthetic movement | A permanent architectural specification |
| Role | Entry Point | Path |
|---|---|---|
| Designers | Understand the philosophy before making decisions | Core Principles → Design Philosophy → Space Geometry |
| Developers | Learn the constraints before writing code | Implementation Guide → Technology Agnostic → Component Specifications |
| Product Managers | Understand the reasoning before approving decisions | User Psychology → Best Practices → Decision Making |
| AI Systems | Load the ontology before generating anything | Glossary → Specification Index → Core Principles |
The conceptual bedrock. Read these first. Everything else derives from them.
- Core Principles — The axioms that govern every decision in the system
- Design Philosophy — The worldview: why interfaces behave the way they do
- Architectural Thinking — Systems-level reasoning about interface structure
How digital space works and why it matters. The mathematics and physics of screen space.
- Space Geometry — The mathematical foundations of screen space
- Object Boundaries — Where one thing ends and another begins
- Geometric Rules — Constraints that create coherence
How objects are structured and perceived. The anatomy and behavior of interface elements.
- Object Structure — The three-layer anatomy of every element
- Appearance Sequence — The order in which things reveal themselves
- Depth Perception — Z-axis meaning and layering
The rules governing digital space. How space behaves under interaction.
- Space Behavior — How space reacts to interaction
- Object Existence — What it means for something to be "on screen"
- Screen as Window — The viewport as a window into infinite space
How things move and why. Animation as physics, not decoration.
- Animation Principles — Purposeful movement that reveals structure
- Prohibited Animations — What never to do and why
- Movement Physics — Natural-feeling motion rooted in physical law
Text as a spatial element. Reading as navigation through information architecture.
- Type System — Foundational type choices and their spatial meaning
- Text Hierarchy — Reading order and emphasis as architectural flow
- Text in Space — Typography as geometry
Composition and structure. How elements relate spatially.
- Composition Rules — How elements relate spatially and hierarchically
- Grid System — Mathematical alignment as structural discipline
- Spatial Layout — Three-dimensional composition
Behavioral specifications, not visual templates. The contract between system and user.
- Component Philosophy — Why components exist and what they contractually promise
- Button Specification — The button as a behavioral contract
- Input Specification — Data entry as spatial conversation
- Card Specification — Content containers with physical boundaries
- Modal Specification — Focused interaction as architectural enclosure
- Navigation Specification — Wayfinding through spatial structure
The atoms of the system. The smallest indivisible units of design language.
- Design Tokens — Token architecture and naming
- Color System — Meaning through color, not decoration
- Spacing System — Rhythm, proportion, and spatial weight
- Border System — Edges and boundaries as the most important visual element
Universal design as a foundational property, not an add-on feature.
- Accessibility Guidelines — Foundational accessibility as architectural requirement
- Keyboard Navigation — Non-pointer interaction as first-class citizen
- Screen Readers — Assistive technology as spatial communication
The human behind the screen. How perception shapes interaction.
- User Psychology — How people think about and perceive interfaces
- Control Feeling — The sense of agency through predictability
- Cognitive Load — Mental effort and its architectural constraints
Concrete applications of the specification. Proof of principle in practice.
- Basic Layout — Simple page compositions following WHITE DIAMOND
- Component Composition — Combining elements with architectural integrity
- Motion Examples — Animation in practice as spatial physics
What to avoid and why. Architectural mistakes that break the system.
- Prohibited Patterns — Architectural violations and their consequences
- Common Mistakes — Frequent errors and how to recognize them
Recommended approaches derived from the principles.
- Recommended Approaches — Proven solutions to common architectural problems
- Decision Making — How to navigate tensions between competing principles
Moving from other systems. The divergence from established conventions.
- From Flat Design — Transitioning from flat to architectural
- From Material Design — Divergence and adoption
Real-world validation of WHITE DIAMOND principles in production environments.
- Case Studies Overview — Why case studies matter and how to read them
- E-commerce Product Listing — Consistent product cards with architectural boundaries
- SaaS Dashboard — Structured data visualization with spatial hierarchy
- Mobile Navigation — Wayfinding that adapts while maintaining integrity
- Form Design — Data entry as spatial conversation
Deep reference material for specification lookup.
- Specification Index — Complete specification listing
- Glossary — Term definitions and ontological precision
- FAQ — Common questions and architectural answers
- RFC: Design Principles — The foundational RFC
Starting points and implementation guidance.
- Page Template — Starting point for page compositions
- Component Template — Starting point for component specifications
- Implementation Guide — How to implement WHITE DIAMOND in any technology
- Technology Agnostic — Framework independence through principled design
WHITE DIAMOND is a living specification. Contributions must follow the same rigor as the specification itself: every change must explain its reasoning, cross-reference existing principles, and maintain technological agnosticism.
See CONTRIBUTING.md for contribution guidelines.
This project is licensed under the MIT License — see LICENSE for details.
For reporting vulnerabilities, see SECURITY.md.