---
title: Style Guide
---

**ESTABLISHING CODE STYLE STANDARDS AND CONVENTIONS FOR ALL PROJECTS**

## 1. INTRODUCTION AND LEGAL FRAMEWORK

### 1.1. Policy Overview

This Style Guide (hereinafter referred to as "the Guide") establishes mandatory code style standards, conventions, and formatting requirements applicable to all projects maintained by our organisation. This Guide operates within our comprehensive legal and policy framework, incorporating our Terms of Service, Contributor Covenant, and all applicable legal protections by reference.

### 1.2. Scope and Applicability

This Guide applies to all code contributions to NHCarrigan-maintained repositories, regardless of contributor status. All contributors to our projects are required to comply with the standards set forth in this Guide.

**IMPORTANT: Non-compliance with this Guide may result in rejection of contributions, requests for modification, or other appropriate actions as determined by project maintainers.**

**Note for Mentorship Programme Participants:** This Guide governs contributions to NHCarrigan-maintained repositories only. It does not apply to your flagship project. Your flagship project is your own intellectual property, and you are entirely free to set your own style standards, choose your own licence, and use your own copyright attribution.

### 1.3. Legal Compliance and Intellectual Property

All code contributions must comply with:
- Our global software licence: Naomi's Public Licence
- Contributor Covenant requirements
- Applicable intellectual property laws and regulations
- Export control and data protection requirements

## 2. GLOBAL CONVENTIONS

These sections apply to all code in any of our projects.

### 2.1. Copyright Notice

All code files should begin with a comment section containing the copyright information:

```js
/**
 * @copyright NHCarrigan
 * @license Naomi's Public Licence
 * @author Naomi Carrigan
 */
```

Note that `copyright` _must_ be assigned to `NHCarrigan`, and our `license` must be applied, but when checking in new code you may attribute yourself as the author, or add yourself to the list for existing code.

## 3. JAVASCRIPT AND TYPESCRIPT PROJECTS

The following sections apply to our JavaScript/TypeScript projects. Style conventions are enforced through our [custom ESLint package](/projects/eslint).

:::caution
We do _not_ use Prettier in any of our projects. Instead, our linter package also handles code styling.

If you are using VSCode, you can add this to your `.vscode/settings.json` file in the project directory to enable auto-formatting on save.

```json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": ["typescript"]
}
```

Because of this, our style guide will not cover the formatting section of our linter package.
:::

### 3.1. Main Rules

These rules apply to all TypeScript code, and will run on files in `src/**/*.ts`.

#### 3.1.1. ESLint Enforced Rules

