Developing Web UI with Domain Driven Design Principles

Enterprise web applications can be significantly improved by integrating Domain-Driven Design (DDD) principles into user interface development. This approach, when combined with modern web platform features such as form-associated custom elements, allows for the creation of a stable and well-defined API for UI components that accurately represent domain entities. In this post, we introduce the UI Entity Protocol, a structured methodology for designing UI components that align with domain logic, enhancing both enterprise development workflows and AI-driven UI composition tools.

Reusable UI Principles with DDD

Applying DDD principles to UI design promotes consistency, reusability, and a more structured approach to building user interfaces. Key benefits include:

• Establishing common UI components that reflect real-world business and domain concepts, creating a cohesive design system.
• Facilitating rapid UI composition by providing structured, domain-driven building blocks that reduce redundant code.
• Enhancing communication and alignment across developers, designers, and business stakeholders by mirroring domain models in the UI.
• Improving domain comprehension for LLMs, enabling AI-driven UI generation and automation through structured, semantically meaningful UI elements.

Core Domain-Driven Design Concepts

What is DDD?

Domain-Driven Design (DDD) is a software development methodology that emphasizes designing software models that are closely aligned with the underlying business domain. It ensures that software solutions are structured around business logic rather than technical infrastructure, thereby improving system maintainability, scalability, and clarity.

What is a Domain?

A domain represents a specific area of business, knowledge, or problem space that an application is designed to model and support. For example, in a smart home system, “Lighting Control” is a domain encompassing all functionality related to controlling lighting systems. Clearly defining domains helps teams ensure that each system component is appropriately contextualized and correctly modeled.

What is an Entity?

An entity is an object in the domain model with a unique identity that persists over time. Unlike simple data structures, entities are not merely defined by their attributes but by their identity and behavior. For example, a smart light within a home automation system is an entity: it has a unique identifier (e.g., an ID or name) and maintains state (such as on or off) while supporting attributes like brightness or color. Even if these attributes change, the entity’s identity remains constant.

Entity Protocol: Standardized Domain UI

The web platform provides a robust and widely supported environment for implementing domain-driven UI components. Leveraging Web Components ensures encapsulation, reusability, and framework-agnostic development, making UI elements portable and adaptable across different projects and ecosystems.

The UI Entity Protocol is a structured set of conventions built on standard Web APIs to create predictable, interactive UI components that represent domain entities. Each entity is mapped to a corresponding custom HTML element, ensuring a uniform approach to state and attribute management.

Key Aspects of the UI Entity Protocol

• Custom Elements: Each domain entity is encapsulated within a reusable web component.
• Form-Associated Custom Elements: Enables participation in native form controls, facilitating form submission and validation.
• Value Property for State: A standardized value property maintains entity state (e.g., on or off).
• HTML Attributes for Entity Attributes: Immutable or configurable attributes such as color="warm" provide structured entity definitions.
• Input and Change Events: Standard DOM events (input or change) facilitate UI updates and state propagation.

Example: Light Entity in Home Assistant

A practical example of this methodology can be found in Home Assistant, an open-source home automation platform. Devices such as lights and thermostats are represented as UI components that adhere to a structured pattern for state control and user interaction.

Example above: a Home Assistant UI card for a light entity. The interface provides a toggle (top right) to turn the light on/off, sliders for brightness (sun icon) and color temperature (thermometer icon), and a color wheel for selecting the light’s color.This example illustrates how a single custom element can present and manage multiple aspects of an entity’s state and attributes in a unified way.

A light entity can be represented using a custom element:

<ui-light value='{ "state": "on", "brightness": 80 }' color="warm"></ui-light>

• value='{ "state": "on", "brightness": 80 }' defines the light’s state and brightness level.
• color="warm" represents an immutable attribute of the entity (e.g., a fixed color temperature).
• Form-associated behavior allows seamless integration into an HTML <form> for submission and validation. This means the browser can track its value and include it in FormData on submit, and you could even apply HTML validation or :valid/:invalid style states if applicable.

Schema of Value Data

Ensuring that UI components properly handle entity state requires a structured schema. Using tools like JSON Schema or Zod, developers can enforce constraints that provide consistency and reliability at both build time and runtime.

For example, the JSON Schema for a light entity’s state might look like this:

{
  "type": "object",
  "properties": {
    "state": { "type": "string", "enum": ["on", "off"] },
    "brightness": { "type": "number", "minimum": 0, "maximum": 100 }
  },
  "required": ["state"]
}

By validating <ui-light> components against this schema, developers can enforce data integrity and ensure predictable behavior across all implementations.

Entity Attributes

Entity attributes define characteristics of an entity, which may be immutable or dynamic, depending on its role in the system.

For example:

• A basic light may have a fixed color="warm" attribute, meaning its color temperature is non-modifiable.
• A smart light could expose a dynamic color state, allowing users to define an RGB value (e.g., rgb(255, 0, 0)).

Differentiating state from attributes ensures that entity models remain both flexible and predictable within an application’s UI framework.

State and Persistence

While stateless components are ideal for general-purpose UI elements, domain entity components often require statefulness to accurately reflect the business domain. Form-associated custom elements provide a structured mechanism for state management within the browser, aligning UI components with domain-driven design principles.

However, state persistence should be managed by the application layer rather than the UI component itself. The role of a domain-driven UI component is to reflect and interact with the entity, not to handle state storage, API communication, or business logic directly. This separation ensures scalability, testability, and maintainability, adhering to best practices in DDD and UI architecture.

Conclusion

• Custom Elements offer a standardized, portable rendering target for UI development.
• The UI Entity Protocol provides a consistent methodology for mapping domain entities to UI components.
• Form-associated components facilitate structured state management and native integration within web applications.
• This approach strengthens the alignment between domain logic and UI, making applications scalable, maintainable, and AI-compatible.

By embracing Domain-Driven UI principles, enterprise applications can achieve a structured, reusable, and semantically rich UI architecture that efficiently scales with evolving business needs. To deep dive into Domain Driven Design checkout Eric Evans book Domain-Driven Design: Tackling Complexity in the Heart of Software.