phinger-cursors: a cursor theme built from parts, a schema and a Figma file

The over-engineering is the feature

Phinger Cursors is introduced with a line that reads as a joke and turns out to be a design brief. It is most likely the most over engineered cursor theme out there, and the readme then spends its length explaining what the engineering is.

The structure is layered, and each layer exists to make the next one possible. There are parts, which are the reusable pieces a cursor is drawn from. There are sprites, which are the parts assembled and styled, named and given the metadata that a cursor theme needs. And there is the theme itself, the set of sprites packaged for an operating system to read.

The parts are the key idea. Every cursor sprite is assembled from core parts, so changing one part changes every sprite that uses it, and the readme says the parts are designed very modularly, which lets one part produce several different icons. The example given is the hand, which comes with a variation for each phinger, so the fingers are separate parts and the hand is the frame around them.

Each part is designed on a base grid of 24 and 32, and the readme claims that this makes the result pixel perfect for any reasonable size. The table of sprites makes the claim concrete, showing the same cursor rendered at 24, 32, 48, 64, 72, 96 and 128.

So the theme is not a folder of hand-drawn cursor images. It is a small assembly system, and the reason a finger can be reused across every hand is that the hand is not a picture of a hand but a frame plus a set of interchangeable fingers. That is a good deal of engineering for a mouse pointer, and it is the reason the project is interesting rather than merely decorative.

Four installation routes, and one package name that is spelled differently

The install section covers four situations, and the first three are handled by distributions rather than by the project.

On Arch Linux the author maintains a package in the user repository, and the readme suggests an AUR helper:

paru -S phinger-cursors

There is a note attached to that, asking to be told if anyone wants to maintain the package in the official Arch Linux repositories so the instructions can be updated, which tells you the maintainer is doing packaging work that upstream distributions usually take over.

Ubuntu is served by a distribution package, with the readme crediting the person who packaged it:

apt-get update
apt-get install phinger-cursor-theme

The name of that package is worth reading twice, because it is spelled differently from the project and from the Arch package. That is the kind of detail that costs a user ten minutes and a search.

NixOS is covered too, through the configuration file:

environment.systemPackages = with pkgs; [
  phinger-cursors
];

and the readme also gives a home-manager configuration for the pointer cursor specifically, naming the light variant, pointing at the package, setting a size of 32 and enabling GTK, which is a nice detail because the pointer cursor size is the one setting users actually change.

The manual route is a tarball extracted into the icon directory for the current user, or into the system directory for all users, and the readme gives the one-line download and extract.

Enabling the theme is a second job

Installing the files is not the same as using the theme, and the readme is careful to separate the two.

If you have a settings application installed that can do it, the readme names three: GNOME Tweaks, a tool called nwg-look, and LXAppearance. Otherwise you enable it manually, and the manual path is two files.

The first is the default icon theme file, where the theme is declared by inheritance:

[Icon Theme]
Name=Default
Comment=Default Cursor Theme
Inherits=phinger-cursors-light

The second is the GTK settings file, where the cursor theme is named directly:

[Settings]
gtk-cursor-theme-name=phinger-cursors-light

Both point at a variant name, and the readme lists the four: a dark variant, a light variant, and their left-handed counterparts. So the choice a user makes is not just light or dark, it is also which hand, and the inheritance in the icon theme file is the mechanism that makes the cursor part of the theme rather than a separate setting.

That two-file dance is standard for X11 icon and cursor themes, and it is also the reason a settings application is worth having. Nothing about it is specific to this project, but a project that adds four variants makes the choice explicit rather than leaving it to a single setting in a preferences panel.

Cursor size is a per desktop environment question

The size section is the most environment-specific part of the readme, and it lists the sizes first: 24, 32, 48, 64, 96 and 128.

Then it gives a command per desktop environment, with a placeholder to be replaced by the size you want. On GNOME it is a settings call on the desktop interface schema, on MATE it is a call on the peripherals-mouse schema, and on Xfce it is a configuration query that sets the GTK cursor theme size property on the xsettings channel.

The MATE entry is worth a second look, because the schema it uses is the GNOME one rather than a MATE specific one, which is the kind of quirk that makes a settings application valuable. The readme also covers the older X11 resource path, where the size goes into the X resources file as a cursor size setting.

So the same theme is resized four different ways depending on the desktop, which is a fair summary of what a cursor theme has to live with on Linux. Wayland appears in the topic list of the repository, and the home-manager configuration shows the pointer cursor being set through that path, but the manual instructions in the readme are the X11 ones, with the icon theme inheritance and the GTK settings file.

The design pipeline runs from Figma to a JSON schema

How it is made is the section that makes this project more than a folder of images.

The cursors are designed in a Figma document, and the readme links the multi-page document and notes that an up to date copy lives in the repository root as a Figma file. That file is part of the repository, which matters for a licensed project, and it is also what makes the build reproducible.

From Figma, the pipeline moves through a separate tool, the Cursor Theme Builder. The readme describes what that tool provides: a JSON schema to describe a cursor theme, an exporter that creates such a JSON file and the assets from a Figma file, and a builder that makes fully functioning X11 cursor theme variants from it. It also transforms cursors into left-handed versions and includes an animation system.

The metadata carried by a sprite is the other half of the story. Each cursor records which cursor and variant it belongs to, what its aliases should be, how to transform it into a left-handed cursor, a hotspot element, and instructions for how it should be animated. That is a lot of information for a picture, and it is what lets the builder produce a theme with the aliases an application expects, with a hotspot that lands where the pointer tip should be, and with a frame sequence for the animated cursors.

The repository contains workflows that extract the theme JSON and the assets and that draft a release with the built variants, so the whole chain from a design file to a downloadable tarball is in version control.

A share-alike licence, a lineage of inspiration, and an issue tracker for feedback

The licence and credits section is short and has a detail that matters for anyone who wants to reuse the assets.

All the assets, and that includes the Figma document itself, are licensed under the Creative Commons share-alike licence, version 4.0. Since the source artwork is in the repository, a modified theme that is redistributed carries the same obligation, and the design file travels with the assets rather than being kept private.

The lineage is acknowledged as well. The cursors were designed from scratch, but they drew inspiration from another cursor theme, which is itself based on the KDE Breeze cursors, and the readme thanks both along with every other cursor theme out there.

The contribution section sets a boundary that is worth stating plainly. Issues are the way in, for missing cursors, for symlinks that do not look right and for design suggestions. But the author says he cannot let people contribute to the Figma document directly, and will listen to constructive feedback through the issues instead. So the design file is a single source of truth under one person's control, and the repository is where the discussion happens.

There is also a community pointer, a Discord server for people who make Linux desktop projects, and a note that the author is working on the cursors and other projects there. The release history shows the rhythm: version 2.0 in April 2024, a 2.1 in July 2024 described as fixing a whoops, and a 2.2 in October 2026, with the last push on the same day.

Editorial conclusion

Adopt Phinger Cursors if you ricing a Linux desktop and want a theme with a genuine design system behind it, with a dark and a light variant plus left-handed versions and six pixel sizes, rather than a repackaged set of icons. Do not adopt it expecting the installer to configure everything, because enabling the theme after installing it is a separate manual step in most environments. Before you commit, check the package names in your distribution's repository, since the Ubuntu package name is spelled differently from the project name, and remember that the artwork and the Figma source are under a share-alike licence, so a modified theme you distribute has obligations.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-SA-4.0
3. phisch/phinger-cursors on GitHub
4. README
5. Releases