One Token Source for the Desktop: How “Nitida” Unifies GNOME Shell and GTK 4 in CardinalOS

November 2026 · CODLAB Editorial Team

Short answer: Traditional Linux desktops maintain separate styling rules for the system shell (GNOME Shell) and application windows (GTK 4 / libadwaita). For the in-development CardinalOS desktop, the “Nitida” visual layer defines colors, spacing, radii, and typography in one JSON token source, compiles target outputs deterministically in the design repository, and is being integrated in stages.

1. The Real Cause of Visual Fragmentation: Two Sources of Truth

A concrete example illustrates how desktop interfaces fragment: on many composite desktops, the top bar uses a slightly warmer charcoal than the Settings window, the Quick Settings menu applies different corner radii and padding than the file manager, and toggling between light and dark modes does not always update every panel along the same tonal scale.

There is a clear architectural reason for this. GNOME Shell renders the desktop environment chrome — top bar, Activities Overview, notifications, and OSD popups — through its own CSS engine (St / Clutter), whereas modern desktop applications render through GTK 4 and libadwaita. Each layer is well engineered on its own, yet each reads visual variables from separate files and naming conventions. Whenever an operating-system team tunes colors, focus rings, or spacing by hand in two places, changes can drift out of sync.

Alongside our preparatory work for CardinalOS, we explored separating a single token source from generated desktop stylesheets in our public prototype repository CodLab Thema (listed on our Projects & Products page). In a dedicated internal design repository, “Nitida” carries that single-source architecture forward for CardinalOS.

2. One Declarative JSON Token Source Instead of Hand-Edited Stylesheets

In the “Nitida” design repository, visual decisions live in a single declarative file (nitida.json) rather than scattered stylesheet edits, structured into design decisions and derived token sets:

• Design decisions, grid scale, and neutral surfaces (decisioni): Contrast rules, a spacing scale on multiples of the 4-pixel grid (spazi: 4, 8, 12, 16, 20, 24, 32, 40, 48 px), corner radii, typography, and the five neutral background layers tela, laterale, superficie, rialzo, and incavo for light and dark modes.
• Derived color and state roles (colori and contrasto_elevato): Text and border hierarchies (testo, testo2, testo3, bordo) plus nine calibrated accent families (default red «Cardinale») with roles such as pieno, su, testo, tenue, selezione, and anello across light, dark, and high-contrast variants.

The deterministic script genera.py compiles nitida.json without embedded magic numbers into the repository’s output artifacts:

1. For GNOME Shell, genera.py emits St stylesheets under shell/ (including dedicated text-scaling sheets plus movimento.css and movimento-ridotto.css) alongside veste.json.
2. For GTK 4 / libadwaita and companion surfaces, the same run emits stylesheets under gtk/, gecko/ (for Cardinal Mail), and browser themes under firefox/ and chrome/.

Across all generated artifacts in the design repository, colors, spacing, and focus tokens stay tied to one file; wiring every generated output into all live desktop surfaces remains staged work in progress.

3. Dedicated Verification Judges for Contrast and Cascade

Visual calm must not come at the expense of readability. Minimalist interfaces frequently fall into the trap of low-contrast gray labels that become tiring to read on an ordinary office monitor in daylight.

In the “Nitida” repository, artifact generation and verification are kept cleanly separate: while genera.py only writes target files, independent judge scripts under giudici/ (notably armonia.py and cascata.py) verify nitida.json and the emitted stylesheets against WCAG contrast formulas (mirroring our web workflow in Checking accessibility before deploy):

• Primary and secondary text across all five neutral surfaces: Verified at or above 7.0 : 1 in standard mode (10.0 : 1 for secondary text in high-contrast mode).
• Tertiary text, accent text, and semantic status roles: Verified at or above 4.5 : 1 against their surfaces (7.0 : 1 in high-contrast mode) so secondary hints stay readable.
• Focus ring (anello) and control borders (bordo): Checked at or above 3.0 : 1 against defined surfaces per WCAG 1.4.11; these checks validate the token pairs in the design repository, while end-to-end verification of every widget across all planned apps precedes public release.

Whenever a modified value in nitida.json violates one of those thresholds or creates overlapping St selectors, the verification judges under giudici/ report a failure.

4. Measured Motion: Generated Motion Stylesheets and Reduced-Motion Design Rule

Motion on a desktop is helpful only when it clarifies spatial relationships — such as moving between workspaces. Overly long, bouncy, or constant animations create visual fatigue and can cause discomfort for users with vestibular sensitivity.

In the “Nitida” design repository, this principle is currently implemented at the generated-artifact layer: alongside shell/movimento.css with brief transition durations from nitida.json, genera.py emits a paired shell/movimento-ridotto.css stylesheet that sets those Shell transition durations to 0 ms, together with the motion tokens in veste.json. As a design rule for CardinalOS, both the Shell via enable-animations = false in GSettings and embedded web or Help views via prefers-reduced-motion: reduce are intended to disable decorative motion; because only an unsigned partial preview is armed today, end-to-end verification across every live desktop surface remains open before release — whereas our mascot Mochi here on codlab.de already enforces this rule.

5. Ten Planned Applications in the Cardinal Family

A desktop design system proves its value when everyday tools work side by side. Ten coordinated applications are planned for the Cardinal Family in CardinalOS: Cardinal Write, Cardinal Sheets, Cardinal Slides, Cardinal PDF, Cardinal Mail, Cardinal Chat, Cardinal Photo, Cardinal Film, Cardinal Studio, and Cardinal Host.

Rather than rewriting mature engines from scratch, CodLab builds on proven open-source foundations, keeps upstream authors visibly credited, and aligns header bars, sidebars, dialogs, and iconography step by step with “Nitida” tokens. Today, Cardinal Photo is installed on our development workstation and six candidates overall are staged in the development environment, while others — including Cardinal Slides and Cardinal Studio — remain under integration, signing, and license review. Listing an application name on the website indicates a planned engineering target, not a published release package.

6. Honest Engineering Boundaries: What “Nitida” Covers Today — and What Remains Open

Trustworthy systems engineering means stating current status and architectural limits upfront:

• Current development status (November 2026): Neither CardinalOS nor “Nitida” has been shipped as a public OS image yet. The JSON generator and contrast judges run deterministically in the design repository; on the desktop, only an unsigned partial preview for panel and glass surfaces is armed today, while dock, Activities Overview, window frames, lock screen, global GTK, and full Cardinal Family integration remain open.
• Third-party custom toolkits: Because CardinalOS is designed as an open Linux desktop, users can install any Flatpak or containerized app. Applications that render custom toolkits without reading GTK 4 system tokens — such as certain Electron apps, game launchers, or specialized studio tools — keep their native appearance without forced recoloring.
• Semantic signal colors: Where third-party apps intentionally define semantic warning or brand colors, “Nitida” is designed to avoid blind overrides that could obscure safety or status cues.

You can inspect captures from isolated GNOME development sessions on the CardinalOS product page on codlab.de and sign up for the release notification on cardinalos.org.