FCL-631 | add front-end ADRS

Author: jlhdxw

doc/adr/0022-tna-frontend-colours-override.md

@@ -0,0 +1,43 @@
+# 22. TNA Front-end colours override
+
+Date: 2025-02-07
+
+## Status
+
+Accepted
+
+## Context
+
+### Background
+
+We are using the TNA colour values provided from the TNA front-end library, however the colours available don't quite match up with the use cases we have in Find Case Law.
+
+### Problem
+
+Because we don't have colours that match up with features and areas on the website, the features don't look right.
+
+### Goals
+
+Introduce a way to have colours that match the features we have on the Find Case Law website.
+
+### Options considered
+
+- Look at using a different colour scheme/not use the TNA colours
+- Add extra colours that aren't part of the TNA colour scheme and mix and match the two
+- Override the relevant TNA colours that don't match the Find Case Law features
+
+## Decision
+
+### Proposed solution
+
+Override the relevant TNA colours by importing the SCSS variable map into our application and override the relevant colours.
+
+### Justification
+
+This allows us to continue using colours that we chose to use in the colour variable ADR, however we will still have the flexibility of modifying colour values to fit the features in Find Case Law.
+
+## Consequences
+
+- We need to maintain a divergence from the TNA colours scheme
+- If the TNA colour variable map changes naming or format upstream, we will need to modify our code
+- The colours we use may not be as accessible as the TNA colour schema

doc/adr/0023-style-lint.md

@@ -0,0 +1,50 @@
+# 23. Style Lint
+
+Date: 2025-02-07
+
+## Status
+
+Accepted
+
+## Context
+
+### Background
+
+We have a basic configuration of Style Lint that runs on a pre-commit hook.
+
+### Problem
+
+Our installation of style lint only has a basic configuration that doesn't lint our CSS properly to ensure consistent CSS throughout our app.
+
+### Goals
+
+We want to have automated style linting so can have consistent and standardised CSS without a large amount of manual intervention when composing CSS and also in the review process.
+
+### Options considered
+
+- Use the stylelint-selector-bem library to ensure bem classes
+- Use stylelint-clean-order library to ensure valid css order
+- Use stylelint-standard-css
+- Create a custom selector class pattern for bem classes
+- Have a style lint configuration file per repository
+- Have a style lint configuration file shared that can be used by all relevant repositories
+
+## Decision
+
+### Proposed solution
+
+- Use stylelint-clean order and stylelint-standard-css libraries
+- Create a custom selector class pattern for bem classes
+- Have a shared style lint configuration but allow each repository to extend that configuration file as necessary
+
+### Justification
+
+- The stylelint-clean-order and stylelint-standard-css libraries work well out of the box and save us writing our own rules
+- The stylelint-selector-bem library does not work out of the box and the configuration needed is the equivalent of just writing your own selector class.
+- Allowing the shared style lint configuration to be customised likely won't be needed too much, however it allows for flexibility should it be needed
+
+## Consequences
+
+- We will need to maintain our own bem selector function - however, the BEM specification is likely to change and so shouldn't need any changes
+- Allowing the shared configuration to be customised could mean slight deviation in in CSS across repos
+- When we make a change to the style-lint, we will need to update the relevant downstream repositories with the new changes and then update any offending CSS

doc/adr/0024-usage-of-gov-uk-front-end.md