- Setters must have a corresponding getter.
- Array methods which return a value must return a value in the callback.
- Arrow functions should always use curly braces.
- Variables must be used within the scope they are defined.
- Comments should always start with a capital letter.
- Avoid overly complex functions.
- `return` statements must either never return a value, or always return a value.
- `if` statements and similar control blocks should always use curly braces.
- Switch statements must always have a default case, and the default case must always come last.
- Never use loose equality.
- A `for` loops iteration direction must match the conditional bound.
- Functions assigned to a property must match the name of the property.
- With the exception of callback functions, all functions should be assigned a name.
- When using the `function` keyword, prefer `function name()` declarations over `const name = function()` expressions.
- Getters should always return a value.
- Getters and setters should be grouped together.
- You should never use logical assignment operators.
- You should never have more than one class per file.
- Logical blocks should not be nested more than five levels deep. Prefer extracting into separate functions.
- Files should not have more than 300 lines. Prefer extracting into modular functions.
- Functions should not have more than 50 lines. Prefer breaking down into smaller logic.
- Callbacks should not be nested more than two levels.
- Functions should not have more than 20 logical statements/branches.
- Constructor names should begin with a capital letter.
- Do not use the `alert` API.
- Promise executor functions should not be async.
- Do not use `await` within loops.
- Do not use bitwise operators.
- Do not use `arguments.caller` or `arguments.callee`.
- Do not declare variables within switch case statements.
- Do not reassign class definitions.
- Do not compare with `-0`.
- Do not perform assignments in conditions e.g. `if (name = "Naomi")`.
- Do not use the `console` API, prefer our custom logger.
- Avoid confusing operator combinations e.g. `a + b ?? c`.
- Avoid constant conditions e.g. `if(false)` or `while(true)`.
- Constructors should not return a value. They implicitly return the instance.
- Do not use control characters `\x00` in regular expressions.
- Do not use `debugger` statements.
- Do not use `delete` on variables.
- Do not start a regular expression with `=` (confusing with `/=` operator).
- Functions should not have multiple parameters with the same name.
- Classes should not have multiple members with the same name.
- Objects should not have multiple keys with the same name.
- If/else statements should not use the same condition.
- Switch statements should not have duplicate case conditions.
- Import statements should not have duplicate imports.
- Prefer using early return over if/else.
- Block statements should not be empty.
- Character classes in regular expressions should not be empty.
- Destructured values should not be empty.
- Static class blocks should not be empty.
- You should not use loose equality with `null`.
- You should not use `eval`.
- Do not reassign the error parameter in a catch block.
- Do not extend native prototypes.
- Do not call `bind` unnecessarily.
- Do not cast to a boolean in conditions.
- Do not use `continue` or `break` unnecessarily.
- All case statements should have a break statement.
- Do not reassign function declarations.
- Do not reassign global values (e.g. `window`).
- Do not use implicit coercion (e.g. `!!bool`, `+num`).
- Do not declare global variables. All values should be scoped to a module.
- Do not reassign to imported variables.
- Do not declare functions in logical blocks.
- Do not pass invalid regular expression strings to `RegExp()`.
- Do not use `this` outside of classes.
- Do not use unusual space characters.
- Do not access `__iterator__`.
- Do not use loop labels.
- Do not create unnecessary blocks.
- Do not nest `if` within `else`, use `else if`.
- Do not use multi-code characters (such as emotes) within character classes.
- Do not chain assignment operators.
- Do not use `\` to create multi-line strings. Use concatenation or template strings.
- `if` conditions should not be in the negative (e.g. `!bool`).
- Do not nest ternary statements.
- Do not use `new` outside of an assignment.
- Do not use `new` with `BigInt` or `Symbol`.
- Do not use `new` with `String`, `Number`, or `Boolean`.
- Do not use octal escapes (e.g. `\8`, `\2`).
- Do not call the `Math`, `JSON`, `Reflect`, `Atomics`, or `Intl` objects as functions or constructors.
- Do not call `new Object()` without an argument.
- Do not use octal literals e.g. `071`.
- Do not reassign function parameters.
- Do not use the `++` operator.
- Do not use `return` in promise executors.
- Do not use the `__proto__` property.
- Prefer calling the Object prototype over builtins (e.g. `Object.prototype.hasOwnProperty.call(foo, "bar")` over `foo.hasOwnProperty("bar")`).
- Do not use literal spaces in regular expressions, use the escape sequence `\s`.
- Do not return assignment operations.
- Do not use `javascript:void` URLs.
- Do not assign a variable to itself.
- Do not compare a variable with itself.
- Do not use the comma operator to evaluate multiple expressions.
- Setters should not return a value.
- Do not allow sparse arrays.
- Do not use `${foo}` template interpolation in regular strings.
- Do not reference `this` before calling `super` in constructors that call `super`.
- Do not reference variables that are not declared.
- Do not initialise variables to `undefined`.
- With the exception of trailing underscores for unused variables, do not use dangling underscores.
- Do not insert line breaks in confusing locations, such as the middle of a variable assignment.
- Do not use a variable in a loop condition that is not modified within the loop.
- Do not use a ternary if a simpler approach exists.
- There should be no unreachable code.
- Do not use control statements in `finally` blocks.
- You must use parentheses when negating `in` or `instanceOf`, e.g. `if (!(key in obj))`.
- Do not use optional chaining where an undefined value is not allowed.
- Do not declare private class members that are not consumed by the class.
- Do not declare variables that are unused.
- Avoid backreferences in regular expressions when they would match nothing.
- Do not use `.call()` or `.apply()` unnecessarily.
- `catch` statements should _handle_ an error, not turn around and throw the error.
- Do not use computed-key syntax for literal keys e.g. `{["a"]: "b"}`.
- Do not concatenate string literals without variables.
- Do not escape characters unnecessarily.
- Do not rename a reference to the same name e.g. `let { a: a } = b;`.
- Do not use redundant `return` statements.
- No use of the `var` keyword.
- Do not merge `TODO` or `FIX` comments into the main branch.
- Do not use the `with` statement.
- An object must use either all long-form definitions `{a : a}` or all short-form definitions `{ a }`, but never a mix of the two `{ a, b: c}`.
- Avoid shorthand operators `+=`, prefer the explicit `x = x + y`.
- Callback functions should be anonymous arrow functions.
- Use `const` for all variables that are not reassigned.
- Capture groups should be named.
- Prefer `Object.hasOwn()`.
- Prefer the spread operator over `Object.assign`.
- Prefer regular expression literals over the RegExp constructor.
- Prefer using the `...` operator instead of `arguments`.
- Prefer the spread operator over `.apply()`.
- Prefer template literals over string concatenation.
- `parseInt()` should always be given a radix.
- When an asynchronous function relies on an argument that might change (such as an object reference), care must be taken to avoid race conditions within that function.
- Generator functions must use the `yield` keyword.
- Object keys must be sorted alphabetically.
- Variables within the same declaration block must be sorted alphabetically.
- If using the `Symbol` function, you must include a description.
- Do not compare to `NaN`, use `Number.isNaN()`.
- `typeof` comparators must be a valid return type of `typeof`.
- Conditions should always start with the variable, not the constant.

#### 3.1.2. TypeScript-ESLint Enforced Rules

- Do not use `await` on functions that do not return a Promise.
- Exported type definitions should use the `export type` keyword.
- Use dot notation for property access, unless such syntax would be invalid.
- Do not use the `delete` keyword with arrays.
- Do not use `<Object>.toString()` on objects. Prefer `JSON.stringify()`.
- Do not assign void values to variables, such as `const log = console.log("Bad");`.
- Do not duplicate types (e.g. `type myType = "A" | "A"`).
- Promises should always be awaited.
- Do not implicitly evaluate code, such as with `new Function()`.
- Do not use `void` with functions that do not return a value.
- Do not use Promises in places that do not consume them (such as callbacks).
- Do not combine string and number values in an enum.
- Do not use unions/intersections with overriding values (such as `any` or `unknown`).
- Do not use comparison operators with boolean values (e.g. `variable === false`).
- Do not pass values to a conditional statement that are always truthy or falsy.
- Do not use unnecessary namespace references.
- Do not use template strings without interpolated values.
- Do not pass type arguments to a function that match the default value of that parameter.
- Do not define unused type parameters in a function.
- Values with an `any` type should not be passed to function calls.
- Values with an `any` type should not be assigned to variables.
- Values which have an `any` type should not be called as functions.
- Do not merge declarations (instead of `interface Foo` and `class Foo`, use `interface Foo` and `class Bar implements Foo`).
- Do not compare enum values against arbitrary values.
- Do not use the `Function` type. Functions should have a specific type signature.
- Values with an `any` type cannot have properties, and such properties should not be accessed.
- Functions should not return an `any` value.
- The unary minus operator should only be used on numbers.
- `throw` statements should only throw an `Error` instance.
- Object properties should be destructured, rather than assigned to variables via direct access.
- Use `<Array>.find()` instead of `<Array>.filter()[0]` to find an element in an array.
- Use `<Array>.includes()` instead of `<Array>.indexOf() === -1`.
- Use `??` instead of `||`.
- Use optional chaining when possible.
- Promises that reject should always return an Error.
- Class members that are not modified outside of the constructor should be `readonly`.
- The `.reduce()` callback should have typed parameters.
- When using a non-global regular expression, use `<RegExp>.exec` over `<String>.match()`.
- Class methods that return `this` should have `this` as the return type, not the class.
- When testing the beginning or end of a string, use `<String>.startsWith()` or `<String>.endsWith()`.
- Functions which return a Promise must use the `async` keyword.
- `<Array>.sort()` should always be given a compare function.
- `async` functions must use `await`, or be rewritten without the promise.
- The `+` operator can only be used with operands of the same type.
- Values interpolated in a template string must be of type `string`.
- Functions which return a promise should await that return value.
- Conditions should not use nullable values - you must always explicitly compare against `null` or `undefined`.
- Switch statements are not preferred, but when you must use them it should have exhaustive cases.
- Unbound class methods must be called with the expected scope (e.g. `myClass.method.bind(myClass)`).
- The `error` parameter in a catch statement is of type `unknown`.
- Function overload signatures must be grouped together.
- Array type definitions should use the generic `Array<T>` over `T[]`.
- `@ts` directives are disallowed, except for `@ts-expect-error` which requires a description.
- Classes with static public properties should have a getter for each property.
- Class methods which are not static must make use of `this` or be converted to static.
- Prefer passing type arguments to a constructor instead of a type annotation.
- Prefer `Record<string, T>` over `{ [key: string]: T}`.
- Do not use any type assertions (`x as T`).
- Object types should be defined with `interface` over `type`.
- Imported values which are only used as types should be imported with `type`.
- Function parameters which are optional or have a default value should come after all mandatory parameters.
- Functions should always have an explicit return type.
- All class members should have an accessibility modifier (`public`, `protected`, `private`).
- All exported functions and public class methods should have explicit parameter and return types.
- Variables should always be initialised with a value.
- Functions which take more than three arguments should take a single object instead.
- Class members should be ordered as `constructor`, `fields`, `statics`, `getters`, `setters`, then `methods`.
- Method types should use the property signature `func: (arg: string) => string`.
- Variables should use `camelCase`, types and classes should use `PascalCase`. Only variables may use a leading underscore to indicate they are unused.
- Never use the `Array` constructor.
- Do not use non-null assertions.
- Enums should not have duplicate values.
- Do not use the `delete` operator on dynamic property accesses.
- Functions, interfaces, and object types should never be empty.
- Do not use `any`.
- Classes should not consist solely of static members.
- The `for...in` loop should not be used.
- When all imported members are type imports, use `import type { a, b }` over `import { type a, type b }`.
- Do not use type annotations for variables with a string, number, or boolean value. These can be inferred.
- The `void` type should only be used as the _sole_ return type of a function. `(): void | string` is invalid.
- Do not reference unsafe values in a loop.
- Do not use number literals which would lose precision due to memory constraints.
- Classes should use `constructor()`, not `new()`. Interfaces for the class should use `new()`, not `constructor()`.
- Do not use namespaces.
- Do not use `require()`.
- Do not declare variables in an inner scope that share a name with a variable in the outer scope.
- Do not alias `this`.
- Do not needlessly assign constructor parameters to class members of the same name.
- Do not `extends` `any` or `unknown`.
- Unused expressions should be removed.
- Unused variables should be removed.
- Do not access a variable before its definition.
- Do not define empty constructors.
- Do not define empty exports.
- Do not use wrapper types (e.g. use `boolean`, not `Boolean`).
- Use `as const` over literal types.
- Enum values should always be explicitly initialised.
- The `for...of` loop should be used over the `for` loop, when the index _value_ is not needed.
- Enum values should always be literal values.
- Do not use TypeScript's `///` reference.
- Do not use overloads when the same result can be achieved via union types or optional parameters.

