UI Architecture Handbook / Index
A living handbook
Eyal's UI Architecture Handbook
A deliberate path through changeable UI systems.Start hereFrom the field
Field notes
Short, standalone notes on specific problems. Each one links back to the handbook chapters it relates to.
From the handbook
UI Architecture Handbook chapters
A field guide for frontend engineers, tech leads, and teams maintaining complex web applications. UI architecture is fundamentally a delivery-velocity concern: by drawing clear boundaries between visual presentation, interaction mechanics, and product rules, teams keep changes localized, reviews fast, and the blast radius of fixes small.
2026-08-01
UI architecture is a delivery-velocity concern
A field guide to structuring frontend code so applications remain fast and safe to change as they grow.
2026-08-04
Design systems need boundaries
A design system gives teams shared interface decisions and guardrails without absorbing product-specific rules.
2026-08-04
Design systems love to show their work
A browsable, versioned demo makes a design system's available choices visible before a team rebuilds them.
2026-08-06
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.
2026-08-09
Building components with clear responsibilities
Shared components stay flexible when their APIs preserve composition, focused behavior, and documented system variants.
2026-08-10
Shared abstractions versus local composition
A premature shared component makes every local change span features. Duplicate until the mechanic is durable enough to extract.
2026-08-14
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.
2026-08-14
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.
2026-08-17
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.
2026-08-19
The parts of a feature
A feature module groups UI, frontend-facing contracts, and a runnable demo while keeping production integrations outside.
2026-08-23
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.
2026-08-27
Building a feature from idea to implementation
A feature implementation puts the plan into a module, demo, and production host without collapsing their boundaries.
2026-08-27
Testing a feature without the host
Prove interface behavior without booting the application shell, authentication, or live services.
2026-08-29
The application is the composer
Route components act as composition roots: connecting ambient host state to the feature's contract.
2026-09-01
Design tools, tokens, and implementation
Design decisions remain reliable when tools, tokens, and implementation preserve one shared vocabulary.
2026-09-02
CSS architecture and ownership
Feature development works best as pure composition, keeping custom CSS as an occasional exception rather than standard practice.
2026-09-06
Evolving a design system without blocking products
Evolve shared primitives through real product evidence without stalling feature velocity with forced migrations.
2026-09-08
Package boundaries define the blast radius
Repository and package boundaries turn architectural rules into compiler constraints so teams can change UI work independently.
2026-09-08
Turning boundaries into build speed
Affected graphs and computation caching turn package architecture into fast, reliable CI feedback.
2026-09-11
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.
2026-09-13
Relocating an independent feature
Once a feature boundary holds in place, move the slice, its contract, demo sandbox, and tests into their own package.
2026-09-14
Architecture that agents can use
Feature boundaries give an AI agent a defined scope, an explicit contract, controlled scenarios, and verifiable feedback.