Eyal'sUI Architecture Handbook
This handbook is my field guide to frontend systems that remain understandable, verifiable, and durable as products grow. It is opinionated, shaped by problems I have seen while building UI platforms, and offered as a working point of view rather than a universal prescription.
Who this is for
Engineers shipping at scale
Built for engineers and leads navigating applications with multiple teams, shared libraries, and dozens of moving parts. It is a playbook for cutting through structural friction, restoring clarity to your architecture, and shipping changes with confidence and speed.
How to read this
Curriculum or field manual
The chapters start with core boundaries, then follow their consequences through design systems, component libraries, and feature delivery. Read sequentially for the complete architecture philosophy, or jump directly into the topic causing friction on your team today.
Start here
The foundational chapter establishes the bedrock for everything that follows: how component boundaries govern delivery speed, and why architecture earns its keep when the next feature is cheaper and safer to ship than the last.
Read Chapter 01: UI architecture is a delivery-velocity concernPart I
Establishing the boundaries
Why UI architecture is fundamentally an engineering velocity investment, measuring success by how safely teams can change products over time.
Part II
Design systems as foundation
Principles for defining shared interface boundaries that align designers and engineers without entangling the system in product-specific business logic.
Part III
Component libraries and UI infrastructure
The operational layer between raw design tokens and product views: layering primitives, managing third-party tools, and avoiding monolithic abstractions.
04
The UI kit: primitives, styles, and interactions
A UI kit stays composable when it separates presentational primitives from headless interaction behaviors instead of shipping monolithic all-in-one widgets.
05
Building components with clear responsibilities
Shared components stay flexible when their APIs preserve composition, focused behavior, and documented system variants.
06
Shared abstractions versus local composition
A premature shared component makes every local change span features. Duplicate until the mechanic is durable enough to extract.
07
When a component library needs an escape hatch
Exporting lower-level primitives alongside turnkey components gives product teams the freedom to build non-standard layouts without bloating library APIs.
08
Third-party UI dependencies are infrastructure too
Wrap defaults, not upstream APIs. Use composable configuration factories to keep third-party engines powerful without building fragile proxy wrappers.
Part IV
Building product features
The lifecycle of self-contained product slices: scoping requirements, structuring internal contracts, running independent tests, and host composition.
09
Feature modules are units of change
A feature module gives one product outcome a clear frontend home, separating feature decisions from shared UI infrastructure and production integrations.
10
The parts of a feature
A feature module groups UI, frontend-facing contracts, and a runnable demo while keeping production integrations outside.
11
Making a feature ready to build
We turn product requirements into a buildable plan by mapping observable UI states, identifying reusable infrastructure, and drafting the port contract.
12
Building a feature from idea to implementation
A feature implementation puts the plan into a module, demo, and production host without collapsing their boundaries.
13
Testing a feature without the host
Prove interface behavior without booting the application shell, authentication, or live services.
14
The application is the composer
Route components act as composition roots: connecting ambient host state to the feature's contract.
Part V
Making design operational
The day-to-day mechanics of running a design system in production: syncing tokens, governing CSS ownership, and evolving APIs without breaking consumers.
15
Design tools, tokens, and implementation
Design decisions remain reliable when tools, tokens, and implementation preserve one shared vocabulary.
16
CSS architecture and ownership
Feature development works best as pure composition, keeping custom CSS as an occasional exception rather than standard practice.
17
Evolving a design system without blocking products
Evolve shared primitives through real product evidence without stalling feature velocity with forced migrations.
Part VI
Delivering change
Leveraging modular repo structure and task graph tooling to isolate risk, minimize build times, and accelerate CI feedback loops.
18
Package boundaries define the blast radius
Repository and package boundaries turn architectural rules into compiler constraints so teams can change UI work independently.
19
Turning boundaries into build speed
Affected graphs and computation caching turn package architecture into fast, reliable CI feedback.
Part VII
Migrating an existing UI
A pragmatic roadmap for untangling legacy UI codebases into autonomous modules safely in place before extraction.
20
Introducing boundaries into an existing UI
Create a frontend-facing boundary inside the code that already ships before moving an existing mixed UI anywhere else.
21
Relocating an independent feature
Once a feature boundary holds in place, move the slice, its contract, demo sandbox, and tests into their own package.
Part VIII
Letting the robots take over
How deterministic interfaces, mock harnesses, and rigid module boundaries create the ideal operating environment for autonomous coding agents.