From db716838cfa781204c7778b882ed35d5fe5f48ee Mon Sep 17 00:00:00 2001 From: Philipp Schaffrath Date: Wed, 26 Jan 2022 00:32:33 +0100 Subject: [PATCH] added documentation and presentation --- README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 91 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f2beafb..3d893b8 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,91 @@ -# phinger-cursors -The most over engineered cursor theme. +# Phinger cursors + +Say hello to your new cursor theme. Phinger cursors is most likely the most over engineered cursor theme out there. + +![preview](assets/preview.png) + +## How to install + +Download [phinger-cursors-variants.tar.bz2](https://github.com/phisch/phinger-cursors/releases/latest/download/phinger-cursors-variants.tar.bz2) from the latest release, or any other [release](https://github.com/phisch/phinger-cursors/releases). + +And extract it into your users `~/.icons` directory: +```sh +tar -xf phinger-cursors-variants.tar.bz2 -C ~/.icons +``` + +Enable your prefered variant (`phinger-cursors` or `phinger-cursors-light`) inside `~/.icons/default/index.theme`: +```ini +[Icon Theme] +Name=Default +Comment=Default Cursor Theme +Inherits=phinger-cursors-light +``` + +And finally, enable it for GTK applications in your `~/.config/gtk-3.0/settings.ini`: +```ini +[Settings] +gtk-cursor-theme-name=phinger-cursors-light +``` + +### Distro repositories + +At the time of writing this, phinger-cursors are not yet part of any major distro repos. So you are not yet able to install this through your favourite package manager. + +Hopefully this will change soon enough to make installation easier. + +## How it's made + +Phinger-cursors are designed in a [Figma](https://www.figma.com) document. Check out the [multi-page Figma document](https://www.figma.com/file/zU99op23bu3Cg438YkhZy8/phinger-cursors) used by this repository. + +You can find an up to date copy of that document in this repositories root directory at [phinger-cursors.fig](phinger-cursors.fig). + +### Parts + +Every cursor sprite is assembled from core parts. Changing one of those parts, will change every cursor sprite that uses it. + +![parts](assets/parts.png) + +Each part is designed on a base grid of 24 and 32: + +![parts](assets/grid sizes.png) + +which means will be pixel perfect for any reasonable size: + +| 24 | 32 | 48 | 64 | 96 | 128 | +|:-:|:-:|:-:|:-:|:-:|:-:| +| ![24](assets/sprite__24.png) | ![32](assets/sprite__32.png) | ![48](assets/sprite__48.png) | ![64](assets/sprite__64.png) | ![96](assets/sprite__96.png) | ![128](assets/sprite__128.png) | + +If possible, parts are designed very modular, which lets you create multiple different icons from one part. A good example is the hand part that comes with multiple variations for each single phinger: + +![phingers](assets/phingers.png) + +### Sprites + +The parts are assembled, and styled into sprites. Those sprites are named and contain metadata necessary to generate a cursor theme from them. Each sprite contains a name, information about the cursor hotspot, animation and which kind of variant it is. + +### Build process + +This repository contains a GitHub workflow, that generates a fully functional X11 cursor theme and variants from the linked figma file. The workflow is defined in [.github/workflows/main.yml](.github/workflows/main.yml). + +It uses the custom made GitHub Action [phisch/figma-cursor-theme-action](https://github.com/phisch/figma-cursor-theme-action) to do that. + +This action exports assets from the Figma file and commits them to [assets](assets), then renders the sprites into pngs and packs them into proper (and if necessary animated) x11 cursor files. It also generates symlinks and variants, bundles them, and creates a release. + +Please refer to the actions [README.md](https://github.com/phisch/figma-cursor-theme-action#readme) for a detailed documentation. + +## License & Credits +All assets, including the Figma document are licensed under the [CC-BY-SA-4.0 License](LICENSE). + +The X11 and Wayland cursors are designed from scratch, and not copied. The original logos belong to X11 and Wayland respectively though. + +Although designed from scratch, phinger cursors drew inspiration from [capitaine-cursors](https://github.com/keeferrourke/capitaine-cursors), which is based on the KDE Breeze cursors. So this is a special thanks to them, and all other amazing cursor themes out there! + +## Contribute + +If you notice any issues like missing cursors or symlinks, something doesn't look quite right to you, or you have suggestions for better designs or new cursors, please open an issue and let me know about it. + +I can't let people contribute to the Figma document directly, but I will listen to constructive feedback through GitHub issues. + +## Support + +If you really enjoy this project, sponsor me a pizza.