Repository files navigation

Atomium is an internal design system forJuntos Somos Mais, using Web Components

Project	Package	Version	Documentation
Core	@juntossomosmais/atomium		README
React	@juntossomosmais/atomium/react		README
Vue	@juntossomosmais/atomium/vue		README
Tokens	@juntossomosmais/atomium-tokens		README

It is built using a variety of powerful technologies, including:

• NX: a set of extensible dev tools for monorepos, which helps us build and manage multiple projects within a single repository.
• Stencil: a web component compiler that generates standard-compliant components using TypeScript, JSX, and HTML.
• Ionic: a set of UI components and tools that help developers build performant, high-quality mobile and desktop applications using web technologies.
• Storybook: a user interface development environment and testing tool that allows us to create and showcase components in isolation.
• Typescript: a typed superset of JavaScript that compiles to plain JavaScript, providing powerful tools for building large-scale applications.
• Web Components: a set of standards that enable the creation of reusable, encapsulated components using open web technologies.

Clone the repository viassh

git clone git@github.com:juntossomosmais/atomium.git

Copy.npmrc.example to.npmrc.

Replace<your-github-token-here> in the.npmrc file with yourGitHub PAT. Your PAT should have following scopes:repo andwrite:packages.

npm inpm run build

If you get errors about unresolved dependencies, you may need to runnpm i --legacy-peer-deps instead.

npm start

If you want to run React Stories locally, you need to run the following command beforenpm start:

npm run docs-react:start

And if you want to run Vue Stories locally, you need to run the following command beforenpm start:

npm run docs-vue:start

npmtest

## Build Libsnpm run build## Build Storybooknpm run docs:build

• apps/docs: Contains the main documentation for the project.
• apps/docs-react: Provides a React version of Storybook for showcasing components.
• apps/docs-vue: Provides a Vue version of Storybook for showcasing components.
• packages/core: The core of Atomium, responsible for building all the components.
• packages/react: The React version of Atomium, automatically generated by Stencil.
• packages/vue: The Vue version of Atomium, automatically generated by Stencil.
• packages/tokens: Contains the design tokens for Atomium, where all the tokens are defined.
• packages/icons: Contains the icons used in Atomium, where all the icons are stored.
• utils/**: Contains utility modules used throughout the project, providing various helper functions and tools.

We are usingStorybook to document our components.

Components stories are written inpackages/core/**/*.core.mdx files to Web Components version andpackages/core/**/*.react.mdx files to React version and are automatically loaded by Storybook. You also can using a shared file calledpackages/**/*.args.ts to share the same args between Web Components and React version.

Tokens stories are written inpackages/tokens/**/*.mdx files.

General documentation is written inapps/docs/**/*.mdx files.

These files are written inMDX.

To enable syntax highlighting in your editor, you need to install the following extensions:

• lit-html

To locally test Atomium using Alpha/Beta versions, follow the steps below:

1. Update the.release-please-manifest.json file in the root directory of the Atomium project with the next version number + alpha. Ex: the current version is2.10.0, so the next alpha version can be2.11.0-alpha.1 (OBS: in the example, it is updating only the core lib, update the libs that your changes impact).

2. Add the same version to the repespectivepackage.json file in the root directory of the lib project. Ex: packages/core/package.json

3. Build the Atomium libraries by running the following command in the root directory of the Atomium project

npx nx run @juntossomosmais/atomium:publish-library-alpha

OBS: you can even share the alpha version with your team, than they can test it locally.

To locally test Atomium using NPM Link, follow the steps below:

Build the Atomium libraries by running the following command in the root directory of the Atomium project

npm run build

Link the Atomium libraries by navigating to thenode_modules/@juntossomosmais/atomium directory

cd node_modules/@juntossomosmais/atomiumnpm link

Import Atomium into your project by linking it using NPM Link. Navigate to your project's directory and run the following command

npm link @juntossomosmais/atomium

This will create a symbolic link between your project and the locally built Atomium libraries.

Now you can use the imported Atomium components in your project and test them locally. Make sure to revert these changes and remove the NPM Link when you're done testing to avoid any conflicts or unexpected behavior with the actual installed version of Atomium in your project.

By following these steps, you can easily test and verify any customizations or modifications you have made to Atomium locally using NPM Link.

We are usingGitHub Actions,GitHub Packages andrelease please to automate the release process.

When a PR is merged into themain branch, the release process is triggered. The release process will create a new release and publish the packages to GitHub Packages.

The Atomium can be deployed to a CDN using S3. The deployment istriggered manually using GitHub Actions

If you get an error in Github Actions to publish to NPM, you can run the following command to restart the release process:

1. Go to theReleases and remove the release that failed
2. Go to theTags and remove the tag that failed or run the following command in your terminal:

git tag -d<tag>git push origin --delete<tag-name>

3. Get the last commit hash from theCommits and run the following command in your terminal:

git reset --hard<commit-hash>git push origin main --force

4. So, a new PR will be created and the release process will be triggered again

!important, as it's an internal design system, we don't accept external suggestions to change or add new components.

We only accept contributions fromJuntos Somos Mais members, but you could like our project and use it as a reference to build your own design system.