Lecture slides

• 1: The Modern Web Platform & Browser Internals
• 2: Semantic HTML, Accessibility, Internationalization & the DOM
• 3: Modern CSS Architecture & Layout Systems
• 4: Modern JavaScript & Asynchronous Programming
• 5: TypeScript, Runtime Contracts & Safe Data Boundaries
• 6: Component-Driven Architecture & Design Patterns
• 7: Reactivity & Rendering Mechanics
• 8: State Management, Routing & Form Architecture
• 9: Client–Server Communication, APIs & Cache Management
• 10: Real-Time Communication, Offline Systems & Client Persistence
• 11: Rendering Topologies: CSR, SSR, SSG & Beyond
• 12: Modern Build Systems, Development Tooling & Team Workflows
• 13: Front-End Security, Authentication & Browser Isolation
• 14: Scaling Front-End Architecture: Design Systems, Monorepos & Micro-Frontends
• 15: Core Web Vitals & Performance Engineering
• 16: Testing Strategies for Resilient Interfaces
• 17: Continuous Delivery, Observability & Maintenance
• 18: Front-End Architecture & Technical Decision-Making

1 - The Modern Web Platform & Browser Internals

The Modern Web Platform & Browser Internals

From the first HTML bytes to the next interaction

Chapter 1 · Modern Front-End Engineering

Polla Fattah

The files loaded. Why does the page still feel slow?

A catalogue heading appears before its image.

Clicking Load products appears to do nothing - then everything changes together.

What would you inspect first: the requests, the handler, or the rendering work?

What we will explain

• How the browser discovers resources.
• Why downloading and executing a script are different events.
• How document state becomes a frame.
• Why synchronous code, microtasks, and timers behave differently.
• What evidence DevTools can - and cannot - provide.

One small page

<link rel="stylesheet" href="styles.css">
<script src="legacy.js"></script>
<script defer src="app.js"></script>

<h1>Products</h1>
<button id="load-products">Load products</button>
<p id="status" role="status"></p>
<img src="hero.webp" alt="Featured products"
     width="800" height="400">
<ul id="products"></ul>

Use the full document in the chapter for the practical.

A browser provides more than a JavaScript engine

The engine executes language code.

The browser also provides networking, the DOM, events, timers, storage, and rendering.

Work can happen concurrently, but ordinary page JavaScript and much rendering work compete for main-thread time.

Navigation has setup costs

For https://shop.example.com/products?page=2:

1. Resolve the destination if necessary.
2. Establish or reuse a connection.
3. Request the document.
4. Begin processing available HTML.

Caches and restored pages can change this path. A small resource on a new origin may still incur setup cost.

Parsing and downloading overlap

HTML bytes arrive → parsing begins
                          ↓
                 stylesheet discovered → request
                          ↓
                 more markup arrives → continue

The browser does not generally wait for the complete HTML before discovering other resources.

The arrows show dependencies, not measured durations.

Discovery can be the delay

<img src="hero.webp" alt="Featured products">

versus a URL assigned only when JavaScript runs:

const image = new Image();
image.src = "hero.webp";

Unless another reference reveals it earlier, the second request depends on script execution. Assigning src can start the request before insertion into the DOM.

A stylesheet can hide another dependency

HTML → stylesheet → needed background image

The browser needs the CSS before discovering the image through that rule.

Discovery, resource use, and request scheduling are different steps. A declared font that is never used need not be downloaded.

Speculative discovery can look ahead

A preload scanner may inspect available markup while the main parser waits for a script.

It can find a later image or script reference.

It cannot execute arbitrary JavaScript to discover its future results or inspect bytes that have not arrived.

Do not assume a universal browser thread arrangement.

Resource hints have different jobs

A hint does not make bandwidth unlimited. Measure whether it addresses an actual delay.

Source HTML is not the live DOM

document.querySelector("#status").textContent = "Loaded";

The DOM changes; the original response does not.

Demonstration: compare the document response in Network with the status paragraph in Elements/Inspector.

Classic scripts can stop the parser

Place this in legacy.js in the head:

console.log(Boolean(document.querySelector("h1")));

The heading has not been parsed: false.

Move the script after the heading: it can find the node.

Node availability does not prove that it has painted.

Choose script timing

For external scripts declared in the initial HTML:

async does not mean execution on a background thread.

CSS can delay a script too

<link rel="stylesheet" href="styles.css">
<script src="legacy.js"></script>

A previously encountered stylesheet can block this script.

The parser is waiting for the script, so CSS can indirectly prolong the pause.

CSS blocking presentation and a script blocking parsing are different dependencies.

Readiness is not responsiveness

• DOMContentLoaded: parsing and relevant deferred script processing have progressed to this milestone.
• Window load: additional load-delaying resources have completed.
• Neither guarantees a particular paint time or fast future interactions.

Module experiments here omit imports and top-level await to keep the comparison focused.

From state to a frame

DOM + stylesheet information
              ↓
      Style calculation
              ↓
           Layout
              ↓
    Paint and raster work
              ↓
         Compositing

An update may reuse work or skip stages. This is a conceptual model, not an engine’s thread diagram.

Width and transform do different things

list.style.width = "320px";
list.style.transform = "translateX(20px)";

Width can change wrapping and neighboring geometry.

A transform changes visual placement without reallocating normal-flow space.

Some transforms can reuse painted content. That is not a universal performance guarantee.

A read can force layout

for (const row of rows) {
  row.style.width = "300px";
  widths.push(row.getBoundingClientRect().width);
}

Compare with writing all widths first, then reading them.

Reset the starting state. Batching may reduce repeated layout; the first read can still require it.

Predict the output

console.log("start");
setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("promise"));
console.log("end");

Write your prediction before running it.

Explain the output

start
end
promise
timeout

Synchronous work finishes first. The already-fulfilled Promise’s reaction runs at a microtask checkpoint before the timer task.

This is not a claim that all asynchronous operations finish before timers.

A task is not followed by a guaranteed paint

Selected task → microtask checkpoint → scheduling continues
                                            ↓
                       rendering when opportunity and scheduling permit

requestAnimationFrame() schedules a callback for a rendering update, not an after-paint notification.

An expensive callback remains expensive.

Why might “Working…” never appear?

Inside the click handler:

status.textContent = "Working…";
const start = performance.now();
while (performance.now() - start < 200) {
  // Bounded demonstration only.
}
status.textContent = "Finished";

Both DOM changes occur. The intermediate state may never reach the screen.

Microtasks are not background work

A microtask can queue another microtask.

The checkpoint keeps processing them, delaying later tasks if the chain grows.

Use the bounded chain in the chapter. Do not freeze the page with an endless loop.

Moving expensive work into a Promise callback does not make it free.

DevTools demonstration: discovery

1. Serve the chapter’s small page over local HTTP.
2. Record browser, cache, and throttling settings.
3. Capture the image request from initial markup.
4. Remove that reference; assign the same URL after a timer.
5. Compare initiators and request start times in separate runs.

Explain differences; do not expect identical millisecond values.

DevTools demonstration: execution and rendering

1. Record a click on the bounded slow handler.
2. Locate its execution in a performance trace.
3. Compare the DOM update with the visible result.
4. Reset the page before comparing layout experiments.

A breakpoint changes timing. A console log proves execution, not paint.

Evidence before optimization

An unexplained trace is a reason to investigate, not to invent a guaranteed sequence.

Practical 01

Produce predictions, comparable observations, and an explanation of one surprise.

The core exercise covers discovery, script timing, scheduling, and rendering work.

Fixed-height virtualization is optional; deeper profiling belongs with Chapter 15.

Open the practical

Check your understanding

• Why can a downloaded script still be waiting?
• What does finding a DOM node tell you about paint?
• Why does a zero-delay timer run later?
• Which evidence would distinguish loading delay from execution cost?

Next: what should the document mean?

Browser behavior explains how a page runs.

Chapter 2 examines how semantic structure, accessible controls, language, and direction describe the interface people use.

Read Chapter 1 · Read Chapter 2

2 - Semantic HTML, Accessibility, Internationalization & the DOM

Semantic HTML, Accessibility, Internationalization & the DOM

Meaningful structure, inclusive interaction, and the browser’s live document tree

Chapter 2

Polla Fattah

Today’s goal

Build a mental model in which one document is shared by:

• the browser;
• keyboard users;
• assistive technologies;
• JavaScript;
• search and other software.

The goal is not to memorise tags. It is to choose structure, behaviour, language, and DOM operations deliberately.