#### 3.1.3. ESLint-Comments Enforced Rules

- Do not use blanket `eslint-disable` directives. All `disable` directives must target specific rules.
- All `disable` directives must include a comment explaining why the linter is being bypassed.

#### 3.1.4. Deprecation Enforced Rules

- Do not use deprecated methods/features, even if the package still supports them.

#### 3.1.5. Import Enforced Rules

- Do not use default imports if the module does not have a default export.
- Do not import modules simply to re-export them.
- Exports should always be at the end of the file.
- With the exception of packages, imports should always have a file extension.
- Imports should always be at the beginning of the file.
- If a module has multiple named exports, group them in a single `export { a, b }` declaration.
- Import statements should be followed by a newline.
- Import paths should never be absolute
- You should not use AMD syntax
- You should not use CJS syntax
- You should not define cyclical imports (if file a imports file b, file b CANNOT import file a)
- Modules should not use a default export.
- A module should not import the same file multiple times.
- You should not use dynamic `require` calls.
- Named import blocks cannot be empty.
- You should not import packages that are not included in the `package.json` file.
- You cannot `import` a CommonJS module.
- Exports must always be declared with `const`.
- You cannot use a named export as the default export.
- You cannot use a named export as the property of a default export.
- You should not have orphaned modules (modules without any exports, or a module which is never imported).
- You cannot use webpack loader syntax.
- Imports must be sorted alphabetically, first grouped by: builtin node modules, external packages, internal packages, modules in parent directory, modules in current directory, type-only imports.
  - There should be no new lines between these groups.

