@grimoirix/design (0.2.0)

Published 2026-11-17 07:26:04 +00:00 by vivy in Grimoirix/grimoirix-frontend-template

Installation

@grimoirix:registry=
npm config set @grimoirix:registry=
npm install @grimoirix/design@0.2.0
"@grimoirix/design": "0.2.0"

About this package

Grimoirix front-end template

A spellbook library of open-source tools. In a closed world, Grimoirix builds bridges. "Freedom is a choice. Share it."

The starting point for every Grimoirix project that has a front end.

This is the preferred design and a reference, not a hard rule. A project may use other colours where it has a reason to.

What is in it

design/
  grimoirix-design-system.md   the rules — read this first
  grimoirix-color-scheme.md    the palette and the token names
  grimoirix-example.html       a working example page
  scss/                        the source: tokens, fonts, base, gx- components
  css/grimoirix.css            scss/ compiled (generated)
  ts/theme.ts                  dark/light switch, no dependencies
  ts/react.ts                  useTheme() hook for React
  ts/components.tsx            notifications, dismissible error, section menu (React)
  js/                          ts/theme.ts compiled (generated)
  fonts/                       the two fonts, self-hosted

design/README.md says what each file is.

Use it

The design is published as the npm package @grimoirix/design on our forge's package registry. The repository and the package are public, so no token is needed to install it.

1. Tell npm where @grimoirix packages live. Put this .npmrc next to the front end's package.json:

@grimoirix:registry=https://git.grimoirix.org/api/packages/Grimoirix/npm/

This is the default, not a fixed value: a mirror can override it with npm config set @grimoirix:registry <url> or the environment variable NPM_CONFIG_@GRIMOIRIX:REGISTRY.

2. Install it.

npm install @grimoirix/design

3. Use it.

// main.ts / main.tsx — before anything renders
import { initTheme } from '@grimoirix/design/theme'
initTheme()
/* the first line of the app's stylesheet */
@import '@grimoirix/design/css';
// React: a theme toggle
import { useTheme } from '@grimoirix/design/react'

A Sass project can use the source instead of the compiled CSS: @use '@grimoirix/design/scss' with ($font-url: '...').

Then build the screens from the gx- classes and the var(--…) tokens. The two hard rules: dark mode is the default, and never pure white (#FFFFFF).

Import What it is
@grimoirix/design/css the compiled styles, fonts included
@grimoirix/design/scss the Sass source
@grimoirix/design/theme the dark/light switch (TypeScript)
@grimoirix/design/react useTheme() for React
@grimoirix/design/components notifications, dismissible error, section menu (React)
@grimoirix/design/theme.js the switch as plain ES module JavaScript
@grimoirix/design/fonts/* the font files

Pick up a design change: npm update @grimoirix/design, as one pull request in that project. Versions follow semantic versioning: a PATCH or MINOR release never needs a code change in the project; a MAJOR release says in its notes what to change.

New project: on the forge, choose New repository and pick this repository as the template, or start empty and follow the three steps above.

Change the design

The colours, fonts and components are defined once, in design/scss/ and design/ts/. Change them here, by pull request to dev.

A shared look is changed here first, never only in a project. If a project needs a new gx- class, a fix to an existing one, or a React component that another project could use, it goes into this package, is released, and the project takes the new version. A project's own stylesheet keeps only what is specific to that product (for example the device card in signage). The product owner's rule (GRI-2168): every project uses the same things, and this template holds all of it, SCSS to TypeScript.

To build and check:

npm ci
npm run build   # scss -> css/grimoirix.css, ts -> js/
npm run check   # generated files up to date, formatting, types

Commit the generated css/ and js/ with the source.

Release it when the change is merged: raise version in package.json (semantic versioning), tag the commit v<version>, and publish with a forge token that has the write:package scope:

npm publish --//git.grimoirix.org/api/packages/Grimoirix/npm/:_authToken=<token>

Projects using it today:

  • grimoire-of-helpdesk
  • grimoire-of-digital-signage

License

See LICENSE.md.

Dependencies

Development dependencies

ID Version
@types/react ^19.2.0
esbuild ^0.25.12
prettier ^3.6.0
sass ^1.93.0
typescript ^5.9.0

Peer dependencies

ID Version
react >=18
Details
npm
2026-11-17 07:26:04 +00:00
244
2026-11-19 16:55:05 +00:00
SEE LICENSE IN LICENSE.md
147 KiB
Assets (1)
Versions (3) View all
0.2.1 2026-11-19
0.2.0 2026-11-17
0.1.1 2026-11-13