Cory Rylan | Web Development Articles

Your Context Files Are a Code Smell

2026-07-18T00:00:00Z

You know the file. AGENTS.md, CLAUDE.md, .cursorrules, whatever your harness calls it. It started as a few lines. Now it's four hundred. "Always use design tokens." "Never hardcode hex values." "Don't add a dependency without checking the bundle size." "Prefer composition over inheritance." A wall of please comply.

Every one of those normative lines is a guardrail you didn't write. The file isn't the solution to your agent problems. It's a symptom of your codebase problems. The more of it you have, the more likely it is that something underneath should have been enforced and isn't.

This isn't really a post about agents. It's a post about all the stuff we should have been doing as engineers the whole time. Agents just turned the lights on.

Context vs Instruction

Not every line in your context file is problematic. There are two very different things living in there.

Descriptive context. Where auth lives. The domain glossary. Which package owns what. Where the test guards are. A new human hire needs the exact same document on day one. None of it is enforceable, none of it implies bad code, and you should keep it. This is onboarding, not a smell.

Normative instructions. "Always use tokens." "Never do X." "Don't add a dep." Every single one of these is a rule a parser could check — and you wrote it as prose and shipped it on a hope.

The rest of this post is about the second pile. This is the signal that the enforcement by the system and codebase was never built.

"But judgment can't be encoded"

Sure, determinism has a ceiling. Type checks, tests, and lint catch a lot, but some calls really do come down to taste. "Don't abstract this prematurely." "This feels over-engineered." You can't write a fitness function for that.

However, here's the thing the objection misses: that ceiling is shared. A rule that's too contextual to encode as a check is also too contextual to encode as an instruction. "Use good taste about premature abstraction" is exactly as useless sitting in a markdown file as it would be as an ESLint rule. The agent can't act on it either. Anything genuinely above the ceiling lives in code review and in the moment — it never lived in your context file to begin with.

So the judgment ceiling doesn't rescue context files. A normative line in AGENTS.md is just a lower-fidelity, unenforced fitness function. Everything below the ceiling should be a real check. Everything above it can't be written down usefully anywhere. The middle, where the file pretends to live, is empty.

Closing the box

Take any normative line in your context file. It is exactly one of two things:

Encodable. Then it's a smell. You just didn't write the rule. (And you no longer have a cost excuse.)
Un-encodable and one-shot. Then it isn't durable policy. It belongs in the prompt or the PR description — not in a file that reloads on every single run.

There's no third bucket. The only thing that could justify a permanent block of prose is "recurring and un-encodable" — and that category is about to disappear.

The Elements team puts it: prompts are runtime hints, not durable data. If a fact lives only in a prompt or a README, the harness doesn't own it. If your enforcement only exists as a sentence you're hoping the model reads, you don't have enforcement.

We always should have done this

Step back from agents for a second. Types. Tests. Lint. Static analysis. Structural fitness functions. None of this is new. We've been preaching deterministic guarantees for years. Agents didn't invent the need, they just made the cost of not having it impossible to ignore.

An agent is a fast, tireless junior dev who does exactly what your enforcement allows and quietly ignores everything your prose merely requests. That's not a knock on the model. That's a mirror. Every "please don't" in your context file is a rule your CI should have been failing on, aimed at a contributor who finally takes you at your literal word.

"Agentic-ready codebase" is a fancy way of saying the hygiene we already knew we wanted, now with a forcing function holding us to it.

The cost excuse is dead

"Writing a custom lint rules for every little thing isn't worth it the effort."

That was a real argument in 2022. Authoring a custom lint rule used to cost the better part of a day. It isn't anymore. Writing a custom rule now costs minutes, and you write it with the agent itself. The economics that justified the prose collapsed. Deferral stopped being a tradeoff and went back to being laziness.

Migration state is the cleanest example, because it looks the most like legitimate prose and isn't. "We're moving from X to Y, prefer Y" is just a deprecation rule: error on new usage, baseline the existing call sites, let CI hold the line. The file that tracks the migration was never documentation. It was an unwritten rule wearing a trench coat.

What it looks like done right

I help maintain NVIDIA Elements, a design system. We have roughly sixty-five custom lint rules across two packages. Every one of them encodes an intention that a lazier repo would have dumped into AGENTS.md as a bullet point.

"No hardcoded hex, use the token" isn't a sentence in a markdown file. It's no-unexpected-css-variable.ts. The migration I just described? Six additional rules: no-deprecated-attributes, no-deprecated-css-variable, no-deprecated-packages, no-deprecated-icon-names, no-deprecated-popover-attributes, no-deprecated-global-attributes.

The detail that makes the whole approach hold up: nearly every one of those rules has a co-located test. The guardrails are themselves verified. That's the answer to "aren't you just moving trust around from the model to the linter?" No. The enforcement is deterministic and tested. The model's compliance is a property of the system, not a property of how nicely I asked.

Harness engineering is treating an agent failure as a system-design problem you solve permanently, not a prompt you retry. When the agent misuses a component, the answer isn't a better instruction, it's a rule that makes the misuse impossible. The supporting model is a "policy compiler" that runs from durable to disposable: metadata, then static tools, then CLI and skills, and only at the far disposable end, contextual markdown. Context files sit at the throwaway end of that gradient by design.

It Takes Time

Sixty-five tested rules is an end state, not an entry fee You don't sit down and write them upfront. You add a rule the moment the agent actually fails at something, not preemptively. The mature repo is where you end up after enough of those moments, not the cost of getting started. Start with almost nothing.

Descriptive context stays. Domain intent, architecture orientation, where the guards live — keep all of it, lean. The target here is narrow: normative code and architecture rules masquerading as documentation. That's the smell. Project-layer enforcement written as prose instead of code.

A large context file is liability laundering at the config layer. It's the same move as shipping code you didn't review and hoping it's fine, just pushed one step earlier in the pipeline. You're hoping the model complies instead of making compliance structural.

The metric isn't how many context files you have. It's the ratio of pleading to enforcement. Every line that pleads is a rule you owe your future self. Go count the imperatives in your AGENTS.md. That number is your backlog.

Dropdown Menus with HTML Popovers and CSS Anchor Positioning

2026-01-19T00:00:00Z

Building nested dropdown menus has traditionally required JavaScript for managing visibility, positioning, and keyboard navigation. With new browser APIs, we can now create fully functional nested dropdown menus using only HTML and CSS. In this post, we'll explore how to combine the HTML Popover API, CSS Anchor Positioning, and entry animations to build accessible nested menus.

An example of HTML Popover APIs combined with CSS Anchor Positioning

The Popover API provides built-in support for showing and hiding content without JavaScript. By adding the popover attribute to an element and using popovertarget on a button, the browser handles the show/hide logic automatically.

<button popovertarget="menu-1">Open Menu</button>
<menu id="menu-1" popover>
  <button>Menu Item 1</button>
  <button>Menu Item 2</button>
  <button>Menu Item 3</button>
</menu>

Clicking the button will toggle the menu visibility. The browser also handles closing the popover when clicking outside of it or pressing the Escape key.

Nesting Popovers

The Popover API supports nesting popovers by using popovertarget within a popover itself. This creates a parent-child relationship where child popovers stay open as long as the parent is open.

<button id="anchor" popovertarget="menu-1">Open Menu</button>
<menu id="menu-1" popover>
  <button>Menu Item</button>
  <button>Menu Item</button>
  <button popovertarget="menu-2">Submenu</button>
  <button>Menu Item</button>
</menu>
<menu id="menu-2" popover>
  <button>Submenu Item</button>
  <button popovertarget="menu-3">Nested Submenu</button>
  <button>Submenu Item</button>
</menu>
<menu id="menu-3" popover>
  <button>Nested Item</button>
  <button>Nested Item</button>
  <button>Nested Item</button>
</menu>

When a menu item with a popovertarget is clicked, the corresponding submenu opens. The browser manages the popover stack, keeping parent menus open while child menus are visible.

CSS Anchor Positioning

The CSS Anchor Positioning API allows us to position elements relative to other elements without JavaScript. For popover menus, we can use implicit anchors with position-anchor: auto to automatically anchor the popover to its triggering button.

[popover] {
  position-anchor: auto;
  position-area: bottom span-right;
  margin: 0;
  padding: 0;
  border: 1px solid #ccc;
  border-radius: 4px;
}

The position-anchor: auto property creates an implicit anchor relationship between the popover and its triggering element. The position-area property defines where the popover should appear relative to the anchor.

For nested submenus, we want them to appear to the right of the parent menu item instead of below:

[popover] ~ [popover] {
  position-area: right span-bottom;
}

This CSS sibling selector targets any popover that follows another popover and positions it to the right.

Entry Animations

To add polish to our menus, we can animate them using @starting-style and transition-behavior: allow-discrete. The @starting-style at-rule defines the initial state before an element is rendered, which is essential for animating elements that transition from display: none.

[popover] {
  transition-timing-function: ease;
  transition-property: opacity, overlay, transform;
  transition-duration: 300ms;
  transition-behavior: allow-discrete;
}

[popover]:popover-open {
  display: flex;
  flex-direction: column;
  opacity: 1;
  transform: translateY(0);
}

@starting-style {
  [popover]:popover-open {
    opacity: 0;
    transform: translateY(-10%);
  }
}

The transition-behavior: allow-discrete property enables transitioning discrete properties like display and overlay. Combined with @starting-style, this creates a smooth fade-in and slide effect when menus open.

Highlighting Active Parent Items

When a submenu is open, it's helpful to highlight the parent menu item that triggered it. We can achieve this with the CSS :has() selector:

[popover]:has(+ [popover]:popover-open) > button[popovertarget] {
  background: oklch(0 0 0 / 0.15);
}

This selector finds any popover that is immediately followed by an open popover, then highlights the button with a popovertarget inside it.

