Migrate from Nimiq Styles Framework to nimiq-css ​

Convert Nimiq Style Framework CSS classes to nimiq-css.

nimiq-css also supports UnoCSS now and will suport Tailwind v4 in the future.

The Nimiq Styles Framework is the current main CSS framework used at Nimiq. This library has been the main inspipration for the new nimiq-css library. This library has has been built with that in mind. It is designed to be as compatible as possible with a clear path for migration. However, there are some breaking changes due to the lack of usage of classes/features implemented by the old Library. These breaking changes are highly opinioned, so if you don't agree with some of the changes or you have better ideas, please let me know and we let's change it.

The Nimiq Styles Framework is currently the main CSS framework used in Nimiq. This library has been the main inspiration for the new nimiq-css library and has been a part of it from the beginning. It is designed to be as compatible as possible, with a clear migration path. However, there are some breaking changes due to the lack of usage of classes/features implemented by the old library. These breaking changes are highly opinionated, so if you don't like some of the changes or have better ideas, please let me know and we'll change them.

One of the biggest changes in this new library is the use of CSS layers. This allows us to have a more modular and scalable library. Another big change is the use of a new brand palette and support for dark mode with .dark class. You can learn more about the new library in a post I wrote.

Now, the new nimiq-css library is being developed to replace the old Nimiq Styles Framework. With simplicity, flexibility and scalability in mind, the new library is being developed to be more modular and easier to use. In this guide, you can see my recommendation to make the migration to nimiq-css. The guide is offered in steps, so you migrate to the new library progressively, one set of classes at a time, or all at once.

Installation ​

npm install nimiq-css

Now, you replace the import:

/* Old */
/* @import url('node_modules/@nimiq/styles/nimiq-style.min.css'); */
/* New */
@import url('node_modules/nimiq-css/css/legacy.css'); /* Import in vite or other bundlers might be different */

Now, you can uninstall the old package @nimiq/styles.

That's it! You are ready to start using the new nimiq-css library.

Icons ​

If you also rely on the icons from the @nimiq/styles package, you should continue to use them. However, another alternative is being developed, nimiq-icons, but it is still in development.

Import the library ​

So far, we have only imported the legacy.css file which contain all of the old code. Now, if you want to start using the new styles, you should also add the following imports:

@import url('node_modules/nimiq-css/css/index.css');

This import uses preflight.css, which resets some of the styles. If you are having issues, make sure you are importing first the index.css and then the legacy/main.css.

The old Nimiq Styles Framework used to have a 8px base for fonts and spacing. The new library uses a default browser font-size. This means that you might need to adjust the spacing and font sizes in your components. You can modify the --nimiq-size variable like html { --nimiq-size: 8px; } but there might be some issues with this approach.

You can see the content of this file in the index.css file. Keep in mind, we are using now CSS layers.

You can learn about the new colors palette and the names in the Developer Center.

Automatic styles ​

In the previous version, you had to add the nq-style class to a container or use specific classes to apply the styles. Now, some of the styles are applied automatically using HTML elements as selectors.

If you don't want styles to be applied to a particular element, you can use the raw class to prevent this.

Basically, nimiq-css is opt-out, so you can remove the classes you don't want to use. The old Nimiq Styles Framework was opt-in, so you had to add the classes to apply the styles.

You can always "opt-out" of the styles by adding the raw class to the element.

The following components are automatically styled in the preflight.css file:

• Body with some default styles.
• Headings h1, h2 and h3. You can remove .nq-h1, .nq-h2 and .nq-h3. But, be aware that the margin-top and margin-bottom have been removed. You need to add them again using margin: 1rem 0.
• Paragraphs p. You can remove .nq-text.
• Paragraphs p and small do not have margin-top and margin-bottom anymore. You need to add them again using margin: 1rem 0 or margin: 0.5rem 0 respectively.
• <small> elements. You can remove .nq-text-s.
• <code> and <pre> elements.
• <input type="text"> and <textarea> elements. You can remove .nq-input.

Replace the classes ​

There are more "atomic" classes. You can see it in atomic.css.

Explicit classes ​

One of the goals of nimiq-css is to allow classes to be used in a more explicit way. So it is always preferable to use the classes in a more explicit way.

With nimiq-css, a new palette of colors has been implemented. You can also use the CSS variables as follows: rgb(var(--nq-neutral-900) / 0.8). You need to wrap it in rgb() to use it as a color.

Buttons & Pills ​

• There are 3 pill sizes. The default pill just use .nq-pill-{COLOR|VARIANT} like pill-green or pill-secondary. If you need other sizes you can use pill-lg or pill-xl.

Card ​

Before: ```html
<div class="nq-card">
  <div class="nq-card-header">
    <h1 class="nq-h1">Card Header</h1>
  </div>
  <div class="nq-card-body">
    <p>Card Body</p>
  </div>
  <div class="nq-card-footer">
    <a>Card Footer</a>
  </div>
</div>

After

<div class="nq-card">
  <header>
    <h1>Card Header</h1>
  </header>
  <section>
    <p>Card Body</p>
  </section>
  <footer>
    <a>Card Footer</a>
  </footer>
</div>

Text inputs ​

Removed classes and styles ​

Everything deleted in the new library is because it is not being used anymore, or not used it much. My main research has been done in the Nimiq Wallet + Hub + Keyguard, which it is our main product. If you think this is a mistake, we can add them back. But remember, you always have them in the legacy.css file.

There are two types of classes that have been removed. The ones replaced by default styles and the ones that are not being used anymore.

• .nq-text, .nq-style p: Now, all the <p> will have this styles.
• .nq-link, .nq-text a, .nq-style a: I don't think this is pretty useful as link are always super different.
• .nq-text-s has been deleted. Instead use the <small> HTML element.
• Heading elements like h1, h2, h3, h4, h5, h6 now do not have margin-top and margin-bottom. You need to add them again using margin: 1rem 0.
• p and small elements do not have margin-top and margin-bottom anymore. You need to add them again using margin: 1rem 0 or margin: 0.5rem 0 respectively.

Atomic CSS in nimiq-css ​

The old Nimiq Styles Framework used to have some atomic classes like flex-grow or hidden. Those classes still available in the new library. See more in the atomic.css file. This file is only used in native CSS. In framework like UnoCSS is not included.

Prose ​

nimiq-css comes with a new class nq-prose that it is useful to style the prose content. It is based on the Tailwind CSS Prose plugin. Just add .prose to you mardown wrapper and you are ready to go. You can also use this for smaller parts of your app.