ADR 4: Model browser specific values and computations (#106)

docs/architecture/decisions/README.md

@@ -2,6 +2,7 @@
 
 The following is an index of all the architecture decisions taken so far. Whenever a new architecture decision report is created, it must be added to the index regardless of its status. For guidance on how to write reports, please refer to the [architecture documentation](../README.md).
 
-- [**ADR-001**](adr-001.md): Use architecture decision reports
-- [**ADR-002**](adr-002.md): Move towards static analysis
-- [**ADR-003**](adr-003.md): Use TypeScript as implementation language
+- [**ADR 1**](adr-001.md): Use architecture decision reports
+- [**ADR 2**](adr-002.md): Move towards static analysis
+- [**ADR 3**](adr-003.md): Use TypeScript as implementation language
+- [**ADR 4**](adr-004.md): Model browser specific values and computations

docs/architecture/decisions/adr-003.md

@@ -2,7 +2,7 @@
 
 ## Context
 
-Having decided on [ADR-002](adr-002.md), we foresee that the Alfa code base will be both significantly larger and more complex than the code base of our proprietary engine. This due to the fact that we will have to implement a great deal of APIs that we have previously relied on the browser implementations of. Coupled with the fact that the most common type of bug we have encountered in the past has been stray `undefined` or `null` values and APIs receiving incorrect parameters, plain JavaScript, even if covered by tests, is simply not an option moving forward. We will either need tooling that can sanity check our JavaScript or move to a language with a proper type system that can enforce API contracts.
+Having decided on [ADR 2](adr-002.md), we foresee that the Alfa code base will be both significantly larger and more complex than the code base of our proprietary engine. This due to the fact that we will have to implement a great deal of APIs that we have previously relied on the browser implementations of. Coupled with the fact that the most common type of bug we have encountered in the past has been stray `undefined` or `null` values and APIs receiving incorrect parameters, plain JavaScript, even if covered by tests, is simply not an option moving forward. We will either need tooling that can sanity check our JavaScript or move to a language with a proper type system that can enforce API contracts.
 
 However, given that browsers are still part of the equation, Alfa must be able to also run in a browser. This way, we ensure that we can implement tools such as our Chrome extension based on Alfa.
 

docs/architecture/decisions/adr-004.md

@@ -0,0 +1,33 @@
+[accessibility support baseline]: https://www.w3.org/TR/WCAG-EM/#step1c
+
+# ADR 4: Model browser specific values and computations
+
+## Context
+
+Having decided on [ADR 2](adr-002.md), we will no longer be tied to any one specific browser and are left with the choice of what to do about things that browsers are not aligned on. For example, if Alfa needs to implement an API to perform a given task and a given set of browsers do not agree on how the API should be implemented, Alfa can do several things:
+
+1. Implement the API the way it is implemented in the _least_ capable browser, in terms of the API, among a given set of browsers.
+
+2. Implement the API the way it is implemented in the _most_ capable browser, in terms of the API, among a given set of browsers.
+
+3. Provide several implementations of the API that cover all the different implementations of the API among a given set of browsers.
+
+Our proprietary accessibility conformance testing engine at Siteimprove takes the second approach in practice as it is usually run within the latest version of the Chrome browser and relies heavily on browser APIs. Other tools that operate with the concept of an [accessibility support baseline][] will typically take a combination of the first and second approach where some browser APIs are used and then others implemented manually according to the capabilities of the [accessibility support baseline][].
+
+The quality shared by the first and second approach is that they both produce just a single implementation of the API, though with potentially different capabilities. However, both approaches suffer from the fact that depending on how the API is implemented, an accessibility issue could be found in either the least or most capable browser, while being missed in the other. As an example, a contrast issue might appear in an older browser that does not support a specific color format, while the contrast would be perfectly fine in a newer browser that does support the specific color format. The third approach avoids this issue entirely by implementing the API in all possible ways for a given set of browsers.
+
+## Decision
+
+We will take the third approach described in the previous section and incrementally adopt it throughout Alfa where it makes sense. To do so, we will introduce the concept of _browser specific values_ that model abstract values that can take on multiple concrete values across different sets of browsers. This way, any API that we may want to implement can either return just a single value or a set of browser specific values in the case where the API would behave differently in different sets of browsers.
+
+To decrease the complexity of working with browser specific values, we will implement them as [monads](<https://en.wikipedia.org/wiki/Monad_(functional_programming)>) and expose a set of operations that allow consumers to perform computations on browser specific values without having to worry about whether they take on one or multiple concrete values.
+
+## Status
+
+Accepted.
+
+## Consequences
+
+By providing a building block for modelling browser specific values, we are in a position to substantially increase the usefulness of Alfa for individuals and organisations that need results for not just a single browser but a range of browsers, old or new.
+
+The onus is of course on us, the Alfa development team, to account for misalignment between browsers and to constantly stay on top of it. We must be pragmatic about when and where to account for browser misalignment and find a balance between complexity added and value provided.