#### 3.1.6. JSDoc Enforced Rules

- `@access` tags should be one of `package`, `private`, `protected`, or `public`.
- Asterisks should be aligned.
- Lines should not be improperly indented.
- `@param` names should reflect the actual parameters.
- `@property` names should reflect the actual properties.
- Should not use `=` (GCC syntax).
- All tags must be valid JSDoc tags.
- `@template` names should be used in the `@typedef`.
- `@license` tag MUST be set to `Naomi's Public Licence`.
- Tags that do not expect content should not have content.
- `@implements` should only be used on constructors or classes.
- Tag descriptions should not be just a reflection of the name.
- Description tags must be complete sentences.
- JSDocs must be multiple lines. The first and last line cannot have text content.
- JSDoc syntax must be valid.
- JSDocs must have a description.
- JSDocs cannot be empty.
- A hyphen should separate the parameter name from the description.
- JSDocs are required on all public functions, classes, and methods. They are encouraged on all public exports.
- Parameters must have a name and description.
- Properties must have a name and description.
- If a function returns a value, it must be documented in `@returns`.
- If a function throws an unhandled error intentionally, it must be documented in `@throws`.
- If a generator yields a value, it must be documented in `@yields`.
- Tags must be sorted alphabetically.
- There should be no blank lines between tags.
- Any types referenced must be valid types.

