JavaScript

JavaScript should improve the experience, not be the only reason the experience works. Too much code, too many dependencies, and too much custom behaviour that reimplements what the browser already handles creates bugs, accessibility gaps, and systems nobody wants to maintain.

These standards describe practical JavaScript for teams shipping real products: progressive enhancement, readable code, sensible modules, and less weight — not clever one-liners or framework theatre.

See code formatting and style for semicolons, quotes, and example layout.

Forms should submit before JavaScript adds validation polish. Navigation should work before transitions exist. Content should make sense before styling arrives. If everything breaks when a script fails to load, the architecture is wrong.

Start with HTML and CSS. Use JavaScript to make the experience better — not to justify basic functionality.

Write for the next developer, not for conference slides. If someone cannot understand the code quickly, rewrite it — use names, steps, and structure that explain intent.

After a group of const or let declarations, leave a blank line before the next statement — see JavaScript formatting.

Hard to maintain

const total = items
    .map((item) => item.price ? item.price.tax?.rate?.value : null)
    .filter(Boolean)
    .reduce((sum, value) => sum + value, 0);

Easier to follow

let total = 0;

for (const item of items) {
    const rate = item.price?.tax?.rate?.value;

    if (rate != null) {
        total += rate;
    }
}

export { total };

Prefer

Avoid

<button type="button" onclick="doThing()">
    Save
</button>

Inline handlers belong in a museum, next to table-based layouts. Keep behaviour in modules where it can be tested, reviewed, and removed.

Defensive checks are fine

Mobile nav and similar UI belong in a module or class that owns the click handlers, ARIA, and keyboard behaviour. The entry point only gathers elements and uses early return when a query returnsnull or the feature is already initialised. Queries miss during refactors and partial renders; init often runs again after client-side navigation, view transitions, or hot reload. Colocate the script with the template or component that outputs the markup when you can — guards still stop duplicate listeners and keep failures quiet while HTML is in flux.

function initMobileNav() {
    const header = document.querySelector('.site-header');
    const menuButton = document.getElementById('nav-menu-button');
    const nav = document.getElementById('primary-nav');

    if (!header || !menuButton || !nav) return;

    // Module or class wires toggle, aria-expanded, escape, focus, etc.
}

initMobileNav();

Use an id on one-off controls like the menu button (id="nav-menu-button"), then getElementById — not a long descendant selector. One toggle per page makes a unique id a good fit. Keep ids out of CSS; in JavaScript they are a quick, explicit lookup when you already know what you need.

Install dependencies because they solve a real problem, not because they are popular. Frameworks should address complexity you actually have — vanilla JavaScript (with TypeScript when it helps) is often enough. Reach for more only when the problem demands it.

Every npm package and every third-party script tag is another surface area: supply-chain risk, compromised CDNs, and code you did not write running in your users’ browsers. Treat new dependencies like hiring — justify them, review what they load, and plan how you would remove them.

You also hand off control of how that behaviour shows up on your site. You do not own its performance budget, its accessibility behaviour, or its release cadence. A widget can regress Core Web Vitals, break keyboard focus, or ship a breaking change on a Friday while your team owns the support inbox. Native or first-party code is slower to build but stays on your standards and your test plan.

Before adding a package or embed, ask whether you could ship a smaller first-party solution, load it only where needed, and document who is responsible when it fails.

Pay attention whenever JavaScript touches:

A keyboard trap is not a clever interaction — it is broken. Accessibility does not stop at HTML.