By the end of today you can

• choose HTML for meaning and behaviour, not default appearance;
• structure a page with headings and landmarks;
• explain accessible names, focus order, labels, and errors;
• use native controls before inventing ARIA widgets;
• distinguish language from writing direction;
• query, traverse, create, and update DOM nodes safely;
• explain event propagation and delegation;
• describe where Web Components fit without replacing semantic HTML.

The chapter’s single model

flowchart TD
    A[Semantic HTML] --> B[Native browser behaviour]
    B --> C[Accessibility representation]
    C --> D[Language and direction]
    D --> E[DOM tree and events]
    E --> F[Web Components]

These are not separate tricks. They are different views of the same interface model.

A running example: a public-service portal

We will imagine a multilingual service interface with:

• a site header and primary navigation;
• a page explaining one service;
• a request form;
• a table of existing requests;
• a status filter;
• Arabic and English content;
• a small custom element where a reusable boundary is useful.

The interface will remain understandable before JavaScript enhances it.

HTML describes meaning, not appearance

These fragments may look similar after CSS:

<div class="heading">Service Requests</div>
<div class="navigation">
  <div class="link">Home</div>
  <div class="link">Requests</div>
</div>

But the browser cannot infer the intended roles reliably.

Prefer the meaningful structure

<h1>Service Requests</h1>

<nav aria-label="Primary">
  <a href="/">Home</a>
  <a href="/requests">Requests</a>
</nav>

<main>
  <!-- the page's primary content -->
</main>

The second version identifies headings, navigation, links, and main content without requiring a stylesheet or a JavaScript guess.

One durable rule

Choose HTML according to meaning and behaviour before styling it according to appearance.

HTML answers:

What is this?

CSS answers:

How should it look?

JavaScript answers only the behaviour that needs application logic.

Build a document hierarchy

<body>
  <header>...</header>
  <nav aria-label="Primary">...</nav>
  <main>
    <h1>Citizen Services</h1>
    <section>
      <h2>Request a document</h2>
    </section>
  </main>
  <footer>...</footer>
</body>

The hierarchy should make sense if all styling disappears.

Headings are content structure

Use heading levels to represent relationships:

<h1>Citizen Services</h1>
  <h2>Request a document</h2>
    <h3>Required information</h3>
  <h2>Existing requests</h2>

Do not choose <h3> because its default font size looks convenient.

There is no automatic outline rescue

Do not assume that nested sections automatically create a perfect heading outline for every tool.

Make the heading hierarchy explicit:

• one clear page-level <h1>;
• meaningful <h2> regions;
• <h3> only when a subsection belongs to the preceding <h2>;
• no skipped levels just for visual size.

Use CSS for size. Use headings for structure.

Landmarks give the page a map

Landmarks help users and tools move through a large interface.

<main> and <nav>

There should normally be one primary <main> for the page.

Give multiple navigation regions useful names:

<nav aria-label="Primary">...</nav>
<nav aria-label="Service sections">...</nav>
<nav aria-label="Breadcrumb">...</nav>

The label distinguishes regions that would otherwise all be announced as navigation.

<header>, <footer>, and <aside>

These elements are contextual:

<article>
  <header><h2>Request status</h2></header>
  <p>...</p>
  <aside>Last updated yesterday</aside>
  <footer>Source: service desk</footer>
</article>

They are meaningful when their content has the corresponding relationship; they are not decorative wrappers to use everywhere.

<section> and <article>

Use <section> for a thematic region that normally has a heading.

Use <article> for content that could stand on its own or be reused:

<section aria-labelledby="requests-title">
  <h2 id="requests-title">Existing requests</h2>
  <article>Request #1042</article>
  <article>Request #1043</article>
</section>

If a generic container has no semantic purpose, <div> is the honest choice.

Lists carry relationships

Use list elements when the content is a list:

<ul>
  <li>Proof of identity</li>
  <li>Proof of address</li>
</ul>

Do not build a list from paragraphs and line breaks merely because CSS will make it look like one.

Tables carry data relationships

<table>
  <caption>Existing service requests</caption>
  <thead>
    <tr><th scope="col">Reference</th><th scope="col">Status</th></tr>
  </thead>
  <tbody>
    <tr><td>1042</td><td>In review</td></tr>
  </tbody>
</table>

The caption and header relationships make the data understandable outside the visual grid.

Figures, captions, and media

<figure>
  <img src="map.png" alt="Service centres in Baghdad and Basra">
  <figcaption>Available service centres.</figcaption>
</figure>

An image’s alternative text describes its purpose in context. Decorative images may use an empty alt=""; omitting alt is not the same decision.

Native controls are behaviour with a contract

Native elements bring established behaviour:

<button type="button">Show request details</button>
<a href="/requests/1042">Open request 1042</a>
<input type="checkbox" name="urgent" id="urgent">
<details><summary>More information</summary>...</details>

The browser, keyboard, accessibility APIs, and form system already understand these controls.

Buttons perform actions; links navigate

<!-- Changes state on this page -->
<button type="button" data-action="filter">Filter</button>

<!-- Takes the user to another resource -->
<a href="/requests/1042">View request</a>

Do not use a clickable <div> when a button or link expresses the real job.

The clickable <div> problem

This creates a visual imitation, not a complete control:

<div class="button" onclick="openDialog()">Open</div>

It lacks, unless you recreate them correctly:

• keyboard activation;
• focusability;
• the button role;
• disabled semantics;
• expected browser behaviour;
• a reliable accessible name.

Start with <button> and style it.

The accessibility tree is not the DOM tree

The browser uses the DOM and other information to expose an accessibility representation.

Assistive technology may receive:

button: Submit request
heading level 1: Citizen Services
navigation: Primary
textbox: Email address

Good structure gives the browser useful information to expose.

Accessible names answer “what is this?”

Controls need names users can perceive through their chosen interface:

<label for="email">Email address</label>
<input id="email" name="email" type="email">

Visible labels are usually the strongest starting point. Placeholder text is a hint and should not replace a label.

Name icon-only controls deliberately

<button type="button" aria-label="Close request details">
  <span aria-hidden="true">×</span>
</button>

The icon is visual decoration. The accessible name communicates the action.

Prefer visible text when space allows; it helps every user, not only screen reader users.

Keyboard interaction is part of the interface

Ask these questions for every interactive feature:

• Can the user reach it with the keyboard?
• Is the focus order logical?
• Is the focus indicator visible?
• Can the user operate it without a pointer?
• Does focus move somewhere sensible after a state change?

Accessibility is interaction design, not a final inspection step.

Focus order follows the interface’s meaning

Avoid using positive tabindex values to force an artificial order.

Prefer:

• meaningful document order;
• native controls;
• a visible focus style;
• a small, deliberate focus-management rule only when a component requires it.

If the DOM order is wrong, CSS reordering does not repair the reading or keyboard model.

Forms are an accessibility system

<form>
  <label for="reference">Reference number</label>
  <input id="reference" name="reference" required>
  <button type="submit">Find request</button>
</form>

The form needs a relationship between label, control, name, value, validation, and error feedback.

Native validation is useful information

<label for="email">Email address</label>
<input id="email" name="email" type="email" required>

Native constraints can provide a baseline. If JavaScript adds custom errors, it must preserve a clear message, association, and recovery path.

Do not make invalid state visible only through colour.

Group related controls

<fieldset>
  <legend>Preferred contact method</legend>
  <label><input type="radio" name="contact" value="email"> Email</label>
  <label><input type="radio" name="contact" value="phone"> Phone</label>
</fieldset>

fieldset and legend communicate the group relationship that a visual box alone cannot provide.

Associate errors with the control

<label for="phone">Phone number</label>
<input id="phone" aria-describedby="phone-error" aria-invalid="true">
<p id="phone-error">Enter a phone number including the area code.</p>

The error should explain what is wrong and how to fix it. Do not only add a red border and expect the user to infer the problem.

ARIA adds semantics only when HTML cannot

ARIA can describe a custom interaction, but it does not automatically create the keyboard behaviour, focus management, state changes, or event handling.

flowchart TD
    A["First choice: Native HTML"] --> B["Second choice: Native HTML + enhancement"]
    B --> C["Last choice: Custom ARIA widget with full contract"]

ARIA can make good HTML worse

Do not add roles that contradict the element’s real meaning:

<button role="heading">Submit</button>

The role does not repair a confused design. Use the element that expresses the job, then add only the missing semantic information.

Language begins in the document

<html lang="en">

