@digitalservicebund/ris-ui

RIS UI

Component library for NeuRIS | 👀 Demo | 📦 npm | 🤖 PrimeVue Docs

Installation

RUI UI contains three things:

• a theme for Vue 3 components from PrimeVue 4;
• custom components;
• a preset and plugin for Tailwind that sets some global styling and exposes the design tokens used by the theme, so you can build custom UI that looks consistent with the components.

Vue and PrimeVue are required for RIS UI to work (you'll see a warning about missing peer dependencies if you're trying to use RIS UI without them). Tailwind is optional. To get started, install:

# Vue and PrimeVue if you haven't installed them already. Tailwind is optional.
npm install vue primevue tailwindcss

# RIS UI
npm install @digitalservicebund/ris-ui

Vue setup

[!NOTE]

If you're using Nuxt, follow the instructions for Nuxt below instead.

Import and apply the RIS UI theme, styling, and fonts where you set up your application (typically main.ts):

  // main.ts
  import { createApp } from "vue";
  import PrimeVue from "primevue/config";
+ import { RisUiTheme, RisUiLocale } from "@digitalservicebund/ris-ui/primevue";
+ import "@digitalservicebund/ris-ui/primevue/style.css";
+ import "@digitalservicebund/ris-ui/fonts.css";

  const app = createApp().use(PrimeVue, {
+   unstyled: true,
+   pt: RisUiTheme,
+   locale: RisUiLocale.deDE
  })

Nuxt setup

If using Nuxt, skip the Vue setup above.

Install the Nuxt PrimeVue module:

npm install @primevue/nuxt-module

Add the PrimeVue module and configure it in nuxt.config.ts:

  // nuxt.config.ts
  export default defineNuxtConfig({
    // your other configuration
    modules: [
+     "@primevue/nuxt-module",
    ],
+   primevue: {
+      usePrimeVue: false, // configured in plugins/ris-ui.ts
+   },
  })

Add a new Nuxt plugin to configure PrimeVue:

// plugins/ris-ui.ts
import { RisUiTheme } from "@digitalservicebund/ris-ui/primevue";
import PrimeVue from "primevue/config";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(PrimeVue, {
    pt: RisUiTheme,
    unstyled: true,
  });
});

Finally, add the styles (e.g. assets/main.css):

@import "@digitalservicebund/ris-ui/primevue/style.css";
@import "@digitalservicebund/ris-ui/fonts.css";

/* Your other CSS */

If not using Tailwind, you may also add these styles directly to the css section of nuxt.config.ts.

With Tailwind

If you want, also install the Tailwind preset (for colors, spacings, etc.) and plugin (for typography classes, etc.):

  // tailwind.config.js
+ import { RisUiPreset, RisUiPlugin } from "@digitalservicebund/ris-ui/tailwind";

  export default {
+   presets: [RisUiPreset],
+   plugins: [RisUiPlugin],

    // your other configuration
  };

To avoid issues with conflicting @layer directives, make sure to integrate the postcss-import module in your PostCSS configuration:

See Adding custom styles - Tailwind CSS.

If you're using Nuxt, you may add the postcss-import module to your nuxt.config.ts file:

  // nuxt.config.ts
  postcss: {
    plugins: {
+     "postcss-import": {},
      tailwindcss: {},
      autoprefixer: {},
    },
  },

Development

To make changes to RIS UI, you'll need the current Node.js LTS along with npm installed on your machine.

To get started, first clone this repository:

git clone https://github.com/digitalservicebund/ris-ui.git

Then install dependencies:

npm install

# This will populate the public/fonts folder. See public/fonts/.gitkeep
# for more information.
npm run sync-fonts

You can now run a local preview to see any changes you make to the code:

npm run storybook

Check out package.json for additional scripts.

Repository contents

RIS UI uses the following tools:

• Storybook, a playground for previewing components and styling
• Tailwind for styling
• Vite as our dev server and bundler
• Unplugin Icons for providing SVG icons as components
• TypeScript
• ESLint and Prettier for code consistency
• Vitest as our test runner

You can find more in package.json, but the above are the ones you'll work with the most.

In terms of files and folders, you'll find:

Folder	Contents
(root)	General docs and configuration
.github/	GitHub Actions configuration
.storybook/	Storybook setup
src/components	Custom Vue components
src/primevue	The RIS UI preset for PrimeVue
src/tailwind	The RIS UI preset and plugin for Tailwind
src/lib	Internal tools and helpers

Tailwind IntelliSense

If you're using VS Code with the official Tailwind extension, you can get autocompletions and more by adding this to your VS Code settings:

{
  // other settings
  "tailwindCSS.experimental.classRegex": ["tw`([^`]*)`"],
}

This will detect Tailwind CSS classes in template strings tagged with tw such as:

import { tw } from "@/lib/tags";

const classes = tw`bg-blue-200 px-16`;

See tags.ts for more information.

Committing

Before making your first commit, you'll need some additional prerequisites installed. These help us with code consistency and quality:

• GitHub CLI: Used for checking the pipeline status before pushing
• jq: Used by our license check, which ensures all our dependencies use allowed licenses only
• Lefthook: Runs Git commit hooks
• Talisman: Validates you're not accidentially committing secrets

Once they're installed, run:

# In ./ris-ui
lefthook install

When you make a commit now, Lefthook will ensure your changes and commit message adhere to our coding guidelines:

• Code is formatted with Prettier
• ESLint passes without warnings
• The commit message follows the Conventional Commits specification. If you're making changes to a component, please use the component name as the scope (multiple scopes are allowed).

Keep in mind that your commit messages will be used for generating changelogs and inferring version numbers when making a release. If you made multiple changes, please consider squashing them to keep the history, as well as the changelogs, tidy and readable.

Making a release

To release a new version, run the "Release to npm" action. This will:

• Build the project
• Publish the build to npm
• Create a Git tag and GitHub release
• Generate a changelog based on the commits since the last release

Releases are created automatically by semantic-release. Please refer to their documentation to learn more about how version numbers are inferred and how changelogs are created.

Contributing

See CONTRIBUTING.md.