@therms/atalaya

React components and style guide for THERMS.

Issue Tracker https://bitbucket.org/thermsio/atalaya/issues

Install

Git master branch, the latest production/stable release, docs: @therms/atalaya

npm i @therms/atalaya

Git next branch, the next major stable release in development and testing, docs: @therms/atalaya@next

npm i @therms/atalaya@next

Development and features on the next branch is primarily for breaking changes (major release version change). This branch/tag should be considered mostly stable and typically published alongside of a lower @latest major release in order to give packages time to migrate from a previous version.

Git x.x.x-beta.x branch, development effort release, docs: @therms/atalaya@beta

npm i @therms/atalaya@beta

Development, refactoring, additions, improvements, etc. are done on the beta branch.

Setup

We provide several ways to import the design system tokens:

• CSS Stylesheets.
• Tailwind.
• JS Tokens / Constants.
• JS Constants.

CSS stylesheet

CSS files ready to import can be found in the css/ folder. Since Atalaya provides support dark/light themes, the tokens had to be broken up into 3 files:

• base.css: contains all the default variables that are always used. Should always be imported before the rest of Atalaya stylesheets.
• color-light, color-dark: share the same CSS variables keys, each one have the corresponding values for their color themes. You should import one or the other depending on the color theme you want to display.

After importing this files, the only thing you need to do is to use the tokens on your css declarations.

Tailwind

If you are using tailwind we provide a preset that will automatically integrate our design tokens to tailwind classes. To enable this, in tailwind's configuration add tailwind.js as a preset.

Important note: If you use Tailwind and our React Components, we recommended that you add Atalaya's folder to the purge configuration. It can prevent specificity errors that cause some components to don't look as expected.

JS Tokens / Constants

We provide some JS objects that provide a more convenient API to define styling on JS based environments. Inside lib/index.js you will find two object tokens and Constants. tokens uses token names as keys, useful for situations like creating css variables programmatically. Constants contains the same information, but it's shape it's more convenient to use on pure JS environments like React.

React Components

Based on Atalaya's foundations, we have created React components that can be imported from lib/index.js. For them to work you will need to wrap you app with <AtalayaWrapper /> this component provides the rest of Atalaya's components with the styling they need. Plus, it adds support for theme toggling.

Docs

This project uses Styleguidist for documenting components. Components are automatically documented and can additionally have [component name].md files to add additional documentation

Running the docs:

npm run docs

Building the docs:

npm run docs:build

Development

This project uses React Cosmos for developing components with quick UI feedback/reloading on the developers local machine. Run npm run cosmos.

To run this project and develop components that are used by another project locally on the same machine, use npm link command in this project and in the other project run npm link @therms/atalaya.

In order for your changes to reflect while you develop, run:

npm run build:dev

Publishing

We use semantic-release for automatic versioning. Every time a new commit has been pushed to master with the feat or fix keyword it will create a new version and publish it to npm. If the commit introduces a breaking change you should add BREAKING CHANGE to the commit message with an explanation of what has been broken. This will let semantic-release know it should publish a new major version instead of a minor one.

If you want to deploy a new version but don't want to push your commits you can run npm run polish.

Known Issues

• Conflict between Tailwind and React Components if node_modules/@therms/atalaya/**/*.js is not included in purge config.