Forem: Yao-Hui Chua

How to Build and Scale Design Systems: Starting with the Right Framework

Yao-Hui Chua — Tue, 28 Apr 2026 05:04:30 +0000

I've been spending the past few months juggling product engineering work with the building and scaling of design systems. While I can't reveal much about how frontends at Amazon work behind the scenes, I can share some generalizable learnings that I believe will be useful to anyone trying to establish a reusable component ecosystem of their own.

To start, I'll just focus on one specific topic: Picking the right front-end rendering framework for your design system.

React Is a (Very) Sensible Default

I've been working with React for about a decade now. I've seen the framework go through various phases:

The early era of class components, accompanied by the somewhat awkward lifecycle methods API (e.g. componentWillMount(), componentWillReceiveProps())
The emergence of React Native and the tempering of some of the "write once, use everywhere" hype
The push towards composition with functional components, hooks, concurrent mode, etc

For any web application that involves rich client-side interactions, the perks of using React and having access to the ecosystem of tooling built around it (e.g. Redux Toolkit, React Native, TanStack, Next.js, as well as component libraries like Mantine) are undeniable. Its declarative API for turning state into UI is also easy enough to pick up for most (even if it requires experience to master).

As indicated by 2025's State of JavaScript survey, React continues to lead in terms of adoption. I've had the chance to work with Angular and Vue 2/3 at various periods of my career, but I've always preferred using React to ship features.

Without having context on the specific needs of an organization, I would strongly recommend React as a safe, reliable default framework of choice for getting started with building and shipping reusable components.

... But Your Situation May Be Different

If you work at a startup and are just looking to ship fast, you're probably not pondering the question: Which framework is best for our design system?. Really, you just want to know: Which framework should we use to ship our Minimum Lovable Product?

The real demand for a design system often arises months or years into development, when your organization's product and engineering scope grows to a point where simply letting individual teams drive their own UI development doesn't scale well.

Such growing pains can manifest in several practical ways. It usually means needing to engage multiple teams just to ensure that:

Atomic UI Components (e.g. Buttons, Alerts) are rendered consistently with the same Design Tokens (e.g. colors, font, spacing)
Composite UI Components (e.g. Product Cards, Chat Widgets, Payment Widgets) don't require teams to do duplicate work
App-level and Page-level UI Patterns (e.g. Page Shell Templates, Form Data Management, Navigation) are upheld consistently, such that the complex interactions within and between screens don't throw off your customers

In particular, in companies where technical decision making is hyper-decentralized (i.e. "loosely coupled and loosely aligned"), these types of problems can easily take form.

The cost of migrating to React (or unifying towards any framework, for that matter) may be too much to bear for some. Organizational challenges and historical decisions can seriously impede the adoption of a design system.

