FCL-631 | add front-end ADRS

Author: jlhdxw

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

@@ -0,0 +1,42 @@
+# 22. TNA Front-End Colour Overrides
+
+**Date:** 2025-02-07
+**Status:** Accepted
+
+## Context
+
+### Background
+
+The application uses colour values provided by the TNA front-end library. However, the available colours do not fully align with the requirements of Find Case Law.
+
+### Problem
+
+The existing TNA colour palette does not provide appropriate mappings for all features and areas within Find Case Law, resulting in inconsistent or suboptimal visual presentation.
+
+### Goals
+
+Establish a mechanism to define colours that align with the requirements of Find Case Law while maintaining compatibility with the TNA front-end library.
+
+## Options Considered
+
+1. Use an alternative colour scheme instead of the TNA colours.
+2. Introduce additional colours outside the TNA scheme and combine them as needed.
+3. Override specific TNA colours to better align with the Find Case Law design.
+
+## Decision
+
+### Solution
+
+Override specific TNA colour values by importing the SCSS variable map into the application and redefining the relevant colours.
+
+### Justification
+
+- Maintains alignment with the colour choices defined in the colour variable ADR.
+- Provides flexibility to adjust colour values as needed for Find Case Law.
+- Reduces the need for a completely independent colour scheme.
+
+## Consequences
+
+- The application will diverge from the standard TNA colour scheme.
+- Changes to the TNA colour variable map (e.g., naming conventions or format) will require updates to the implementation.
+- The modified colours may not fully adhere to the accessibility standards of the TNA scheme.

doc/adr/0023-style-lint.md

@@ -0,0 +1,47 @@
+# 23. StyleLint Configuration
+
+**Date:** 2025-02-07
+**Status:** Accepted
+
+## Context
+
+### Background
+
+A basic configuration of StyleLint is currently enforced through a pre-commit hook. However, this configuration is minimal.
+
+### Problem
+
+The existing StyleLint setup lacks comprehensive rules to ensure consistent and standardised CSS. This results in potential inconsistencies that require manual intervention during development and code reviews.
+
+### Goals
+
+Implement an automated style linting configuration that enforces consistent and standardised CSS while minimising manual effort during composition and review.
+
+## Options Considered
+
+1. Use the `stylelint-selector-bem` library to enforce BEM class naming.
+2. Use the `stylelint-clean-order` library to enforce a structured CSS property order.
+3. Use `stylelint-standard-css` to enforce general CSS best practices.
+4. Define a custom selector class pattern for BEM class naming.
+5. Maintain a per-repository StyleLint configuration file.
+6. Use a shared StyleLint configuration file across repositories, with the option for per-repository extensions.
+
+## Decision
+
+### Solution
+
+- Use the `stylelint-clean-order` and `stylelint-standard-css` libraries for property ordering and general CSS best practices.
+- Define a custom selector class pattern for BEM class naming.
+- Maintain a shared StyleLint configuration file that can be extended by individual repositories as needed.
+
+### Justification
+
+- The `stylelint-clean-order` and `stylelint-standard-css` libraries provide effective linting out of the box, reducing the need to define custom rules.
+- The `stylelint-selector-bem` library requires extensive configuration, making it equivalent to defining custom rules manually.
+- A shared StyleLint configuration ensures consistency across repositories while allowing flexibility where necessary.
+
+## Consequences
+
+- The BEM selector function must be maintained internally. However, as the BEM methodology is stable, changes should be infrequent.
+- Allowing repositories to extend the shared configuration introduces the possibility of slight deviations in CSS conventions across projects.
+- Any updates to the StyleLint configuration will require corresponding updates in downstream repositories, including adjustments to any affected CSS.

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

