Blade

The Design System that powers Razorpay

📦 Packages
- @razorpay/blade
- @razorpay/blade-old
🏁 Getting Started
📝 Versioning & Publishing
⌛️ Current State
🤝 How to contribute
📝 License

📦 Packages

Blade right now has 2 packages

`@razorpay/blade`

This package is under active development. In this README we'll only refer to this version of blade.

This package is under maintenance and it won't have any major releases. It will be soon deprecated once the newer version is released as a stable release. Documentation for this package can be found here

🏁 Getting Started

⚙️ Installation

✍🏻 Pre-requisite

Before you install the package, make sure that you have performed following steps: Before using universe just ensure following things

You must be running Node version >=14.0.0
You must have yarn installed
Generate a Personal Access Token on GitHub by visiting this link
- From Enable SSO, click Authorize button next to Razorpay logo.
Run code ~/.bashrc or code ~/.zshrc in your editor and add this line
```
export GITHUB_ACCESS_TOKEN="<YOUR_TOKEN>"
```
Run source ~/.bashrc or source ~/.zshrc based on the file you added your token.
Run code ~/.npmrc and append the following

# add following to your .npmrc
@razorpay:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:always-auth=true
//npm.pkg.github.com/:_authToken=${GITHUB_ACCESS_TOKEN}

⬇️ Add blade to your application

$ yarn add @razorpay/blade

🔜 Add blade libraries to your figma project

🧑🏻‍💻 Local Development

Testing Local Changes

We have all the examples under packages/examples directory. To run any example project with the updated changes follow the steps below:

Setup the example project

$ cd packages/examples/<example-name>
$ yarn

Publish the blade package with your changes using yalc.

# run this from packages/blade directory
$ npx yalc publish

Install the updated blade package using yalc.

# run this from packages/examples/<example-name> directory
$ npx yalc add @razorpay/blade

Run the example project and verify the changes

# this script can vary based on the kind of project so check the example `package.json` to find the relevant script to start the project
$ yarn start

Running Tests

We use react-testing-library for writing tests. If you want to write platform specific tests then suffix the test file with filename.native.ts or filename.web.ts

To run the tests for web projects follow the steps below:
```
$ cd packages/blade
$ yarn test:web
```
To run the tests for native projects follow the steps below:
```
$ cd packages/blade
$ yarn test:native
```

To update the snapshots run the test commands with -u as suffix

👀 How to use blade?

Tokens

To start using tokens in your application you can follow below steps:

Wrap you component tree with BladeProvider and pass it paymentTheme or bankingTheme tokens.

// App entry point
import { BladeProvider } from '@razorpay/blade/components';
import { paymentTheme } from '@razorpay/blade/tokens';

function App(): JSX.Element {
  return (
    <React.Fragment>
      <BladeProvider themeTokens={paymentTheme}>
        <Card />
      </BladeProvider>
    </React.Fragment>
  );
}

export default App;

You can also pass in optional colorScheme prop to the BladeProvider mentioning whether you want the light, dark or system's default color scheme. The default is light.

<BladeProvider themeTokens={paymentTheme} colorScheme='dark'>
   <Card/>
</BladeProvider>

After you've wrapped your component tree under BladeProvider, you can use the useTheme() hook to get the access to the current theme context.

import { useTheme } from '@razorpay/blade/components';

const Card = (): React.ReactElement => {
  const { theme } = useTheme();
  return (
    <React.Fragment>
      <DisplayLarge theme={theme}>Cash Advance</DisplayLarge>
      <StyledCard theme={theme}>
        <CaptionRegular theme={theme}>
          This amount will be deducted in 3 installments from your settlement balance between Feb
          18-20 on a daily basis.
        </CaptionRegular>
      </StyledCard>
    </React.Fragment>
  );
};

const StyledCard = styled.div(
  ({ theme }: { theme: Theme }) => `
    width: 368px;
    background-color: ${theme.colors.surface.background.level2.lowContrast};
    border-radius: ${theme.border.radius.medium}px;
    padding: ${theme.spacing[5]}px;
    display: flex;
    flex-direction: column;
`,
);

📝 Versioning & Publishing

The first step in publishing a new version of blade is to first the mention the type of change and bump the version. We are using changesets to handle automated versioning for us based on the intent of the change we mention in the PR.
Once a PR is approved by the authors of blade, based on if the PR needs a new version to be published the author will add a changeset to the PR.
After the changeset is added and the PR is merged the release workflow gets triggered by GitHub actions.
The release workflow runs build script which runs rollup to bundle blade and generates relevant types as well.
After the build script finishes, we'll have 3 bundles which will be published under @razorpay/blade scope

@razorpay/blade/components
@razorpay/blade/tokens
@razorpay/blade/utils

🗒 You can read in depth about our shipping strategy here

⌛️ Current State

Here's a glimpse of where we are currently in our journey of building the design system.

🤝 How to contribute

To contribute to this project you should follow these things:

Open an issue with all the details mentioned in the issue template.
Discuss possible solutions and approaches on the issue itself and once finalized, you can start working on implementing the solution.
Ensure you write the necessary tests or update existing tests/snapshots wherever required.

Read how to test your changes here
Make sure to add/update the examples under packages/examples/tokens-usage directory.
Checkout a new branch with the type of change you're committing and the module it's affecting. The type of change could be one of fix, feat, chore, docs, ci, refactor, build followed by / followed by a very short description. For eg: feat/add-component-button
Stage all your files and run git commit. This will lint the staged files, prettify them and then run the unit tests.
Once all the checks are passed you'll be shown a prompt. Follow the steps in the prompt and fill in the relevant information. We use semantic commit messages. An example of semantic commit message is shown below.

feat: allow overriding of webpack config
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, test etc.

Push the branch, open a PR and add a link to the issue that you had opened in the PR description.

📝 License

Licensed under the MIT License.

invalidtoken / blade