This repository includes a shared CSS library, preprocessed with Sass, along with HTML examples based on it. It also houses a user interface (UI) kit in Angular and a typed, tree-shakable icon library.
The CSS has been architectured to be independent of any specific Javascript framework. This makes it possible for contributors to easily integrate component libraries from other frameworks such as React or Vue.js. The Angular UI library has also been constructed free of any dependencies on design systems/frameworks like Bootstrap or Google's Material. This ensures a reduction in dependence on third-party vendors 🛠️.
The CSS framework and Angular component library utilize Storybook for comprehensive documentation and seamless usage.
You can also play with the library in a live app-like environment at codesandbox.io.
To get started, you can access the installation instructions and documentation on e-Gov CVI's Storybook:
📌 https://e-gov.github.io/cvi/
The styles in this repository take inspiration from the initial Veera Design System, which you can find here:
🔗 https://www.figma.com/file/nNCV5kRqdRkS8MOCK1ZbqU/Veera-Design-System
Please note, e-Gov CVI is not Veera. We've taken inspiration from their work, but our approach and implementation are unique 💡.
To discuss any issues, suggestions or questions, join our public CVI Signal group.
Follow these steps to install and integrate our library:
-
📥 Add the public Koodivaramu registry to your project by following the instructions provided here. In short, you will need to update your
.npmrcfile. Be sure to choose the second radio button in the Koodivaramu UI ("project-level registry setup"). -
📦 Install the necessary package to your project:
- CSS framework: Use the command
npm i --save @egov/cvi-styles - Angular components: Use the command
npm i --save @egov/cvi-ng - React components: Use the command
npm i --save @egov/cvi-react - Icons: Use the command
npm i --save @egov/cvi-icons
- 🏁 After installation, import the dependencies into your project. You'll find dedicated instructions for this in the documentation for the CSS framework, Angular components, and icons.
The built packages are published to the public Koodivaramu repository, from where you can download and add them to your application. You can access it via the following link:
In addition, the Storybook Docker image is also published to the Koodivaramu repository:
If you want to contribute to the Common Visual Identity Component Library, follow these steps:
- Create a fork of the repository.
- Make changes in your own fork.
- Create a pull-request back to this repository.
Feel free to use the library sandbox available at codesandbox.io to verify issues or play with existing components.
For more detailed instructions, follow the link below:
When adding/upgrading peer dependencies, ensure that they are also updated in the following files:
libs/LIB-NAME/package.jsonfor peerDependencies.libs/LIB-NAME/ng-package.jsonfor dependencies to be packaged with the library.
The project follows the conventional commit format convention and uses the semver nx plugin for versioning. Ensure to use the appropriate commit messages.
Use [cvi-component-selector=local-selector-name] naming convention for content projection selectors.
For example, to introduce a content selector that inserts custom content before a title in a panel (eg. fictional PanelComponent/<cvi-ng-panel> component), an appropriate code would be <ng-content select="[cvi-ng-panel=before-title]"></ng-content>.
Run the following command to build documentation and start the Storybook locally:
npm run storybook
To run Storybook locally using Docker, follow these steps:
- Build the Docker image with the following command:
docker build -f ./libs/storybook/Dockerfile -t cvi-storybook .
- Start the Storybook container with the following command:
docker-compose up storybook
- Stop the container with the following command:
docker-compose down
- the Storybook interface at
http://localhost:3005/in your web browser.
To see a diagram of the dependencies of your projects, run the following command:
nx graph
This will provide you with an overview of your workspace and how the different projects and libraries are interconnected.
To learn more about the Nx build system, check out the following resources:
To run Cypress tests against Storybook, make sure that Storybook is up and running (see the previous section). Then, run the following command: npm run cypress:ui
This will open up the Cypress visual testing tool. Select E2E Testing to view all component tests. Note that Cypress tests use Angular components in iFrame windows, which is why Storybook needs to be up and running.
The project uses automatic screenshot testing via Chromatic.
- To run the tests, use the following command in your terminal:
npm run chromatic - Open the resulting URL and review the visual changes.
💡 Chromatic CI also runs on every push. The action always passes (even when visual changes are detected) except for cases when a story is broken. Contributors and reviewers should check the results of the action (and accept or decline them in the Chromatic UI) by following a link in the build log. 💡
Publishing to Chromatic also gives a possibility to share a Storybook link for a specific branch (even non-pushed, if the local npm command is used) in this format:
https://<branch>--6373995e3f280e239470296d.chromatic.com
Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions. 🎉