Complete Implementation

Here's the complete CSS for our nested dropdown menus:

[popover] {
  background: transparent;
  flex-direction: column;
  position-anchor: auto;
  position-area: bottom span-right;
  padding: 0;
  margin: 0;
  border: 1px solid #ccc;
  border-radius: 4px;
  transition-timing-function: ease;
  transition-property: opacity, overlay, transform;
  transition-duration: 300ms;
  transition-behavior: allow-discrete;
}

[popover] ~ [popover] {
  position-area: right span-bottom;
}

[popover]:popover-open {
  display: flex;
  opacity: 1;
  transform: translateY(0);
}

@starting-style {
  [popover]:popover-open {
    opacity: 0;
    transform: translateY(-10%);
  }
}

[popover]:has(+ [popover]:popover-open) > button[popovertarget] {
  background: oklch(0 0 0 / 0.15);
}

[popover] button {
  background: oklch(0 0 0 / 0.05);
  border-radius: 0;
  border: 0;
  padding: 8px;
  min-width: 100px;
  text-align: left;
  font-size: 14px;
  display: inline-flex;
  align-items: center;
  gap: 12px;
}

[popover] button:hover {
  background: oklch(0 0 0 / 0.15);
}

[popover] button[popovertarget]::after {
  content: '▶';
  display: inline-block;
  margin-left: auto;
  font-size: 0.8em;
  color: #484848;
}

Conclusion

The combination of the Popover API, CSS Anchor Positioning, and entry animations enables creating nested dropdown menus without JavaScript. The browser handles click-outside behavior, escape key handling, and the popover stacking context automatically. Check out the full working demo below!

Getting Started with 3D Printing - A Quick Guide

2025-12-06T00:00:00Z

I often get asked by parents and friends for 3D printing recommendations, especially when their kids are showing interest. Here's my opinionated but concise starting point for anyone looking to get into the hobby.

Highly recommend Bambu Labs for 3d printing. The software comes with Mac/Windows apps as well as iOS and Android. Bambu printers integrate directly with Makerworld for one-click printing. Bambu Lab printers can be found directly on their site or at a local Micro Center

Recommended Printers

Kids and Beginners ($200-400)

Usually can be found on sale for around $200 USD. Reliable and easy to use. Comes with sample filament and test prints to get started immediately.

https://us.store.bambulab.com/products/a1-mini

Teen and Adults ($500-900)

Enclosed printer for more advanced materials and larger prints.

https://us.store.bambulab.com/products/p2s

High End / Enthusiasts ($2000+)

Top of the line printers, largest print volumes, sensors, and materials.

https://us.store.bambulab.com/collections/h2-series

Filament

Filament is the plastic material used to print with. Filament comes in a variety of colors and types of plastics with varying levels of strength and rigidity. Its important to be aware certain plastics require additional safety measures.

Filament can be purchased around $20 USD on the Bambu website or Amazon. I recommend either the Bambu brand or Overture from Amazon.
Beginners should stick with PLA filament as this is safer than more advanced plastics that require active ventilation systems such as ABS.
Filaments should be stored in a cool dry area, with humidity no higher than 30%. High humidity will cause the filament to become brittle and fail during printing.

Safety and Support

3d printing takes practice and patience.

Bambu Labs has a beginners online course to 3d printing https://bambulab.com/en/support/academy
Bambu support has a support site full of resources on debugging issues: https://bambulab.com/en/support
Do not print in an enclosed space or bedroom. 3d printing can vent gases or micro plastics. Print in an open well ventilated area.
Do not leave printers unattended for extended periods. 3d printers run at very high temperatures when printing and can be a fire hazard similar to kitchen appliances.

Parents

Bambu Labs apps and site are very easy to use and get started with finding 3d models via https://makerworld.com/. However, the model content on the site does not restrict content or have parental controls, so be aware and attentive when kids are browsing models online.

Using Angular CLI and Wireit

2025-07-27T00:00:00Z

As Angular and front-end projects grow in complexity, build and test times inevitably increase, impacting developer productivity and CI/CD pipeline efficiency. Long build times can slow down development cycles, delay deployments, and increase infrastructure costs. Wireit, a open source build orchestration tool, offers a solution by introducing intelligent caching and task orchestration to your npm scripts.

In this post, we'll explore how to integrate Wireit with the Angular CLI to significantly improve build and test performance through caching, while maintaining the familiar Angular development experience.

Angular CLI

The Angular CLI is the standard tool for creating, building, and testing Angular applications. Starting with Angular v20, creating a new project is as simple as running ng new followed by your project name. The CLI provides a comprehensive set of commands that handle everything from development servers to production builds.

At its core, the Angular CLI provides two essential commands for any Angular project:

ng build - Compiles your Angular application into static files ready for deployment
ng test - Runs your unit tests using Karma and Jasmine

A typical Angular project's package.json includes these standard scripts:

"scripts": {
  "ng": "ng",
  "start": "ng serve",
  "build": "ng build",
  "watch": "ng build --watch --configuration development",
  "test": "ng test"
}

While these commands work well for small to medium projects, as your codebase grows, you'll notice build times increasing from seconds to minutes. This is where Wireit comes in to help optimize your workflow.

Wireit

Wireit is a build orchestration tool that adds intelligent caching and task dependencies to npm scripts. Instead of running the same build or test commands repeatedly, Wireit caches the results and only re-runs them when the input files have changed. This can dramatically reduce build times, especially in CI/CD environments where builds run frequently.

To get started with Wireit, first install it as a dev dependency:

npm install --save-dev wireit

Then, you can convert your existing npm scripts to use Wireit. Here's how to transform the basic Angular build script:

"scripts": {
  "build": "wireit"
  ...
},
"wireit": {
  "build": {
    "command": "ng build",
    "files": [
      "src/**/*",
      "!src/**/*.spec.ts",
      "angular.json",
      "package.json",
      "tsconfig.json",
      "tsconfig.app.json"
    ],
    "output": [
      "dist/angular-wireit/**/*"
    ]
  }
}

The Wireit configuration has two critical properties:

files: Specifies which files Wireit should monitor for changes. When any of these files change, Wireit knows it needs to re-run the build. Notice we exclude test files (!src/**/*.spec.ts) since they don't affect the build output.
output: Defines the build artifacts that Wireit should cache. If the input files haven't changed, Wireit can skip the build entirely and restore these cached outputs.

Let's see the caching in action. When you run the build for the first time:

✅ Ran 1 script and skipped 0 in 2.2s.

Wireit executes the Angular build normally. But when you run the same command again without changing any source files:

✅ Ran 0 scripts and skipped 1 in 0s.

The build completes instantly! Wireit detected that no input files changed, so it skipped the build entirely. This is particularly powerful in CI environments where multiple jobs might need the same build artifacts.

Configuring Tests with Wireit

Tests require a slightly different configuration since they don't produce deployable artifacts but still benefit from caching:

"scripts": {
  ...
  "test": "wireit"
},
"wireit": {
  ...
  "test": {
    "command": "ng test --no-watch --no-progress --browsers=ChromeHeadless",
    "files": [
      "src/**/*",
      "angular.json",
      "package.json",
      "tsconfig.json",
      "tsconfig.app.json",
      "tsconfig.spec.json"
    ],
    "output": [
      "dist/test-out/**/*"
    ]
  }
}

Note that the test configuration:

Includes all source files (both application and test files) in the files array
Uses a different output directory (dist/test-out) than the build, typically for artifacts like test coverage reports.
Runs tests in headless mode for consistent CI execution

This separation ensures that build and test caches don't interfere with each other, allowing you to cache both independently.

Wireit Service

So far, we've configured Wireit for one-time build and test commands. But what about long-running processes like development servers or watch modes? Wireit handles these with a special service configuration.

A Wireit service is a long-running process that doesn't produce cacheable output but may depend on other tasks. Services are perfect for development workflows where you want the benefits of Wireit's dependency management without caching.

"scripts": {
  "start": "wireit",
  "test:watch": "wireit"
},
"wireit": {
  "start": {
    "command": "ng serve",
    "dependencies": [
      "build"
    ],
    "service": true
  },
  "test:watch": {
    "command": "ng test",
    "service": true
  }
}

The service: true flag tells Wireit that these commands:

Run continuously until manually stopped
Don't produce cacheable output
Should be restarted if their dependencies change

Notice that the start script depends on build. This means Wireit will ensure a fresh build exists before starting the development server, useful when switching branches or pulling changes.

Wireit Dependencies

One of Wireit's most powerful features is its dependency management system. You can define relationships between scripts, and Wireit will automatically execute them in the correct order, running independent tasks in parallel for optimal performance.

The dependencies array allows any script to specify which other scripts must complete successfully before it runs. For example, you might want to ensure your code builds successfully before running tests, or that linting passes before building.

Wireit analyzes the entire dependency tree and executes tasks as efficiently as possible. If two tasks don't depend on each other, they'll run in parallel. This automatic parallelization can significantly speed up complex workflows.

Creating a CI Entry Point

A common pattern is to create a single entry point for CI pipelines that runs all necessary checks:

"scripts": {
  "ci": "wireit",
  "build": "wireit",
  "test": "wireit",
  ...
},
"wireit": {
  "ci": {
    "dependencies": [
      "build",
      "test"
    ]
  },
  "build": {
    "command": "ng build",
    "files": ["src/**/*", "!src/**/*.spec.ts", "angular.json", "package.json", "tsconfig.json", "tsconfig.app.json"],
    "output": ["dist/angular-wireit/**/*"]
  },
  "test": {
    "command": "ng test --no-watch --no-progress --browsers=ChromeHeadless",
    "files": ["src/**/*", "angular.json", "package.json", "tsconfig.json", "tsconfig.app.json", "tsconfig.spec.json"],
    "output": ["dist/test-out/**/*"]
  }
}