#### 3.1.7. Unicorn Enforced Rules

- Regular expressions should use special shorthand where possible.
- `catch` blocks should always have `error` as the parameter.
- When destructuring an object, all consumed properties should be destructured. Do not perform direct property access on an object that is previously destructured.
- When spreading a ternary in an array, both sides of the expression must be of the same type.
- Functions should be declared in the highest scope possible.
- `Error()` constructor calls must always be given a message.
- Escape sequences must use uppercase text.
- Files should be named in camelCase.
- Do not pass function references as callbacks to array methods.
- Do not use `.forEach()`.
- Do not use `this` in array methods.
- Do not chain `.push()` calls.
- Do not use `.reduce()`.
- Do not access properties directly from an `await` expression.
- Do not use `await` in Promise methods such as `.all()`.
- Files should not be empty.
- Do not use a `for` loop when you can use a `for...of` loop.
- Use Unicode escape sequences over hexadecimal escape sequences.
- Use `Array.isArray()` over `instanceof Array`.
- `GET` or `HEAD` requests should never have a body.
- Do not declare variables that start with `new` or `class`.
- Do not use `.length` as the argument to `.slice()`.
- Use `Buffer.from()`, not `new Buffer()`.
- Do not use objects as default parameters.
- Do not pass single-element arrays to Promise methods.
- Do not define a class that only has static members.
- Do not use `.then()`.
- Do not assign to `this`.
- Do not use `typeof x === "undefined"`.
- `await` cannot be used on non-promise values.
- You cannot ignore consecutive values when destructuring an array, e.g. `[,,,, val]`.
- You cannot use IIFEs.
- Promises should not return `.resolve()` or `.reject()`.
- You should not spread an array into a new array without adding values.
- You should not associate any case statements with the default statement.
- Number literals cannot have trailing zeroes after the decimal place.
- Number literals must use proper case.
- Numbers over 9999 should use `_` to separate each group of three digits, e.g. `10_000`.
- If you need to flatten an array, use `Array.flat()`.
- Prefer `.flatMap()` over `.map().flat()`.
- Prefer `indexOf` over `findIndex`.
- Prefer `.some()` over `.filter().length`.
- Prefer `.at()` for accessing array and string indices.
- Prefer `.codePointAt()` over `.charCodeAt()`.
- Prefer `Date.now()` over `new Date().getTime()`.
- Use default parameters instead of reassigning undefined values.
- Use `Math.trunc` to round numbers, not bitwise operators.
- Use ESM modules, not CJS.
- Use coercion functions such as `String()` directly.
- Use a negative index instead of `.legnth - 1`.
- Use the `node:` protocol when importing built-in packages.
- Use `Number` properties instead of global helpers e.g. `Number.isNaN()` over `isNaN()`.
- Use `Object.fromEntries` to create an object from key-value pairs.
- If a `catch` block does not use the `error` parameter, the parameter should be omitted.
- Prefer calling prototype methods over instance methods.
- Prefer using `Set.has()` over `Array.includes` to check for existence.
- Prefer using `Set.size` over `Array.length`.
- Prefer using the spread operator over `Array.concat()` or `String.split("")`.
- Prefer using `String.replaceAll()` over regex searches.
- Prefer `String.slice()` over `String.substr[ing]()`.
- Prefer `String.startsWith()` or `.endsWith()` over `RegExp.test()`.
- Prefer `String.trim[Start|End]()` over `String.trim[Left|Right]()`.
- Use `structuredClone` to create a deep clone of an object.
- Use top-level await instead of IIFEs.
- Variable names should not be abbreviated.
- `Array.join()` must always be given a separator.
- `Number.toFixed()` must always be given a digits argument.