@@ -0,0 +1,52 @@
+# 24. Usage of GOV.UK Front-end
+
+Date: 2025-02-07
+
+## Status
+
+Accepted
+
+## Context
+
+### Background
+
+The Find Case Law website is a public government service. The GOV.UK front-end library has various useful components that are built to be used by government services.
+
+### Problem
+
+We want to build various features on the Find Case Law website at pace without having to build everything from scratch, and we want these features to use components that are accessible and work in a standard way.
+
+### Goals
+
+- Build features on the Find Case Law website that are accessible
+- Build features on the Find Case Law website at pace
+- Build features on the Find Case law that work in an industry standard way
+- Have minimal code to maintain
+
+### Options considered
+
+- Build our own component library from scratch
+- Add the GOV.UK front-end library as a dependency and override any styling that doesn't match Find Case Law
+- Create a copy of the GOV.UK component library and make changes to the core code for styles that doesn't match Find Case Law
+- Use a non-government supported component library and style it to match the Find Case Law branding
+
+## Decision
+
+### Proposed solution
+
+- Add the GOV.UK front-end library as a dependency
+- Override styling that doesn't match Find Case law
+- Ensure the CSS for overriding is as decoupled from our application as possible
+- Ensure the HTML for usage of the components is decoupled from our application as possible by creating Find Case Law equivalent components that inherit from the GOV.UK components
+
+### Justification
+
+- By adding the GOV.UK front-end library as a dependency, we will get any new features and changes that happen upstream
+- By overriding styling that doesn't match Find Case Law, it means we'll have less breaking changes when we update the library and we don't couple our styling heavily with the usage of the library
+- By using our own component HTML that inherits/uses the HTML from the GOV.UK front-end library, and decoupling our application from the GOV.UK front-end components, it allows updating the GOV.UK front-end library with minimal breaking changes
+
+## Consequences
+
+- We can build new features at pace without having to build too much
+- New components and features will be accessible
+- By decoupling the implementation of the GOV.UK front-end library, it requires minimal maintenance and a smaller blast radius when breaking changes happen upstream

doc/adr/0025-usage-of-home-office-front-end.md

@@ -0,0 +1,46 @@
+# 25. Usage of Home Office Front-end
+
+Date: 2025-02-07
+
+## Status
+
+Accepted
+
+## Context
+
+### Background
+
+We have a number of different alert components used within the application.
+
+### Problem
+
+Having multiple different styles of alert components from different libraries creates an inconsistent experience for users and also means we have multiple components to maintain.
+
+### Goals
+
+- An alert component that is consistent throughout
+- Minimal maintenance with an alert component
+- An accessible alert component
+- Styled to match the Find Case Law service
+
+### Options considered
+
+- Custom built alert component
+- GOV.UK alert component
+- TNA front-end alert component
+- Home office alert component
+
+## Decision
+
+### Proposed solution
+
+Use the home office alert component, but don't include the whole library - just take a copy of this specific component.
+
+### Justification
+
+It matches the style of the Find Case Law styles closest with minimal style changes.
+
+## Consequences
+
+- We will have a consistent alert component that matches the style we want in Find Case law
+- We need to manually maintain another external dependency for the sake of a single component

doc/adr/0026-playwright-for-end-to-end-tests.md

@@ -0,0 +1,47 @@
+# 26. Playwright for end to end tests
+
+Date: 2025-02-07
+
+## Status
+
+Accepted
+
+## Context
+
+### Background
+
+We want to have end to end tests across the Find Case Law website so that we can have confidence our service is working as expected while making changes and implementing new features.
+
+### Problem
+
+Testing the service end to end is currently a manual process and takes a lot of time. Doing this end to end test manually also gets forgotten and it means potentially areas of the website that are less frequently used may get broken without anybody noticing.
+
+### Goals
+
+- Have end to end tests for the key paths within the Find Case Law website
+- Have end to end tests that can be run automatically in CI/CD
+- Use a standard/well maintained library
+- Have the tests written in a language that all developers can write the tests for
+
+### Options considered
+
+- Cypress
+- Playwright
+- Capybara
+- Puppeteer
+
+## Decision
+
+### Proposed solution
+
+Playwright
+
+### Justification
+
+Playwright is the only option that allows writing the test in python which is the language all the developers can write code in. It is also very well maintained and the most standard option available.
+
+## Consequences
+
+- End to end tests for all key user paths need to be written and maintained
+- We will have confidence the service is working as intended while making changes and adding new features
+- When we change the key user paths within the service, we will need to update the relevant end to end tests

doc/adr/0027-automated-accessibility-checking.md