For a passage in another language:

<p lang="ar">مرحباً بكم في خدمات المواطنين</p>

Language metadata supports pronunciation, hyphenation, spell checking, translation, search, and assistive technology decisions.

Language and direction are different

lang identifies the language. dir identifies the writing direction.

<p lang="ar" dir="rtl">خدمات المواطنين</p>
<p lang="en" dir="ltr">Citizen services</p>

Arabic does not mean every surrounding interface region must be permanently right-aligned. Direction belongs to the text and layout context.

Direction can be automatic

<p dir="auto">User-entered text appears here.</p>

dir="auto" lets the browser infer direction from the first strong character. It is useful for unknown user content, but explicit direction is better when the application knows the language and layout contract.

Bidirectional text needs isolation

User-generated text can contain characters with different directionality.

<p>
  Ticket reference: <bdi>{{ reference }}</bdi>
</p>

Use <bdi> when embedded user text should not disturb the surrounding order. Use <bdo dir="rtl">...</bdo> only when deliberately overriding direction.

RTL is not “mirror everything”

RTL-aware design considers:

• text direction;
• logical properties such as margin-inline-start;
• icon meaning;
• navigation order;
• tables and numbers;
• mixed-language content;
• focus and reading order.

Do not replace every left value with right and call the interface localized.

The DOM is a live tree

HTML is the source representation. The DOM is the browser’s live object tree.

flowchart TD
    Doc[Document] --> HTML[html]
    HTML --> Head[head]
    HTML --> Body[body]
    Body --> Header[header]
    Body --> Main[main]

JavaScript reads and changes this live tree. It does not edit the original Markdown or HTML source file.

Nodes and elements are related

The DOM contains different node types:

• document nodes;
• element nodes;
• text nodes;
• comment nodes.

An element is a node, but not every node is an element. APIs such as children, childNodes, parentElement, and textContent expose different views of that tree.

Query the DOM precisely

const form = document.querySelector('[data-service-form]');
const fields = form.querySelectorAll('input, select, textarea');

Use stable, meaningful selectors. Check whether a query can return null, and avoid assuming that a selector matched the element you intended.

querySelector() returns the first match. querySelectorAll() returns a static NodeList of all matches.

Traverse relationships deliberately

const row = event.target.closest('tr[data-request-id]');
const requestId = row?.dataset.requestId;

Useful relationships include:

• parentElement;
• children;
• nextElementSibling;
• closest();
• matches().

Traversal should express the component boundary, not depend on fragile visual nesting.

Create and insert elements safely

const message = document.createElement('p');
message.textContent = userMessage;
message.className = 'status-message';
container.append(message);

Prefer textContent for untrusted text. Do not use innerHTML as a convenient string formatter when the value may contain user or remote data.

Attributes and properties are connected, not identical

checkbox.setAttribute('aria-checked', 'true');
checkbox.checked = true;

Attributes are markup-facing values. Properties are live JavaScript-facing state. Boolean controls make the distinction especially visible:

checkbox.defaultChecked // initial value
checkbox.checked        // current live value

Events connect users to the DOM

button.addEventListener('click', (event) => {
  submitRequest();
});

Events carry an interaction through a tree. Understanding that path is more reliable than attaching random handlers until the interface appears to work.

Event propagation has phases

flowchart LR
    subgraph Capture["1. Capture Phase"]
        W1[window] --> D1[document] --> A1[ancestors]
    end
    subgraph Target["2. Target Phase"]
        A1 --> T[target element]
    end
    subgraph Bubble["3. Bubble Phase"]
        T --> A2[ancestors] --> D2[document] --> W2[window]
    end

The event can be observed at different points in the path. This is why a parent can respond to an interaction that occurred on a child.

target and currentTarget differ

list.addEventListener('click', (event) => {
  console.log(event.target);        // where it started
  console.log(event.currentTarget); // this listener's element
});

Confusing these values is a common source of bugs in delegated interfaces.

Default actions and propagation are different

link.addEventListener('click', (event) => {
  event.preventDefault(); // cancel navigation
  event.stopPropagation(); // stop this event moving farther
});

stopPropagation() does not cancel the browser’s default action. Use each operation only for the problem it solves.

Event delegation scales repeated UI

table.addEventListener('click', (event) => {
  const button = event.target.closest('[data-action="cancel"]');
  if (!button) return;
  cancelRequest(button.dataset.requestId);
});

One listener can handle current and future matching descendants. The handler must still validate the target and preserve keyboard-accessible controls.

Put the public-service interface together

<html lang="en">
  <body>
    <header>...</header>
    <nav aria-label="Primary">...</nav>
    <main>
      <h1>Citizen Services</h1>
      <section aria-labelledby="form-title">...</section>
      <section aria-labelledby="table-title">...</section>
    </main>
    <footer>...</footer>
  </body>
</html>

Now add language metadata, labels, native controls, meaningful table headers, and safe DOM updates before adding custom interaction.

Web Components extend HTML

Web Components provide browser-native mechanisms for reusable boundaries:

• Custom elements define a new element name;
• Shadow DOM can isolate internal markup and styles;
• Slots allow controlled content insertion.

They are tools for encapsulation, not a reason to discard document meaning.

A custom element still needs a contract

class RequestStatus extends HTMLElement {
  connectedCallback() {
    this.textContent = this.getAttribute('status') ?? 'Unknown';
  }
}

customElements.define('request-status', RequestStatus);

The element needs clear inputs, output meaning, lifecycle behaviour, and an accessibility story. Encapsulation does not make an interface accessible by itself.

Shadow DOM is not a security boundary

Shadow DOM can hide implementation details and scope styles.

It does not automatically provide:

• security isolation;
• an accessible name;
• keyboard behaviour;
• correct focus management;
• a good component API.

Treat it as an encapsulation mechanism, not a trust boundary.

Slots preserve controlled composition

<request-card>
  <span slot="status">In review</span>
</request-card>

Slots allow consumers to provide content to named insertion points. The component still owns the surrounding semantics and must define how slotted content participates in the accessible interface.

The component should not erase the document

Good component design preserves:

• meaningful HTML where native elements already work;
• accessible names and labels;
• predictable keyboard behaviour;
• language and direction metadata;
• a clear DOM and event contract.

Web Components are an extension point, not a replacement for semantic HTML.

Misconceptions to leave behind (Part 1)

Misconceptions to leave behind (Part 2)

The practical lab

Build a semantic multilingual service interface.

The runnable code will be in the separate Playground repository. This deck provides the learning sequence and the current repository provides the instructions.

Practical stages 1–3: structure and meaning

1. Create the document hierarchy with header, nav, main, and footer.
2. Add meaningful headings, sections, articles, lists, a figure, and a table.
3. Build a request form with labels, native controls, a fieldset, and a legend.

Check that the page still communicates its structure without CSS.

Practical stages 4–6: interaction and language

4. Test the interface with keyboard-only navigation.
5. Add English and Arabic content with correct lang and dir values.
6. Inspect the accessibility representation and repair missing names or relationships.

Do not treat a passing visual inspection as an accessibility test.

Practical stages 7–10: DOM and components

7. Query and update the DOM with safe text insertion.
8. Add event delegation for repeated request rows.
9. Create a small Web Component with an explicit contract.
10. Draw the final architecture and identify what remains native HTML.

The exercise is complete when the component boundary is explainable, not merely when the screen looks correct.

Try it yourself

Choose one interface feature and review it in four views:

1. What does the raw HTML say?
2. What does the keyboard user experience?
3. What name and role does assistive technology receive?
4. What does the DOM event path do when the user interacts?

Write one improvement that helps at least two of these views at once.

Troubleshooting questions

Change one thing at a time and inspect the actual DOM after each change.

Completion check

• I can choose semantic elements without relying on their default styles.
• I can describe the page using landmarks and a heading hierarchy.
• Every form control has a meaningful accessible name.
• I can use the keyboard through the interface and see focus.
• I can distinguish lang from dir and handle mixed-direction text.
• I can query and update the DOM without unsafe string insertion.
• I can explain event propagation, default actions, and delegation.
• I can describe what Web Components add and what they do not guarantee.
• I completed the Chapter 2 practical in the companion Playground.

Next: Modern CSS Architecture & Layout Systems

Chapter 3: the cascade, layout systems, responsive design, container queries, layers, design tokens, and the difference between visual flexibility and structural chaos.

Modern Front-End Engineering

3 - Modern CSS Architecture & Layout Systems

Modern CSS Architecture & Layout Systems