@@ -0,0 +1,49 @@
+# 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 Frontend library provides pre-built, accessible components designed for government services.
+
+### Problem
+
+To develop new features efficiently, the project requires a component library that is accessible, follows industry standards, and minimises maintenance effort. Building all components from scratch would slow development and increase maintenance overhead.
+
+### Goals
+
+- Ensure accessibility in new features.
+- Accelerate development.
+- Maintain industry-standard component behavior.
+- Minimise code maintenance.
+
+## Options Considered
+
+1. Build a custom component library from scratch.
+2. Use the GOV.UK Frontend library as a dependency and override styling where necessary.
+3. Fork the GOV.UK component library and modify core styles directly.
+4. Use a third-party component library and style it to match Find Case Law branding.
+
+## Decision
+
+### Solution
+
+- Add the GOV.UK Frontend library as a dependency.
+- Override styles that do not align with Find Case Law where necessary.
+- Keep CSS overrides as decoupled from the application as possible.
+- Wrap GOV.UK components in Find Case Law-specific components to decouple usage from direct dependency on GOV.UK markup.
+
+### Justification
+
+- Using GOV.UK Frontend as a dependency ensures compatibility with upstream updates and feature additions.
+- Overriding styles selectively minimises breaking changes and prevents tight coupling between Find Case Law styling and GOV.UK components.
+- Abstracting GOV.UK components into Find Case Law equivalents allows for future changes with minimal impact when updating the library.
+
+## Consequences
+
+- New features can be built efficiently without unnecessary development overhead.
+- Components remain accessible and adhere to government service standards.
+- Decoupling from direct GOV.UK component usage reduces maintenance effort and limits the impact of upstream changes.

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
+
+The application currently uses multiple alert components from different libraries, leading to inconsistencies in styling and behavior.
+
+### Problem
+
+The use of multiple alert component styles results in an inconsistent user experience and increases maintenance overhead by requiring support for multiple implementations.
+
+### Goals
+
+- Standardise the alert component across the application.
+- Minimise maintenance effort.
+- Ensure accessibility.
+- Align the alert component's styling with the Find Case Law service.
+
+## Options Considered
+
+1. Build a custom alert component.
+2. Use the GOV.UK Frontend alert component.
+3. Use the TNA Frontend alert component.
+4. Use the Home Office alert component.
+
+## Decision
+
+### Solution
+
+- Use the Home Office alert component.
+- Extract and integrate only this component rather than including the entire Home Office Frontend library.
+
+### Justification
+
+- The Home Office alert component aligns most closely with the Find Case Law styling, requiring minimal modifications.
+- Using a pre-existing, accessible component reduces development and maintenance effort compared to a custom implementation.
+- Extracting only the required component avoids unnecessary dependencies from the full Home Office Frontend library.
+
+## Consequences
+
+- The application will have a consistent and accessible alert component.
+- The extracted component will need to be manually maintained as an external dependency.

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

@@ -0,0 +1,46 @@
+# 26. Playwright for End-to-End Testing
+
+**Date:** 2025-02-07
+**Status:** Accepted
+
+## Context
+
+### Background
+
+End-to-end (E2E) tests are required to ensure the Find Case Law website functions as expected while implementing changes and new features.
+
+### Problem
+
+Currently, end-to-end testing is performed manually, which is time-consuming, prone to being overlooked, and increases the risk of regressions in less frequently used areas of the website.
+
+### Goals
+
+- Implement automated end-to-end tests for critical user paths.
+- Integrate tests into the CI/CD pipeline for automated execution.
+- Use a well-maintained and widely adopted testing framework.
+- Ensure tests are written in a language all developers are comfortable with.
+
+## Options Considered
+
+1. **Cypress** – Popular and feature-rich but requires JavaScript/TypeScript.
+2. **Playwright** – Supports multiple languages, including Python, and is well-maintained.
+3. **Capybara** – Primarily used in Ruby environments, not suitable for this project.
+4. **Puppeteer** – JavaScript-based and less feature-complete for end-to-end testing compared to Playwright.
+
+## Decision
+
+### Solution
+
+Use **Playwright** for end-to-end testing.
+
+### Justification
+
+- Playwright supports Python, ensuring all developers can contribute to test writing and maintenance.
+- It is a well-maintained, widely adopted, and feature-rich testing framework.
+- Playwright provides robust support for modern web applications, including handling multiple browser contexts, network mocking, and parallel execution.
+
+## Consequences
+
+- End-to-end tests must be written and maintained for all critical user paths.
+- Automated testing will increase confidence in the stability of the service during development and deployment.
+- Updates to key user paths will require corresponding updates to the end-to-end tests.

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

@@ -0,0 +1,45 @@
+# 27. Automated Accessibility Checking
+
+**Date:** 2025-02-07
+**Status:** Accepted
+
+## Context
+
+### Background
+
+Automating accessibility testing is necessary to ensure that the Find Case Law service meets accessibility standards consistently.
+
+### Problem
+
+Accessibility testing is currently a manual process with no standardised approach. As a result, accessibility best practices are often overlooked during development, leading to inconsistent compliance and potential usability issues.
+
+### Goals
+
+- Implement an automated process to flag accessibility issues in the codebase.
+- Standardise accessibility tests to ensure consistency and alignment with formal accessibility audits.
+
+## Options Considered
+
+1. **BrowserStack** – Provides accessibility testing as a service but adds external dependencies and potential cost overhead.
+2. **PA11Y** – An open-source tool, but requires additional configuration and does not integrate with Playwright.
+3. **Axe-Core** – A widely used accessibility engine, but would require additional scripting for automation.
+4. **Wave Chrome Extension with a test script** – Useful for manual checks but does not support automated testing.
+5. **Axe-Playwright** – A wrapper around Axe-Core that integrates directly with Playwright for automated accessibility testing.
+
+## Decision
+
+### Solution
+
+Integrate **Axe-Playwright** into the existing automated test suite to perform accessibility checks on all pages covered by end-to-end tests.
+
+### Justification
+
+- Seamlessly integrates with the existing Playwright-based testing setup.
+- Provides standardised accessibility checks aligned with industry best practices.
+- Works within the CI/CD pipeline, enabling continuous accessibility monitoring.
+
+## Consequences
+
+- All pages covered by end-to-end tests will undergo automated accessibility checks, ensuring key user journeys remain accessible.
+- Any new pages requiring accessibility validation must have corresponding Playwright tests.
+- Large feature implementations that introduce accessibility issues will need to be fixed before merging and releasing code.

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

