simplybusiness-mobius v1.13.2
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:
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
- 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. - Run
yarn release
and follow the prompts to specify the version number. A browser window will open to create a new release on Github. - 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.