From cascade decisions to responsive, internationalized component systems

Chapter 3

Polla Fattah

Today’s goal

Stop treating CSS as a collection of visual fixes.

Today we will use CSS as:

• a precedence system;
• a value and token system;
• a layout system;
• a responsive system;
• an internationalization system;
• and an architecture for change.

By the end of today you can

• explain why a CSS declaration wins or loses;
• use cascade layers to control ownership;
• distinguish raw tokens from semantic tokens;
• choose normal flow, Flexbox, Grid, or positioning intentionally;
• use intrinsic sizing, minmax(), clamp(), and subgrid;
• distinguish viewport responsiveness from container responsiveness;
• build direction-independent layouts with logical properties;
• use modern selectors without creating specificity traps;
• compare plain CSS, CSS Modules, utility CSS, and CSS-in-JS by problem;
• design a responsive multilingual catalogue without JavaScript measurement.

CSS is a system, not decoration

A dashboard must answer architectural questions:

• What happens when the page narrows?
• What happens when a card moves into a narrow sidebar?
• How do cards align when descriptions have different lengths?
• How do long translations affect the layout?
• Which rule wins when a library and the application disagree?
• How can one design decision update the whole interface?

These are system-design questions expressed through CSS.

The chapter’s progression

flowchart TD
    A[Cascade & Precedence] --> B[Values & Tokens]
    B --> C[Layout Systems]
    C --> D[Responsive Design]
    D --> E[Internationalized Layout]
    E --> F[Modern Selectors]
    F --> G[Styling Architecture]

The goal is not to memorise properties. It is to make CSS behaviour predictable enough to change safely.

The cascade is the foundation

<button class="action primary">Submit request</button>

button  { background: gray; }
.action { background: blue; }
.primary { background: green; }

The cascade decides which declaration supplies the final value.

The answer is not always “the last rule”.

Why declarations compete

Candidate declarations may differ by:

1. origin and importance;
2. cascade layer;
3. specificity;
4. scope or proximity where relevant;
5. source order.

The useful question is:

Why did this declaration win?

That question is more valuable than memorising a score.

Browser, user, and author styles

The page starts with more than our stylesheet:

• the browser supplies user-agent styles;
• users may supply preferences or styles;
• the author supplies application styles.

An unstyled <h1> is already bold, large, and separated from nearby text.

Author CSS is not the only styling authority. This matters especially for accessibility preferences and !important declarations.

Inheritance is an architectural tool

body {
  color: #222;
  font-family: system-ui, sans-serif;
}

Descendant text normally receives these values without repeating them on every element.

Properties such as color and font-family commonly inherit. Properties such as margin, padding, border, and width normally do not.

Use inheritance for broad design decisions, then override at meaningful boundaries.

Specificity is not a quality ranking

.card h2 { color: navy; }

#dashboard .card h2.title {
  color: purple;
}

The second selector is harder to override, but that does not make it better.

High specificity increases the cost of future changes.

Prefer a selector that is easy to reason about and easy to replace.

Do not reduce specificity to arithmetic alone

Specificity is one stage in the cascade, not the entire cascade.

Before comparing selectors, ask:

• Are both declarations in the same origin?
• Are they in the same layer?
• Is one declaration important?
• Is a scoped rule involved?
• Only then: which selector is more specific?

The browser is resolving a precedence system, not grading CSS style.

Source order is the final tie-breaker

.notice { color: blue; }
.notice { color: green; }

When the earlier cascade stages tie, the later declaration wins.

Source order is useful for intentional overrides. It is dangerous when a stylesheet becomes a sequence of unexplained patches.

Cascade layers make ownership explicit

@layer reset, base, components, utilities;

@layer reset { /* normalize browser differences */ }
@layer base { /* element defaults and typography */ }
@layer components { /* cards, forms, navigation */ }
@layer utilities { /* small explicit overrides */ }

The layer order is declared once. A later layer can win without requiring an increasingly specific selector.

Layer precedence comes before specificity

@layer base {
  #app .button { color: blue; }
}

@layer components {
  button { color: green; }
}

The simple selector in the later components layer can win over the highly specific selector in the earlier base layer.

This lets architecture control precedence before selector complexity grows.

A practical layer architecture

@layer reset, tokens, base, components, utilities, overrides;

Possible ownership:

The names matter less than the stable ownership contract.

Custom properties participate in the cascade

:root {
  --color-accent: #1464a0;
}

.button {
  background: var(--color-accent);
}

Custom properties are live CSS values. They inherit, cascade, and can be overridden by component or theme boundaries.

They are more powerful than text replacement.

Custom properties can represent decisions

.card {
  --card-gap: 1rem;
  gap: var(--card-gap);
}

.card--compact {
  --card-gap: 0.5rem;
}

The component keeps one layout rule. A meaningful boundary changes the value.

This is different from searching and replacing every 1rem in a project.

Raw tokens and semantic tokens

Raw token:

--blue-600: #1464a0;

Semantic token:

--color-action-primary: var(--blue-600);

Components should usually consume semantic meaning. If the brand palette changes, the component should not need to know the replacement colour.

Token ownership has direction

flowchart TD
    A[Raw palette] --> B[Semantic meaning]
    B --> C[Component usage]
    C --> D[Page composition]

Avoid letting a component reach backward into arbitrary raw palette values.

Stable semantic names reduce the blast radius of visual change.

Theming with custom properties

:root {
  --surface-page: #ffffff;
  --text-primary: #172a42;
}

[data-theme="dark"] {
  --surface-page: #0c2238;
  --text-primary: #f5f7fa;
}

body {
  background: var(--surface-page);
  color: var(--text-primary);
}

The component stays attached to meaning. The theme changes the values.

Start with normal flow

Normal flow is the layout system already provided by the browser.

<main>
  <h1>Catalogue</h1>
  <p>Results appear below the heading.</p>
  <ul>...</ul>
</main>

Let content determine height and let blocks participate in the document before reaching for positioning.

Positioning changes the relationship

.badge {
  position: absolute;
  inset-block-start: 0.5rem;
  inset-inline-end: 0.5rem;
}

Absolute positioning can be correct for a badge anchored to a card. It is a poor replacement for a page layout system when content can grow or translate.

Use fixed and sticky positioning with equally explicit viewport and scrolling assumptions.

Flexbox is one-dimensional

Use Flexbox when items are primarily arranged along one main axis:

.toolbar {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 1rem;
}

The main axis follows flex-direction. The cross axis is perpendicular to it.

Main axis and cross axis

.toolbar {
  display: flex;
  flex-direction: row;
}

For a row:

• the main axis is inline/horizontal in the usual LTR case;
• the cross axis is block/vertical.

Use justify-content for main-axis distribution and align-items for cross-axis alignment. Always consider writing direction before describing an axis as “left” or “right”.

Flex sizing is not just alignment

.toolbar__search {
  flex: 1 1 20rem;
  min-inline-size: 0;
}

Flex sizing considers:

• the flex basis;
• grow and shrink factors;
• available free space;
• minimum sizes;
• intrinsic content size.

min-inline-size: 0 can be necessary when a flexible child must be allowed to shrink rather than force overflow.

Grid is two-dimensional

.catalogue {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 1.25rem;
}

Grid describes rows and columns together. It is a strong choice when the relationship between both axes matters.

Grid tracks express constraints

.catalogue {
  grid-template-columns:
    repeat(auto-fit, minmax(min(100%, 16rem), 1fr));
}

This says:

• create as many tracks as fit;
• do not make a card narrower than its useful minimum;
• share remaining space between tracks.

The layout responds to available space without a device list.

Intrinsic sizing asks the content

.label {
  inline-size: fit-content;
}

Useful intrinsic concepts include:

• min-content: the smallest size without avoidable breaking;
• max-content: the size needed by the unwrapped content;
• fit-content(): a bounded content-aware size.

Intrinsic sizing is especially important when translations and user content change the amount of text.

Alignment is a separate decision

.card-grid {
  display: grid;
  place-items: start stretch;
}

Do not mix up:

• track sizing;
• item alignment inside a track;
• content distribution across tracks.

The right property depends on which relationship you are trying to control.

Grid or Flexbox?

They are complementary systems, not competing religions.

Nested Grid has a boundary

A nested grid creates a new grid context:

.card-list { display: grid; }
.card { display: grid; }

The inner card does not automatically inherit the outer grid’s tracks. This is often correct, but it means related content may fail to align across siblings.

subgrid shares tracks intentionally

