@grimoirix/design (0.1.1)

Published 2026-11-13 08:50:22 +00:00 by vivy in Grimoirix/grimoirix-frontend-template

Installation

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

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
  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/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:

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-13 08:50:22 +00:00
373
2026-11-18 20:01:33 +00:00
SEE LICENSE IN LICENSE.md
141 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