@atom-learning/components

---

title: Introduction description: This package is one part of the Atom Learning design system. category: Overview priority: 1

Getting started

Clone the repo

git clone [e-mail]:Atom-Learning/components.git

Install dependencies

yarn install

Before starting to develop on this project, please consider the following:

• Read the contribution guide
• Read the versioning section
• Read the accessibility section
• Check that the pre-commit hooks work before pushing into a branch
• Always commit your changes to a branch and request a code review by raising a PR.
• Always include tests for the changes introduced

Available yarn scripts

• dev: Starts the libary for development
• build:lib: Builds the library and populates the dist folder
• build:docs: Builds the documentation and exports it to be consumed by the documentation project
• clean: Deletes the dist folder to ensure a clean build
• format: Formats the code using Prettier
• lint: Lints the code using Eslint
• test: Runs the testing suit using Jest
• test:watch: Runs the testing suit in watch mode
• validate: Runs all the validate commands (see package.json for more details) - This command is used by the CI too, to check pushed changes
• start:sandbox: Starts up a sandbox

---

Versioning

The project follows the SemVer standard Semantic Versioning to make using the library easy. SemVer uses the MAJOR.MINOR.PATCH notation to identify changes with MAJOR representing breaking changes that are not backwards compatible, MINOR representing new features / non-breaking additions and PATCH representing fixes.

It is also a requirement to use Semantic commits as each tag will translate to a different type of version upgrade. For example:

• Commits with a breaking change will be associated with a major release.
• Commits with type 'feat' will be associated with a minor release.
• Commits with type 'fix' will be associated with a patch release.

Note: The precommit hooks will prevent commits that don't have the required tag prefixed to the message

Versioning happens automatically when a feature branch gets merged into main. semantic-release is employed to calculate the new version number by running through all the new commits and their commit message tag. Once the new version is calculated, it updates the package.json and automatically updates the CHANGELOG.md. Then it proceeds to publish the new version both in GitHub and npm.

Note: Once a branch gets merged into main, it is automatically published, therefore main always needs to be in a pristine state. For that reason, following the GitFlow model, all work needs to happen into a branch, and main is locked

Purpose

• To ensure that each version is marked clearly and can be consumed without any issues
• To reduce the amount of manual effort required to publish a new version
• To help enforce the selected standards and frameworks, and reduce the room for human error

Tools

• Semantic-release
• Plugins:
  • @semantic-release/commit-analyzer - checks commits messages for the required tags
  • @semantic-release/release-notes-generator - creates/updates the release notes
  • @semantic-release/npm - publishes version to npm
  • @semantic-release/github - publishes version to GitHub Releases
• husky - precommit hook to prevent incomplete commit messages

---

Accessibility

The design system is aiming to adhere to strict accessibility standards with AA as the minimum. To enable this, eslint-plugin-jsx-a11y is set to strict mode. Different tools are used to validate the components as each serves a different purpose. The accessibility unit tests will fail the pipeline and prevent releasing inaccessible components. However, these tests are only valid with the context they are testing on, so they can't guarantee 100% that a component is fully accessible. Therefore, manual testing is required along with design validation.

Before developing a component, please take some time to read the following sections and the reading provided.

Things to consider whilst developing

• Using React.Fragment where possible to avoid adding extra <div>

  Sometimes we break HTML semantics when we add <div> elements to our JSX to make our React code work, especially when working with lists (<ol>, <ul> and <dl>) and the HTML <table>. In these cases we should rather use React Fragments to group together multiple elements. for examples please look at the React documentation

• Add unit tests to test accessibility Add an accessibility unit test (using the jest-axe) to ensure that the components' different variations don't have any accessibility issues. Example:

it('has no programmatically detectable a11y issues', async () => {
  render(<Flex />, document.body)
  const results = await axe(document.body)
  expect(results).toHaveNoViolations()
})

Note: axe doesn't catch contrast issues when run on jsdom which jest is using.

• Using the React Testing Library rules into adopting a user-centric testing an approach. Priority
  • Test real interactions
  • Verify the perceivable results
• Always validating any concerns with the design team
• Manually test complex components for keyboard navigation

Things to consider whilst consuming the library

As mentioned above, accessibility testing is heavily reliant on the context, so when using the Design System in an app, please consider the following:

• Testing the components for accessibility in the context of where they are used
• Testing the entire page for at least the following:
  • contrast issues
  • keyboard navigation
  • autofocus
  • general accesibility issues
• Always raising concerns to the design team

Reading list

• Axe-core rules
• Accessibility
• React Library Testing - priority
• Testing Accessibility
• Debunking the Myth: Accessibility and React
• Accessibility auditing with react-axe and eslint-plugin-jsx-a11y
• jest-axe