diff --git a/src/foundations/about/page.mdx b/src/foundations/about/page.mdx index a6270e6c..8f613252 100644 --- a/src/foundations/about/page.mdx +++ b/src/foundations/about/page.mdx @@ -1,22 +1,22 @@ export const metadata = { title: "About", description: - "Foundations is an opinionated collection of components, patterns, and guidelines for building modern digital products", + "Foundations is an opinionated collection of components, patterns, and guidelines for building modern digital products.", }; ## What is Foundations? -Foundations is an opinionated collection of components, patterns, and guidelines for building modern digital products. While it includes a robust set of UI components, it goes far beyond basic interface elements to provide comprehensive resources for building complete digital experiences. +Foundations is an opinionated collection of components, patterns, and guidelines for building modern digital products. While it includes a robust set of UI components, it goes far beyond basic interface elements to provide comprehensive resources for creating complete digital experiences. -From web applications to marketing sites, Foundations covers everything from foundational UI components to advanced interaction patterns, state management strategies, content modeling, and performance optimizations. It's designed to help developers create high-quality digital products by providing well-documented, tested, and production-ready solutions. +From web applications to marketing sites, Foundations covers everything from foundational UI components to advanced interaction patterns, state management strategies, content modelling, and performance optimisations. It's designed to help developers create high-quality digital products by providing well-documented, tested, and production-ready solutions. ## How to use Foundations There are two main ways to use Foundations: -1. **Copy and Customize**: Take the components, patterns, or entire feature implementations you need and integrate them directly into your project. Each solution is designed to be self-contained and easily customizable. This approach gives you full control over the code and allows you to modify it to match your specific requirements. +1. **Copy and Customise**: Take the components, patterns, or entire feature implementations you need and integrate them directly into your project. Each solution is designed to be self-contained and easily customizable. This approach gives you full control over the code and allows you to modify it to match your specific requirements. -2. **Learning Resource**: Use Foundations as a reference and learning tool. Study our implementation patterns, from accessibility considerations in UI components to complex state management in applications, or content modeling for data-heavy products. This knowledge can help you build your own solutions from scratch with confidence. +2. **Learning Resource**: Use Foundations as a reference and learning tool. Study our implementation patterns, from accessibility considerations in UI components to complex state management in applications, or content modelling for data-heavy products. This knowledge can help you build your own solutions from scratch with confidence. ## Project context @@ -26,7 +26,7 @@ Foundations was created by [Significa](https://significa.co) as an internal reso - Bootstrap new projects with proven, production-ready solutions - Speed up development while maintaining high standards for user experience, accessibility, and performance - Share knowledge and promote good practices within our team -- Standardize our approach to common challenges in web development +- Standardise our approach to common challenges in web development While this is primarily an internal tool, we've made it open source to contribute to the developer community and share our learnings. @@ -36,7 +36,7 @@ Foundations draws inspiration from several excellent projects in the developer c - [shadcn/ui](https://ui.shadcn.com/): For its innovative approach to component distribution and documentation - [Lucia Auth](https://lucia-auth.com/): For its excellent documentation structure and learning resources -- Other similar projects that prioritize education and flexibility over traditional dependency-based solutions +- Other similar projects that prioritise education and flexibility over traditional dependency-based solutions However, we take a broader approach. While these projects focus on specific aspects of web development, Foundations aims to be a comprehensive resource covering the full spectrum of modern web development, from UI components to complete application architectures and beyond. @@ -45,7 +45,7 @@ What sets Foundations apart is our focus on: - Complete solutions over isolated components - Production-ready patterns over basic implementations - Real-world scenarios over simplified examples -- Documentation over dependencies +- Documentation on dependencies - Learning resources over black-box solutions - Flexibility over one-size-fits-all approaches @@ -53,10 +53,10 @@ What sets Foundations apart is our focus on: Unlike traditional libraries that you install as dependencies, Foundations takes a different approach: -- Solutions are meant to be copied and customized +- Solutions are meant to be copied and customised - Documentation explains not just what things do, but why and how they work - Code is written to be read and understood, not just used -- Best practices for accessibility, performance, and SEO are built-in, not afterthoughts +- Best practices for accessibility, performance, and SEO are built in, not afterthoughts - Patterns are based on real-world production use, not theoretical examples This approach means you're not tied to our update cycle, version constraints, or design decisions. You have full control over the code you use, while still benefiting from our years of experience building digital products. diff --git a/src/foundations/components/instance-counter/page.mdx b/src/foundations/components/instance-counter/page.mdx index b0624954..d783c1d8 100644 --- a/src/foundations/components/instance-counter/page.mdx +++ b/src/foundations/components/instance-counter/page.mdx @@ -44,4 +44,4 @@ Returns a `number` that represents the current index of the component within the ## Limitations -The indices are assigned based on the order of React's `useEffect` hook execution. While this generally matches the DOM order, if, for some reason, it does not, it may lead to unexpected behavior. +The indices are assigned based on the order of React's `useEffect` hook execution. While this generally matches the DOM order, if, for some reason, it does not, it may lead to unexpected behaviour. diff --git a/src/foundations/components/marquee/page.mdx b/src/foundations/components/marquee/page.mdx index 4a654f49..ec3ebd59 100644 --- a/src/foundations/components/marquee/page.mdx +++ b/src/foundations/components/marquee/page.mdx @@ -17,10 +17,10 @@ export const metadata = { ## Features -- **Native-Like Implementation**: Closely mirrors the behavior of the native (now deprecated) marquee element, including maintaining a single-element structure +- **Native-Like Implementation**: Closely mirrors the behaviour of the native (now deprecated) marquee element, including maintaining a single-element structure - **Dynamic Content Cloning**: Automatically creates the optimal number of content clones based on element size and content length - **Automatic Text Wrapping**: Text content is automatically wrapped in `` elements to ensure proper rendering with CSS transforms -- **Customizable Gap**: Supports flexible spacing between items using CSS gap property, allowing for consistent and adjustable spacing between content elements +- **Customizable Gap**: Supports flexible spacing between items using the CSS gap property, allowing for consistent and adjustable spacing between content elements - **Intersection Observer**: Pauses animation when not in viewport - **Flexible Duration Control**: Duration can be specified as: - A fixed number @@ -75,4 +75,4 @@ export const metadata = { ## Best Practices -**Avoid Media Without Dimensions**: when using images or videos in a marquee, always specify explicit `width` and `height` attributes. Without proper dimensions, the content may cause layout shifts as it loads, disrupting the smooth scrolling behavior. This is especially important since the marquee needs to calculate the total content length to determine scrolling speed and clone count. +**Avoid Media Without Dimensions**: When using images or videos in a marquee, always specify explicit `width` and `height` attributes. Without proper dimensions, the content may cause layout shifts as it loads, disrupting the smooth scrolling behaviour. This is especially important since the marquee needs to calculate the total content length to determine scrolling speed and clone count. diff --git a/src/foundations/components/sequence/page.mdx b/src/foundations/components/sequence/page.mdx index 51d0cd61..dac1e633 100644 --- a/src/foundations/components/sequence/page.mdx +++ b/src/foundations/components/sequence/page.mdx @@ -31,10 +31,10 @@ export const metadata = { ## Features - **Automatic Progression**: Items advance automatically based on configurable durations -- **Progress Indication**: Exposes a `--progress` css variable to show progression through each item, and a `--index` css variable to show the current index +- **Progress Indication**: Exposes a `--progress` CSS variable to show progression through each item, and a `--index` css variable to show the current index - **Keyboard Navigation**: Full keyboard support for manual navigation - **ARIA Support**: Full accessibility implementation with proper ARIA attributes -- **Unstyled**: No default styles, just the sequence behavior +- **Unstyled**: No default styles, just the sequence behaviour - **Intersection Observer**: Pauses progression when not in viewport ## Anatomy @@ -54,7 +54,7 @@ export const metadata = { ### Sequence -The root container component that manages the state and behavior of the sequence. +The root container component that manages the state and behaviour of the sequence. Warning: If you have custom components that use buttons instead of the native elements, you should ommit the `aria-errormessage` and `aria-invalid` attributes. See [Custom Selects](#custom-selects) below. +> Warning: If you have custom components that use buttons instead of the native elements, you should omit the `aria-errormessage` and `aria-invalid` attributes. See [Custom Selects](#custom-selects) below. ```tsx {2,4,5,9-13} showLineNumbers title="input.tsx" const Input = ({ invalid: propsInvalid, id, ...props }: InputProps) => { @@ -78,7 +78,7 @@ const Input = ({ invalid: propsInvalid, id, ...props }: InputProps) => { ### Custom Selects -If you are using a custom `Select` component that uses a button instead of a native select element, you should ommit the `aria-errormessage` and `aria-invalid` attributes as they're reserved for form elements that can have validation errors (such as `input`, `textarea` and `select`): +If you are using a custom `Select` component that uses a button instead of a native select element, you should omit the `aria-errormessage` and `aria-invalid` attributes as they're reserved for form elements that can have validation errors (such as `input`, `textarea` and `select`): ```tsx {2,4,8-10} showLineNumbers title="select.tsx" const SelectTrigger = ({ children, id, ...props }: SelectTriggerProps) => { @@ -101,7 +101,7 @@ const SelectTrigger = ({ children, id, ...props }: SelectTriggerProps) => { ### Radio and Radio Groups -Radio buttons are a bit special as they need to be grouped together, so the aria attributes should be set on the `RadioGroup` component instead: +Radio buttons are a bit special as they need to be grouped, so the aria attributes should be set on the `RadioGroup` component instead: ```tsx showLineNumbers title="radio-group.tsx" interface RadioGroupProps extends React.ComponentPropsWithRef<"div"> { @@ -150,7 +150,7 @@ Given that we'll have a nested structure, we'll also need some attributes on the ``` -We'll just add the `id` and `aria-describedby` attribute: +We'll just add the `id` and `aria-describedby` attributes: ```tsx {6,11,12} showLineNumbers const Radio = ({ @@ -220,9 +220,9 @@ export { Label }; ## Fieldset and Legend -A `fieldset` is an HTML element used to group related elements within a form, providing a semantic way to organize form controls. It is often used in conjunction with the `` element, which provides a caption for the group. +A `fieldset` is an HTML element used to group related elements within a form, providing a semantic way to organise form controls. It is often used in conjunction with the `` element, which provides a caption for the group. -This grouping not only helps with visual organization but also improves accessibility by allowing screen readers to understand the relationship between grouped elements. +This grouping not only helps with visual organisation but also improves accessibility by allowing screen readers to understand the relationship between grouped elements. Here we create a `Fieldset` component that will automatically register the `Legend` elements and expose them to the `Field` context. @@ -251,7 +251,7 @@ You can add a `FieldDescription` and `FieldError` to the `Field` component:
- This is a description very very long description + This is a very, very long description
diff --git a/src/foundations/guides/automated-tests/page.mdx b/src/foundations/guides/automated-tests/page.mdx index b37a891b..78e9bdeb 100644 --- a/src/foundations/guides/automated-tests/page.mdx +++ b/src/foundations/guides/automated-tests/page.mdx @@ -1,6 +1,6 @@ export const metadata = { title: "Automated tests", - description: "How to make it easy to setup automated tests with Playwright", + description: "How to make it easy to set up automated tests with Playwright", }; ## Overview @@ -15,13 +15,13 @@ I'm sure you are probably wondering why Playwright? _Hold on to your horses!_ Playwright is known for its robust API, parallel execution, and ability to handle complex scenarios like network mocking, authentication, and visual testing. -But enough of the big words, well what I am trying to say is: +But enough of the big words, well, what we are trying to say is: -- its easier to use, -- it has simpler ways to integrate -- it has the best auto-waiting feature, unlike some others that I won't name (CYPRESS!!! πŸ˜†) -- you can run multiple tests in parallel (completely independent of each other) -- overall its pretty cool +- It's easier to use, +- It has simpler ways to integrate +- It has the best auto-waiting feature, unlike some others that I won't name (CYPRESS!!! πŸ˜†) +- You can run multiple tests in parallel (completely independent of each other) +- Overall, it's pretty cool! ### Why a guide? @@ -42,7 +42,7 @@ Check https://playwright.dev/docs/running-tests for other flags ### What's Installed? -Playwright will download the browsers needed as well as create the following files. +Playwright will download all the necessary browsers and create the following files. ``` playwright.config.ts @@ -146,9 +146,9 @@ export default defineConfig({ ### Some points to note: - Retries & Workers should be limited to 2 or lower on the CI to improve the efficiency of the tests -- Default timeout is 30s for each test case, this can be increased as you see fit but be mindful of the time so that the test execution do not take too long -- Reports generated locally should be separated from the ci reports -- webServer is setup so that before the Playwright CI runs the test script the page is served, this should be modified to suit the project +- Default timeout is 30s for each test case. This can be increased as you see fit, but be mindful of the time so that the test execution does not take too long +- Reports generated locally should be separated from the CI reports +- webServer is set up so that before the Playwright CI runs the test script, the page is served; this should be modified to suit the project - Remember to add the following generated files to .gitignore, .eslintignore && .prettierignore ``` @@ -256,7 +256,7 @@ test.describe("shop the look card works", () => { ### Debug tests in UI mode -Asides from using `console.log` and `debugger`, Playwright UI mode offer a better debugging experience, where you can easily walk through each step of the test and visually see what was happening before, during and after each step. +Aside from using `console.log` and `debugger`, Playwright UI mode offers a better debugging experience, where you can easily walk through each step of the test and visually see what was happening before, during and after each step. ### Debug tests with the Playwright Inspector @@ -267,9 +267,9 @@ Or, press the play button to run your test from start to finish. Once the test h ### Debug tests with VSCode extension -With the VS Code extension you can debug your tests right in VS Code, see error messages, set breakpoints and step through your tests. +With the VS Code extension, you can debug your tests right in VS Code, see error messages, set breakpoints and step through your tests. -You can also debug in live mode with the VSCode extension or right click and select debug test (Just install the VSCode extension for better experience). +You can also debug in live mode with the VSCode extension or right-click and select debug test (Just install the VSCode extension for a better experience). ### Enable Tracing for Debugging Failed Tests @@ -283,9 +283,9 @@ Playwright provides a built-in test generator that records user actions and conv There are two ways to use it: -- install the VS Code extension and generate tests directly from VS Code. The extension is available on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) +- Install the VS Code extension and generate tests directly from VS Code. The extension is available on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) This opens a browser where interactions are recorded and transformed into a Playwright script. -- use codegen to generate locators: run `npx playwright codegen playwright.dev` replace playwright.dev with the url of the page you want to pick a locator from +- Use codegen to generate locators: run `npx playwright codegen playwright.dev` replace playwright.dev with the url of the page you want to pick a locator from This is good to get you started on your tests. @@ -315,7 +315,7 @@ When dealing with elements that load asynchronously, follow these strategies: #### Consistent Locators - Prefer `getByRole()`, `getByText()`, and `getByLabel()` for better test resilience. -- Avoid relying on css or xpath selectors when semantic roles are available. +- Avoid relying on CSS or XPath selectors when semantic roles are available. #### Improved Test Stability @@ -324,23 +324,23 @@ When dealing with elements that load asynchronously, follow these strategies: ### Key Points -- Use user-facing locators like `getByRole`, `getByText`, and `getByLabel` instead of CSS selectors because your DOM can easily change and this can lead to failed tests. -- Leverage web first assertions like `toBeVisible`, `toHaveValue`, `toHaveText` etc. Playwright automatically retries these assertions, with a default timeout of 5 seconds.. -- Focus on user-visible behavior (i.e. test things that real users interact with like color, texts, UI elements etc) +- Use user-facing locators like `getByRole`, `getByText`, and `getByLabel` instead of CSS selectors because your DOM can easily change, and this can lead to failed tests. +- Leverage web-first assertions like `toBeVisible`, `toHaveValue`, `toHaveText`, etc. Playwright automatically retries these assertions, with a default timeout of 5 seconds.. +- Focus on user-visible behaviour (i.e. test things that real users interact with, like colour, texts, UI elements, etc) - Keep tests independent and stateless to reduce flakiness and improve reliability. -- Use `beforeEach` and `afterEach` for setup/teardown for example, if multiple test cases require the same page, use `beforeEach` to navigate to it, ensuring a fresh context for every test.. +- Use `beforeEach` and `afterEach` for setup/teardown. For example, if multiple test cases require the same page, use `beforeEach` to navigate to it, ensuring a fresh context for every test.. - Chain and filter locators to precisely target elements instead of selecting broad areas of the page. - Take advantage of test generators to speed up test creation - Run tests in parallel to speed up execution. - Test across all supported browsers to ensure cross-browser compatibility. -- Centralize configuration in `playwright.config.ts` to maintain consistency across test runs. +- Centralise configuration in `playwright.config.ts` to maintain consistency across test runs. -Pheew! thats a lot of do's and don'ts, but depending on your use case, these guidelines can be adjusted to fit the needs of your tests. After all, Playwright gives you the flexibility to make testing work your way! πŸš€. +Pheew! That's a lot of dos and don'ts, but depending on your use case, these guidelines can be adjusted to fit the needs of your tests. After all, Playwright gives you the flexibility to make testing work your way! πŸš€. ## Test Reports Playwright provides built-in reporting capabilities. -Run `npx playwright show-report` to view the report. This will generate a report by default a html page in playwright-report folder. +Run `npx playwright show-report` to view the report. This will generate a report by default as an HTML page in the playwright-report folder. Check https://playwright.dev/docs/test-reporters for more information @@ -351,8 +351,8 @@ To ensure test reports are accessible: ### Serve from public/ Directory -Update your CI/CD with the snippet below just after the Run Playwright tests to move the playwright test reports to the public folder. -Next.js automatically serves static files from the public folder, so if you move it there it should be accessible +Update your CI/CD with the snippet below, just after the Run Playwright tests, to move the Playwright test reports to the public folder. +Next.js automatically serves static files from the public folder, so if you move it there, it should be accessible ``` - name: Move Playwright report to public directory @@ -391,9 +391,9 @@ export default async function handler( ## Continuous Integration (CI) -When installing Playwright using the VS Code extension or with npm init playwright@latest you are given the option to add a GitHub Actions workflow. +When installing Playwright using the VS Code extension or with npm init playwright@latest, you are given the option to add a GitHub Actions workflow. This creates a `playwright.yaml` file inside a `.github/workflows` folder containing everything you need so that your tests run on each push and pull request into the main/master branch. -After a few modifications here's an example for a SvelteKit app on vercel: +After a few modifications, here's an example for a SvelteKit app on Vercel: ``` name: Playwright Tests @@ -452,7 +452,7 @@ jobs: ### The workflow performs these steps: -1. Run on a schedule (in the example above it runs on every wednesdays 00:00 UTC) +1. Run on a schedule (in the example above, it runs on every Wednesday 00:00 UTC) 2. Clone your repository 3. Install Node.js 4. Install NPM Dependencies @@ -461,8 +461,8 @@ jobs: 7. Build Application 8. Run Playwright tests 9. Add the playwright report to the current build -10. Deploy project with the new reports -11. Upload the report (artifact) to the GitHub UI for a period of 30 days +10. Deploy the project with the new reports +11. Upload the report (artefact) to the GitHub UI for a period of 30 days ### Why are we running the Playwright CI on a schedule? diff --git a/src/foundations/guides/hierarchical-selection/page.mdx b/src/foundations/guides/hierarchical-selection/page.mdx index 0defada7..99815c1b 100644 --- a/src/foundations/guides/hierarchical-selection/page.mdx +++ b/src/foundations/guides/hierarchical-selection/page.mdx @@ -35,7 +35,7 @@ interface HierarchicalItem { ### Selection Logic -The key behaviors in hierarchical selection are: +The key behaviours in hierarchical selection are: 1. **Parent Selection**: Selecting a parent selects all enabled children 2. **Child Selection**: When all children are selected, the parent becomes selected @@ -117,7 +117,7 @@ const data: HierarchicalItem[] = [ ]; ``` -### Step 2: Initialize the Hook +### Step 2: Initialise the Hook Set up the selection hook with your desired options: @@ -275,7 +275,7 @@ function HierarchicalField({ value, onChange, data, error }) { ### Performance -- **Memoize filtered data**: Use `useMemo` for filtered results in search +- **Memorise filtered data**: Use `useMemo` for filtered results in search - **Debounce search**: Prevent excessive filtering on every keystroke - **Virtualize large lists**: Consider virtualization for hundreds of items - **Lazy load children**: Load child data on demand for large datasets diff --git a/src/foundations/guides/performance-tracking/page.mdx b/src/foundations/guides/performance-tracking/page.mdx index 6960d98a..611ed803 100644 --- a/src/foundations/guides/performance-tracking/page.mdx +++ b/src/foundations/guides/performance-tracking/page.mdx @@ -1,5 +1,5 @@ export const metadata = { - title: "Performance tracking & bundle analyzer", + title: "Performance tracking & bundle analyser", description: "A comprehensive guide to setting up performance tracking and bundle analysis for Next.js applications", }; @@ -9,7 +9,7 @@ export const metadata = { Monitoring web application performance is crucial for delivering an optimal user experience. This guide will walk you through setting up performance tracking and bundle analysis tools for your Next.js application. These tools will help you: - Track and measure performance metrics -- Analyze your JavaScript bundles +- Analyse your JavaScript bundles - Establish performance budgets - Integrate performance checks into your CI pipeline @@ -29,35 +29,35 @@ By following this guide, you'll establish a robust performance monitoring system ### Installing Required Packages **First, let's install the necessary dependencies.** -We'll need Lighthouse CI for performance testing and `@next/bundle-analyzer` for bundle analysis. Although there are other bundle analyzers you can use depending on the frameworks' bundler (i.e. webpack or vite), other top-notch examples are rollup-plugin-visualizer and webpack-bundle-analyzer. +We'll need Lighthouse CI for performance testing and `@next/bundle-analyser` for bundle analysis. Although there are other bundle analysers you can use depending on the frameworks' bundler (i.e. webpack or Vite), other top-notch examples are rollup-plugin-visualizer and webpack-bundle-analyzer. For this example we are using Next.js (i.e `@next/bundle-analyzer` and `@lhci/cli`) ``` # Install Lighthouse CI npm install -D @lhci/cli -# Install Next.js Bundle Analyzer -npm install -D @next/bundle-analyzer +# Install Next.js Bundle Analyser +npm install -D @next/bundle-analyser ``` -`@next/bundle-analyzer` is used to create a visual representation of the breakdown of your app's bundle, this can give insights on what affects your application (especially external libraries) on first load. It also helps differentiates between initial load and lazy-loaded chunks. -`@lhci/cli` is a library from the Google's lighthouse tool we are familiar with on chrome web browser, and it helps provide insights on the performance of your app with the same metrics you see when you use it on chrome devtools. Lets call it automated performance tracker. +`@next/bundle-analyzer` is used to create a visual representation of the breakdown of your app's bundle. This can give insights into what affects your application (especially external libraries) on first load. It also helps differentiate between initial load and lazy-loaded chunks. +`@lhci/cli` is a library from Google's Lighthouse tool we are familiar with on Chrome web browser, and it helps provide insights on the performance of your app with the same metrics you see when you use it on Chrome DevTools. Let's call it an automated performance tracker. ### What's Installed? (i.e. files added during installation) After installation, you'll need to create the following files: - lighthouserc.js: Configuration file for Lighthouse CI -- next.config.js (modified): Updated Next.js configuration to include the bundle analyzer +- next.config.js (modified): Updated Next.js configuration to include the bundle analyser - .github/workflows/lighthouse.yaml (optional): GitHub Actions workflow for CI integration Let's look at each of these files in detail. ## Configuration -### Next.js Bundle Analyzer Configuration +### Next.js Bundle Analyser Configuration -First, let's set up the bundle analyzer by modifying the `next.config.js` file: +First, let's set up the bundle analyser by modifying the `next.config.js` file: ```js title="next.config.js" // next.config.js @@ -73,7 +73,7 @@ const nextConfig = { module.exports = withBundleAnalyzer(nextConfig); ``` -With this configuration, you can run the bundle analyzer using: +With this configuration, you can run the bundle analyser using: ``` ANALYZE=true npm run build @@ -83,7 +83,7 @@ ANALYZE=true npm run build Now, let's set up Lighthouse CI. Create a `.lighthouserc.js` file in your project root: -There are two options to track the performance of your app and this will affect your configuration +There are two options to track the performance of your app, and this will affect your configuration ### OPTION 1: Delta-based Approach (Compare with Previous Scores) @@ -128,7 +128,7 @@ module.exports = { maxDelta: -0.05, }, ], - // Warn if best-practices drops by more than 5 points + // Warn if best-practices drop by more than 5 points "categories:best-practices": [ "warn", { @@ -192,7 +192,7 @@ module.exports = { target: "temporary-public-storage", }, bulldozer: { - // Only keep data from main branch as baseline + // Only keep data from the main branch as baseline dailyBranches: ["main", "master"], // Keep last 10 baseline runs dailyLimit: 10, @@ -202,14 +202,14 @@ module.exports = { }; ``` -#### Lets breakdown the configuration +#### Let's break down the configuration 1. **collect** - Gathering Lighthouse Reports - URLs to test: Runs Lighthouse on https://nextjs-performance-xi.vercel.app/. (change to the staging or production URL) - Runs per test: Conducts 3 test runs and takes the median score. - Settings: - - Uses β€œperf” preset (optimized for performance testing). + - Uses β€œperf” preset (optimised for performance testing). - Only audits performance, accessibility, best practices, and SEO (no PWA checks). 2. **assert** - Enforcing Performance Standards @@ -327,9 +327,9 @@ module.exports = { }; ``` -#### Lets breakdown the configuration +#### Let's break down the configuration -Similar to the first configuration the only difference is the assert, so i will just highlight that section here: +Similar to the first configuration, the only difference is the assert, so we will just highlight that section here: This section compares new reports with previous ones and sets pass/fail criteria. @@ -352,8 +352,8 @@ Category Score Assertions (Fail if below threshold) - Total Blocking Time (TBT): 🚨 Warn if > env var (TBT_THRESHOLD) or default 300ms. - Time to Interactive (TTI): 🚨 Warn if > env var (TTI_THRESHOLD) or default 3500ms. -All of these are subject to change based on the application, for most of these configuration its set to warn. -Also its best to run the lighthouseci command on local before the first deployment so that there are available values to be compared it and the CI can work well. +All of these are subject to change based on the application; for most of these configurations, it's set to warn. +Also, it's best to run the lighthouseci command locally before the first deployment so that there are available values to be compared and the CI can work well. ### Adding Scripts to package.json @@ -362,16 +362,16 @@ Add these scripts to your package.json file: ```json title="package.json" "scripts": { // ... existing scripts - "analyze": "ANALYZE=true next build", + "analyse": "ANALYZE=true next build", "lhci": "lhci autorun" } ``` ## Reports -### Bundle Analyzer Reports +### Bundle Analyser Reports -When you run npm run analyze, the bundle analyzer will generate a visual report showing your application's bundle composition. This report helps you: +When you run npm run analyse, the bundle analyser will generate a visual report showing your application's bundle composition. This report helps you: - Identify large dependencies - Find duplicate modules @@ -391,14 +391,14 @@ Lighthouse CI generates comprehensive performance reports that include: - Performance Score - Overall rating of your app's performance - Accessibility Score - Rating of how accessible your app is - Best Practices Score - Rating of adherence to web best practices -- SEO Score - Rating of search engine optimization +- SEO Score - Rating of search engine optimisation **Key metrics to monitor:** - First Contentful Paint (FCP) - Time until the first content is rendered - Largest Contentful Paint (LCP) - Time until the largest content element is rendered - Cumulative Layout Shift (CLS) - Measure of visual stability -- Total Blocking Time (TBT) - Sum of time where main thread was blocked +- Total Blocking Time (TBT) - Sum of time where the main thread was blocked - Time to Interactive (TTI) - Time until the page becomes fully interactive When running npm run lhci, you'll receive a link to a temporary public dashboard with your results. @@ -422,7 +422,7 @@ on: jobs: build-and-analyze: - name: Build and Analyze with Lighthouse + name: Build and Analyse with Lighthouse runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -432,7 +432,7 @@ jobs: node-version: 20.x - name: Install dependencies run: npm ci - - name: Build with bundle analyzer + - name: Build with bundle analyser run: | ANALYZE=true npm run build env: @@ -453,7 +453,7 @@ jobs: with: name: next-build-and-reports path: | - .next/analyze + .next/analyse .lighthouseci retention-days: 30 ``` @@ -470,7 +470,7 @@ on: jobs: build-and-analyze: - name: Build and Analyze with Lighthouse + name: Build and Analyse with Lighthouse runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -480,7 +480,7 @@ jobs: node-version: 20.x - name: Install dependencies run: npm ci - - name: Build with bundle analyzer + - name: Build with bundle analyser run: | ANALYZE=true npm run build env: @@ -512,14 +512,14 @@ jobs: with: name: next-build-and-reports path: | - .next/analyze + .next/analyse .lighthouseci retention-days: 30 ``` ## Setting Up LHCI Server (Optional) -For more advanced usage, you can set up a Lighthouse CI Server to store and visualize historical data: +For more advanced usage, you can set up a Lighthouse CI Server to store and visualise historical data: 1. Install the LHCI server: @@ -545,8 +545,8 @@ upload: { --- -Setting up performance tracking is just another tool in your arsenal to ensure code quality consistency overtime and more granular control on things that affects performance over time. -Also, remember that performance optimization is an ongoing process. Regularly review your reports, set increasingly ambitious goals, and make performance a key consideration in your development workflow. +Setting up performance tracking is just another tool in your arsenal to ensure code quality consistency over time and more granular control on things that affect performance over time. +Also, remember that performance optimisation is an ongoing process. Regularly review your reports, set increasingly ambitious goals, and make performance a key consideration in your development workflow. For more detailed information, check out: @@ -554,4 +554,4 @@ For more detailed information, check out: - [Next.js Bundle Analyzer documentation](https://www.npmjs.com/package/@next/bundle-analyzer) - [Web Vitals](https://web.dev/vitals/) for understanding core performance metrics -Happy optimizing! +Happy optimising! diff --git a/src/foundations/hooks/use-match-media/page.mdx b/src/foundations/hooks/use-match-media/page.mdx index a9893e8a..65828a92 100644 --- a/src/foundations/hooks/use-match-media/page.mdx +++ b/src/foundations/hooks/use-match-media/page.mdx @@ -6,7 +6,7 @@ export const metadata = { ## Features -- **Media Query Support**: Observe any CSS media query for responsive behavior +- **Media Query Support**: Observe any CSS media query for responsive behaviour - **Real-time Updates**: Automatically updates when the media query match changes ## API Reference diff --git a/src/foundations/hooks/use-mouse-pan/page.mdx b/src/foundations/hooks/use-mouse-pan/page.mdx index 18dbef6d..cbb2c8df 100644 --- a/src/foundations/hooks/use-mouse-pan/page.mdx +++ b/src/foundations/hooks/use-mouse-pan/page.mdx @@ -14,7 +14,7 @@ export const metadata = { - **Scroll Snap Support** - Seamlessly works with CSS scroll-snap properties for precise control - **Multi-Axis Support** - Handles both horizontal and vertical scrolling directions -- **Native Scroll Integration** - Preserves native scrolling behavior for wheel and touch events, allowing for a seamless cross-device experience +- **Native Scroll Integration** - Preserves native scrolling behaviour for wheel and touch events, allowing for a seamless cross-device experience ## API Reference diff --git a/src/foundations/hooks/use-prefers-reduced-motion/page.mdx b/src/foundations/hooks/use-prefers-reduced-motion/page.mdx index e82cb713..422095ac 100644 --- a/src/foundations/hooks/use-prefers-reduced-motion/page.mdx +++ b/src/foundations/hooks/use-prefers-reduced-motion/page.mdx @@ -22,4 +22,4 @@ This setting should be checked before implementing animations to ensure complian ### Note -For projects that already has motion installed, this hook already exists [here](https://motion.dev/docs/react-use-reduced-motion). Also to note tailwindcss has `motion-reduce` +For projects that already have motion installed, this hook already exists [here](https://motion.dev/docs/react-use-reduced-motion). Also, to note tailwindcss has `motion-reduce` diff --git a/src/foundations/hooks/use-scroll-lock/page.mdx b/src/foundations/hooks/use-scroll-lock/page.mdx index 102a18d4..783b64da 100644 --- a/src/foundations/hooks/use-scroll-lock/page.mdx +++ b/src/foundations/hooks/use-scroll-lock/page.mdx @@ -25,7 +25,7 @@ export const metadata = { name: "target", type: "string | HTMLElement | RefObject", description: - "The target element to lock the scroll on. Can be a string (selector), HTMLElement, or a RefObject with a HTMLElement.", + "The target element to lock the scroll on. Can be a string (selector), HTMLElement, or a RefObject with an HTMLElement.", }, }} /> diff --git a/src/foundations/hooks/use-ticker/page.mdx b/src/foundations/hooks/use-ticker/page.mdx index 13440c59..1b78cc05 100644 --- a/src/foundations/hooks/use-ticker/page.mdx +++ b/src/foundations/hooks/use-ticker/page.mdx @@ -31,6 +31,6 @@ The hook returns an object with the following properties: ## About `requestAnimationFrame` -`requestAnimationFrame` is a browser API that schedules a callback to be executed before the next browser repaint. It's the recommended way to create animations and game loops as it automatically synchronizes with the browser's refresh rate. +`requestAnimationFrame` is a browser API that schedules a callback to be executed before the next browser repaint. It's the recommended way to create animations and game loops as it automatically synchronises with the browser's refresh rate. You can read a more in-depth overview of `requestAnimationFrame` on our blog: **[Mastering JavaScript Web Animations](https://significa.co/blog/master-javascript-web-animations)**. diff --git a/src/foundations/setup/page.mdx b/src/foundations/setup/page.mdx index da4eb7a0..45406926 100644 --- a/src/foundations/setup/page.mdx +++ b/src/foundations/setup/page.mdx @@ -1,6 +1,6 @@ export const metadata = { title: "Setup", - description: "How to setup your project to use Foundations.", + description: "How to set up your project to use Foundations.", }; ## Prerequisites @@ -8,7 +8,7 @@ export const metadata = { - A [React 19](https://react.dev/blog/2024/12/05/react-19) project. - [Tailwind 4](https://tailwindcss.com/) installed and configured. -> We are using React 19. If you still on 18, please check the [React 19 migration guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide). +> We are using React 19. If you are still on 18, please check the [React 19 migration guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide). > A few common changes are: > > - `ref` is now a prop like the others, so we don't need to use `forwardRef`.