### 3.2. React Rules

These rules apply to TSX, and will run on files in `src/**/*.tsx`.

- Boolean properties should be named accordingly, such as `isEnabled` instead of `enabled`.
- Buttons must always have a `type` attribute.
- If a radio button or checkbox is checked, it must be `readonly` or have an `onChange` handler.
- Default properties should match the property types.
- Properties, state, and context should always be destructured.
- Components must always have a name.
- A component cannot consume another component's propTypes.
- PropTypes cannot use `any`, `array`, or `object`.
- `forwardRef` components must use `ref`.
- Components should always be defined as named arrow functions.
- State should have matching names, e.g. `[color, setColor]`.
- `iframes` should always use the `sandbox` attribute.
- Boolean properties should always be explicitly written: `<Component prop={true}>`.
- Spaces between JSX elements must be explicitly written: `{' '}`.
- Files that contain JSX must have the extension `.jsx` or `.tsx`.
- Fragments should always use the shorthand syntax.
- Event handlers must be appropriately named: `onChange={this.handleChange}`
- Iterators must always have a `key` prop, and it should never be the index.
- You should not use `.bind()` in component props
- You should not insert comments as text nodes.
- Contexts should not use mutable values (e.g. objects), to prevent re-renders.
- Components should not have duplicate properties.
- Avoid leaking conditional values. Prefer `condition ? <Component> : null` over `condition && <Component>`.
- Element text should always be wrapped in JSX containers.
- You should never use `javascript:` urls.
- `target=_blank` must always be accompanied with `rel=noreferrer`.
- You should not use variables that are not declared.
- You should not use fragments unless there is no singular wrapping element.
- Components should use PascalCase.
- You should not spread props multiple times.
- Props should be sorted alphabetically.
- You should not access `this.state` inside any `setState` functions.
- You should not use arrow functions for lifecycle methods.
- Children cannot be passed as props.
- You cannot use dangerous properties (`dangerouslySetInnerHTML`).
- You cannot use deprecated methods.
- You cannot use `setState` in `componentDidMount` or `componentDidUpdate` or `componentWillUpdate`.
- You cannot directly mutate `this.state`.
- You cannot use `findDOMNode`.
- You cannot use `isMounted`.
- Each file should have only one component.
- `ReactDOM.render`'s return value should not be used.
- You should not use string references.
- `this` cannot be used in stateless functional components.
- HTML entities must be escaped.
- You cannot use unknown HTML properties.
- You cannot use unsafe lifecycle methods.
- You cannot define a component within another component.
- Class components should not have unused methods.
- Components should not have unused propTypes or state
- Class components should use the ES6 `class Component extends React.Component` syntax.
- Props should be readonly.
- Stateless components should be pure functions.
- Property accesses must be reflected in the propTypes.
- Any optional property must have a default value.
- Classes using the `render` method MUST return a value.
- Components without children must still have a separate closing tag.
- State initialisation must always happen in the constructor.
- Static properties should be defined as `static name = `.
- The `style` property must always be an object.
- Void elements `img`, `br` etc. must never have children.

