Every one of these was a rational response to a real problem. The cascade was dangerous at scale. Naming was fragile. Global stylesheets did break silently when teams grew. But every solution also threw away something valuable – separation of concerns, central design authority, semantic markup, small footprints, or all four at once.

It is 2026. CSS has quietly become a different language. Not through a single headline feature, but through the accumulation of capabilities that, taken together, change what is structurally possible:

• @layer gives you explicit control over cascade priority, making specificity wars a solved problem.
• @scope contains styles to a DOM subtree without any naming convention, build tool, or runtime.
• @property lets you register typed, inheritable custom properties with defaults – turning the cascade into a contextual type system.
• :has() lets CSS inspect the contents and relationships of elements, eliminating most presentational classes.
• Native nesting removes the last major reason anyone reached for a preprocessor.
• Container queries let components respond to their own size rather than the viewport.
• @starting-style and the allow-discrete transition behaviour let you animate elements appearing and disappearing – no JS, no libraries.
• Styleable form elements (<select>, <input>, <details>) are finally arriving, killing one of the oldest reasons to reach for a component library.

None of these existed in practical cross-browser form five years ago. Most shipped in the last two or three. Collectively, they make a new paradigm possible – one that reclaims everything we gave up without reintroducing the problems that drove us away.

This document describes that paradigm. It is opinionated. It is practical. And it is not a framework – it is a set of architectural principles that produce clean markup, collision-proof styles, central design authority, and a CSS footprint measured in kilobytes.

The five principles

1. The markup is the source of truth. HTML should be semantic and nearly class-free. If you are adding a class purely to give CSS something to grab onto, that is a smell. Modern CSS can select on structure, content, attributes, and relationships. Let it.

2. The cascade is an asset, not a liability. Layers make cascade priority explicit. Scopes make it bounded. Typed properties make it a contextual inheritance system. Stop fighting the cascade and start programming it.

3. Design decisions are centralised. Every colour, spacing value, radius, and typographic choice flows from a single set of design tokens. Components consume tokens; they never hardcode values. A change at the token level propagates everywhere, including through utilities.

4. Collisions are structurally impossible. Not prevented by discipline. Not prevented by naming. Prevented by the platform: @layer ordering resolves before specificity, and @scope boundaries prevent selectors from leaking. This is enforcement, not convention.

5. Utility classes are for composition gaps, not for components. A thin layer of token-derived utilities – spacing, colour, visibility – handles the seams between composed blocks. If you are stacking more than two utilities on one element, extract a semantic rule. The utility layer is an escape valve, not an architecture.

Part I: The layer stack

Everything begins with an explicit layer order declared once, at the top of your root stylesheet:

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

This single line eliminates the entire category of “my styles are being overridden and I don’t know why.” Layers resolve in declared order regardless of specificity. A selector in components will never beat a selector in utilities, and a selector in utilities will never beat a selector in overrides – even if the component selector is #app .sidebar nav > ul > li > a:first-child and the override selector is .mt-l.

No !important. No specificity hacks. No re-ordering your <link> tags and praying.

Each layer has a clear purpose:

reset – Normalise browser defaults. This is your Meyer reset, your box-sizing: border-box, your margin zeroing. Written once, touched never.

tokens – Design primitives. Colours, spacing scale, type scale, radii, shadows, motion timing. These are registered custom properties living on :root (or contextual overrides on [data-theme], [data-density], etc.). This is the single source of design truth.

layout – Page-level structure. Your grid shells, your sticky headers, your sidebar-plus-content frames. These concern where things go, not what things look like.

components – The visual identity of discrete UI elements. Cards, buttons, form fields, nav bars, dialogs. Each scoped to its own DOM subtree.

utilities – A deliberately thin set of single-purpose helpers for composition gaps. Margins between siblings, text alignment in a one-off context, visually-hidden content. Never more than 40–60 rules total.

overrides – The “break glass in emergency” layer. Page-specific tweaks, third-party widget fixes, temporary hacks with a /* TODO: remove after redesign */ comment. By living in the highest layer, these always win without needing !important, and they are easy to find and audit.

What this solves

• Specificity wars: Gone. Layer order is the first (and usually only) resolution mechanism.
• Ordering fragility: Gone. It does not matter which <link> tag comes first as long as everything is assigned to its layer.
• !important escalation: Gone. The override layer exists precisely for this purpose, with no need for specificity nuclear options.
• “Where does this rule go?”: Answered by the layer name. A new developer can look at the layer declaration and understand the architecture in ten seconds.

Part II: Scoped components

Within the components layer, every component is wrapped in a @scope block:

@layer components {
  @scope (.card) {
    :scope {
      background: var(--surface);
      color: var(--on-surface);
      border-radius: var(--radius-m);
      padding: var(--space-m);
      container-type: inline-size;
    }

    .title {
      font-size: var(--text-lg);
      font-weight: 600;
      line-height: 1.25;
    }

    .body {
      line-height: 1.6;
    }

    .actions {
      display: flex;
      gap: var(--space-s);
      justify-content: flex-end;
    }
  }

  @scope (.badge) {
    :scope {
      font-size: var(--text-xs);
      padding: var(--space-xs) var(--space-s);
      border-radius: var(--radius-full);
      background: var(--color-accent);
      color: var(--on-accent);
    }
  }
}

Notice: .title inside .card and .title inside any other component are completely separate selectors. @scope ensures that the rules inside @scope (.card) only match elements that are descendants of .card. There is no collision, no leaking, no need for .card__title or data-card-title or any other workaround.

You can use short, readable class names – .title, .body, .actions, .icon – across your entire codebase without fear. This is what BEM was trying to achieve, but enforced by the browser rather than by human discipline.

Scoping boundaries with to

@scope also supports a lower boundary, which limits how deep the scope reaches. This prevents a component from styling the internals of a nested child component:

@scope (.card) to (.card, .badge, .dialog) {
  /* These rules will NOT penetrate into nested .card,
     .badge, or .dialog subtrees */
}

This is the compositional boundary that CSS Modules and Shadow DOM tried to provide, but without the tooling overhead of the former or the harsh isolation of the latter. Scoped styles participate in the cascade normally – they inherit, they can be overridden by higher layers – they just can’t reach into components that don’t belong to them.

The case for @scope over class-prefix conventions

You might be tempted to achieve similar isolation with .card-title instead of @scope (.card) { .title {} }. The difference is structural:

• If someone writes .card-title inside a nested component, it will match. @scope will not.
• If someone accidentally omits the prefix, it silently becomes a global rule. @scope selectors are local by default.
• BEM requires every developer to remember and apply the convention. Scope is enforced by the parser.

Conventions are not architecture. @scope is architecture.

Part III: Typed design tokens

Design tokens in most systems are untyped custom properties: --color-primary: #3b82f6. This works, but it has limitations – you cannot transition them, there is no validation, and nothing stops someone from writing padding: var(--color-primary) and getting a silent failure.

@property fixes this:

@property --surface {
  syntax: "<color>";
  inherits: true;
  initial-value: #ffffff;
}

@property --on-surface {
  syntax: "<color>";
  inherits: true;
  initial-value: #1a1a1a;
}

@property --space-unit {
  syntax: "<length>";
  inherits: true;
  initial-value: 0.25rem;
}

