@grimoirix/design (0.2.1)
Installation
@grimoirix:registry=npm config set @grimoirix:registry=npm install @grimoirix/design@0.2.1"@grimoirix/design": "0.2.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
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, WCAG AA contrast
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-helpdeskgrimoire-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 |