.cards {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
}

.card {
  display: grid;
  grid-template-rows: subgrid;
  grid-row: span 3;
}

subgrid allows descendants to participate in the parent grid’s track sizing. It is useful when card headings, descriptions, and actions should align across cards with different content lengths.

Do not use subgrid automatically

Use it when shared track alignment is a real requirement.

Avoid it when:

• cards have independent internal structure;
• the extra coupling makes the component harder to reuse;
• a simpler normal flow is sufficient;
• the alignment is only decorative.

Layout power should follow a demonstrated relationship.

Responsive design is not a device list

Avoid designing only for:

flowchart LR
    A[Phone] --> B[Tablet] --> C[Desktop]

Real interfaces encounter:

• split-screen windows;
• zoom;
• long translations;
• embedded cards;
• sidebars;
• accessibility text size changes;
• unusual aspect ratios.

Responsive design responds to constraints, not product labels for devices.

Begin with a fluid layout

.page {
  inline-size: min(100% - 2rem, 72rem);
  margin-inline: auto;
}

.title {
  font-size: clamp(1.75rem, 4vw, 3.5rem);
}

Let the interface adapt continuously before adding a breakpoint.

Media queries answer environment questions

@media (width < 48rem) {
  .site-nav {
    display: none;
  }
}

Media queries respond to the viewport or other environment features:

• viewport width;
• colour scheme;
• pointer precision;
• reduced motion;
• contrast preferences;
• print.

They are not the only responsive tool.

Container queries answer component-space questions

.catalogue-shell {
  container: catalogue / inline-size;
}

@container catalogue (width < 36rem) {
  .catalogue-toolbar {
    flex-direction: column;
  }
}

The component responds to the space it actually receives, whether that space comes from the page, a sidebar, or a nested layout.

Media queries and container queries differ

Container queries do not replace media queries. They solve a different scope of responsive reasoning.

Name containers when the relationship matters

.results-panel {
  container: results / inline-size;
}

@container results (width > 42rem) {
  .result-card { grid-template-columns: 1fr auto; }
}

Names make the component’s dependency explicit and avoid accidental reliance on an unrelated ancestor container.

Container query units

.card-title {
  font-size: clamp(1rem, 3cqi, 1.6rem);
}

Container-relative units include:

• cqw and cqh;
• cqi and cqb for logical axes;
• cqmin and cqmax.

Use them when the component’s typography or spacing should track its container.

Responsive typography needs limits

h1 {
  font-size: clamp(2rem, 5vw, 4.5rem);
  line-height: 1.05;
}

clamp(min, preferred, max) prevents a fluid value from becoming unusably small or excessively large.

Readable text is a layout constraint, not a decorative afterthought.

Modern viewport units

Some mobile viewport units distinguish the small, dynamic, and large viewport:

.app-shell {
  min-block-size: 100dvb;
}

Choose viewport units according to whether browser UI changes should affect the layout. Do not assume every mobile viewport is a stable 100vh rectangle.

Responsive images belong to layout

<img
  src="catalogue-small.webp"
  srcset="catalogue-small.webp 640w,
          catalogue-large.webp 1280w"
  sizes="(width < 48rem) 100vw, 50vw"
  alt="A service catalogue dashboard">

Image dimensions, aspect ratios, loading behaviour, and object fitting affect layout stability and performance together.

CSS has logical axes

Prefer logical properties when the interface can change direction:

.card {
  margin-inline: auto;
  padding-block: 1rem;
  padding-inline: 1.25rem;
  border-inline-start: 0.25rem solid var(--color-accent);
}

This expresses the relationship instead of hard-coding physical left and right values.

Inline and block are relationships

flowchart TD
    subgraph Inline["Inline Axis"]
        I[Direction text progresses: horizontal LTR/RTL or vertical]
    end
    subgraph Block["Block Axis"]
        B[Direction blocks stack: perpendicular to inline axis]
    end

In horizontal English text these often resemble horizontal and vertical. In RTL or vertical writing modes, the physical interpretation changes.

Logical CSS keeps the component contract stable.

Direction-independent components

.toolbar {
  display: flex;
  gap: 1rem;
  margin-inline-start: auto;
}

.status {
  border-inline-start: 0.3rem solid var(--status-color);
  padding-inline-start: 0.75rem;
}

Test the component with different dir values rather than copying the whole stylesheet and swapping every physical property.

Some things should not mirror

Direction-aware layout does not mean every visual symbol flips.

Consider separately:

• text and reading order;
• navigation arrows;
• media-play controls;
• brand marks;
• charts and geographic maps;
• numbers and code.

The correct decision follows meaning, not a blanket mirror operation.

Modern selectors express relationships

CSS can now describe relationships more directly:

/* Group alternatives without repeating a block */
:is(.primary, .secondary) { border-radius: 0.5rem; }

/* Match without adding specificity */
:where(.card h2) { margin-block-end: 0.5rem; }

Use these features to make intent clearer, not to hide an unmaintainable selector strategy.

:has() selects based on a relationship

.field:has(input:invalid) {
  border-color: var(--color-error);
}

The parent can respond to the state of a descendant without JavaScript merely to add a class.

Still check whether the selector expresses a stable relationship and whether a class would make the ownership clearer.

CSS nesting needs readable boundaries

.card {
  padding: 1rem;

  & > h2 {
    margin-block: 0;
  }

  &:hover {
    box-shadow: 0 0.5rem 1rem rgb(0 0 0 / 12%);
  }
}

Nesting can keep a component’s local rules together. Deep nesting still creates coupling and should not replace a clear component contract.

User preferences are part of responsiveness

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Other preferences can affect colour, contrast, and interaction assumptions. Responsive design includes the user’s environment, not only its dimensions.

Motion should communicate something

Use motion to communicate:

• a change of state;
• a relationship between locations;
• progress or feedback;
• continuity during an interaction.

Avoid motion that delays reading, causes discomfort, or exists only because a component has an animation library available.

Styling architecture is a dependency system

Every approach answers questions about:

• where styles live;
• how names are scoped;
• how styles are composed;
• how themes are represented;
• how overrides work;
• how unused styles are removed;
• how runtime and build-time costs are distributed.

The right choice depends on the project’s constraints and ownership boundaries.

Plain CSS

Strengths:

• native browser model;
• no framework requirement;
• easy to inspect in DevTools;
• supports layers, custom properties, and modern selectors.

Risks:

• unclear naming can create collisions;
• global ownership can become ambiguous;
• unused styles need a deliberate strategy.

Architecture is still required even when no tool generates the CSS.

Component-oriented CSS and CSS Modules

Component-oriented CSS groups styles around an interface boundary.

CSS Modules add build-time scoping:

flowchart LR
    A[Card.module.css] --> B[Build Step] --> C[Generated Local Scoped Class Names]

They reduce accidental collisions, but they do not decide:

• token ownership;
• layout responsibility;
• accessibility;
• responsive strategy;
• whether a component boundary is well designed.

Utility-first CSS

Utility classes make small decisions explicit in markup:

<div class="grid gap-4 md:grid-cols-3"></div>

Benefits can include consistency and fast composition. Costs can include noisy markup, difficult component-level meaning, or a false belief that utilities remove architecture.

Utilities are a vocabulary, not a complete design system.

CSS-in-JS is not one technology

CSS-in-JS can mean different things:

• runtime style generation;
• build-time extraction;
• component-local syntax;
• theme-aware value functions;
• atomic style generation.

Compare the actual tool’s runtime cost, debugging model, SSR behaviour, accessibility support, and ownership boundaries - not the category label.

Compare problems, not fashion

Ask:

• How many teams own the styles?
• Do styles need to work without a framework runtime?
• How important is runtime theming?
• What is the build and delivery environment?
• How will developers debug the final CSS?
• How will shared components evolve?

Choose the smallest architecture that meets the real constraints.

The running catalogue interface

We will build a responsive multilingual catalogue with:

• semantic page structure;
• a toolbar;
• summary cards;
• a product grid;
• theme tokens;
• container-aware cards;
• RTL-safe spacing;
• reduced-motion support.

The interface is a test of relationships, not a gallery of CSS tricks.

Establish the cascade and tokens

@layer reset, tokens, base, components, utilities;

@layer tokens {
  :root {
    --surface-page: #f5f7fa;
    --surface-card: #ffffff;
    --text-primary: #172a42;
    --color-accent: #1d588c;
    --space-3: 0.75rem;
  }
}

Start by deciding who owns values and who owns component rules.