@property --density {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@property --radius-m {
  syntax: "<length>";
  inherits: false;
  initial-value: 0.375rem;
}

Why this matters

Type safety. A <color> property will reject a length value. A <number> property will reject a string. The browser enforces your design system’s type contracts.

Animatability. Unregistered custom properties cannot be transitioned – the browser does not know their type and so cannot interpolate. Registered properties with syntax: "<color>" or syntax: "<length>" can be smoothly transitioned and animated. Theme switches can fade. Density changes can ease. No JavaScript.

Explicit inheritance control. Some tokens should inherit (colours, density, typography), and some should not (border-radius, shadow depth). @property lets you declare this explicitly, preventing surprising inheritance chains.

Initial values as documentation. The initial-value serves as both a fallback and a declaration of the design system’s default. If a component references var(--surface) and nobody has set it, it gets white. Not unset. Not an empty string. A typed, intentional default.

Contextual theming through inheritance

Because registered properties participate in the cascade’s inheritance, theming becomes DOM-structural rather than imperative:

@layer tokens {
  [data-theme="dark"] {
    --surface: #1a1a1a;
    --on-surface: #e5e5e5;
    --surface-raised: #2a2a2a;
  }

  [data-density="compact"] {
    --density: 0.65;
  }

  [data-density="spacious"] {
    --density: 1.4;
  }
}

Now wrap any subtree in <section data-theme="dark"> and every component inside it – buttons, cards, inputs, badges – adapts automatically. No theme prop drilling. No context providers. No runtime JS. The cascade does what it has always done: it passes values down the tree. You are just giving it better values to pass.

A component written once works in light mode, dark mode, compact density, spacious density, and any combination thereof – without knowing any of these contexts exist. This is the separation of concerns that inline styles (and Tailwind) fundamentally cannot achieve.

The token scale

Define your spacing scale as derivations from a base unit:

@layer tokens {
  :root {
    --space-unit: 0.25rem;
    --space-xs: calc(var(--space-unit) * 1);   /* 0.25rem */
    --space-s:  calc(var(--space-unit) * 2);   /* 0.5rem  */
    --space-m:  calc(var(--space-unit) * 4);   /* 1rem    */
    --space-l:  calc(var(--space-unit) * 6);   /* 1.5rem  */
    --space-xl: calc(var(--space-unit) * 8);   /* 2rem    */
    --space-2xl: calc(var(--space-unit) * 12); /* 3rem    */
  }
}

Every spacing value in the system derives from --space-unit. Multiplied by --density, you can scale the entire spatial system:

button {
  padding: calc(var(--space-s) * var(--density))
           calc(var(--space-m) * var(--density));
}

One number – --density – controls how tight or loose every component feels. One number – --space-unit – controls the underlying spatial grid. Central authority. Zero duplication. Maximum leverage.

Part IV: Content-relational styling

This is the most radical departure from how we have written CSS for the last twenty years. The premise: most classes exist to tell CSS something CSS can now figure out for itself.

:has() is a relational pseudo-class. It lets you select an element based on what it contains. Combined with structural pseudo-classes, attribute selectors, and native nesting, you can write CSS that responds to the shape of the DOM – not to manually applied labels.

The semantic article

<article>
  <img src="hero.jpg" alt="A coastal sunset">
  <h2>The Quiet Coast</h2>
  <p>Long-form body text here.</p>
  <footer>
    <time datetime="2026-03-15">March 15, 2026</time>
    <span>8 min read</span>
  </footer>
</article>

@layer components {
  @scope (article) {
    :scope {
      padding: var(--space-m);
      background: var(--surface);
    }

    /* Article with a hero image: grid layout */
    :scope:has(> img:first-child) {
      display: grid;
      grid-template-rows: 200px 1fr auto;

      > img {
        width: 100%;
        height: 100%;
        object-fit: cover;
        border-radius: var(--radius-m) var(--radius-m) 0 0;
      }
    }

    /* Article without an image: accent border */
    :scope:not(:has(> img)) {
      border-left: 3px solid var(--color-accent);
    }

    /* Article containing a blockquote: pull-quote style */
    :scope:has(blockquote) {
      font-style: italic;
      background: var(--surface-muted);
    }

    /* Article followed by another article: tighter margin */
    :scope:has(+ article) {
      margin-bottom: var(--space-s);
    }
  }
}

The HTML contains no presentational classes. No .article--with-hero. No .article--text-only. No .article--quote-variant. The CSS reads the DOM structure and adapts. Add an image, the layout changes. Remove it, the border appears. The markup stays clean, semantic, and concerned only with content.

Relational form styling

<form>
  <label>
    Email
    <input type="email" required>
  </label>
  <label>
    Message
    <textarea required></textarea>
  </label>
  <button type="submit">Send</button>
</form>

@layer components {
  @scope (form) {
    :scope:has(:invalid) button[type="submit"] {
      opacity: 0.5;
      cursor: not-allowed;
    }

    label:has(:focus-visible) {
      color: var(--color-accent);
    }

    label:has(:invalid:not(:placeholder-shown)) {
      color: var(--color-danger);
    }

    label:has(:valid) {
      color: var(--color-success);
    }
  }
}

No JavaScript. No form libraries. No state management. The submit button dims when any required field is invalid. Labels change colour based on validation state. All driven by the DOM state that the browser already tracks.

When to still use classes and attributes

Content-relational styling handles structural variations. But some distinctions are truly semantic – the difference between a primary and a destructive button, for instance, is not structural. For those, use data attributes:

<button data-variant="primary">Save</button>
<button data-variant="danger">Delete</button>

@scope (button) {
  :scope {
    padding: var(--space-s) var(--space-m);
    border-radius: var(--radius-m);
    font-weight: 500;
  }

  :scope[data-variant="primary"] {
    background: var(--color-primary);
    color: var(--on-primary);
  }

  :scope[data-variant="danger"] {
    background: var(--color-danger);
    color: var(--on-danger);
  }
}

Why data-variant rather than .btn-primary? Because data attributes carry semantic meaning – they describe what something is, not what it should look like. And because they are scoped by the @scope block, they cannot collide with data attributes on unrelated components. This is a deliberate choice: classes for scoping boundaries, data attributes for semantic variations, and :has() for structural variations. Each selection mechanism has a clear, non-overlapping purpose.

Part V: The utility layer

Utilities are not the architecture. They are the mortar between bricks.

The utility layer is thin – 40 to 60 rules at most – generated directly from your design tokens. It covers three domains: spacing, colour, and visibility.

@layer utilities {
  /* Spacing -- derived from token scale */
  .mt-xs  { margin-top: var(--space-xs); }
  .mt-s   { margin-top: var(--space-s); }
  .mt-m   { margin-top: var(--space-m); }
  .mt-l   { margin-top: var(--space-l); }
  .mt-xl  { margin-top: var(--space-xl); }
  .mb-xs  { margin-bottom: var(--space-xs); }
  .mb-s   { margin-bottom: var(--space-s); }
  .mb-m   { margin-bottom: var(--space-m); }
  .mb-l   { margin-bottom: var(--space-l); }
  .mb-xl  { margin-bottom: var(--space-xl); }
  .gap-s  { gap: var(--space-s); }
  .gap-m  { gap: var(--space-m); }
  .gap-l  { gap: var(--space-l); }

  /* Colour -- text overrides */
  .text-muted   { color: var(--color-muted); }
  .text-accent  { color: var(--color-accent); }
  .text-danger  { color: var(--color-danger); }
  .text-success { color: var(--color-success); }

  /* Typography */
  .text-center { text-align: center; }
  .text-sm     { font-size: var(--text-sm); }
  .text-lg     { font-size: var(--text-lg); }
  .font-bold   { font-weight: 700; }

  /* Display and visibility */
  .visually-hidden {
    clip: rect(0 0 0 0);
    clip-path: inset(50%);
    height: 1px;
    width: 1px;
    overflow: hidden;
    position: absolute;
    white-space: nowrap;
  }

  .flex       { display: flex; }
  .flex-col   { flex-direction: column; }
  .items-center { align-items: center; }
}

That is the entire utility layer. Fifty-odd rules. Compare this with Tailwind’s thousands.

The discipline

Utilities are for composition gaps – the space between components that no single component should own:

<section>
  <article>...</article>
  <article class="mt-l">...</article>  <!-- gap between siblings -->
</section>

<footer class="mt-xl text-center text-muted">
  <p>&copy; 2026 Acme Corp</p>
</footer>

If you find yourself writing class="flex items-center gap-s text-sm text-muted font-bold", you have built a component out of utilities. Stop. Extract it into a scoped component rule.

The two-utility rule: if an element needs more than two utilities, it likely deserves a semantic style. This is not a hard limit – it is a code smell threshold.

Because the utilities reference design tokens, a central change to --space-m propagates through both component styles and utilities. Central authority is preserved even in the escape hatch.

Part VI: Container queries and intrinsic layout

Media queries ask “how wide is the viewport?” Container queries ask “how wide is the component?” This distinction matters enormously in component-based design, where the same card might appear in a narrow sidebar and a wide main content area within the same viewport.

@layer components {
  @scope (.card) {
    :scope {
      container-type: inline-size;
      /* ... base styles ... */
    }

    @container (min-width: 400px) {
      :scope {
        display: grid;
        grid-template-columns: 200px 1fr;
      }
    }

    @container (min-width: 700px) {
      :scope {
        grid-template-columns: 300px 1fr auto;
      }

      .actions {
        flex-direction: column;
        align-self: start;
      }
    }
  }
}

The card adapts to its own available space, not the screen. This is intrinsic design – the component carries its own layout logic. No breakpoint props. No size-variant classes. No JavaScript resize observers.

Combined with @scope and :has(), you reach a level of component autonomy that previously required a JavaScript framework. The component knows its boundaries (scope), its content (:has()), and its available space (container queries). All in CSS. All without a build step.

Part VII: Motion and transitions

CSS can now handle most of the transitions that used to require JavaScript animation libraries.

Entry and exit animations with @starting-style

dialog[open] {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 200ms ease, transform 200ms ease,
              display 200ms allow-discrete;

  @starting-style {
    opacity: 0;
    transform: translateY(-1rem);
  }
}

dialog:not([open]) {
  opacity: 0;
  transform: translateY(-1rem);
  transition: opacity 150ms ease, transform 150ms ease,
              display 150ms allow-discrete;
}

Dialogs, popovers, dropdown menus, toast notifications – all can animate in and out with CSS alone, using the native HTML elements and attributes. No Framer Motion. No GSAP. No useTransition hook.

The allow-discrete value lets you transition display: none to display: block, which was impossible until recently. Elements can now truly appear and disappear with fluid motion, not just opacity tricks over invisible-but-still-present DOM nodes.

Token-driven motion

Centralise your timing in the token layer:

@layer tokens {
  :root {
    --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
    --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
    --duration-fast: 100ms;
    --duration-normal: 200ms;
    --duration-slow: 400ms;
  }

  @media (prefers-reduced-motion: reduce) {
    :root {
      --duration-fast: 0ms;
      --duration-normal: 0ms;
      --duration-slow: 0ms;
    }
  }
}

By zeroing all durations under prefers-reduced-motion, every transition in your entire system respects the user’s motion preference – automatically, centrally, without any per-component logic.

Putting it all together

Here is a minimal but complete example showing all principles working in concert.

tokens.css

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

@layer tokens {
  @property --surface {
    syntax: "<color>";
    inherits: true;
    initial-value: #ffffff;
  }

  @property --on-surface {
    syntax: "<color>";
    inherits: true;
    initial-value: #1a1a1a;
  }

  @property --color-accent {
    syntax: "<color>";
    inherits: true;
    initial-value: #3b82f6;
  }

  @property --density {
    syntax: "<number>";
    inherits: true;
    initial-value: 1;
  }

  :root {
    --space-unit: 0.25rem;
    --space-xs: calc(var(--space-unit) * 1);
    --space-s:  calc(var(--space-unit) * 2);
    --space-m:  calc(var(--space-unit) * 4);
    --space-l:  calc(var(--space-unit) * 6);
    --space-xl: calc(var(--space-unit) * 8);
    --radius-m: 0.375rem;
    --radius-full: 9999px;
    --text-sm: 0.875rem;
    --text-base: 1rem;
    --text-lg: 1.25rem;
    --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
    --duration-normal: 200ms;
  }

  [data-theme="dark"] {
    --surface: #1a1a1a;
    --on-surface: #e5e5e5;
  }

  [data-density="compact"] {
    --density: 0.65;
  }

  @media (prefers-reduced-motion: reduce) {
    :root {
      --duration-normal: 0ms;
    }
  }
}

components/card.css

@layer components {
  @scope (.card) to (.card) {
    :scope {
      background: var(--surface);
      color: var(--on-surface);
      border-radius: var(--radius-m);
      padding: calc(var(--space-m) * var(--density));
      container-type: inline-size;
      transition: box-shadow var(--duration-normal) var(--ease-out);
    }

    :scope:hover {
      box-shadow: 0 4px 12px rgb(0 0 0 / 0.1);
    }

    :scope:has(> img:first-child) {
      padding: 0;
      > img {
        width: 100%;
        aspect-ratio: 16 / 9;
        object-fit: cover;
        border-radius: var(--radius-m) var(--radius-m) 0 0;
      }
      > :not(img) {
        padding-inline: calc(var(--space-m) * var(--density));
      }
      > :last-child {
        padding-bottom: calc(var(--space-m) * var(--density));
      }
    }

    .title {
      font-size: var(--text-lg);
      font-weight: 600;
    }

    .meta {
      font-size: var(--text-sm);
      color: color-mix(in srgb, var(--on-surface) 60%, transparent);
    }

    @container (min-width: 500px) {
      :scope:has(> img:first-child) {
        display: grid;
        grid-template-columns: 200px 1fr;
        > img {
          height: 100%;
          border-radius: var(--radius-m) 0 0 var(--radius-m);
        }
      }
    }
  }
}

The HTML

<main>
  <section data-theme="dark">
    <article class="card">
      <img src="sunset.jpg" alt="Coastal sunset">
      <h2 class="title">The Quiet Coast</h2>
      <p>Body text...</p>
      <p class="meta">March 15, 2026 &middot; 8 min read</p>
    </article>
  </section>

  <aside data-density="compact">
    <article class="card">
      <h2 class="title">No Image Here</h2>
      <p>This card has no hero image, so it gets different styling.</p>
    </article>
  </aside>
</main>

Count the classes: card, title, meta. Three. The card adapts to dark mode, compact density, presence or absence of images, and its own container width – all from CSS. The markup is readable. The styles are centralised. Collisions are impossible.

What we stopped needing

What this is not

This is not a framework. There is no npm install. There is no config file. There is no build step (though you can add one if you want file splitting or minification – that is your choice, not a requirement).

This is an architectural pattern. It tells you how to organise your CSS and what tools to reach for in each situation. The implementation is vanilla CSS. The browser is the runtime.

It does not ask you to unlearn CSS. It asks you to use the CSS that actually exists today, instead of the CSS you learned to work around in 2015.

What it asks of you

Stop adding classes reflexively. Before writing class="...", ask: can :has(), a structural pseudo-class, or a data attribute handle this?

Stop fearing the cascade. You control it now. Layers are your priority system. Scopes are your boundaries. Properties are your type system. The cascade is not your enemy – it is your most powerful tool.

Stop reaching for JavaScript to style things. Theme providers, resize observers, animation libraries, conditional class logic – most of these exist because CSS could not do the job. It can now.

Accept the small imperfections. There will be edge cases where you need a utility class, or a manual class, or an override. That is fine. This is not about purity. It is about having a default posture that produces clean, scalable, maintainable CSS – and reaching for escape hatches only when you genuinely need them.

The cascade was never the problem. Our inability to control it was. That problem is solved.

Time to start fresh and begin building a brand new system! One that is clean and modern. Version 2.0 we’ll call it. We will learn from our mistakes and get it right with an all new team.

This time it’ll be different.

The Greenfield-Bedlam Cycle

Take a deep breath.

That tangled codebase you’re looking at started its life with similar aspirations. And then reality hit: a quick fix here, a compromise there, some over-eager abstraction in the heat of the moment, and before long, it’s death by a thousand corner cuts.

With stakeholders to please and deadlines to meet, the technical debt piles up, until all that remains of the original architecture is a chalk outline in the rough shape of a strategy design pattern.

Once a codebase has been through the grinder of business for a fiscal year or two, the debt can become so expensive that a certain class of organization (that rhymes with schmenterprise) would rather just send it adrift on an ice floe and start over from scratch.

I call it the Greenfield-Bedlam Cycle of enterprise software development; when a large enterprise keeps building the same software solution over and over, only to have it become a nightmare of incalculable risk within months of deployment. When this happens, the old solution is scrapped and the cycle starts over with a brand new Greenfield project.

Even in lean organizations with stronger technical vision, I have encountered the view that non-trivial codebases cannot be kept clean and maintainable over longer timeframes. At least not in fast-evolving fields like front end web development, where the same framework library meta-framework will happily reinvent itself five times in ten years, each time creating a trail of dead remains of legacy code scattered across the web.

You can’t blame someone for having a cynical stance on the longevity of things when the very house they live in was built on quicksand.

Confronting The Messy Reality

How do we break the Greenfield-Bedlam Cycle? Can we somehow stop the atrophy of our codebases and create software solutions that last longer - much longer - and that remains functional, maintainable, and extensible for years or decades, without sacrificing development speed or relying on mythical 10x developers? And can we achieve this not just occasionally by happy accident, but methodically, repeatably?

I believe so, and the key to unlocking this power is acknowledging the imperfections of technology and developers, and the messy reality that your code will meet once it hits production. As a developer or software architect, you cannot opt out of reality, so you have to design around it.

Messy Reality Number 1: Requirements change

All project requirements are based on assumptions and limited information. In a matter of hours, assumptions can be invalidated or leadership priorities can change. Perhaps you simply encounter overwhelming success and need to scale beyond your wildest projections.

How would you change your design to face the reality that requirements could change at any point in almost any way?

Messy Reality Number 2: External circumstances change

Any new codebase is designed based on a version of reality that will not exist in 18 months. Technological innovation could make part of your solution obsolete, a competitor could launch a killer app that pulls the rug out from under your product, security vulnerabilities may be uncovered, or dependent libraries are abandoned by their maintainers, forcing you to replace them.

In short: Reality drifts

How would you change your design to face the reality that almost any technology it uses could require replacement on short notice?

Messy Reality Number 3: Mistakes are made

Even a stack of mind-boggling complexity can be maintainable by a highly skilled developer with in-depth knowledge of the tech, the domain, the patterns and paradigms. That person could never have an ‘off’ day; and they would always be given all the time and resources they need. Does that sound like the world of enterprise? I have it on good authority that it’s not the world of FAANG either.

In all likelihood, the developer assigned to work on your stack on a given day is going to be on a deadline or unfamiliar with some part of the domain or tech. They might be lazy (in the “move fast and break things” sense of the word), or just having a bad day. A lot of the developers who are going to work on your codebase in 18 months haven’t even been hired yet, and some are still in school or interviewing for their first consulting job.

The fact is, your code is going to see some hasty workarounds in its life, and not even the most meticulously designed software architecture survives first contact with a junior developer. That is, not unless it was built to adapt and endure – to resist bad changes and even self-heal over time.

How would you change your design to face the reality that the developers maintaining your solution will be making mistakes like they’re going out of fashion?

Principles of long-lived software design

How do we architect systems to survive and even thrive in a messy reality?

Principle 1: Know the developers

“People are part of the system. The design should match the user’s experience, expectations, and mental models.”

~ Principles of computer system design: an introduction

To achieve longevity in our solutions, we must consider the skill and time constraints of the end users (developers/maintainers) and design a system with the largest-possible Pit of Success for the average developer to stumble towards.

This often means “killing your darlings” by meeting the developers where they are, not where you wish they were. There could be a significant skill gap between where the team is today and where they need to be to maintain the system you’re proposing. Few companies will invest in a comprehensive training program to not only re-train your current developers, but also bring all future hires up to speed – including after you leave or get promoted to senior management?

Even if it breaks your heart; that cool technology you like probably has to go.

Knowing the developers can also mean creating frameworks or abstractions that remove boilerplate and flatten the learning curve, or relying on patterns and even naming conventions that are already familiar to the devs.

In 2014, I had to build a frontend framework for a team of backend developers, and rather than try to convert them all to JavaScript enthusiasts, I created an HTMX-like markup syntax and async DOM manipulation component allowing them to build and maintain interactive frontend features without ever having to leave their familiar C#.

Finally, ‘knowing the developers’ means helping the developers know. Supporting their daily workflow by investing in writing rich documentation, templates and developer tooling, and spending time evangelizing the system, will reduce the friction of working on the system, and pay dividends in the long run.

You want both existing and future team members to feel intuitively familiar going into the codebase. This will allow them to make robust changes from day one.

Principle 2: Keep It Simple

Designing for longevity might sound like advocating for highly abstracted Ravioli Code, but that is not the case. For instance, in the early phases of development, you can safely assume that each iteration will be so different that any abstraction you built in the previous one will have to be scrapped anyway. The pragmatic way to design for such drastic change is to cobble together an MVP with bash scripts and bubble gum, since the next version will start from scratch either way.

Any complex system that works is invariably found to have evolved from a simple system that worked. The inverse proposition also appears to be true: A complex system designed from scratch never works and cannot be made to work. You have to start over, beginning with a working simple system.

Gall’s Law

As a rule, abstractions should be avoided until they can pay for themselves by taming parts of the code which have become unwieldy. Pragmatic, well-timed abstraction is beneficial, whereas premature abstraction violates Gall’s Law and leads to broken software.

Start Simple. You Ain’t Gonna Need It.

Principle 3: Design for change

Try to ensure that the systems you design are easy to change.

Naming things

Make the code - and repo structure - intuitive, adhering to the Principle of Least Surprise. If a developer doesn’t find the natural place to apply a change in the first or second place they look, they might just come up with a creative solution instead. Now you have two places where authorization rules are defined. Next week it could be three. Every ‘surprise’ in your design will attract code rot over time.

Encapsulation

Identify natural domain boundaries and encapsulate them with clear contracts. Rather than a technical boundary defined by microservice gateways and deployment bundles, or an organizational boundary defined by lines of management, a ‘domain boundary’ encapsulates a family of concepts which are likely to change together because they are intrinsically coupled, such as Users and UserProfiles.

Encapsulation by good domain boundaries simplifies future refactoring and aligns with real world aspects of your business/product, which are naturally long-lived.

The paved road

Prefer the well established stack over the ‘best’ one, since the 75% ‘batteries included’ solution that just works beats the 100% solution that requires constant tinkering because the stack is unstable and the developer ecosystem doesn’t exist yet. The exception is when you’re building systems at massive scale, where the absolute value of even a small incremental improvement can dramatically outweigh the cost of a team tinkering away on the 100% solution.

For open source dependencies, consider the size of the community and the number of contributors. If the project is maintained by a single person, it makes for a risky dependency. How frequently are major versions released? That is how often breaking changes are introduced. Do the maintainers keep updating and patching older versions, or will your team be forced to migrate to whole new versions every year to address unpatched security vulnerabilities?

When it comes to cloud platforms and application frameworks, these are load-bearing structures for your application, and you should choose the most stable and well supported option available. When it comes to libraries and services, you can afford to be more experimental as long as you take the necessary precautions, which brings us to…

Loose coupling

Keep systems loosely coupled: if you have fifty services all sending their logs to some 3rd party analytics tool, then consider creating a custom facade library to wrap all communication with the 3rd party tool. That way, when the day comes that the company changes logging tools (a safe bet), you only have to change the facade library in one place rather than all fifty services.

…but be pragmatic: If you can’t achieve looser coupling without adding a ton of complexity (stomping all over the KISS principle), you are probably better off accepting a bit of tight coupling. Certain key decisions, such as your choice of cloud provider, are one way doors with no easy way out, and while this may feel risky, it can bring great benefits; and one should never trade ten birds in the hand for one in the bush.

Open standards

Make sure that all critical business data is stored and accessible over open or de facto standards. ODBC is an open standard, as is Apache Arrow, whereas AWS S3 is an example of a defacto standard.

Stay away from closed proprietary data formats to prevent data lock-in and maximise the chances of future tool integrations just working out of the box.

Go build things to last

“What are you waiting for?! DO IT! JUST DO IT! YES, YOU CAN! JUST DO IT! If you’re tired of starting over, STOP GIVING UP!”

~ Shia LaBeouf, possibly referring to this article

Once you begin thinking of code in terms of longevity, it changes your approach to most aspects of software development.

The value of good documentation skyrockets when code needs to outlive multiple teams of maintainers. You still take on tech debt, but you may determine that some classes of tech debt (e.g. a quick and dirty one-off script or MVP) are acceptable while others (unintuitive naming or convention-breaking folder structures) are not. Your policies and preconceptions about automated tests, encapsulation, etc. – all need to be revisited when designing systems to stay in production for a decade or longer.

In return for this, however, you get a codebase that actively resists bad code; that neatly allows for innovation or changing requirements; a codebase that stays lean while maintaining high developer productivity for years – and which doesn’t require a costly bottom-up rebuild for every 2-3 years.

The result is faster development, higher quality, happier developers, and all of that at a significantly lower total cost of ownership.

Something I could one day nail to my wall if and when I ever get around to launching a startup of my own.

I didn’t expect it to come out as poetry though.

Start with a monolith

Start in the cloud

Start with a stack you know

Lean in for the KISS

 

DevOps is rocket fuel

Tests give you speed

Stay off the bleeding edge

This is your creed

 

Start with an MVP

Forget about scale

Look for that market fit

Make that first sale

 

Obsess over customers

Know why they click

Shorten your feedback loop

Don’t be a dick

 

Don’t chase that VC yet

Start with no dough

Launch early and often

Then pitch once you grow

 

And when you have…

 

Your culture can get out of hand

like a manifesto turned poem

Don’t hire what you cannot coach

Grow slow… or grow home

I will free admit that this is aggressively self-indulgent, pompous even… but it’s not wrong.

Hiring the right people

If I am going hiking, I don’t want the person who has memorized all the different hardening grades in the alloys of his pocket knife. I want the person who could start a fire in the dark in four different ways with nothing but a rock and pinecone. And in two more ways if the pinecone is wet.

Apply that to software and you have a surprisingly powerful recruiting method. Personally, in 10 years of hiring, I have not regretted a single hiring decision I made in this way.

(This is not the article to get into the details of hiring developers, but if you are interested, feel free to ask me. You may regret asking though – I can talk for hours about recruiting.)

Giving them what they need

Par for the course is powerful hardware, choose-your-own-keyboard, and the occasional conference ticket; but two essential things that top developers need to be both happy and highly productive, is clear direction and trust.

Once developers understand the “why” behind a high level requirement and are trusted with the details, they are free to explore and implement new and creative solutions. Such solutions may arrive at the goal in unconventional ways, but they almost always arrive both faster and better than anticipated by stakeholders or architects.

Getting out of the way

Obviously, don’t micromanage, but take it a step further and eliminate any and all interruptions and dependencies that get in the way of the work or pull the developer out of their productive ‘flow’. By my count, even the smallest interruption costs at least 30 minutes of productivity, in part due to the context switch itself but mainly from the process of slowly getting back into the flow of coding.

As for dependencies, any process that requires getting a response from a person outside the immediate team introduces a perfect storm of context switching, busy-waiting, and in some case even anxiety; these are people who may very well have spent 10,000 hours learning to code alone in front of a computer: a lot of them don’t like talking to people, let alone people they don’t know.

Finally, hands-off management is not ears-off management. Every team has needs which evolve over time, and as a leader your job is to listen and provide, whether that means coaching them, buying them nerf guns, or fighting off stakeholders when they come bearing gifts of this week’s feature creep (and it is always feature creep).

1. The willingness to make mistakes. Small mistakes can be accepted as the cost of doing business, bigger ones can be automatically detected and remediated in real time. Velocity is gained through automation and no-blame culture.
2. The number of hours per week where a state of high-productivity ‘flow’ can be achieved. Flow can only happen where developers have uninterrupted time and clarity of goals. Velocity is gained through hands-off leadership.
3. The ability to make decisions in real time, without having to ask permission or coordinate with external teams. Velocity is gained through trust, transparency and architectural decoupling.

In short: Automation, No-blame culture, Hands-off leadership, Trust, Transparency, and Architectural decoupling.

Tenets of Lean, but boogeymen in the typical enterprise.