The @grams-dev/ui package is a collection of UI components designed for use with the Grams ecosystem. It provides developers with a set of reusable and customizable UI elements to create user-friendly decentralized applications (dApps).
- UI Components: A library of pre-built UI components tailored for Grams dApps.
- Theme Customization: Easily customize the appearance and styling of components to match your dApp's design.
- Responsive Design: Components are optimized for various screen sizes and devices, ensuring a seamless user experience.
- Accessibility: Prioritizes accessibility standards to ensure that all users can interact with your dApp.
- Easy Integration: Simple integration with existing Grams projects or new dApps being built from scratch.
You can install the @grams-dev/ui package via your preferred package manager.
npm install --save @grams-dev/uiyarn add @grams-dev/uiIn your index.(js|ts), import the i18n object from @grams-dev/i18n to access the translation strings
import '@grams-dev/i18n';Then, you'll need to import the grams.css CSS file distributed by the package. This should be done at the root of your project (in index.js or App.tsx of your React app) and will look like:
import '@grams-dev/ui/dist/grams.css';
...Once installed, you can import and use the UI components in your Grams dApp. Here's an example of how to use a Button component:
import React from 'react';
import { Unlock } from '@grams-dev/ui';
const MyComponent = () => {
return (
<Unlock onUnlock={() => console.log('User unlocked!')} />
);
};You can customize the appearance and behavior of the UI components using the provided props and CSS styles.
For more detailed information and examples, refer to the Storybook.
Above we imported grams.css into the root of our project. grams.css contains a number of CSS variables that can be used across the project that consumes our component library.
In your CSS, you can use the variables defined in variables.css like:
.example-container {
color: var(--grams-color-primary);
background: var(--grams-background);
}See: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties for more information about CSS Variables.
Comprehensive documentation for @grams-dev/ui is available at https://storybook.grams.dev. It includes detailed usage instructions, component reference, and examples to help you get started with the package.
Contributions to @grams-dev/ui are welcome! If you encounter any issues or have suggestions for improvements, please feel free to open an issue or submit a pull request on the GitHub repository.
gcx (Recommended)
gcx setup -r uiThe @grams-dev/ui package is open source and distributed under the Apache License 2.0. Your contributions to the project are appreciated and will be licensed accordingly.
npm run test
npm run build
To run a live-reload Storybook server on your local machine:
npm run storybook
To export your Storybook as static files:
npm run build:storybook
This will also copy the CNAME from the root directory to the static files. You can change it to any CNAME you want.
Grams UI provides several convenient scripts to help with development and maintenance of the library.
The /create-component script is used to generate a new UI component in the Grams UI library. It automates the process of setting up the component's file structure, boilerplate code, and test files. To use this script, run the following command:
npm run create:component <ComponentName>Replace <ComponentName> with the desired name of your component, using PascalCase. This script will create a new folder in the src/components directory with the specified component name, along with the necessary files and directory structure.
The /create-page script is used to generate a new page component in the Grams UI library. Similar to the /create-component script, it sets up the file structure and boilerplate code for a new page component. To use this script, run the following command:
npm run create:page <PageName>Replace <PageName> with the desired name of your page component, using PascalCase. This script will create a new folder in the src/pages directory with the specified page name, along with the necessary files and directory structure.
The /release script automates the process of releasing a new version of the Grams UI library. It performs various tasks such as version bumping, creating release notes, generating changelogs, and publishing the package to the package registry. To use this script, run the following command:
npm run releaseThis script will guide you through the release process, prompting for version updates and generating necessary release files. It ensures that the release process is streamlined and follows best practices.
Make sure to review and update the relevant configuration files (such as package.json and CHANGELOG.md) before running the release script to ensure accurate versioning and documentation.
These scripts provide a convenient way to perform common tasks when developing and maintaining the Grams UI library. Feel free to explore and utilize them as needed for your development workflow.
First, make sure you have an NPM account and are logged into NPM using the npm login command.
Then update the name field in package.json to reflect your NPM package name in your private or public NPM registry. Then run:
npm publish
The "prepublishOnly": "npm run build" script in package.json will execute before publish occurs, ensuring the build/ directory and the compiled component library exist.
I recommend you host the component library using NPM. However, if you don't want to use NPM, you can use GitHub to host it instead.
You'll need to remove build/ from .gitignore, build the component library (npm run build), add, commit and push the contents of build. See this branch for an example.
You can then install your library into other projects by running:
npm i --save git+https://github.com/grams-dev/ui.git#branch-name
OR
npm i --save github:grams-dev/ui#branch-name
The example component TestComponent respects the user's dark mode operating system preferences and renders the component in the appropriate theme.
This is achieved by using the media query: @media (prefers-color-scheme: dark) in combination with CSS variables. The colours that change depending on dark mode preference can be found in src/index.css. Example usage of these variables can be found within src/TestComponent/TestComponent.css.
Read https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme for more details.
The Rollup plugin rollup-plugin-postcss supports Sass, Less and Stylus:
- For Sass, install less:
yarn add node-sass --dev - For Stylus, install stylus:
yarn add stylus --dev - For Less, install less:
yarn add less --dev
If you want to use CSS Modules, update postcss in rollup-config.js to:
postcss({
modules: true
})
Code splitting of your components is not supported by default.
Read this section of my blog post to find out how and why you would enable code splitting of your components. In summary, code splitting enables users to import components in isolation like:
import TestComponent from '@grams-dev/ui/dist/TestComponent';
This can reduce the bundle size for projects using older (CJS) module formats.
You can check out this branch or this commit to see what changes are neccesary to implement it.
Please note, there's an issue with code splitting and using rollup-plugin-postcss. I recommend using rollup-plugin-sass instead alongside code splitting.
Checkout the official Rollup plugin list for additional helpful plugins.