Build the page layout

.page {
  display: grid;
  grid-template-columns: minmax(0, 1fr);
  gap: var(--space-6);
  inline-size: min(100% - 2rem, 80rem);
  margin-inline: auto;
}

@media (width > 60rem) {
  .page { grid-template-columns: 16rem minmax(0, 1fr); }
}

The page breakpoint responds to the viewport. The components inside it should still respond to the space each one receives.

Build the toolbar with Flexbox

.toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 0.75rem;
}

.toolbar__search {
  flex: 1 1 18rem;
  min-inline-size: min(100%, 12rem);
}

Wrapping is part of the design. It is better than forcing every control into a single row that cannot contain translated labels.

Build the product grid with Grid

.product-grid {
  display: grid;
  grid-template-columns: repeat(
    auto-fit,
    minmax(min(100%, 16rem), 1fr)
  );
  gap: 1rem;
}

The grid expresses a useful minimum and lets the available container determine how many columns fit.

Adapt cards to their container

.product-grid { container: products / inline-size; }

.product-card {
  display: grid;
  gap: 0.75rem;
}

@container products (width > 42rem) {
  .product-card {
    grid-template-columns: 1fr auto;
  }
}

The card does not need to know whether the product grid is on the full page or inside a sidebar.

Use subgrid only for a shared alignment

.product-card {
  grid-template-rows: subgrid;
  grid-row: span 3;
}

If product names, descriptions, and actions should line up across a row, subgrid can share the parent tracks.

If cards do not need shared rows, keep their internal layout independent.

Make the catalogue RTL-safe

.catalogue {
  padding-inline: 1rem;
  margin-inline: auto;
}

.status {
  border-inline-start: 0.25rem solid var(--status-color);
  padding-inline-start: 0.75rem;
}

Test English, Arabic, and Sorani Kurdish content with long labels. Do not assume that replacing left with right is localization.

Respect reduced motion

@media (prefers-reduced-motion: reduce) {
  .catalogue * {
    transition: none;
    animation: none;
  }
}

The user preference is a real requirement. It belongs in the component’s architecture and verification, not only in a final accessibility audit.

CSS architecture has dependencies

flowchart TD
    Tokens[Tokens] --> Components[Components] --> Composition[Layout Composition]
    Tokens -.-> Themes[Themes]
    Components -.-> Responsive[Responsive Contexts]
    Composition -.-> Pages[Pages]

When a component reaches into page-specific selectors, or a page owns a component’s internal spacing, the dependency direction becomes unclear.

Good CSS makes change flow through deliberate boundaries.

Misconceptions to leave behind (Part 1)

Misconceptions to leave behind (Part 2)

The practical lab

Build a responsive multilingual catalogue.

The runnable implementation belongs in the separate Playground repository. The practical instructions define the evidence that the layout works.

Practical stages 1–3

1. Establish semantic HTML and a small token layer.
2. Add reset, base, components, and utilities cascade layers.
3. Convert raw values into semantic tokens and add light/dark theme values.

At each stage, inspect which layer and token supplied the final style.

Practical stages 4–6

4. Build the page layout with normal flow and Grid.
5. Build the toolbar with wrapping Flexbox.
6. Build the product grid with minmax() and intrinsic sizing.

Test narrow widths and long translated labels before adding more breakpoints.

Practical stages 7–9

7. Demonstrate subgrid where card rows must align.
8. Add container queries for cards and the toolbar.
9. Make spacing, borders, and alignment direction-independent.

Use DevTools to test the same component in more than one container.

Practical stages 10–12

10. Respect reduced motion.
11. Use :where(), :is(), :has(), or nesting where they make relationships clearer.
12. Draw the CSS architecture and document ownership boundaries.

The final deliverable is an explainable system, not merely a screenshot.

Try it yourself

Take one product card and test it in four environments:

• wide page content;
• narrow sidebar content;
• English text;
• Arabic or Sorani Kurdish text.

Record one layout decision that remains valid in all four environments and one decision that must adapt.

Troubleshooting questions (Part 1)

Troubleshooting questions (Part 2)

Completion check

• I can explain why a declaration wins.
• I can use cascade layers to represent ownership.
• I can distinguish raw tokens from semantic tokens.
• I can choose Flexbox, Grid, or normal flow for a reason.
• I can use intrinsic sizing and minmax() without a device list.
• I can explain when subgrid is useful.
• I can distinguish media queries from container queries.
• I can use logical properties for direction-independent layout.
• I can respect reduced motion and long translated content.
• I can compare styling architectures by project constraints.
• I completed the responsive multilingual catalogue practical.

Next: Modern JavaScript & Asynchronous Programming

Chapter 4: lexical scope, closures, asynchronous work, promises, cancellation, and the event loop as an application runtime.

Modern Front-End Engineering

4 - Modern JavaScript & Asynchronous Programming

Modern JavaScript & Asynchronous Programming

Control state, boundaries, timing, cancellation, and data flow

Chapter 4

Polla Fattah

Today’s goal

Move beyond syntax toward the language model needed for modern front-end work.

We will connect:

• scope and closures;
• objects and composition;
• data transformation and immutability;
• modules and dynamic loading;
• promises and asynchronous execution;
• concurrency, races, and cancellation;
• locale-aware output.

By the end of today you can

• explain where a JavaScript binding lives;
• use closures deliberately without confusing them with copied values;
• describe prototype delegation and why classes do not remove it;
• choose data transformation methods for clarity;
• update nested state without accidental mutation;
• design module boundaries and dynamic imports;
• distinguish sequential work from concurrent work;
• handle rejected promises and cancellation explicitly;
• prevent stale results from winning a race;
• format numbers, dates, and plurals for a locale.

The chapter’s progression

flowchart TD
    A[Scope & Closures] --> B[Objects & Composition]
    B --> C[Data Operations & Immutability]
    C --> D[Modules & Iteration]
    D --> E[Promises & async/await]
    E --> F[Concurrency & Cancellation]
    F --> G[Locale-Aware Output]

The core idea is:

Modern JavaScript controls state, boundaries, timing, and data flow.

Lexical scope: where a name can be used

const applicationName = "Citizen Portal";

function showName() {
  console.log(applicationName);
}

showName();

The function can look outward to the scope that surrounds it.

An outer scope cannot look inward into a function’s private bindings.

Scope follows the source-code structure. It is lexical, not based on which function happened to call another function at runtime.

Block scope is a lifetime boundary

if (loggedIn) {
  const message = "Welcome back";
  console.log(message);
}

console.log(message); // ReferenceError

Practical rule:

• prefer const by default;
• use let when reassignment is required;
• understand that both respect block scope;
• treat a block as a useful lifetime boundary.

Closures retain bindings

function createCounter() {
  let count = 0;

  return function increment() {
    count += 1;
    return count;
  };
}

const counter = createCounter();
counter(); // 1
counter(); // 2

createCounter() finished, but increment retains access to its lexical environment.

The closure does not copy count. It retains access to the binding.

Closures appear everywhere in front-end code

function attachFilter(input, applyFilter) {
  input.addEventListener("input", () => {
    applyFilter(input.value);
  });
}

The callback remembers input and applyFilter from the surrounding scope.

Common uses include:

• event handlers;
• callback configuration;
• private state factories;
• debounced functions;
• memoized computations;
• request controllers.

Closures can keep data alive

function createLogger(records) {
  return (message) => {
    records.push({ message, at: Date.now() });
  };
}

As long as the returned logger is reachable, records remains reachable too.

Closures provide privacy and state, but they can also retain large objects, DOM nodes, or subscriptions longer than intended.

Release listeners, timers, and references when the feature is destroyed.

Objects have a prototype model

An object can delegate property lookup to another object through its prototype.

const service = {
  describe() {
    return "public service";
  }
};

const request = Object.create(service);
request.id = 1042;
request.describe(); // delegated lookup

The object does not need to own every method directly.

Prototype delegation is not copying

Property lookup conceptually follows:

flowchart TD
    A[Request object itself] -->|if absent| B[Service prototype]
    B -->|if absent| C[Object.prototype]
    C -->|if absent| D[undefined]

This affects identity, mutation, method lookup, and debugging. Understand the delegation even when your code uses class syntax.

Classes are syntax over prototypes

class RequestRecord {
  constructor(id) {
    this.id = id;
  }

  describe() {
    return `Request ${this.id}`;
  }
}

The method is associated with the class prototype. Class syntax improves readability for some designs; it does not replace JavaScript’s prototype model.