### 3.3. Playwright Rules

These files apply to Playwright End-to-end tests, and will run on `e2e/**/*.spec.ts`.

- All tests must have at least one `expect` assertion.
- `describe` calls cannot be nested more than two levels deep.
- Playwright APIs must be `await`ed.
- Tests cannot be commented out.
- `expect` cannot be called conditionally.
- Tests cannot contain conditional logic.
- Setup and teardown hooks cannot be duplicated.
- You cannot use element handles (`page.$`).
- You cannot use `page.$eval()`.
- Tests cannot be focused with `.only()`.
- Tests cannot be forced with `{ force: true }`.
- You cannot use `getByTitle()`.
- You cannot use the `networkidle` option.
- You cannot use `first()`, `lat()`, or `nth()`.
- You cannot use `page.pause()`.
- You cannot use `page.locator()`. Prefer specific methods like `page.getByRole()`.
- Tests cannot be skipped with `.skip()`.
- `expect` can only be called within test blocks.
- You cannot reference variables in `page.evaluate()`.
- Some Playwright methods are synchronous - these cannot be `await`ed.
- You cannot use `.not()` when a specific matcher exists.
- You cannot use `page.waitForSelector()` or `page.waitForTimeout()`.
- Prefer `.toBeGreaterThan()` over `(x > 5).toBe(true)`.
- Prefer `.toBe(5)` over `(x === 5).toBe(true)`
- Hooks should be ordered as Playwright calls them: `beforeAll`, `beforeEach`, `afterEach`, `afterAll`.
- Hooks should be at the top of the test.
- Test names should be lowercase.
- Use `.toStrictEqual()` over `.toEqual()`.
- Use `.toBe()` over `.toStrictEqual()` for primitive values.
- Use `.toContain()` over `.includes()`.
- Use `.toHaveCount()` over `locator.count()` and `.toHaveLength()` over `.length`.
- Prefer assertions like `.toBeVisible()` over `(locator.isVisible()).toBe(true)`.
- Setup and teardown code must be in a hook.
- `.toThrow()` assertions require a message.
- Tests must be within a `describe` block.
- All `expect()` calls must have a custom message.
- Promises that contain an `expect` must be awaited.
- Tests must have a title that is not empty.

### 3.4. Vitest Rules

These files apply to Vitest unit tests, and will run on `test/**/*.spec.ts`.

:::warn
We also mandate the use of `describe`, `it`, and `expect` over `suite`, `test`, and `assert`.
:::