Now your CI pipeline can simply run npm run ci, and Wireit will:

Check if the build cache is valid
Check if the test cache is valid
Run both in parallel if they're independent, or in sequence if one depends on the other
Skip any tasks where the cache is still valid

This approach scales very well to monorepos where you might have dozens of interdependent projects. Wireit ensures everything runs in the correct order while maximizing parallelization and caching.

Conclusion

Wireit levels up the Angular CLI development experience by adding intelligent caching and dependency management without changing your familiar workflow. By wrapping your existing npm scripts with Wireit, you can achieve:

Dramatic speed improvements: Skip redundant builds and tests when files haven't changed
Better CI/CD efficiency: Reduce pipeline times
Simplified orchestration: Define dependencies between tasks and let Wireit handle the execution order
Monorepo readiness: Scale your build system as your project grows

You can also adopt Wireit incrementally. Start with your slowest scripts and expand from there. Your team can continue using the same npm commands they're familiar with while benefiting from Wireit's optimizations under the hood.

To see a complete example of Angular CLI with Wireit integration, check out the demo below!

Domain-Driven Design for UI Components, Improving Consistency and Quality

2025-03-05T00:00:00Z

In an organization with inconsistent code quality and best practices, applying Domain-Driven Design (DDD) principles can bring much-needed structure. This is especially true for reusable UI component libraries, which often suffer when business logic and inconsistent patterns creep in. DDD offers a way to enforce clear boundaries and a shared understanding of the domain, without stifling collaboration or agility. Below, we explore how DDD can help and practical tips to introduce it smoothly.

Enforcing Boundaries to Mitigate Churn and Instability

One major benefit of DDD is the introduction of well-defined boundaries and APIs between different parts of the system. In DDD terms, these boundaries are often called bounded contexts—each context encapsulates a portion of the business and has a clear interface (API) for interacting with other contexts. By designing explicit interfaces and domain boundaries, you create a more stable structure that localizes the impact of changes. For example, an Open Host Service (a DDD pattern) suggests providing a stable API that hides internal changes from clients (domain driven design - Formalizing Open-Host service - Stack Overflow). This means teams can refactor or improve the internals of a component or service without breaking everything that depends on it. The result is less thrash and reduced "churn" across the organization because changes in one area are less likely to cascade into others.

From a UI component library perspective, this might mean each component or group of components has a well-defined API and responsibility. If the organization is undergoing frequent changes (people moving teams, requirements shifting), having these clear-cut boundaries acts like shock absorbers. When new developers come in or teams restructure, they can understand the system via its published APIs and domain modules, instead of diving into a tangled codebase. This structured approach also aligns well with team boundaries: ideally, each team can own a domain context and its components, focusing on their part of the system. In practice, when the domain cuts line up with team ownership, developers don’t need to keep the whole system in mind all the time, which "reduces cognitive load and leads to more focus, fewer errors, and shorter lead times" (Your Architecture as a Crime Scene! Forensic Analysis for Your Angular Solutions - ANGULARarchitects). In short, clear boundaries help each team (and component) do its job with minimal conflicts, mitigating the organizational instability that comes from everyone stepping on each other’s toes.

Keeping Business Logic Out of UI Components

Another key DDD principle is separating core business logic from presentation. In a healthy architecture, UI components should focus on how things look and feel, not on complex business decisions. DDD helps enforce this by encouraging layered designs (or hexagonal architecture) where domain logic lives in its own layer or service. The UI layer then communicates with the domain via well-defined APIs. This prevents the UI code from becoming a dumping ground for ad-hoc business rules.

Practically, this means designing UI components to be "dumb" (or presentational) wherever possible—they simply render data given to them—and keeping the "smart" decision-making in a domain layer or a container component. Consider a reusable UI component library: if such a library starts containing calculations for prices, date validations, or workflow logic, it becomes harder to reuse (since those rules might differ across contexts) and harder to maintain (a simple UI tweak could inadvertently break a business rule). By contrast, if you apply DDD thinking, the library’s components would expose **inputs and outputs that align with the Ubiquitous Language (shared domain terms), and any heavy lifting is done elsewhere (in domain services or state management).

This separation pays off in scalability and maintainability. When business rules change, you update the domain logic in one place rather than touching many UI components. The UI stays consistent and is less likely to break due to logic changes it shouldn’t have concerned itself with. As one expert advises: "for your own sake and the next developer’s, try to keep domain logic out of your controllers, views and [UI] components" ( Blazor - Where to put your domain logic). By following DDD, you naturally prevent excessive business logic from leaking into the UI, resulting in cleaner, more testable components. A button component doesn’t need to know how a refund is calculated; it just needs to call a service and display the result. This leads to a codebase where each piece has a single, clear purpose – UI for display and interaction, domain for business decisions – making the system easier to reason about.

Risks of Ignoring DDD: Bugs and Misalignment

What happens if you don’t apply these DDD principles? Inconsistent practices might continue, and the issues can compound as the system grows:

More Bugs and Unpredictable Behavior: When business logic sprawls into UI components or there are no clear boundaries, the codebase tends to experience a lot of code churn – constant rewrites and changes as different people touch the same code in inconsistent ways. Studies have found a "strong connection between high volumes of code churn and the number of defects" in a system (High code churn is not your friend | DrinkBird). In other words, if your code is in a constant state of structural flux, it’s easy for bugs to slip in. Every UI tweak might inadvertently affect a business rule and vice versa, leading to a fragile system. Without DDD-enforced structure, "the system lives in a constant state of flux where bugs are easily introduced" and knowledge disperses haphazardly (High code churn is not your friend | DrinkBird). The lack of clear ownership can mean nobody fully understands the feature, increasing the chance of mistakes.
Inconsistent Terminology and Confusion: In an unstructured environment, different teams or developers may use different terms for the same concept. For example, one team calls a key entity "Account" while another calls it "Organization" or "Customer" in the UI. This inconsistent language is more than just a naming annoyance – it causes real confusion for both developers and users. As one DDD practitioner notes, "Inconsistent terminology is a common source of confusion… Sometimes you find two [terms] in the same codebase, the UI using a third one!" (Domain Driven Design: Building a Common Language for Your Team - Paul Grau). Without a shared Ubiquitous Language (a core idea in DDD where everyone uses the same vocabulary for the domain), miscommunication can lead to bugs (for example, a developer misunderstands a requirement because the terms were unclear) and a poor user experience (if labels and concepts aren’t aligned).
Lack of Shared Domain Understanding: Perhaps the biggest risk is that teams don’t have a unified mental model of the business domain. If every developer has a slightly different understanding of how a "Booking" or "Order" works, their code will reflect those differences, creating an inconsistent mess. DDD addresses this by getting domain experts and developers to refine a model together, but ignoring DDD often means domain knowledge is spread thinly and tribal knowledge reigns. In fact, a classic study found that a "thin spread of domain knowledge within development teams [is] one of the major problems in building large, complex systems" (
Adam Tornhill's Programming Pages
). In practical terms, this means no one person or team grasps how the whole system should behave. Features built by different teams may not integrate well, edge cases get missed, and it’s hard to plan changes because there’s no single source of truth for business rules. You might also see the same logic duplicated in multiple places (since there was no central domain layer), which multiplies the bugs and maintenance effort.

Not applying DDD in a complex org can lead to a buggy, confusing system where each team speaks a "different language" and nobody has a clear big picture. These issues slow down development and erode trust in the code. DDD isn’t a magic bullet, but it directly tackles these problems by promoting a shared language, clear ownership of logic, and boundaries that confine the ripple effects of changes.

Incremental and Practical Adoption of DDD Principles

Adopting DDD principles doesn’t have to be an all-or-nothing, overnight revolution. In fact, it’s often best done incrementally to avoid overwhelming the team or causing an abrupt process change. Here are some practical ways to introduce DDD concepts gradually:

Start with Language and Models: Begin by improving communication. Work with your team and domain experts to define a few key terms in your domain and make sure everyone uses them consistently (for example, decide once and for all if it’s called "Order" or "Purchase" in code and conversations). You can introduce the idea of a glossary or ubiquitous language document. This doesn’t require changing any code, but it sets the stage for design changes. It’s a quick win – even just renaming variables or components to the agreed terms can improve clarity.
Identify Pain Points (Seams) in the Code: Look for parts of the UI or library that are causing frequent bugs or are notoriously hard to change. These are good candidates to refactor using DDD ideas. For instance, if a certain component is doing too much (calculating data, calling APIs, and rendering UI all at once), that’s a "seam" where you could introduce a boundary. Maybe split it into a domain service (or state management logic) and a simpler UI component. You don’t have to refactor the whole app—just peel off one feature at a time. One strategy is to implement new features in a DDD-aligned way while leaving legacy code as-is for now. Over time, more of the system follows the new patterns. As a guide: "Not every part of the domain needs to conform to the new structure from the start. Over time introduce boundaries at points of frequent change or fragility." (How to Implement a Hexagonal Architecture: A Comprehensive Guide—TheLinuxCode). This targeted approach ensures you’re fixing the most impactful problems first.
Apply Layering in New Development: When building the next new component or feature, try using a layered approach (even if the whole project isn’t there yet). For example, create a service or module for business logic and keep the new UI component pure. Use this as a pilot to demonstrate the benefits. Over a few iterations, others will notice that this new code is easier to work with. This creates organic buy-in. It aligns with the advice that DDD "should be approached iteratively, allowing for adjustments based on feedback and changing business needs" (Kinda Technical | A Guide to Domain-Driven Design - Successful DDD Implementations). Think of each small step as a mini-experiment: learn from it and refine your approach in the next step.
Leverage Tools for Enforcement: If you have a monorepo or modular setup (for example, using Nx or Lerna), you can start organizing libraries by domain and adding automated enforcement. Some teams tag modules as domain, ui, etc., and use lint rules to prevent, say, a ui component from directly depending on a domain-agnostic util outside its context (Domain Driven Design Implementation Plainly - DEV Community). The goal isn’t to police developers, but to provide strong guidance and guard rails so they don’t accidentally introduce unwanted couplings. Over time, these structures become the norm.