@@ -0,0 +1,47 @@
+# 28. Using SASS for All CSS
+
+**Date:** 2025-02-07
+**Status:** Accepted
+
+## Context
+
+### Background
+
+The Find Case Law front-end requires a maintainable and efficient styling approach.
+
+### Problem
+
+Writing styles in pure CSS is inefficient, difficult to maintain, and increases the risk of inconsistencies across the application.
+
+### Goals
+
+- Implement a simple and efficient approach to writing CSS.
+- Reduce duplication and promote reusability of styles.
+- Ensure compiled CSS is optimised for performance.
+
+## Options Considered
+
+1. **Pure CSS** – Lacks support for variables, mixins, and other features that improve maintainability.
+2. **LESS** – Similar to SCSS but less commonly used and supported in government services.
+3. **SCSS** – Widely used, flexible, and compatible with GOV.UK Frontend and other government-supported libraries.
+4. **Stylus** – Less commonly adopted and has a smaller ecosystem.
+5. **PostCSS** – Powerful but primarily used for processing CSS rather than writing styles directly.
+
+## Decision
+
+### Solution
+
+Adopt SCSS as the standard for all front-end styling in Find Case Law.
+
+### Justification
+
+- SCSS is widely used in public sector applications, including GOV.UK services.
+- Seamlessly integrates with government-supported libraries such as GOV.UK Frontend.
+- Enables writing efficient and maintainable CSS using variables, mixins, and nesting.
+- Supports compiling optimised CSS with reduced duplication.
+
+## Consequences
+
+- SCSS-supported libraries can be integrated more easily.
+- GOV.UK Frontend styles can be imported and customised as needed.
+- Styles will be more maintainable, efficient, and consistent across the application.

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

@@ -0,0 +1,53 @@
+# 29. CSS Spacing Variable Convention
+
+**Date:** 2025-02-07
+**Status:** Accepted
+
+## Context
+
+### Background
+
+Spacing values across the application are currently inconsistent and do not follow a standardised convention.
+
+### Problem
+
+The lack of a consistent spacing convention results in:
+
+- Inconsistencies in user experience and visual design.
+- Increased maintenance overhead when adjusting spacing.
+- Difficulty in making layout changes efficiently.
+
+### Goals
+
+- Standardise spacing values across the Find Case Law front-end.
+- Reduce maintenance effort when updating spacing.
+- Provide a clear convention to enable faster development and modifications.
+
+## Options Considered
+
+1. **Use SCSS functions** – Generate spacing values dynamically based on a base size (e.g., `calc(base-size * 1.5)`).
+2. **Use named size variables** – Define a static set of variables (`xs`, `sm`, `lg`, `xl`) based on relative size.
+3. **Use numerical naming convention** – Define a static set of variables using a numbered scale (`space-1`, `space-2`, etc.).
+4. **Use variables that mimic values** – Define variables where the name directly reflects the value (e.g., `space-1` equals `1rem`).
+
+## Decision
+
+### Solution
+
+Adopt a static set of variables following a numerical naming convention (e.g., `space-1`, `space-2`, etc.).
+
+### Justification
+
+- SCSS functions add unnecessary cognitive complexity, as the output is not immediately clear when reading the SCSS.
+- Named size variables (e.g., `xs`, `sm`, `lg`) lack clear relationships between values, making it harder to determine spacing hierarchy.
+- Variables that mimic their values directly (e.g., `space-1 = 1rem`) create unnecessary maintenance overhead, as renaming would be required if values change.
+- A numerical naming convention provides:
+  - **Consistency** – Ensures predictable spacing across the application.
+  - **Maintainability** – Values can be adjusted without renaming variables.
+  - **Clarity** – Developers can easily compare spacing values in relation to each other.
+
+## Consequences
+
+- **Consistent user experience** – Spacing will be uniform across the website.
+- **Simplified development** – A clear convention reduces ambiguity and speeds up implementation.
+- **Easier maintenance** – Updating spacing values will not require renaming variables.