It's one thing to convince clients to migrate from one version of React to another, but it's another thing to navigate more entrenched blockers (e.g. resource constraints, content management and rendering systems that don't support React, legacy product flows that are stitched together with server-rendered markup and jQuery, etc).

With this in mind, it is sometimes helpful to not fixate on React (or any specific front-end framework, for that matter). Rather, one can turn to the browser spec.

Web Components Are Great for Interoperability

While adoption of React has surged over the years, Web Components have also come a long way. Most browsers now support the Web Components V1 spec. We've also seen the emergence of Stencil and the replacement of Polymer with Lit.

Using Web Components instead of React to ship design system components may help you navigate interoperability challenges. Web Components are registered to the Window object and accessible to the global DOM by default:

customElements.define("my-custom-element", MyCustomElement);

Depending on the front-end landscape of your organization, different teams may have their UI templates defined using different technologies (e.g. React, PHP, JSP, etc). The neat thing about Web Components is that they are built to the browser spec, which makes them reusable across these frameworks.

Here's an example of a React component using a custom web component internally:

import React from 'react';
import './user-card.js'; // Ensure the component is registered

const Profile = ({ user }) => {
  return (
    <div>
      <h1>React Dashboard</h1>
      {/* React passes data via attributes */}
      <user-card name={user.name} theme="dark">
        <p>This is a React-managed bio.</p>
      </user-card>
    </div>
  );
};

export default Profile;

And here's an example of a JSP file also using the same custom web component internally:

<%-- profile.jsp --%>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
<head>
    <script src="user-card.js" defer></script>
</head>
<body>
    <h1>JSP Dashboard</h1>

    <%-- Assume 'user' bean is available in the request scope --%>
    <user-card name="${user.name}" theme="dark">
        <p>Logged in via Java/Spring Security.</p>
    </user-card>
</body>
</html>

As with most tools, there are always tradeoffs. In my opinion, the key thing with using Web Components over React is that you trade ease of development for interoperability.

... But Web Components Are Also Finnicky

Yes, Web Components require a lot of manual plumbing. This is natural, given they are built to match the browser spec. Lit and Stencil reduce this to some extent, but you still don't get the full range of development abstractions from frameworks like React and Vue (e.g. virtual DOM).

A lot of the complexity of working with Web Components stems from the Shadow DOM. You will need to deal with:

The Shadow DOM's encapsulation of subtree nodes and styles: A generic document.querySelector call will not return nodes inside a custom element. Global CSS classes will not influence their styles either, though there are exceptions.
Using open and closed modes: The short (and perhaps over-simplified) answer is that open mode is usually desirable, since it exposes the .shadowRoot and allows you to re-run queries within the subtree. This gives you access to the nodes and their properties (e.g. innerText), which can be useful for testing. Consumers will have to be intentional about overriding subtree nodes if they want.
Relating Properties to Attributes: In React, we mostly only care about props and state and don't have to think too much about defining them as class properties. With Web Components, we are dealing with HTML Elements that have both properties and attributes, and we need to have an idea of how to relate them (e.g. whether to use two-way or one-way binding for data, such as a value attribute that gets updated by an input event).
Slot Change Handling: While child updates may trigger re-renders in React, the same cannot be said for Web Components. Any coupling between the slot container and the slotted container has to be managed with slotchange handlers, since the slot container typically operates in the Shadow DOM even while the slotted content remains in the Light DOM.
Writing Encapsulated CSS: You will need to apply the :host selector to your CSS and have an understanding of which styles are scoped to the Shadow DOM, and which are not. Escape hatches, such as an exemption of properties like font-family, and CSS variables, allow for styles to be passed from the Light DOM to the Shadow DOM, which is useful for consistency and theming.
Accessibility Gotchas: Given that ids are unique within the Shadow DOM, you will have trouble using the for attribute to relate <label>s to <input>s, unless they exist within the same subtree. Communication between <form> elements in the Light DOM and <input>s within the Shadow DOM is also limited.
Consumer Plumbing: As a consumer, event handling may not be as simple as passing onXyzChange directly to the Web Component, as you would do with a React "prop". You will need write your own event listeners. A few things help to address this: Lit and Stencil both offer helpers that wrap your Web Components as React components, while React 19 fully supports Web Components such that you can directly pass your complex data and event handlers directly to Web Components.

In essence, the Shadow DOM helps to provide a layer of encapsulation over our custom elements, but this encapsulation comes with gotchas that developers without experience can easily trip on. LLM-assisted development will go a long way in mitigating these blindspots.

Consider a Hybrid Approach

In an ideal world, teams would share the same dependency tree and the need to address interoperability challenges would be minimal.

Clearly, we don't live in an ideal world, so some amount of interoperability is typically required. In the event that your organization uses different front-end frameworks to generate different types of templates (PHP, JSP, React), a hybrid approach may be ideal. This usually means two things:

Creating stateless UI elements using Web Components. You would maintain, in a distinct package, a set of Web Components for stateless UI primitives like your Button, Modals, and Alerts.
Handling the assembly of these stateless UI elements in React, or any other team's framework of choice. You would let your consumers import your reusable components package. Your consumers can then reference the HTML tags corresponding to your stateless elements in their respective UI templates (<my-button>, <my-modal>, etc).

A middle of the road approach like this allows you to make firm decisions on core design system concerns like typography, colors, and sizing, while giving the consumers of your components the room to own their stateful logic for matters such as user interactions (e.g. form inputs) and side effects (e.g. API requests).

... But Consolidate If You Can

Personally, I would still advise teams to unify their front-end development around a single framework. For large engineering organizations, in particular, the merits of using a consistent set of tools far outweigh the potential upside of experimentation. Your code and patterns become more predictable, which also makes it easier to build custom AI agents to do larger-scale refactors.

There is a time and place for experimentation. This can be limited to "Labs teams" working on special projects or pages with unique data requirements. Upgrades to new major versions are also worthy of consideration. Experimenting with entirely new frameworks, on the other hand, is seldom worth it — the development benefits need to be extremely compelling to justify the long-term cost.

All that said, I know that the reality on the ground is often different for many organizations. This is where the value of a hybrid approach lies.

What's Next?

Picking the right front-end framework is just one piece of the puzzle. There are so many considerations you'll need to be mindful of when buiding a design system: Token schemas, theming, CSS vending, tree shaking, layered testing, FOUC/FOUT, AI usage, etc. In a future post, I'll provide a high-level overview of some of these topics and suggest a mental model that developers can use.

The Cognitive Costs of AI Chatbots and a Framework for Better Design

Yao-Hui Chua — Thu, 12 Mar 2026 02:44:01 +0000

As engineers, when we talk about the "cost" of using AI, we tend to focus on billing costs — the cost of running OpenSearch clusters, invoking models through Bedrock, provisioning instances, etc. It's easy to forget that a frustrating user experience is often the most expensive cost to an organization.

At a time when companies are trying to aggressively incorporate AI experiences into their products, it may be tempting to want to hop on the bandwagon and package every new product requirement as a single-threaded, AI-powered chat experience. This approach, when applied to the wrong customer need, can wind up incurring a tax on the customer's mental bandwidth.

To be clear, I don't have professional experience as a UX designer or a product manager. That said, I'd like to think that I've been in enough cross-stakeholder discussions to take notice of design anti-patterns when they occur. I can't talk specifics, so I'll just illustrate this trend with a hypothetical example (and with the help of images generated using Nano Banana 2 ✨).

Product Use Case

Suppose you are building a B2B platform that enterprise employees use to book business travel. A key product requirement would be to have a "Policy Exception" process. Specifically, when an employee needs to book a flight or hotel that is over the company's budget (perhaps due to a last-minute project or limited availability), we'll need to ensure that certain conditions are met before the employee can get an exception.

On paper, this looks like a perfect use case for an AI-powered chat assistant. You might conceive of an "AI Concierge" which chats with the employee, asks for justifications, checks the company handbook, and approves the booking. However, we begin to see cracks in this model once we try to scale this out to complex tasks that require fine-grained user input.

Cognitive Overload

Chats are, by their very nature, "single-threaded experiences" — the user submits a query, and the agent responds.

When a user manages their travel plans, they aren't necessarily just looking at a single data point, or even a single series of data points. Instead, they may very well be making different decisions across different entities (e.g. making adjustments to multiple trips, with each trip being associated with a flight, a hotel, and a car rental).

An AI agent might ask: "I see your hotel is $100 over budget. Can you provide a justification?" As the employee works through their hotel budget, they might realize that changing their flight date would make a cheaper hotel available, or that the car rental for a separate trip needs to be revised.

In a chat window, context management and backtracking can be tough for the user. In a dashboard, the UI holds the state; in a chat, the user's brain fills this role. Specifically, customers would have to:

Keep the information that they've been presented with fresh in their mind
Scroll back up to find previous details if they've forgotten them
Interrupt the current thread if backtracking is required

For complex tasks involving multiple configurable items, a spatial UI (e.g. a dashboard), may very well be superior to a linear UI (e.g. a chat interface). Dashboards allow the user to navigate as they wish, whereas a chat "locks" them in the current discussion and makes it difficult for them to retain a bird's eye view of the current state.

Deterministic vs Non-Deterministic Workflows

It is easy for product, design, and engineering leaders to conflate agentification with automation.

Returning to our travel booking use case — in this example, the rules for approving a flight are usually deterministic:

If flight > 6 hours, then Business Class = Allowed.
If booking is < 24 hours away, then Price Cap = +50%.

LLMs are fundamentally probabilistic. Using a non-deterministic agent to handle rules that are strictly deterministic introduces risk, latency, and "hallucination" potential. If the rules are already well-defined, it may be wiser to prioritize building out your business logic behind a deterministic, client-facing API first. You can worry about exposing this as a tool to an AI agent later.

A Playbook for Product and Design Teams

Before committing to building an agentic chat interface for a core workflow, product managers and designers should ask themselves the following questions:

Information Complexity: Are we dealing with multiple entities that each require a series of user decisions? If yes, does the user need to be able to review the state of all entities, or is this more of a "select-and-forget" type of workflow?
Visual Real Estate: Is there sufficient space to reasonably present the decisions at stake in a single-threaded conversation? In particular, do you have mobile users and have you considered their needs?
Deterministic vs Non-Deterministic: Are the rules governing your new workflow largely binary (e.g. if X, then Y), or do they require some amount of subjective, human-like judgment?
Efficiency of User Input: Is it actually faster for a user to address their issue with a sentence, or to click a button?

You can see where I'm going with this. A use case that has high information complexity, limited real estate, strictly deterministic rules and a need for efficient user input is likely best served by a static user experience as the primary interface. An AI chatbot can serve as the secondary interface which handles the "long-tail" of subjective questions that a static UI can't predict.

It goes without saying that the two types of experiences are not mutually exclusive. Your product team can absolutely build a static UX alongside an agentic one. However, it is important to prioritize the experience that makes the most sense for your customers. To return to my original example — a "Policy Exception" customer journey should be built with a dashboard first and supplemented with a chatbot later.

The Best of Both Worlds: A Hybrid Approach

With this in mind, it's worth noting that there are ways to blend deterministic workflows with non-deterministic ones. In fact, I would argue that most products should strive to offer this type of hybrid UX, so that customers can select the UX journey that best addresses their needs.

One option is to have your AI agent as a supplementary assistant that talks users through the main experience. Several products, such as TurboTax, do this well:

This allows your user to have a bird's eye view of what's at stake, take actions as needed, while being able to communicate with an agent to get deeper insight.

Alternatively, you can also program your AI chat experience in a way that "locks users" into deterministic workflows when needed:

With this approach, customers have to complete a bounded, deterministic workflow contained within a UI widget before continuing to speak with the agent. If we go back to the "Policy Exception" use case I described, I wouldn't be a fan of this approach, because it gives the user less agency and prevents them from interjecting with questions.

That said, there's a definitely a good time and place for this type of UX. For example, surfacing an "Add to Cart" button in the chat experience is an excellent choice — Information Complexity in this situation is somewhat low and the user saves on having to type out their request (e.g. "Please add this item to my cart").

Conclusion

In a nutshell, don't blindly hop on the AI bandwagon! Customer-facing AI chatbots are a powerful tool and can elevate your core user experience. However, depending on your use case, you may need to build out a reliable static experience first before supplementing it with an agentic one.

As a front-end engineer, there are many exciting things to look out for in the realm of developing robust "static-agentic" hybrid user experiences. For example, Google has previewed plans to define a specialized UI protocol called A2UI that bridges the gap between the traditional text responses from agents and the need for highly interactive UI widgets. In the coming months and years, I also expect we'll see plenty of new patterns emerge around how parent web applications keep their state in sync with their child chatbot widgets.

AWS Cognito and IAM for Front-End Developers

Yao-Hui Chua — Fri, 16 Sep 2022 03:12:26 +0000

Whenever you build a web application, you'll often need to provision accounts for your users. By users, I'm specifically referring to customers who interact with your services via your JavaScript/TypeScript frontend.

Managing these user accounts comes with plenty of challenges. Not only will you need to persist user profiles, you'll need to figure out how users can be organized into groups, how to store credentials, what kind of auth mechanisms would be suitable, and so on.

If you're a front-end developer who mainly cares about building enjoyable web experiences, these concerns might seem tedious to deal with. Fortunately, AWS Cognito handles them for you.

In my previous blog post, I covered some basic concepts around Identity and Access Management (IAM). Now, I'd like to build on these concepts by explaining how front-end developers can easily use AWS' Cognito and IAM services to set up authentication and authorization for customer-facing applications.

AWS Cognito

As mentioned, AWS Cognito handles all the nasty user management work. When using Cognito, you really just need to be familiar with two offerings: User pools and Identity pools.

To pull a quote from the Cognito console:

User pools are user directories that provide sign-up and sign-in options for your app users. Identity pools provide AWS credentials to grant your users access to other AWS services.

User Pools

The term "user pool" is an intuitive one, as it refers to a collection of users (which can be organized into groups).

Cognito provides plenty of features for customizing how this collections of users can be managed. Amongst other things, you can:

Enable multi-factor authentication
Set up federation with identity providers such as Google or Facebook
Run customized logic as users progress through their auth-related user journeys (e.g. signing up, signing in).

When a user from your user pool logs into your application successfully, they'll have access to an ID (JWT) token from Cognito. This token can be used to obtain a set of AWS credentials corresponding to a specific IAM role. At this point, you might be wondering: How do we relate Cognito users to IAM identities at all?

Identity Pools

This is where identity pools come in.

Identity pools are a bit trickier to understand. The identities we're dealing with are IAM identities, which means their settings (e.g. permission policies) are defined in IAM, not Cognito.

I prefer to think of an identity pool as a collection of associations between IAM roles and Cognito user pools. For example, given a user pool MyUserPool, we may want to define an identity pool which assigns one IAM role (e.g. MyAuthenticatedRole) for users who are authenticated and another IAM role (e.g. MyUnauthenticatedRole) for users who are not.

In other words, these identity pools specify the relationships between user pools and IAM roles. As such, Cognito users are able to exchange Cognito tokens for AWS credentials. Front-end clients receive these credentials from STS, which allows Cognito users to interact with AWS services.

In Practice

The steps for getting started with Cognito and IAM are relatively straightforward. On your JavaScript/TypeScript frontend, I recommend using the Amplify SDK, which supports many common authentication and authorization use cases.

AWS Console TODOs

On the AWS Console, you'll have to:

Create a Cognito user pool with an app client representing your front-end web application.
Create a Cognito identity pool with roles for authenticated and unauthenticated users. As you create the identity pool, be sure to link it to your user pool and app client by listing Cognito as an Authentication provider. Also, ensure your authenticated and unauthenticated roles have the necessary IAM policies in place for them to interact with your AWS services, such as API Gateway and S3.

Front-End Application Code TODOs

In your front-end application code, you'll need to:

Store the region, user pool, identity pool id, and app client id in a configuration object (e.g. config).
Initialize Amplify with this config object (e.g. Amplify.configure(config)).
Use Amplify's Auth module for your auth-related operations. For example, you can simply invoke Amplify.Auth.signUp(...) to register a user and add them to your user pool.
Use Amplify's other modules for interacting with other services. For example, you can use Amplify.API to speak with your API Gateway endpoints.

One thing worth calling out with Amplify's API module is that it handles a lot of the IAM-based authorization work for you.

Under the hood, when you invoke a method such as Amplify.API.post(...), the module derives temporary AWS credentials corresponding to the appropriate role (e.g. MyAuthenticatedRole). These credentials are used to sign the frontend request payload before sending it to API Gateway. See this article on SigV4 for details on the signing process.

For an overview of what the architecture I've described looks like, check out this section from an AWS Identity Workshop.

Wrapping Up

Note that using Cognito with IAM is not strictly necessary. For example, you can set up your endpoints on API Gateway to directly rely on Cognito user pools for authorization. Personally, I prefer the IAM-based approach, because it aligns "how Cognito users interact with APIs" with "how AWS services generally interact with each other".

I'm constantly impressed by how much AWS is able to abstract out these software building blocks to help developers scaffold their applications quickly. For anyone looking to get their hands dirty with the tools covered, here are some useful references:

A Beginner's Guide to Cognito from one of my favorite channels:
Workshop: Using Amazon Cognito for Serverless Apps
Building an application with AWS Amplify, Amazon Cognito, and an OpenID Connect Identity Provider
Identity and Access Management for Amplify

Werewolf: A New Neo-Noir VSCode Theme

Yao-Hui Chua — Wed, 02 Jun 2021 18:48:33 +0000

Telltale's The Wolf Among Us was released in 2013 and is arguably one of the company's strongest entries in its catalog of story-driven games. The series isn't perfect, but it does have a very cinematic quality to it. The art design and narrative elements blend together really well to create a world which oscillates between fantasy and reality.

The game's thoughtful use of colors, in particular, stood out to me so much that I felt compelled to port some of its neo-noir vibes over to my workspace. A brand new VSCode theme was the perfect way to capture the spirit of this masterpiece.

You can find the final product on the VSCode Marketplace and its corresponding repository on GitHub.

Helpful Resources

Before I started working on my new theme, I searched for tutorials that could lead me through this process.

To save you time, the best guide out there at this moment is Sarah Drasner's article on CSS Tricks. It's a handy resource that walks you through the initial setup, configuration basics, and even some important points on accessibility. Alternatively, you can also take a peek at VSCode's official documentation for getting started with your first extension.

Throughout the theming process, I had some takeaways that I'll briefly share with you in this post.

Referencing Art

If you're basing your color palette on some art you've discovered, you might want to find a couple of expressive images that capture the look and feel you're gunning for. While working on my theme, I used the following piece of concept art pulled from ArtStation by Gray Rogers:

This depiction of the cityscape was important in helping me determine the kind of mood I wanted to evoke with my choice of colors. I understood that:

The theme's backdrop had to be a mix of darker shades (variants of purple and red)
Points of interest could be highlighted with bursts of neon (variants of blue and green) or yellow

This eventually led to combinations of colors like the one you see below:

Each time I spun up VSCode to iterate on my theme's colors, I adjusted my IDE's window and positioned it right next to my reference image:

This provided me with a sanity check of sorts. I was able to look at the current state of my theme and compare it to the art piece: If my theme felt like an extension of its source of inspiration, then I knew I was on the right track.

Calibrating Colors

As you might've noticed in some of the code snippets, not every noteworthy piece of syntax can be differentiated with single versions of blue, green, and yellow.

Thus, I had to expand my selection of colors by exploring different compositions of RGB values.

For example, I used #43BF90 for integers/floats and #7ACCC9 for strings. Both hex codes have a substantial amount of green in them (which makes them appear somewhat similar) but the latter also has a substantial amount of blue (which gives string primitives a more tealish glow and helps them stand out slightly from their numerical counterparts).

You can imagine extending this approach to type annotations as well. In my case, I used a darker orange for primitive type references (e.g. boolean, string) and used a color resembling gold for complex object types (e.g. Props).

To me, it makes sense to use RGB values that are slight variations of each other when coloring tokens that are functionally similar, because it feels like an intuitive way of classifying related chunks of information.

Theming the UI before the Syntax

To be clear, building a VSCode theme mostly just involves assigning hex values to keys in a JSON file that permits common violations such as trailing commas and comments:

{
    "name": "Werewolf",
    "type": "dark",
    "colors": {
        "activityBar.background": "#220033",
        "editor.background": "#1D0622",
        // ... VSCode interface colors
    },
    "tokenColors": [
        {
            "name": "Comment",
            "scope": [
                "comment",
                "punctuation.definition.comment"
            ],
            "settings": {
                "foreground": "#6464B3"
            }
        },
        // ... Syntax highlighting colors 
    ]
}

There are two major sections here: colors and tokenColors. colors manages the different components in your VSCode interface (e.g. your editor, sidebar, terminal, etc), while tokenColors handles syntax highlighting.

My suggestion is to work through your preferred colors first by going through the list of available options in the VSCode docs. You can think of these color settings as being responsible for composing the "frame" within which your code will be displayed. Updating the background colors of your editor, sidebar, and terminal is enough to radically change the overall appearance of your IDE.

Configuring tokenColors, on the other hand, is a trickier task that I wouldn't want to front-load. Syntax highlighting can be as involved as you'd like it to be; you can easily find yourself tinkering with minor details that demand a lot of consideration (e.g. your preferred colors for brackets, comments, etc).

Looking Back

I named this theme Werewolf (after the main character of the series) and shared it publicly a few months ago. Some minor administration was required too; I had to set up proper channels and templates for submitting pull requests and issue reports on the GitHub repository.

Looking back, I'm not sure this project taught me substantial things about web development, but spending those hours playing around with a bunch of colors like a kid was a pretty fun and relaxing experience.

My only regret is not shipping this out earlier because The Wolf Among Us is a pretty dated game at this point. If there's a certain visual language out there that inspires you, I encourage you to take a couple of evenings off to give theming your VSCode a shot!

Warcraft III and Web Development

Yao-Hui Chua — Tue, 20 Oct 2020 02:06:23 +0000

I ended my stint as a web engineer at Carousell a few weeks ago. With the extra time I had on my hands, I dusted off a couple of old laptops and wandered through various files and folders from my teenage life.

One of the gems I came across was a custom Warcraft III map I created in the mid-2000s that I never got around to finishing. I had planted units (i.e. character models) in their respective groups and had shaped up the terrain to look fairly immersive, but the bulk of the gameplay was still incomplete.

I figured I owed it my younger self to see the project through, so I dug up my old Warcraft III keys, re-installed the game, and started hacking away on the World Editor.

Going Back In Time

It was definitely strange revisiting the World Editor after more than a decade. Back in the day, I didn't have the slightest idea about the basics of programming, so I sort of fumbled my way through variables and conditionals. I usually tell people that my first experience with programming was Harvard's CS50, but perhaps Warcraft –– yes, Warcraft –– prepared me in ways I never realised.

There are a number of similarities between map editing and web development. This isn't exactly a profound insight, as you'd expect to find overlapping patterns between most types of user-facing applications anyway. Still, I think it'll be fun to explore this space and draw some comparisons.

Triggers / Event Listeners

Warcraft's World Editor is composed of multiple editors such as the Object Editor, the Sound Editor, and the Trigger Editor. The Trigger Editor, in particular, manages a collection of triggers which are each responsible for coordinating a specific in-game behaviour.

Suppose you want to kickstart a cinematic sequence when a unit enters a particular area. The corresponding trigger might look something like this:

Every trigger is divided into three components: Events, Conditions, and Actions. There are several online tutorials which do a solid job of explaining the rudiments, but experienced programmers will have an easy time understanding the terms: Whenever an Event occurs, the Warcraft runtime confirms if all specified Conditions have been satisfied before it runs a series of defined Actions.

As web developers, a huge part of our job involves working with event listeners, which are functionally identical to these triggers. We watch for browser events (such as resize and keydown) and respond to them by executing handlers which may subsequently invoke web APIs (such as timers and XMLHTTPRequests).

In any event-based system, a common mistake people make is forgetting to unsubscribe listeners after they've become irrelevant. Allowing a trigger to repeat itself more than once in a Warcraft map can make for a disjointed gaming experience. Similarly, in the case of web applications, failing to remove listeners can easily lead to memory leaks and unwanted side effects.

Layers / Browser Tools

Deciding how to place units, designate regions, angle cameras, and curate the terrain — these are all important aspects of a custom Warcraft map.

In the World Editor, each of these concerns are owned by a specific layer. For example, we can only move units around the map with the cursor if the Unit Palette has been selected. Likewise, if you wanted to modify the texture of the ground, you'd have to engage the Terrain Palette. We can't select items across layers and modify them simultaneously.

In the realm of web development, we often find ourselves switching between the templating (HTML), styling (CSS), and interactivity (JavaScript) tools available to us on the browser. The boundaries between them are a lot fuzzier thanks to inlined styles/scripts in HTML and the fluidity of frameworks such as React and Vue which allow us to blend the different syntaxes together (e.g. JSX, MDX).

Using triggers, map authors can direct elements from one layer to interact with elements from another (e.g. creating a specific type of unit at region X). This is kind of similar to how web developers use JavaScript to make changes to the DOM or CSSOM. Although the separation of concerns takes a fair bit of getting used to in both cases, it goes a long way providing people with a more cohesive development experience.

Player Journeys / User Journeys

At the risk of stating the obvious: As the complexity of a Warcraft map grows, the number of triggers involved naturally increases. Hence, it's important to put some thought into how triggers are classified, so that map authors have an easier time reviewing and modifying them.

For single-player maps with multiple acts or chapters, it can be difficult to keep track of the triggers used at each point of the player's journey. I've found it appropriate to group triggers by the Quests they are associated with:

Each quest can be thought of as an independent slice of the game. One quest might require the player to bring character A to point X, while another might task the player to survive enemy attacks for a specified amount of time. Unless you go out of your way to design a map that heavily relies on choice and consequence, the triggers of one quest usually don't have much bearing on the triggers of another. Thus, it makes sense to bunch up triggers together based on the quests they belong to.

In web applications, many user journeys can span multiple pages. For instance, making a purchase on an e-commerce platform can take a user from the product details page, to the cart, and then to the checkout screen. In the same vein, I've found it helpful to modularise frontends by grouping data operations by their corresponding pages.

In that sense, one might say that the relationship between quests and player journeys in Warcraft maps is somewhat analogous to the relationship between pages and user journeys in large web applications.

Concluding Thoughts

Ultimately, the challenges of map editing are still very different from web development. This is especially the case if you're creating a custom map with narrative elements. Beyond designing the in-game logic, you'll also have to get your hands dirty with other domains such as cinematography, writing, and pacing.

There are plenty of details I haven't gotten into in this article. The Warcraft Trigger Editor, at its core, is just a GUI for defining scripted behaviours. Blizzard's JASS language allows map authors to tap into all kinds of in-game possibilities.

Today, the presence of platforms such as Dreams lowers the barriers to entry for people to create games without fussing too much over the lower-level details. It's exciting to see where this field is headed and what kinds of fancy creations will emerge. Personally, I'm keeping an eye out for updates from this Avatar remake.

Feel free to watch the finished product on YouTube! It's not terribly exciting and it pales in comparison to some of the more impressive works out there, but I'm satisfied with what I got out of the creative process. My goal with this exercise was to simply reconnect with my past self while dipping my toes in as many aspects of map editing as possible:

Writing and directing cinematic sequences
Managing quests and their associated triggers
Playing with music, environment effects, and sounds
Importing and using custom models made by the community

If you've played games like Warcraft in the past, I hope this post inspires you to have fun in a similar fashion!