Composition is often simpler than inheritance

Instead of a deep hierarchy:

flowchart LR
    A[BaseRecord] --> B[ServiceRecord] --> C[UrgentServiceRecord] --> D[LocalisedUrgentRecord]

compose focused capabilities:

const record = {
  ...withIdentity(1042),
  ...withStatus("in-review"),
  ...withLocale("ar")
};

Composition can reduce coupling and make a capability easier to reuse or replace.

Destructuring names the data you need

const request = {
  id: 1042,
  status: "in-review",
  applicant: { name: "Sara" }
};

const {
  id,
  status,
  applicant: { name }
} = request;

Destructuring can make data flow obvious, but avoid extracting so much that the source of a value becomes difficult to follow.

Rest and spread have different jobs

const { id, ...details } = request;
const updated = { ...request, status: "approved" };

• rest collects the remaining values;
• spread expands values into a new object or array.

Both are shallow operations.

Spread is not a deep copy

const original = { preferences: { theme: "dark" } };
const copy = { ...original };

copy.preferences.theme = "light";
console.log(original.preferences.theme); // light

The outer object is new. The nested object is still shared.

Know which references remain shared before calling something an immutable update.

Optional chaining is a guarded lookup

const phone = applicant?.contacts?.primaryPhone;

It is useful when a value is legitimately absent.

It does not:

• validate the data shape;
• supply a meaningful fallback;
• prove that a missing value is acceptable;
• repair a broken API contract.

Use it where absence is part of the model, not everywhere as a blanket guard.

Nullish coalescing preserves meaningful zeroes

const pageSize = settings.pageSize ?? 20;

?? falls back only for null or undefined.

That differs from ||:

0 || 20   // 20
0 ?? 20   // 0

Choose the operator according to the domain meaning of empty strings, zero, false, null, and undefined.

Transform collections by intent

const labels = requests.map(request => request.statusLabel);
const open = requests.filter(request => request.status === "open");
const selected = requests.find(request => request.id === id);
const hasUrgent = requests.some(request => request.priority === "urgent");
const allValid = fields.every(field => field.valid);

Each method communicates a different question. Prefer the method whose name matches the operation.

Use reduce() when it clarifies

const totals = requests.reduce((summary, request) => {
  summary[request.status] = (summary[request.status] ?? 0) + 1;
  return summary;
}, {});

reduce() can express aggregation, but it can also hide a complicated algorithm inside one callback.

Use a loop or named helper when the steps matter more than compactness.

Immutable update patterns

const nextState = {
  ...state,
  filters: {
    ...state.filters,
    status: "open"
  }
};

The update creates new references along the changed path and preserves unrelated references.

This helps state systems compare identity and makes change boundaries visible.

Identity and change detection

const same = state.filters === nextState.filters; // false
const sameList = state.requests === nextState.requests; // true

Identity can communicate which part of a state tree changed.

That does not mean every object must be recreated on every update. Preserve references when the value did not change.

Do not turn immutability into dogma

Mutation can be reasonable when:

• the object is local to one operation;
• no other consumer observes it;
• the mutation improves clarity or performance;
• ownership is explicit.

The architectural question is not “mutation or no mutation?”

It is:

Who can observe this value, and what change signal do they rely on?

ES Modules create boundaries

// format-status.js
export function formatStatus(status) {
  return status.replaceAll("-", " ");
}

// screen.js
import { formatStatus } from "./format-status.js";

Modules provide:

• explicit dependencies;
• module scope;
• reusable exports;
• a graph the build tool can inspect.

Modules are architecture, not only file organization.

Named and default exports

Named exports make the public vocabulary explicit:

export function parseRequest() {}
export function validateRequest() {}

Default exports can represent one primary value:

export default class RequestClient {}

Choose a consistent convention. Avoid making consumers guess whether a module has one canonical thing or a set of named capabilities.

Module scope is private by default

const cache = new Map();

export function getCached(key) {
  return cache.get(key);
}

cache is not a global just because the module can access it. Consumers see only what the module exports.

This is a useful boundary for implementation details and state ownership.

The module graph is a dependency graph

flowchart TD
    Screen[screen.js] --> ReqClient[request-client.js]
    Screen --> FormatStatus[format-status.js]
    ReqClient --> HTTP[http.js]

The graph affects:

• evaluation order;
• bundling;
• caching;
• code splitting;
• circular-dependency risk;
• ownership and testing boundaries.

Design imports as deliberately as public API calls.

Dynamic imports load on demand

button.addEventListener("click", async () => {
  const { openReport } = await import("./report.js");
  openReport();
});

Dynamic imports can reduce initial work and defer rarely used features.

They add asynchronous failure, loading state, and chunk-boundary concerns. A dynamic import is not free merely because it is written in one line.

Iteration is more than for loops

An iterable provides a protocol for producing values over time.

for (const request of requests) {
  renderRequest(request);
}

Arrays, strings, Maps, Sets, DOM collections, and custom objects can participate in iteration.

The protocol separates “how values are produced” from “how they are consumed.”

Iterators produce one value at a time

const iterator = ["queued", "open"].values();
iterator.next(); // { value: "queued", done: false }
iterator.next(); // { value: "open", done: false }
iterator.next(); // { value: undefined, done: true }

The done flag is part of the contract. Iterators can represent sequences that are calculated lazily rather than stored as a complete array.

Generators pause and resume

function* statuses() {
  yield "queued";
  yield "in-review";
  yield "approved";
}

Generators provide a convenient way to define an iterator. They can model progressive work, but they do not automatically make expensive work asynchronous or cancellable.

Async iteration represents arriving values

for await (const event of stream) {
  renderEvent(event);
}

Async iteration is useful when values arrive over time. The consumer still needs to understand completion, errors, backpressure, and cancellation.

From callbacks to promises

Callbacks can express completion and failure, but nested workflows become hard to compose:

loadUser(id, user => {
  loadRequests(user, requests => {
    render(requests);
  }, handleError);
}, handleError);

Promises represent a future result and provide composable success and failure paths.

A promise represents a future result

const request = fetch("/api/requests/1042");

request.then(response => response.json())
  .then(data => render(data))
  .catch(error => showError(error));

A promise is not the result itself. It represents a pending, fulfilled, or rejected computation.

Creating promises is an ownership decision

function wait(ms) {
  return new Promise(resolve => {
    setTimeout(resolve, ms);
  });
}

Create a promise when adapting a callback or exposing an asynchronous contract.

Do not wrap an API in a new promise without a reason; unnecessary wrappers can hide errors and complicate cancellation.

Promise chaining carries values forward

fetch("/api/requests")
  .then(response => response.json())
  .then(requests => requests.filter(isVisible))
  .then(renderRequests);

Each handler returns the value or promise for the next step.

Returning nothing intentionally passes undefined; forgetting to return is a common source of a broken chain.

Promise errors propagate through the chain

loadRequests()
  .then(validateResponse)
  .then(renderRequests)
  .catch(error => showError(error));

An exception or rejection skips forward to the next compatible rejection handler. Place recovery at the boundary that can actually decide what to do.

async and await improve expression

async function loadScreen() {
  const response = await fetch("/api/requests");
  const requests = await response.json();
  renderRequests(requests);
}

await makes a promise result available inside the function. It does not turn the browser into a blocking environment.

Async functions always return promises

async function answer() {
  return 42;
}

answer().then(console.log); // 42

Even a plain return value is wrapped in a fulfilled promise. Callers must still decide how to handle rejection.

Handle errors at the right boundary

