Mobius

Simply Business Design System

Where to find us

• Slack Channels:
  • Support: #frontend-tooling-support
  • Development: #frontend-tooling

mobius-core fundamentals and libraries

Typescript

Typescript is a strongly typed implementation of javascript.

In such a large and complex codebase type checking is a requirement in order to be able to develop effectively. It provides clarity of what is provided to each component or method and drastically reduces debugging time by removing a whole class of errors.

Read more on the Typescript docs page.

Theme UI

Theme UI provides a way for us to apply styles across all of our components by setting defaults or conditional styles in a shared style sheet. The styles then propagate through use of a special sx prop that is passed to each component. It has the flexibility to apply styles across the whole project or at the inline per-component basis.

Read more one the Theme UI docs page.

React Spectrum, Aria and Stately

Abobe has created a library for React that is built around accessibility, internationalisation, and reusability. We depend on this framework to provide us the functionality we need to build cross-platform, cross-business websites.

Spectrum is an Adobe design system that has been implemented for React. Aria and Stately are designed specifically for React and provide a library of hooks that are focused on UI components and state managment respectively.

For more information see the docs here: Spectrum, Aria, Stately.

Getting started guide

Once you have cloned this repo, in the root folder, run the following command to install the project dependencies:

$ yarn install

Then to run the app in Storybook run:

$ yarn storybook

Storybook runs our sandbox development environment where all of our components are rendered. Each component is rendered individually and if it has different states (hover, disabled etc) then each state is rendered on it's own page.

This provides a quick and accessible way to see each of the project's components in a simple UI. Benefits this provides include allowing you to see what effect your changes have during development with a short feedback loop and allowing product designers etc to view what the team is working on.

Creating your first component

Our docs have all the information you need to start building your first component, including a guide to using plop to generate the boiler plate for a component in less than a minute. The docs also contain information relating to our design and architectural decisions.

Testing locally

mobius-core uses jest as a testing framework. yarn handles running the tests; to run the tests for the whole project run this command from the root directory:

yarn test

A useful way to run the tests is to add the --watch flag to the command above. This watches for changes to your code and runs the tests for changed files each time the file is saved.

To run a specific test file you need to cd in to the correct package (e.g. mobius-simplybusiness) and then run:

yarn test $filepath

Testing in external projects

Using yarn link

To link your local copy of a mobius package to an external project you're working on, run the following in each package you want to link:

$ yarn link

Then move to the root folder of the project you want to test mobius in, and run the following:

$ yarn link package-name

Every time the linked packages are rebuilt, the project should pick up the changes correctly.

More info:

• yarn link documentation

Using tarballs

In the root folder, run the following:

$ yarn run lerna:build
$ yarn run lerna:pack

Inside each package folder, you should now find the corresponding tarball:

packages/mobius-core
├── dist
├── mobius-core-v0.1.0.tgz   <--- Tarball
├── node_modules
├── package.json
├── src
└── ...

Copy each package tarball into your external project and add them as dependencies:

// package.json
{
  "dependencies": {
    "mobius-core": "file:./mobius-core-v0.1.0.tgz"
    ...
  },
  "resolutions": {
    "mobius-core": "file:./mobius-core-v0.1.0.tgz"
    ...
  }
}

Run the following:

$ yarn install

You can now use the libraries in your external project.

Deployment process

Once you have opened a PR make a request to members of the team to review your PR.

Please make the request on github and drop a message & link in our slack channel, #frontend-tooling

Each PR will require approval by a FETT member in order to be able to be merged. Non-team members can also provide reviews and approval but the PR won't be mergable until a team member has approved it.

Once the build is green and approved just click the merge button to automatically deploy.

Deployment process

1. Update the CHANGELOG.md file to include details about the release. Don't just use a list of commits, the changelog is intended to be a user-readable summary of the things that have changed, following the format specified at https://keepachangelog.com/en/1.0.0/. Commit directly to master.
2. Run yarn release and follow the prompts to specify the version number. A browser window will open to create a new release on Github.
3. Jenkins will build and publish the library to BNW Registry. This typically takes about 10 minutes.

Repos consuming Mobius

TODO

Contributing

When opening a PR, open it as a draft and ping #frontend-tooling to get reviews from the maintainers.