By taking it step by step, you avoid the perception of DDD as a "big bang" re-architect. Instead, it feels like a natural evolution of the codebase. Remember that DDD is as much about how we think and communicate as how we code. So even discussions in planning meetings that gradually steer toward domain terms and away from low-level UI tweaks are part of the incremental adoption. Over time, these increments add up to a significantly more robust and well-organized system.

Structured, But Still Collaborative (Guiding Contributions)

One fear teams have with any structured approach is that it will impose rigid rules and hamper collaboration or creativity. It’s important to emphasize that enforcing structure doesn’t mean shutting people down – it means guiding everyone to contribute in a way that benefits the whole project long-term.

In fact, DDD by its nature is highly collaborative. One of its central ideas is the Ubiquitous Language, which is "a collaborative process involving all stakeholders… No single group owns the language; it’s built together and used by everyone" (Domain Driven Design: Building a Common Language for Your Team - Paul Grau). This ensures that developers, product managers, designers, and domain experts are all on the same page. Rather than each team doing their own thing in isolation (which can happen in a free-for-all codebase with no rules), DDD encourages cross-team dialogue about the domain. For example, if two teams share concepts (like "Customer" or "Inventory"), DDD would have them agree on definitions and boundaries for those concepts. This kind of structured discussion actually improves collaboration – it prevents siloed decisions that clash later.

When it comes to a UI component library, having structure means contributors will know where and how to add new components or enhancements. Think of it like contributing to a well-organized open-source library: there are contribution guidelines and a defined architecture, but those exist to maintain quality and coherence, not to reject ideas. Developers can certainly propose a new component or a change, but with DDD principles in place, the conversation will be guided: "Which bounded context does this belong to?," "Does this belong in the UI library or in the domain layer?," "What should we name this component so it aligns with our domain language?" These questions make sure the contribution fits nicely into the big picture, reducing the back-and-forth later to rework things.

Also, a structured approach can actually speed up onboarding and collaboration. New team members or contributors can read the docs to learn the domain terminology and the system’s partitioning. They don’t have to decode a tangled mix of UI and business code to figure out where to make a change – the boundaries are marked. This clarity lowers the barrier for any engineer to contribute meaningfully. Teams remain open to suggestions, but structure provides a compass so that suggestions and improvements head in a productive direction. One could say, DDD sets the stage so that collaboration is more about the ideas than fighting fires in the code. The focus shifts to "Does this solve the business problem?" rather than "Will this break something in that other module?", because the latter is less likely when the architecture is well-defined.

Finally, enforcement of structure can be done with a light touch. Encourage peer reviews to not just check code style, but also architectural fit. This is not about rejecting a contribution with "you put this in the wrong place, go away" – it’s about mentoring: "This logic is great, let’s move it to our domain service so the UI stays clean." In the long run, developers appreciate this guidance because they end up with code that’s easier to maintain. It’s a bit like having building codes for constructing a house – they might constrain some choices, but everyone understands it leads to a safer, more stable house. And all the builders (developers) can still be creative within those guidelines, collaborating to build something great.

Communicating DDD Benefits Without the Drama

When introducing DDD to other teams, how you communicate can determine whether you get alignment or pushback. It’s crucial to frame the conversation in a non-confrontational, inclusive way. Here are some tips to get everyone on board smoothly:

Share Problems, Then Solutions: Start by pointing out the pain points in the current setup that everyone can relate to. For instance, bring up that last incident where a small UI change broke a bunch of functionality, or the confusion over inconsistent naming that caused extra meetings. By focusing on the issues (not blaming anyone for them), you create a common cause. Then introduce DDD principles as solutions to those specific problems. For example: "We often see bugs because feature logic is scattered in our components. If we organize by domain and keep logic in one place, we could prevent those bugs." This way, DDD isn’t a random new fad—it’s directly tied to solving the team’s struggles.
Avoid Jargon Overload: While you and a few others might be excited about "bounded contexts" and "aggregates," those terms can sound foreign or intimidating to others. When talking to other teams, use plain language or relatable analogies. Instead of "bounded context," you might say "Let’s clearly separate the order management code from the inventory code, so each can evolve on its own." Instead of "ubiquitous language," say "We should all agree on the same names for things to avoid confusion." Once people see the logic, you can introduce the official terms in a workshop or document. The goal is understanding. If people understand the why, they’re more likely to accept the how.
Emphasize Benefits, Not Critique: Frame the adoption of DDD as a positive improvement, not a criticism of past work. For example: "Our codebase has served us well so far, but as we scale, we need a clearer structure. This approach will help us add features faster and catch bugs earlier." Highlight concrete benefits that matter to them: fewer bugs, easier code reviews, ability to reuse components, clearer requirements, etc. You can mention examples of other companies or projects (if you know any) that succeeded with a domain-driven approach, to give confidence that this isn’t unproven. The key is to show that this is about making everyone’s life easier. Nobody wants more process for its own sake, but they’ll listen if it solves daily headaches.
Be Patient and Show Progress: Changing architecture and mindset is a gradual process. A non-confrontational approach means you don’t press for 100% adoption overnight. Agree on some initial steps (maybe the incremental ones mentioned earlier) and set checkpoints. Celebrate small wins publicly: "Hey, since we introduced the new Order domain module, our order-related bugs dropped this month" or "The new component library structure allowed the Mobile team to reuse our component with no changes – great example of how clear boundaries help us." Positive reinforcement can win over skeptics more than any whitepaper. Over time, as people see the value, they’ll naturally align with the approach.

In all these communications, maintain a tone of respect and teamwork. It’s about aligning towards a common goal (high-quality, maintainable software) rather than implying anyone was "doing it wrong" before. By focusing on shared values – like code quality, velocity, and developer happiness – you can ensure that adopting DDD principles is viewed as a collective improvement effort, not an imposed mandate. This minimizes friction and builds a supportive environment for the changes to take root.

Conclusion

Domain-Driven Design can sound abstract at first, but at its core it’s about making software a better mirror of the business domain while keeping the technical complexity in check. For a reusable UI component library in a messy environment, DDD principles provide exactly what’s needed: clear boundaries (so components and teams don’t step on each other), separation of concerns (so UIs stay simple and logic stays correct), and a shared language (so everyone knows what we mean by "Order" or "Booking"). Adopting DDD doesn’t require a dramatic upheaval – you can fold it into your development process gradually, picking the parts that address your pain points one by one. By doing so, you’ll likely find that code quality improves, the rate of bugs goes down, and developers can move faster with confidence.

Most importantly, none of this comes at the cost of collaboration. In fact, you’ll communicate more and better – talking about the domain and design instead of firefighting issues. Teams remain empowered to contribute, now guided by a common vision of "how we design software here." In the long run, that shared discipline pays off as the codebase grows: it stays coherent, maintainable, and aligned with the business. DDD, when applied pragmatically, becomes less of a strict rulebook and more of a guiding philosophy that everyone buys into. It’s about creating a sustainable, quality-driven engineering culture. And for a mid-level engineer looking to make an impact, championing these ideas in a friendly, example-driven way can be a rewarding path to improving your organization’s software and the happiness of the team building it.

Developing Web UI with Domain Driven Design Principles