- Files must have `.spec.ts` extension.
- consistent-test-it
- Tests must have at least one `expect`.
- `describe` calls cannot be nested more than two levels deep.
- Prefer `.toHaveBeenCalled()` over `.toBeCalled()`.
- Tests cannot be commented out.
- `expect` cannot be called conditionally.
- Tests cannot contain conditional logic.
- Tests cannot be run conditionally.
- Tests cannot be disabled.
- You cannot use the `done()` callback.
- Setup and teardown hooks cannot be duplicated.
- Tests cannot be focused with `.only()`.
- Test titles must be unique.
- `node:test` cannot be imported.
- Snapshots cannot use string interpolation.
- `expect` must be within `it` or `test`.
- Tests cannot use `return`.
- Prefer `toHaveBeenCalledWith()` over `toHaveBeenCalled()`.
- Prefer `.toBeGreaterThan()` over `(x > 5).toBe(true)`.
- Use `describe.each` instead of manual loops.
- Prefer `.toBe(5)` over `(x === 5).toBe(true)`.
- All tests must start with `expect.assertions(number)`.
- Use `expect.resolves(fn)` over `expect(await fn)`.
- Hooks should be ordered as Vitest calls them: `beforeAll`, `beforeEach`, `afterEach`, `afterAll`.
- Hooks should be at the top of the test.
- Test titles should be lowercase.
- Prefer `vi.fn().mockResolvedValue(val)` over `vi.fn().mockImplementation(() => Promise.resolve(val))`.
- Prefer `vi.spyOn(Date, "now")` instead of overwriting the global `Date.now = vi.fn()`.
- Use `.toStrictEqual()` over `.toEqual()`.
- Use `.toBe()` over `.toStrictEqual()` for primitive values.
- Use `.toBeFalsy()` over `.toBe(false)`.
- Use `.toBeObject()` over `.toBeInstanceOf(Object)`.
- Use `.toBeTruthy()` over `.toBe(true)`.
- Use `.toContain()` over `.includes()`.
- Use `.toHaveLength()` over `.length`.
- Use `test.todo()` instead of `test.skip()`.
- Setup and teardown code must be in a hook.
- `.toThrow()` assertions require a message.
- Tests must be within a `describe` block.
- The `describe` callback should not have any parameters and cannot use `return`.
- All `expect()` calls must have a custom message.
- Tests must have a title that is not empty.

## 4. LIMITATION OF LIABILITY AND DISCLAIMERS

### 4.1. Reference to Comprehensive Liability Framework

**IMPORTANT: Comprehensive liability limitations, damage exclusions, and maximum liability caps are set forth in our Limitation of Liability and Indemnification Policy, which is incorporated herein by reference.**

### 4.2. Style Guide Disclaimer

This Guide establishes mandatory standards for code contributions. However, compliance with this Guide does not guarantee acceptance of contributions. Project maintainers reserve the right to:

- Request modifications to code that complies with this Guide
- Reject contributions for reasons beyond style compliance
- Modify or update this Guide at any time without prior notice
- Interpret Guide requirements in specific contexts as necessary

### 4.3. Technical Accuracy Disclaimer

While we strive to maintain accurate and current information in this Guide, technical standards, tooling, and best practices evolve continuously. Contributors are responsible for:

- Verifying current tool versions and compatibility
- Ensuring their development environment matches project requirements
- Adapting to updates in this Guide as they are published
- Consulting project-specific documentation for additional requirements

## 5. CONCLUSION

This Style Guide represents our commitment to maintaining high-quality, consistent, and maintainable code across all projects. By adhering to these standards, contributors help ensure that our codebase remains accessible, professional, and aligned with industry best practices.

All contributors are expected to familiarise themselves with and comply with the requirements set forth in this Guide. Questions about specific requirements or requests for clarification should be directed to project maintainers through appropriate communication channels.

---

*For questions about style requirements or to suggest improvements, please contact project maintainers through the designated channels outlined in our Contributor Covenant.*