@@ -0,0 +1,48 @@
+# 27. Automated accessibility checking
+
+Date: 2025-02-07
+
+## Status
+
+Accepted
+
+## Context
+
+### Background
+
+We want to automate our accessibility testing
+
+### Problem
+
+Accessibility testing across the Find Case law service is a manual process, with a number of approaches that could be taken without much consistency. During the development process accessibly is often forgotten as it's not necessarily easy to remember all the various accessibility best practices when building websites.
+
+### Goals
+
+- Have an automated way of flagging accessibility issues in our code
+- Ensure the accessibility tests are standardised and catch issues that would be raised in a normal accessibility audit
+
+### Options considered
+
+- Use a service like BrowserStack
+- Use PA11Y
+- Use Axe-Core
+- Use Wave chrome extension with a test script
+- Use Axe-playwright
+
+## Decision
+
+### Proposed solution
+
+Add the axe-playwright library to our existing automated test and automatically do an accessibility check on all pages covered by our end to end testing suite.
+
+### Justification
+
+- Easiest option to add into our existing testing setup
+- Has standardised tests and covers the main accessibility checks
+- Already works with our CI/CD
+
+## Consequences
+
+- All our pages covered by end to end tests will have an accessibility check against them ensuring our key user journeys are accessible
+- Pages that we want to automatically check their accessibility will need a playwright test added
+- If we implement large features without checking for accessibility, they will need to be fixed before code can be merged and released

doc/adr/0028-sass-for-all-css.md

@@ -0,0 +1,51 @@
+# 28. Using SASS for all CSS
+
+Date: 2025-02-07
+
+## Status
+
+Accepted
+
+## Context
+
+### Background
+
+We need to style the Find Case Law front-end.
+
+### Problem
+
+Styling applications in pure CSS is inefficient and prone to causing inconsistencies.
+
+### Goals
+
+- Simple, easy solution to writing efficient CSS
+- Reduce duplication and promote sharing shared CSS
+- Have the ability to compile performant CSS and reduce duplication
+
+### Options considered
+
+- Pure CSS
+- LESS
+- SCSS
+- Stylus
+- PostCSS
+
+## Decision
+
+### Proposed solution
+
+Use SCSS throughout all Find Case Law front-end styling.
+
+### Justification
+
+- Used across most government public service applications
+- Allows easily using external government supported libraries like GOV.UK front-end
+- Allows writing simple, efficient CSS
+- Can share CSS via mixins
+- Can use it to compile performant CSS
+
+## Consequences
+
+- We'll be able to easily use SCSS supported libraries
+- We can use GOV.UK front-end library and import their CSS into our components
+- Our CSS will be efficient, simple and we will be able to reduce duplication

doc/adr/0029-css-spacing-variable-convention.md

@@ -0,0 +1,51 @@
+# 29. CSS Spacing Variable Convention
+
+Date: 2025-02-07
+
+## Status
+
+Accepted
+
+## Context
+
+### Background
+
+Spacing values across the application are inconsistent and don't follow a convention.
+
+### Problem
+
+Not having a standard spacing convention creates inconsistencies in the user experience, the design of the website and increases the amount of maintenance needed for making changes to spacing.
+
+### Goals
+
+- Allow for better consistency throughout the Find Case Law front-end
+- Reduce the maintenance cost when updating spacing across the website
+- Have a convention to follow to allow making changes at pace
+
+### Options considered
+
+- Use SCSS functions to generate spaces from a base size, i.e. calc(base-size \* 1.5)
+- Have a static number of variables that follow a naming convention based on their size, i.e. "xs" for a small size, and "xl" for a large size
+- Have a static number of variables that follow a numerical naming convention based on their space, i.e. "space-1" for a small size
+- Have variables that directly mimic their value, i.e. "space-1" would be "1rem"
+
+## Decision
+
+### Proposed solution
+
+Have a static number of variables that follow a numerical naming convention based on their space, i.e. "space-1"
+
+### Justification
+
+All options potentially allow for consistency, however:
+
+- Using CSS functions increase the cognitive complexity when reading the SCSS as it's not immediately clear what the output from the function would be
+- Having a static number of variables that follow a naming convention based on their size also does not make it immediately clear what the value could be in relation to others.
+- Having variables that mimic their value directly mean when a value on a variable updates, the variable has to update to, making using a variable at all redundant
+
+Using a static number of variables that follow a numerical naming convention allows for consistency, reduces the maintenance cost of updating space as the values aren't tied to the variable name and makes it easy to understand the sizing variables relatively when building components.
+
+## Consequences
+
+- Consistent user experience as spacing across the website won't be slightly different in various places
+- Make it easy to update and build new features with a clear convention to follow