async function loadScreen() {
  try {
    const response = await fetch("/api/requests");
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (error) {
    showRecoverableError(error);
    throw error;
  }
}

Do not catch an error merely to log it and then pretend the operation succeeded.

Not every failure is a network error

An async operation can fail because:

• the request was blocked or offline;
• the server returned a non-2xx response;
• the body was invalid JSON;
• validation rejected the data;
• rendering code threw;
• the user cancelled the work;
• a stale result was deliberately ignored.

Your error model should preserve the difference when the UI needs it.

Sequential work is sometimes correct

const user = await loadUser();
const permissions = await loadPermissions(user.id);

The second operation depends on the first. Sequential execution expresses that dependency.

The cost is that total time includes both waits.

Accidental sequential work is a performance bug

const categories = await loadCategories();
const featured = await loadFeatured();

If the requests are independent, this waits unnecessarily.

Start independent work together, then await the combined result.

Promise.all() expresses all-or-nothing coordination

const [categories, featured] = await Promise.all([
  loadCategories(),
  loadFeatured()
]);

The operations start without waiting for one another. The combined promise fulfils when all fulfil and rejects when one rejects.

Use it when one failure should prevent the combined result from being used.

Promise.allSettled() preserves every outcome

const results = await Promise.allSettled([
  loadRecommendations(),
  loadAnnouncements(),
  loadOptionalMetrics()
]);

Use it when partial success is meaningful and each result needs its own status.

The choice communicates product behaviour, not only JavaScript preference.

Concurrency is not parallelism

Several asynchronous operations can be in flight at once while JavaScript continues on its event loop.

That does not mean JavaScript is running those callbacks on several CPU cores.

Concurrency is about overlapping waiting and coordinating completion.

Parallelism is about simultaneous execution.

Race conditions can happen in one thread

sequenceDiagram
    participant UI as User Interface
    participant Net as Network
    Note over UI: Types "ca" (Req A)
    UI->>Net: Request A ("ca")
    Note over UI: Types "car" (Req B)
    UI->>Net: Request B ("car")
    Net-->>UI: Response B arrives (150ms)
    Note over UI: UI shows "car" results
    Net-->>UI: Response A arrives late (800ms)
    Note over UI: Race! Stale "ca" overwrites "car"

If every response renders immediately, request A can overwrite the newer result for care.

Single-threaded JavaScript does not remove ordering races between asynchronous operations.

Race conditions are correctness problems

The question is not only:

Which request finished last?

It is:

Which result is still valid for the current user intent?

Freshness is an application rule. The network does not know which response the user currently cares about.

Strategy 1: ignore stale results

let latestQuery = "";

async function search(query) {
  latestQuery = query;
  const result = await fetchResults(query);
  if (query !== latestQuery) return;
  renderResults(result);
}

This is simple and safe when the old work is harmless. It still spends the resources needed to finish the old request.

Strategy 2: cancel outdated work

let controller;

async function search(query) {
  controller?.abort();
  controller = new AbortController();
  const response = await fetch(`/api/search?q=${query}`, {
    signal: controller.signal
  });
  return response.json();
}

Cancellation can save work and communicate that the previous intent is no longer relevant.

The UI must distinguish cancellation from an unexpected failure.

AbortController is a general signal

const controller = new AbortController();

fetch(url, { signal: controller.signal });
timer(signal, controller.signal);

controller.abort();

The signal is a shared cancellation contract. The operation decides how to listen and clean up when the signal aborts.

Cancellation is an application design problem

Ask:

• What work belongs to the cancelled intent?
• Who owns the controller?
• What resources need cleanup?
• Should cancellation be silent or visible?
• Can a new operation replace the old one safely?
• What happens if cancellation occurs after the result arrives?

Adding AbortController without defining ownership only moves the ambiguity.

Debouncing delays the start of work

function debounce(callback, delay) {
  let timer;
  return (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => callback(...args), delay);
  };
}

Debouncing waits for a pause in input before starting work.

It reduces the number of operations. It does not cancel a request that already started.

Debouncing and cancellation solve different problems

flowchart TD
    A["Debounce: delay unnecessary starts"] --> B["Cancellation: stop outdated work in flight"]
    B --> C["Freshness: reject obsolete results"]

Search interfaces often need all three.

Error propagation needs an owner

flowchart TD
    T["Transport layer: reports request failure"] --> D["Data layer: validates and normalizes data"]
    D --> F["Feature layer: decides recoverable UI state"]
    F --> S["Screen layer: presents feedback and retry"]

Do not let every layer catch and replace the same error with a vague message.

Each boundary should add context or make a decision.

finally is for cleanup

setLoading(true);

try {
  await loadResults();
} catch (error) {
  showError(error);
} finally {
  setLoading(false);
}

Use finally for work that should occur after success, failure, or cancellation: loading flags, controller references, locks, and temporary UI state.

Avoid unhandled promise rejections

Every promise chain needs an intentional owner:

void saveDraft().catch(error => {
  reportSaveFailure(error);
});

If a caller intentionally starts background work, make that intent visible and attach a failure path. A rejected promise should not disappear silently.

Internationalization is more than translation

Locale-aware interfaces consider:

• language and script;
• number formatting;
• currencies;
• dates and time zones;
• relative time;
• plural rules;
• segmentation;
• direction and layout.

Do not concatenate English assumptions into strings and call the result localized.

Format numbers with Intl.NumberFormat

const formatter = new Intl.NumberFormat("ar-IQ", {
  maximumFractionDigits: 2
});

formatter.format(12345.67);

The locale controls grouping, decimal conventions, digits, and other display rules. Formatting belongs near presentation, not in the domain value itself.

Currency is a meaning, not a symbol

new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD"
}).format(1234.5);

Do not hard-code a dollar sign or assume that the currency code determines the entire visual format.

Keep the numeric amount and currency identity separate until presentation.

Dates need a locale and a time-zone decision

new Intl.DateTimeFormat("en-GB", {
  dateStyle: "medium",
  timeZone: "Asia/Baghdad"
}).format(date);

Formatting is not the same as deciding what instant or calendar meaning the application intends. Store and transmit a clear temporal representation.

Relative time communicates change

const relative = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
relative.format(-1, "day"); // yesterday

The correct unit and rounding policy are application decisions. A relative label should not hide the exact timestamp when the exact time matters.

Plural rules are grammatical rules

const plural = new Intl.PluralRules("en");
plural.select(1); // one
plural.select(2); // other

Different languages have different plural categories. Avoid building messages with count === 1 ? "item" : "items" as a universal model.

Intl.Segmenter respects language boundaries

const segmenter = new Intl.Segmenter("ar", {
  granularity: "word"
});

for (const part of segmenter.segment(text)) {
  console.log(part.segment);
}

String length and substring boundaries are not always equivalent to visible words or user-perceived characters.

A cancelable search: step 1

Debounce the user’s input so each keystroke does not immediately start work:

const scheduleSearch = debounce((query) => {
  runSearch(query);
}, 250);

This controls the rate of starts. It does not yet control in-flight requests.

A cancelable search: step 2

Cancel the previous request when a newer query becomes authoritative:

let activeController;

async function runSearch(query) {
  activeController?.abort();
  activeController = new AbortController();

  const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`, {
    signal: activeController.signal
  });

  return response.json();
}

The feature owns the controller because it owns the current search intent.

A cancelable search: step 3

Handle cancellation separately from failure:

try {
  const results = await runSearch(query);
  renderResults(results);
} catch (error) {
  if (error.name === "AbortError") return;
  showSearchError(error);
}

Cancellation is expected control flow. It should not flash an error message for the user.

A cancelable search: the complete contract

flowchart TD
    A[Input event] --> B[Debounce delay]
    B --> C[Create current AbortController]
    C --> D[Cancel previous active request]
    D --> E[Fetch network data with signal]
    E --> F[Validate response & token freshness]
    F --> G[Format locale-aware values]
    G --> H[Render current results only]
    H --> I[Cleanup controller in finally]

Each arrow is a boundary where an error, race, or ownership decision can occur.

The practical lab

Build a cancelable locale-aware search.

The runnable Vite and TypeScript implementation will live in the separate Playground repository. This deck describes the JavaScript behaviour and the evidence to collect.

Practical stages 1–3

1. Use closure state for a small search controller or cache.
2. Apply immutable updates to the search state.
3. Split the feature into modules with clear imports and exports.

Write down which module owns the current query, results, and cancellation controller.

Practical stages 4–6

4. Dynamically import an optional result formatter or panel.
5. Compare sequential and concurrent independent requests.
6. Create a deliberate race condition by delaying responses differently.

Observe how a correct build can still show incorrect stale data.

Practical stages 7–9

7. Prevent stale results from replacing newer results.
8. Add AbortController cancellation.
9. Add input debouncing.

Test rapid typing, clearing the input, slow responses, cancellation, and network failure separately.

Practical stages 10–11

10. Add locale-aware numbers, dates, plurals, and direction.
11. Draw the asynchronous flow and label every ownership boundary.

The final diagram should show what starts work, what can cancel it, what can reject, and what is allowed to update the UI.

Try it yourself

Choose one asynchronous feature in an application you know.

Answer:

• Can two operations be in flight together?
• What makes an old result stale?
• Who owns cancellation?
• Which failures are expected user flow?
• Where should locale formatting happen?

Write one explicit contract before changing the code.

Troubleshooting questions (Part 1)

Troubleshooting questions (Part 2)