2025-03-02T00:00:00Z

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 (for example, 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 (for example, 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 (for example, 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 (for example, 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.

Styling HTML Form Validation with CSS

2025-02-28T00:00:00Z

HTML form validation is a powerful feature that helps users fill out forms correctly. When a user submits a form, the browser will automatically validate the form fields and display error messages if the form is invalid. These error messages are displayed by the browser and are not customizable by default. In this blog post, we will explore how to create custom form validation styles using only CSS.

HTML Validation

HTML form validation is a feature that is built into all modern browsers. When a user submits a form, the browser can automatically validate the form fields based on the input type and provided attributes. For example, if a user enters an invalid email address in an email input field, the browser will display an error message indicating that the email address is invalid.

<form>
  <label for="email">email</label>
  <input type="email" id="email" name="email" required />
  <button type="submit">Submit</button>
</form>

In this example, we have a simple form with an email input field that is required. When the user submits the form without entering a valid email address, the browser will display an error message indicating that the email address is required.

Native Validation States in CSS

HTML form elements have built-in validation states that can be styled using CSS. The :valid and :invalid states can be used to style form elements based on their validation status. For example, you can change the border color of an input field when it is invalid by using the following CSS:

input:invalid {
  border-color: red;
}

However the :invalid selector is active even when the user has not interacted with the form control. This can be confusing for users as they may see error messages before they have even attempted to fill out the form. To avoid this, you can use the newer CSS pseudo-classes :user-invalid and :user-valid which only apply when the user has interacted with the form control.

input:user-invalid {
  border-color: red;
}

Custom Validation Messages

The native forms API can provide baseline validation messages for form fields. Example for an email input field with a incorrect email format we see the following:

We can customize the validation message using setting novalidate on the form element and some custom CSS. For example, we can display a custom inline error message when the user has not entered a valid email address:

<fieldset>
  <label for="email">email</label>
  <input type="email" id="email" name="email" required />
  <span aria-live="polite">valid email required</span>
</fieldset>

Using the CSS :user-invalid pseudo-class, we can combine it with the CSS :has selector to display custom inline error messages when a form field is invalid.

[aria-live='polite'] {
  color: red;
  font-size: 12px;
  display: none;
}

fieldset:has(:user-invalid) {
  input {
    border: 2px solid red;
  }

  [aria-live='polite'] {
    display: block;
  }
}

In this example, we leverage the :has selector to target the fieldset element when it has a invalid form field. We then use the aria-live attribute to show a custom error message when the user has not entered a valid email address.

Conclusion

By using the :user-invalid pseudo-class and the :has selector, you can create custom error messages for form fields. HTML form validation combined with these newer CSS features can help improve the UX of forms without requiring heavy JavaScript based solutions. Check out the full working demo below!

Design System Architecture - Managing CSS Themes

2024-08-27T00:00:00Z

Design Systems must help scale UI development across organizations and across user devices. This includes theming capabilities such as light, dark, and high contrast themes. This blog post will dive into managing CSS themes by showing strategies for dynamically loading themes and detecting which themes are available and even know when an individual theme has been loaded via events.

Detecting Active Themes

Using CSS variables to detect which theme is currently active is a powerful technique. By setting a unique CSS variable for each theme, you can easily check which theme is currently active.

To set up your CSS files for theme detection, define the --theme variable in each theme’s CSS file:

/* theme.dark.css */
:root {
  --theme: dark;
}

/* theme.light.css */
:root {
  --theme: light;
}

Then in JavaScript you can check for your active theme like so:

function getActiveTheme() {
  return getComputedStyle(document.documentElement).getPropertyValue('--theme');
}

Detecting Loaded Themes

Detecting which theme has been loaded is a similar but slightly different problem that which theme is currently being applied to our web page. We may want to determine what themes are available at runtime but not which theme is currently active. This can be useful for dynamically loading themes or for debugging purposes.

With this setup, each theme declares its unique identifier through a CSS variable, making it easy to detect which theme is active at any given time.

/* theme.dark.css */
:root {
  --theme: dark;
  --theme-dark: true;
}

/* theme.light.css */
:root {
  --theme: light;
  --theme-light: true;
}

Here’s a simple JavaScript function to detect if the theme is loaded:

function isThemeLoaded(value) {
    return getComputedStyle(document.documentElement).getPropertyValue('--theme') === value;
}

console.log(isThemeLoaded('dark'));

This function uses getComputedStyle to retrieve the value of the --theme-dark variable from the root element (:root). If the theme has been applied correctly, this value will return true, indicating that the theme has been loaded

Dynamic Loading

Dynamic loading of themes is a technique that improves performance by loading themes only when they are needed. This approach ensures that your application remains lightweight and fast, as unnecessary CSS files are not loaded upfront.

Using CSS Constructable Style Sheets its easy to load a CSS file and append it dynamically in a way that can be reused in memory (useful for Shadow DOM). Here’s how you can implement dynamic theme loading in JavaScript:

async function loadTheme(value) {
  const theme = await import(`./theme.${value}.css`, { with: 'css' }); // with syntax is relatively new, check browser support or your build tooling
  const sheet = new CSSStyleSheet();
  sheet.replaceSync(theme.default);
  document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
}

This function dynamically imports the CSS file for the selected theme. The import() function loads the CSS file only when the user requests it. Then a new CSSStyleSheet is created to hold the imported styles. The newly created stylesheet is added to the document, applying the styles immediately.

This method allows us to programmatically load themes when needed, reducing the initial load time of the application and improving performance.

Detecting Dynamic Loading

Sometimes it may be necessary to know when a theme has been loaded. One way to detect a theme loading is by listening for custom animation events triggered by the keyframe animations defined in the theme’s CSS file.

Here’s how you can set up your CSS files to trigger these events:

/* theme.dark.css */
:root {
  --theme: dark;
}

@keyframes theme-dark { }

:root {
  animation: theme-dark;
}

/* theme.light.css */
:root {
  --theme: light;
}

@keyframes theme-light { }

:root {
  animation: theme-light;
}

Each theme defines an empty keyframe animation (theme-dark or theme-light) and applies this animation to the root element. This setup allows us to detect when the theme has been fully loaded by listening for the animationstart event.

Here’s the JavaScript code to detect when a theme has been dynamically loaded:

function onThemeLoad(value, fn) {
  document.documentElement.addEventListener('animationstart', e => {
    if (e.animationName === `theme-${value}`) {
      fn(e);
    }
  });
}

onThemeLoad('dark', e => console.log(e));

This function adds an event listener to the root element, waiting for the animationstart event. When the event is triggered, it checks if the animation name matches the expected theme. If it does, the callback function is executed, confirming that the theme has been successfully loaded.

Conclusion

Managing CSS themes in a design system requires careful consideration of both performance and user experience. By detecting loaded themes through CSS variables, dynamically loading themes only when necessary, and detecting theme application through animation events, you can build a flexible and efficient theming system. This approach not only improves the overall performance of your application but also ensures that users have a smooth and responsive experience when switching between themes. Check out the live demo below to see these techniques in action!

Flow Charts with CSS Anchor Positioning

2024-05-31T00:00:00Z

With the introduction of the CSS Anchor Position API in Chrome 125, it's never been easier to position an element relative to another element. This is a great way to manage complex positioning use cases like popovers and tooltips.

However, CSS Anchor Positioning can be used for more than just popovers and tooltips, it can be used to create basic flow chart diagrams. In this post we will learn how to use CSS Anchor Positioning to create flow charts and diagram with just CSS.

This post won't cover the full Anchor Positioning API. To learn more about the CSS Anchor Positioning API in depth check out the Chrome Dev blog post Introducing the CSS anchor positioning API.

Basic Positioning

CSS Anchor Positioning is a great way to position an element relative to another element.

Basic CSS Anchor Position Demo

To create our first anchored element we need to provide a name to div "one" so we can reference it. Anchor names must be unique and start with two dashes --.

.one {
  anchor-name: --anchor-one;
}

Next we need to provide the anchor positioning for div "two." We will use anchor(--anchor-one top) to position div "two" relative to the top of div "one."

.two {
  position-anchor: --anchor-one;
  bottom: anchor(--anchor-one top);
  justify-self: anchor-center;
}

We assign the div "two" bottom position to the top of div "one" using anchor(--anchor-one top). We also use justify-self: anchor-center to center div "two" horizontally relative to div "one." We can position any side of dive "two" to any side of div "one" using the same syntax (top, left, bottom, right).

Multiple Anchors

With CSS Anchor Positioning we can anchor an element to two other elements at the same time.

CSS Anchor Positioning Multiple Demo

Just like div "one" we assign an anchor name to div "two" for our new third div to reference.

.one {
  anchor-name: --anchor-one;
}

.two {
  anchor-name: --anchor-two;
}

The third div can now reference anchors one and two for positioning. To position div "three" to the center of both divs "one" and "two," we use the anchor() function for each side of the element. We can position any side of div "three" to any side of either div "one" or "two."

In this instance we are using center instead of a side to position relative to. This creates a overlap effect for the anchors.

.three {
  top: anchor(--anchor-one center);
  bottom: anchor(--anchor-two center);
  left: anchor(--anchor-one center);
  right: anchor(--anchor-two center);
}

Basic Flow Chart Nodes

Using what we learned with anchor positioning we can create a basic flow chart.

Basic Flow Chart using CSS Anchor Position Demo

Using the same technique by anchoring an element between two nodes we can create a flow chart like effect with some additional CSS tricks.

For the third div we can change the background color to use a background gradient to create a line effect in the middle of the div.

.line {
  anchor-name: --line;
  top: anchor(--one center);
  bottom: anchor(--two center);
  left: anchor(--one center);
  right: anchor(--two center);
  position: absolute;
  z-index: -1;
  background: linear-gradient(#2d2d2d, #2d2d2d) no-repeat center/2px 100%;
}

Now that we have the centered positioned line, we can use CSS pseudo elements to create the arrow head on each side of the line.

.line::before {
  position: fixed;
  display: block;
  content: '';
  background: #2d2d2d;
  height: 2px;
}

.line::before {
  bottom: anchor(--one center);
  left: anchor(--one right);
  right: anchor(--line center);
}

Then again with a CSS pseudo element on the other side of the line.

.line::before,
.line::after {
  position: fixed;
  display: block;
  content: '';
  background: #2d2d2d;
  height: 2px;
}

.line::before {
  bottom: anchor(--one center);
  left: anchor(--one right);
  right: anchor(--line center);
}

.line::after {
  bottom: anchor(--two center);
  right: anchor(--two left);
  left: anchor(--line center);
}

Basic Flow Chart using CSS Anchor Position Demo

Multiple Node Flow Chart

This approach can be expanded on by providing additional nodes and chaining the anchors. However when we add additional lines we need to flip the line directions depending on the nodes relative position to the anchor. The CSS position-try-options allows a easy way to declare fallback positions to use if the element can't be rendered within the provided space relative to the anchor.

.line {
  position-try-options: flip-block, flip-inline, flip-block flip-inline;
  ...
}

Complex Flow Chart using CSS Anchor Position Demo

Draggable Flow Chart

Using a bit of JavaScript we can make our node elements draggable and create a draggable flow chart.

Complex Flow Chart using CSS Anchor Position Demo

Getting Started with HTML Form Events

2024-04-21T00:00:00Z

HTML forms are a fundamental part of web development, and understanding how to work with form events is crucial for building dynamic and interactive user interfaces. In this blog post, we'll explore the various types of form events provided by HTML forms and form control inputs.

Input Event

The input event is triggered whenever the value of an <input> element changes. This includes typing a new character, deleting a character, or pasting text into the field.

Our example will use a simple text input to get updates from the user input.

<label for="my-input">Text:</label>
<input id="my-input" type="text" /> 

<script type="module">
  const input = document.querySelector('input[type=text]');
  input.addEventListener('input', (event) => {
    console.log(event, input.value);
  });
</script>

In this example, we're using the querySelector method to select the <input> element with a type attribute set to "text". We then add an event listener for the input event, which is triggered whenever the value of the input field changes.

Change Event

The change event is similar to the input event, but it's only triggered when the user commits a change to the input field (for example, by pressing Enter or clicking away or "blurring" from the field).

Here's an example of how to use the change event:

<label for="my-input">Text:</label>
<input id="my-input" type="text" /> 

<script type="module">
  const input = document.querySelector('input[type=text]');
  input.addEventListener('change', (event) => {
    console.log(event, input.value);
  });
</script>

In this example, we're using the same HTML code as before, but this time we're listening for the change event instead of the input event.

Selection Inputs

Some HTML inputs such as the select or input type radio will trigger both input and change events at the same time. These inputs don't emit input the same way as text input since the value selected has no indeterminate state as the user is typing.

<label for="my-select">Select:</label>
<select id="my-select">
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
  <option value="3">Option 3</option>
</select>

<script type="module">
  const select = document.querySelector('select');
  select.addEventListener('input', (event) => {
    console.log(event, select.value);
  });

  select.addEventListener('change', (event) => {
    console.log(event, select.value);
  });
</script>

When the user selects a option both the input and change events will fire simultaneously.

Form Submit

The <form> element can also trigger events when its contents change. Forms can trigger a submit event when a submit button is clicked or the user submits via the enter key.

<form>
  <label for="my-input">Text:</label>
  <input id="my-input" type="text" /> 

  <label for="my-select">Select:</label>
  <select id="my-select">
    ...
  </select>

  <button type="button">Cancel</button>
  <button>Submit</button>
</form>

By default buttons in a form element will trigger a submit event. In cases where you want the button to not trigger the submit you must add type="button".

const form = document.querySelector('form');
form.addEventListener('submit', (event) => {
  event.preventDefault();
  console.log(event);
});

The submit event default behavior is to trigger a post back to the host server. In cases where you want to handle the event yourself via JavaScript use event.preventDefault().

Native events "bubble" meaning we can listen to events of child elements from a parent element. This can be helpful for when you want to capture input or change events of multiple inputs within a form.

const form = document.querySelector('form');
form.addEventListener('input', (event) => console.log(event));
form.addEventListener('change', (event) => console.log(event));
form.addEventListener('submit', (event) => {
  event.preventDefault();
  console.log(event);
});

In this example, we're using the same HTML code as before, but this time we're listening for input, change, and submit events.

That's it! We've explored the various types of input, selection, and form events that you can use in your HTML forms. By understanding how to work with these events, you'll be able to build more dynamic and interactive user interfaces for your web applications. Check out the full working example below.

Dynamic Contrast Layers with CSS Style Queries

2023-09-30T00:00:00Z

Creating complex nested UIs often involves balancing the fine line between aesthetics and usability. An important part of this balance is controlling the contrast in layered elements. Components nested often can blend into their parent components, making it difficult to distinguish between them.

Components typically don't have a way to know their nesting level, so they can't adjust their contrast accordingly. Traditional approaches involve using CSS variables with naming conventions such as *-on-value to represent a manual color change when on a certain layer. This approach is not only complex but also difficult to maintain.

However, with the latest CSS features, namely CSS Style Queries, you can make your UI adapt in real-time, with a dynamic layering system. Let's dive in to understand how we can build dynamic contrast layers using CSS Style Queries.

Setting Up Base Styles

We start by defining base styles using CSS custom properties. These variables set up different shades for our backgrounds:

:root {
  --layer-background: #2d2d2d;
  --layer-background-100: #2d2d2d;
  --layer-background-200: #4b4b4b;
  --layer-background-300: #757575;
  --layer: 200;
}

The --layer variable is important here as it will control which contrast layer we are currently in.

Using @container Queries

Next, we set up @container style queries to alter these styles based on the value of --layer:

@container style(--layer: 200) {
  [layer] {
    --layer-background: var(--layer-background-200);
    --layer: 300;
  }
}

@container style(--layer: 300) {
  [layer] {
    --layer-background: var(--layer-background-300);
    --layer: 200;
  }
}

[layer] {
  background: var(--layer-background);
}

The @container style(--layer: 200) and @container style(--layer: 300) queries allow you to dynamically adjust the style based on the current value of the --layer variable. It's like media queries but on a DOM Element/Component level.

Implementing Layers

Finally, we utilize these styles in our HTML elements:

<div layer>
  <input value="input" layer />
  <button layer>button</button>
  <div layer>
    <input value="input" layer />
    <button layer>button</button>
  </div>
</div>

Here, the [layer] attribute acts as a flag for elements that need dynamic contrast. The CSS rules we defined earlier will automatically update these elements based on the current --layer value.

No matter what the nesting level is, the contrast will always be consistent. This is because the --layer variable is updated based on the current nesting level. This ensures that the contrast is always consistent, no matter how deep the nesting is.

Conclusion

With CSS Style Queries, dynamic layering has become much more flexible and maintainable. You no longer have to write bulky CSS code or rely on JavaScript to make real-time UI adaptations. This opens up a new opportunities for building more accessible, and visually consistent web UI.

High Performance HTML Tables with Lit and CSS Contain

2023-08-31T00:00:00Z

Web applications often need to handle large amounts of data, with HTML tables being a common method for presentation. However, traditional HTML tables can become slow and unresponsive when dealing with thousands of rows. Fortunately, with Lit, a modern, lightweight web component library, and the magic of CSS contain, you can create high performance tables with ease.

Introduction

When working with large data sets that require display in an HTML table, performance can become a bottleneck. By combining Lit with the CSS contain property, we can achieve a high-performance table rendering experience.

Lit

The example uses TypeScript and Lit for defining a custom element. Lit is a lightweight web component library that provides a powerful templating engine for creating custom elements. While this example uses lit to render our HTML, we will be focusing on the render performance of the table and CSS itself, not the JavaScript execution time.

Below is our Lit custom element definition. This component will create a table with 10,000 rows and 4 columns. We will keep the content and CSS to a minimum to focus on the performance of the table itself.

import { html, css, LitElement } from 'lit';
import { customElement } from 'lit/decorators/custom-element.js';

@customElement('ui-element')
export class Element extends LitElement {
  static styles = [css`...`];

  #items = Array.from(Array(10000).keys()).map(i => ({ id: i, status: 'status', task: 'task', value: 'value' }));

  render() {
    return html`
    <table>
      <thead>
        <tr>
          ${Object.keys(this.#items[0]).map(i => html`<th>${i}</th>`)}
        </tr>
      </thead>
      <tbody>
        ${this.#items.map(i => html`
        <tr>
          ${Object.keys(i).map(key => html`<td>${(i as any)[key]}</td>`)}
        </tr>`)}
      </tbody>
    </table>
    `;
  }
}

The table is populated with dynamic data stored in the #items array.

#items = Array.from(Array(10000).keys()).map(i => ({ id: i, status: 'status', task: 'task', value: 'value' }));

The render method makes use of Lit's html tag to create the table dynamically.

render() {
  return html`
    <table>
      <!-- header and body -->
    </table>
  `;
}

Let's take a look at the performance profile of this table with a bound scroll height of 300px.

Render Performance

Below is our HTML Table rendered with a Lit based Web Component. This table is rendering 10,000 rows and 4000 cells.

Our render time on a Macbook M1 Pro hits around ~950ms. We can see the majority of the work is in the render phase (purple) and only a fraction is JavaScript execution (yellow). Even with only a fraction of the rows visible in the viewport, the browser still needs to render all 10,000 rows.

CSS Contain

The static styles property includes all CSS needed for the table and the host element. Here, the contain property improves performance by isolating the rendering of the element.

:host {
  contain: strict;
  contain-intrinsic-height: 300px;
}

The CSS Containment: Isolates the element from the rest of the layout, reducing layout and paint times. The Intrinsic Heights: contain-intrinsic-height allows browsers to lay out the page more efficiently by providing a expected default height to prevent layout reflow calculations

The table row adds similar properties with the addition of content-visibility: auto, which skips rendering of off-screen elements. This is property is what gives a huge performance boost to the table.

& tr {
  contain: strict;
  content-visibility: auto;
  contain-intrinsic-height: auto 42px;
}

Now let's take a look at the same table without CSS contain adjustments.

Our render time on a Macbook M1 Pro hits around ~500ms. We can see the render has dropped quite a bit. A large amount of the work is no longer required because the browser is no longer rendering all 10,000 rows, but only the rows visible in the viewport.

Now sub second renders with both versions of the table may be negligible, but the performance gains will be more noticeable on more complex tables or lower end devices. Let's update the grid to contain a button in each cell to introduce some complexity but omit the CSS Contain properties.

We can see the render time jumps significantly, on a Macbook M1 pro the render time is ~11 seconds. This is because the browser is rendering all 40,000 buttons, even though only a fraction are visible in the viewport. Let's add back the CSS Contain properties.

Our render time drops down to about ~500ms. This is a huge performance gain, especially when dealing with complex tables. It is not ideal to ever have tables if this size from an accessibility and user experience standpoint, but it is a good example of how CSS contain can improve performance.

Conclusion

Using CSS contain property can yield a highly performant rendering, capable of handling large datasets without sacrificing user experience. Checkout the working demo below!

High Performance HTML Tables with Lit and Virtual Scrolling

2023-07-30T00:00:00Z

Web applications often need to handle large amounts of data, with HTML tables being a common method for presentation. However, traditional HTML tables can become slow and unresponsive when dealing with thousands of rows. Fortunately, with Lit, a modern, lightweight web component library, and the magic of virtual scrolling, you can create high performance tables with ease.

Setting the Table

Let's start with a basic LitElement named ui-element:

import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators/custom-element.js';
import { virtualize } from '@lit-labs/virtualizer/virtualize.js';
import { styles } from './element.css.js';

@customElement('ui-element')
class Element extends LitElement {
  static styles = [styles];

  #items = new Array(10000).fill('').map((_i, n) => ({ column: `${n}-0`, column1: `${n}-1`, column2: `${n}-2`, column3: `${n}-3` }));

  render() {
    //...
  }
}

Our custom element ui-element has an array #items containing 10,000 objects, with each object having four key-value pairs. That's a lot of data for an HTML table!

Rendering with Lit

Next, we use Lit's html tagged template to create the table. We define a header using <thead>, and for each key in our item object, we render a table header <th>:

render() {
  return html`
  <table>
    <thead>
      <tr>
        ${Object.keys(this.#items[0]).map(i => html`<th>${i}</th>`)}
      </tr>
    </thead>
    <tbody>
      //...
    </tbody>
  </table>
  `;
}

Virtual Scrolling

Here comes the tricky part. If we tried to render all 10,000 rows, our application would become sluggish. Virtual scrolling is a technique that only renders the items that are currently visible in the viewport.

We leverage @lit-labs/virtualizer, a library that provides a function virtualize to achieve this:

${virtualize({ scroller: true, items: this.#items, renderItem: (i: any) => html`
  <tr>
    ${Object.keys(i).map(key => html`<td>${i[key]}</td>`)}
  </tr>`
})}

We tell virtualize to create a scrollable area with scroller: true and pass our #items array. The renderItem function takes an item and returns a template literal to generate a row <tr> with a cell <td> for each key-value pair in the item.

import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators/custom-element.js';
import { virtualize } from '@lit-labs/virtualizer/virtualize.js';
import { styles } from './element.css.js';

@customElement('ui-element')
class Element extends LitElement {
  static styles = [styles];

  #items = new Array(10000).fill('').map((_i, n) => ({ column: `${n}-0`, column1: `${n}-1`, column2: `${n}-2`, column3: `${n}-3` }));

  render() {
    return html`
    <table>
      <thead>
        <tr>
          ${Object.keys(this.#items[0]).map(i => html`<th>${i}</th>`)}
        </tr>
      </thead>
      <tbody>
        ${virtualize({ scroller: true, items: this.#items, renderItem: (i: any) => html`
          <tr>
            ${Object.keys(i).map(key => html`<td>${i[key]}</td>`)}
          </tr>`
        })}
      </tbody>
    </table>
    `;
  }
}

Conclusion

With Lit and virtual scrolling, you can efficiently manage and present large amounts of data in HTML tables. These techniques enable smooth user experiences, making your web application more responsive and performant. Check out the full working demo below!

Creating Dynamic Tables in Lit

2023-06-30T00:00:00Z

In this tutorial, we'll dive into creating dynamic tables in Lit, a lightweight, efficient, and powerful library for developing web components. Lit makes it easy to create highly reusable UI components that can be used in any web application. In our example we will create a small HTML table that displays data from a dynamic data source.

First, import the required modules:

import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators/custom-element.js';
import { styles } from './element.css.js';

Here we are importing html and LitElement from the lit package. html is a tagged template function that we will use for creating HTML templates. LitElement is the base class from which our component will extend. customElement decorator is used to define a custom element.

Next, we declare a custom element:

@customElement('ui-element')
class Element extends LitElement {
  static styles = [styles];
  ...
}

Using the @customElement decorator, we create a new custom element called 'ui-element' that extends LitElement. styles is an optional property to provide styles for the custom element.

We then define an array of objects, #items, each object representing a row in the table:

#items = [
  { id: 'one', status: 'complete', task: 'build' },
  { id: 'two', status: 'working', task: 'test' },
  { id: 'three', status: 'failed', task: 'deploy' }
];

Each object has id, status, and task properties which we will use as the columns of our table. Next is the render function, which is where the dynamic table is created:

render() {
  return html`
  <table>
    <thead>
      <tr>
        ${Object.keys(this.#items[0]).map(i => html`<th>${i}</th>`)}
      </tr>
    </thead>
    <tbody>
      ${this.#items.map(i => html`
      <tr>
        ${Object.keys(i).map(key => html`<td>${i[key]}</td>`)}
      </tr>
      `)}
    </tbody>
  </table>
  `;
}

In this function, we create a <table> with <thead> and <tbody> elements. The header row is generated by mapping over the keys of the first item in our #items array and creating a <th> element for each key.

The body of the table is generated by mapping over #items. For each item, we create a <tr> element. Within this, we map over the keys of the item and create a <td> element for each key, inserting the corresponding value.

That's it! With this setup, you have a dynamic table in Lit. This table adapts to the structure and contents of the #items array, allowing flexibility and reusability in your web components. Check out the full working demo in the link below!

Creating Dynamic Tables in Angular

2023-05-31T00:00:00Z

Displaying data in tables is a common requirement in our apps. Angular provides declarative features and techniques to create dynamic tables. In this blog post, we will be exploring how to create dynamic tables in Angular by breaking down and explaining a example that leverages these Angular template features.

Component Setup

import 'zone.js/dist/zone';
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { bootstrapApplication } from '@angular/platform-browser';

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule],
  template: `...`,
})
export class App {
  items = []
}

bootstrapApplication(App);

Starting from the top, we import the necessary modules: zone.js/dist/zone, @angular/core, @angular/common, and @angular/platform-browser. CommonModule is imported from @angular/common to access common Angular directives like ngFor.

Next, we define a Component using the @Component decorator and leveraging the new standalone component API introduced in Angular 16.

Templating

One of the methods to create DOM quickly from Arrays and Objects the use of the structural directives *ngFor and the Pipe keyvalue. These Directives allow for iterating over objects or arrays directly in component templates easily and reflect/update when there are any changes to that data.


@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule],
  template: `
    <table>
      <tbody>
        <tr>
          <th *ngFor="let field of items[0] | keyvalue">{{field.key}}</th>
        </tr>
        <tr *ngFor="let item of items">
          <td *ngFor="let field of item | keyvalue">{{field.value}}</td>
        </tr>
      </tbody>
    </table>
  `,
})
export class App {
  items = [
    { id: 'one', status: 'complete', task: 'build' },
    { id: 'two', status: 'working', task: 'test' },
    { id: 'three', status: 'failed', task: 'deploy' }
  ]
}

The template is where we define our dynamic table. We utilize HTML table tags (<table>, <tbody>, <tr>, <th>, <td>) to structure the table and Angular's *ngFor directive to iterate over the data and display it.

The first <th> tag uses *ngFor to loop over the keys of the first item in our items array, this will create a column header for each key in the item object. The keyvalue pipe is used to transform the object into an array of key-value pairs, allowing *ngFor to loop over them.

In the following <tr> tag, another *ngFor directive is used to loop over each item in our items array. Within each table row, a <td> tag uses a *ngFor directive to loop over the fields of the item object just like our columns, creating a table data cell for each field.

It's important to note that when using the keyvalue pipe that the default order of the field will be sorted alphabetically as property order is not guaranteed on JavaScript objects.

That wraps up our dive into creating dynamic tables in Angular. This approach allows for great flexibility as the structure of the table adapts to the data, accommodating additional fields or changes in the data structure. Check out the full working demo below!

Reusable UI Components Anti-Pattern, API Inheritance

2023-04-30T00:00:00Z

When designing and building reusable UI Components, certain API choices can cause unexpected problems down the road as components mature. In this post, we are going to cover one of those anti-patterns, API Inheritance.

Let's start with our use case story, a simple button. We build out our reusable button and ship it to production without issue.

<ui-button>
  menu
</ui-button>

A few weeks later, a new feature request comes in that wants buttons to have an icon in the button for certain use cases. We have a ui-icon component built, so we add it to the button component and add a new API to render our button with and designated icon. We keep it simple and terse by adding an icon property/attribute to render the icon.

<ui-button icon-name="menu">menu</ui-button>

The button is shipped to production and everything works out as expected. A few weeks later, we get a new request. In certain cases, the icon in the button should change between a solid or outline style. So we add a new endpoint to customize our icon within the button.

<ui-button icon-name="menu" icon-solid>menu</ui-button>

But before we get to ship our feature, another request has come in. The optional icon we added in the button actually needs to be at the start, before the text within the button.

<ui-button icon-name="menu" icon-align="start" icon-solid>
  menu
</ui-button>

Encapsulating child components and exposing their APIs to the host component might seem appealing for the sake of terse code. However, over time, as the icon component's API grows, the host component's API (for example, the button API) may experience pressure to absorb and expose additional API endpoints for the icon. This pressure, known as "API Inheritance," can create tightly coupled and non-explicit APIs that only exist for specific component combinations. Consequently, the API becomes more complex and verbose as more "escape hatches" are required.

Introducing "escape hatch" APIs like positioning in our button can complicate things even further for use cases of internationalization where reading order and elements are reversed for right-to-left languages.

Let's look at an alternative composition-based approach with the same requirements as above.

<ui-button>
  menu <ui-icon name="menu" solid></ui-icon>
</ui-button>

Rather than having the button expose an icon, we can use composition to render the icon within the button. In Web Components, this can be done with the slot APIs, Angular with ng-content, and React with the children prop.

By using composition, we prevent the button from inheriting the API of the icon. As the icon API grows, the button remains stable. This keeps the component APIs distinct, with one API to use per component. Composition avoids creating a third meta API that acts as a glue between coupled component APIs.

<!-- API Inheritance -->
<ui-button icon-name="menu" icon-align="start" icon-solid>
  menu
</ui-button>

<!-- API Composition -->
<ui-button>
  menu <ui-icon name="menu" solid></ui-icon>
</ui-button>

In our example, API inheritance results in an API with 77 characters, while composition produces an API with only 67 characters. API inheritance, although initially tempting, can lead to increasingly complex APIs over time. By leveraging composition, we can avoid supporting tightly coupled APIs and maintain a smaller, easier-to-learn supported API surface area in the long run.

CSS Container Queries in Web Components

2023-03-31T00:00:00Z

CSS Container Queries provide a powerful way to apply styles based on the size of a component's container, rather than just the size of the viewport. This allows for more modular, responsive, and reusable components. In this blog post, we will explore how to use CSS Container Queries in Web Components by examining a code example and understanding its different parts.

Our example component will adjust its text and border color based on its current size.

Creating a Web Component

First, let's examine the JavaScript code for creating the Web Component:

const template = document.createElement('template');
template.innerHTML = `
  ...
`;

class Element extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.appendChild(template.content.cloneNode(true));
  }
}

customElements.define('ui-element', Element);

In this code snippet, we create a new HTML template element and set its innerHTML property with the desired styles and markup. We then define a new custom element called ui-element by extending the HTMLElement class. In the constructor, we attach a shadow root and clone the contents of the template into it. Finally, we register the custom element using customElements.define.

Defining the Styles

Now let's take a closer look at the styles in the template:

:host {
  display: block;
  container-type: inline-size;
}

p {
  --color: red;
  color: var(--color);
  border: 2px solid var(--color);
  padding: 12px;
  margin: 0;
}

The :host selector targets the custom element itself. We set its display to block, add a margin to separate it from other elements, and enable inline resizing. We also set the container-type property to inline-size, which is required for container queries to work. The container-type sets the appropriate container type for the container query. This can be along the block or inline axis.

We define a paragraph style with a custom property --color, which is later used for both the text color and border color. Initially, the color is set to red.

Applying Container Queries

Now, let's look at the container queries themselves:

@container (min-width: 200px) {
  p {
    --color: blue;
  }
}

@container (min-width: 400px) {
  p {
    --color: green;
  }
}

We use the @container at-rule to apply styles based on the container's width. When the container's width is at least 200 pixels, we change the color to blue, and when it's at least 400 pixels, we change it to green. These styles will be applied to the paragraph element inside the component.

Using the Web Component

Lastly, let's look at how to use the Web Component in our HTML code:

<ui-element style="width: 150px">hello there</ui-element>
<ui-element style="width: 250px">hello there</ui-element>
<ui-element style="width: 400px">hello there</ui-element>

We create three instances of the ui-element component, each with different widths. The container query styles will be applied based on the width of each component, resulting in different colors for each instance.

We learned how to use CSS Container Queries in Web Components to create responsive and reusable components. Container queries enable developers to apply styles based on the size of a component's container, making it easier to create modular and adaptable designs. Check out the full working demo below!

Reusable Component Patterns - Default Slots

2023-02-28T00:00:00Z

When building reusable Web Components, it's important to consider how developers will use them in various contexts. One common challenge is providing reasonable defaults that work for most use cases, while still allowing customization when necessary.

For example, imagine an alert message component that can display different status states, such as success, warning, and danger.

<ui-alert>default alert</ui-alert>
<ui-alert status="info">info alert</ui-alert>
<ui-alert status="success">success alert</ui-alert>
<ui-alert status="warning">warning alert</ui-alert>
<ui-alert status="danger">danger alert</ui-alert>

Each state may require a different icon to be displayed within the alert message. By default, the component can provide its own set of icons for each status state, but this may not be sufficient for all use cases.

One approach to address this challenge is to use the Shadow DOM feature Slots, which allow developers to customize or project content into specific parts of a component's template without having to modify the component's implementation.

With default slots, the alert component can internally provide default icons for different status states, while still allowing developers to customize the icons as needed. Here's an example of how this could be implemented:

<!-- ui-alert template -->
<slot name="icon">
  <ui-icon name=${this.status}></ui-icon>
</slot>

The above code defines a default slot named "icon" within the alert component's template. It uses JavaScript template literals to dynamically set the name of the icon based on the status of the alert.

Developers can then use this slot to project their own icon into the alert component, overriding the default icon:

<!-- API usage -->
<ui-alert>
  <span slot="icon">🎉</span>
  custom icon alert
</ui-alert>

In the above example, the developer is passing a custom icon to the alert component using the icon slot. The component will render this custom icon instead of the default icon for the "warning" status state.

By using default slots, we can mitigate the risk of tightly coupled APIs and maintain a clear separation of concerns between the alert and icon elements. It also allows developers to have full control over the custom icon without the alert element needing to expose the icon through a series of inherited attributes and properties.

As with all API design choices, there are tradeoffs involved and it's important to consider the benefits and potential challenges of each approach. However, using default slots is a powerful technique for building reusable components that provide reasonable defaults while also allowing for customization when necessary. Check out the full working demo below!

Reusable Component Anti-Patterns - Semantic Obfuscation

2023-01-31T00:00:00Z

In this post we will take a look at one of the common pitfalls when designing a highly reusable UI component. We will look at the various tradeoffs when rendering application provided content within our reusable component.

When designing composition-based component APIs, it is important to push the semantics of the HTML into the light DOM or within control of the consumer. This helps to create valid DOM structure and improved overall accessibility. For example, if a card component includes an h1 heading, this creates an incorrect DOM structure as there should only be one h1 element within the page. By pushing the semantics of the heading up into the light DOM, the consumer can control the heading level and ensure that the page structure is correct.

<!-- ui-card internal template -->
<h1><slot name="header"></slot></h1>
<slot></slot>
<slot name="footer"></slot>

<!-- consumer API -->
<ui-card>
  <div slot="header">header</div>
  <p>content</p>
</ui-card>

It is important to push the semantic meaning of elements up to the consumer, rather than obfuscating it internally. This enables the consumer to control the appropriate heading levels for their page, which is important for accessibility and features like aria-describedby for associating content. By exposing the semantic meaning of elements to the consumer, we can enable more accessible and flexible behaviors in our components and libraries.

<!-- ui-card internal template -->
<slot name="header"></slot>
<slot></slot>
<slot name="footer"></slot>

<!-- consumer API -->
<ui-card>
  <h2 slot="header">header</h2>
  <p>content</p>
</ui-card>

This example uses Web Components and Shadow DOM however this principal applies to frameworks as well, like React children props and Angular ng-content.

Composition-based APIs may sometimes be more verbose than other approaches, however they have the advantage of lowering the overall API surface area of the system and ensuring that there is only one way to use any component. This makes it easier for consumers to learn and use the APIs, as the usage remains predictable and reliable throughout the system.

API abstractions can provide a convenient layer on top of the components, making them more concise and opinionated while still enabling consumers to access the reusable components directly as needed. However, it is important to carefully consider the tradeoffs involved in using these abstractions. It's easier to add new abstractions but much more difficult to fix or remove the wrong abstractions.

Year Reflections of 2022

2022-12-31T00:00:00Z

This year has been a big one for me in terms of career growth and personal development. I made the decision to leave my position on the Clarity Design Team at VMware and join the ML Ops team for Autonomous Vehicles at NVIDIA. This has been an exciting opportunity that has allowed me to work with cutting-edge technology and contribute to the development of self-driving cars.

In addition to my new role at NVIDIA, I also made open-source contributions through my work on BlueprintUI. I launched a revamped and consolidated version of all my previous UI open source projects, which has been well-received by developers and designers alike.

I also had the opportunity to speak at two industry events this year. The first was DevUp St. Louis, where I taught a one-day Angular workshop. The second was WebCon at the University of Illinois, where I gave a talk on design systems. Both of these experiences allowed me to share my knowledge and insights with others in the tech community.

Overall, it's been a busy and rewarding year for me. I'm excited to see what the future holds and continue learning and growing as a professional.

Cory Rylan | Web Development Articles

Your Context Files Are a Code Smell

Context vs Instruction

"But judgment can't be encoded"

Closing the box

We always should have done this

The cost excuse is dead

What it looks like done right

It Takes Time

Dropdown Menus with HTML Popovers and CSS Anchor Positioning

The HTML Popover API

Nesting Popovers

CSS Anchor Positioning

Entry Animations

Highlighting Active Parent Items

Complete Implementation

Conclusion

Getting Started with 3D Printing - A Quick Guide

Recommended Printers

Kids and Beginners ($200-400)

Teen and Adults ($500-900)

High End / Enthusiasts ($2000+)

Filament

Safety and Support

Parents

Using Angular CLI and Wireit

Angular CLI

Wireit

Configuring Tests with Wireit

Wireit Service

Wireit Dependencies

Creating a CI Entry Point

Conclusion

Domain-Driven Design for UI Components, Improving Consistency and Quality

Enforcing Boundaries to Mitigate Churn and Instability

Keeping Business Logic Out of UI Components

Risks of Ignoring DDD: Bugs and Misalignment

Incremental and Practical Adoption of DDD Principles

Structured, But Still Collaborative (Guiding Contributions)

Communicating DDD Benefits Without the Drama

Conclusion

Developing Web UI with Domain Driven Design Principles

Reusable UI Principles with DDD

Core Domain-Driven Design Concepts

What is DDD?

What is a Domain?

What is an Entity?

Entity Protocol: Standardized Domain UI

Key Aspects of the UI Entity Protocol

Example: Light Entity in Home Assistant

Schema of Value Data

Entity Attributes

State and Persistence

Conclusion

Styling HTML Form Validation with CSS

HTML Validation

Native Validation States in CSS

Custom Validation Messages

Conclusion

Design System Architecture - Managing CSS Themes

Detecting Active Themes

Detecting Loaded Themes

Dynamic Loading

Detecting Dynamic Loading

Conclusion

Flow Charts with CSS Anchor Positioning

Basic Positioning

Multiple Anchors

Basic Flow Chart Nodes

Multiple Node Flow Chart

Draggable Flow Chart

Getting Started with HTML Form Events

Input Event

Change Event

Selection Inputs

Form Submit

Dynamic Contrast Layers with CSS Style Queries

Setting Up Base Styles

Using @container Queries

Implementing Layers