Lucidglyph

About

Improvements for the Linux font rendering stack.

Includes tweaks for FreeType, Fontconfig, and other components. See
Details for more information, and Notes for the list of
after-install recommendations and known issues with their possible mitigations.

What it does?

• Improves clarity of medium and small fonts.
• Ensures consistent rendering across displays with varying pixel densities.
• Keeps system components and fonts intact. Only rendering tweaks.

Visual comparison is available on the project's
wiki page.

Note that this project is just a collection of tweaks that reflect the
author's vision on how font rendering should look like.

Due to the nature of the rendering stack features used in this project being
still experimental or even completely not supported by most of the Linux
desktop environments (like proper gamma correction and blending), correct
rendering cannot be guaranteed in some cases.

Previously known as freetype-envision

Usage

Install

Download the latest release from
the releases page
(Assets - Source code) and unpack it.

Open the terminal in the unpacked directory and execute the command below with
elevated permissions:

shCopy
sudo ./lucidglyph.sh install

See User mode for per-user installation.

Then reboot to apply the changes.

Remove

Use the same script from the section above with elevated permissions:

shCopy
sudo ./lucidglyph.sh remove

Then reboot to apply the changes.

Upgrade

Follow the steps from the Install section above and the script will
request user confirmation to allow the upgrade.

User Mode

Warning

Experimental feature, expect things not to work as intended. User feedback is
greatly appreciated.

Caution

If you are a power user who relies heavily on symbolic links for custom
Fontconfig rules and use lucidglyph versions from 0.10.0 to 0.11.1,
please check this to
avoid possible corruption of symlinks during an upgrade or removal of this
project in per-user mode.

This issue has been resolved and mitigated in 0.12.0 release. No manual
intervention is required.

User mode allows the project to be installed for the current user only, without
any need for elevated privileges (sudo) or system-wide changes.

To activate this mode, pass the --user (or -u) argument on main script run:

shCopy
./lucidglyph.sh --user [COMMAND]

Blacklist

Specific modules can be blacklisted individually, disabling the desired parts
of the project.

The blacklist should be provided through the --blacklist (-b) option when
calling the install command and will be automatically preserved between
updates. One --blacklist option can hold only one module name or glob pattern
provided in literal string format (single quotes).

You can get the names of the modules by inspecting the contents of the
src/modules/ directory.

The below example will prevent modules from being installed in the respective
order:

• src/modules/environment/lucidglyph-freetype-properties.conf
• src/modules/fontconfig/11-lucidglyph-grayscale.conf

shCopy
sudo ./lucidglyph.sh install \
    -b 'environment/*freetype-properties*' \
    -b 'fontconfig/*grayscale*'

Notes

Font Recommendations

Below are the lists of fonts that are recommended (and not) for use with
lucidglyph installed. These are subjective, opinionated suggestions, not strict
guidelines - hence, lucidglyph does not enforce any font overwrites by itself.

Fonts in the "Not Recommended" group are generally not recommended for usage
due to poor legibility and improper geometry at small sizes after
stem-darkening (see Details).

Serif:

• Noto Serif

Sans-serif:

• Inter, Adwaita Sans
• Noto Sans

Not Recommended:

• Cantarell

Monospace:

• DejaVu Sans Mono
• MesloLG, Menlo
• JetBrains Mono

Font Hinting

This project does not assign the hinting settings forcefully, only "suggesting"
the system to use the "Slight" hinting if no other option is set. This is the
intended behavior since hinting settings are usually really taste-dependent, so
the final choice was left to the end user.

Flatpak

Flatpak provides a sandboxed environment for any software run through it, which
implies having a strict set of permissions. If the package maintainer fails to
configure the permissions properly, which is not a rare case, access to some
directories with important configuration files may be restricted.

After the per-user install, if you start noticing the differences
in font rendering between system and Flatpak software:

Execute the command below to check if the sandbox of the specific package has
access to the per-user font configuration directory. Replace <PACKAGE-ID> with
the real package name:

shCopy
flatpak run --command=sh <PACKAGE-ID> \
    -c '[ ! -r "$HOME/.config/fontconfig" ] && echo "Access Denied"'

If the command above outputs "Access Denied" then you will have to manually
allow the sandbox to access the specified directory (read-only mode is
sufficient).

This can be done either for this specific package:

shCopy
flatpak override --user --filesystem=xdg-config/fontconfig:ro <PACKAGE-ID>

Or create a global override that will affect all Flatpak software:

shCopy
flatpak override --user --filesystem=xdg-config/fontconfig:ro

Be careful since creating global overrides may brake some Flatpak software.

To revert this specific change, execute:

shCopy
flatpak override --user --nofilesystem=xdg-config/fontconfig <PACKAGE-ID>

Alternatively, reset all the package permissions to defaults, also cleaning the
entry from ~/.local/share/flatpak/overrides/, by executing:

flatpak override --user --reset <PACKAGE-ID>

Chromium

Starting from version 133 (February 2025), Chromium now uses the self-written
replacement for FreeType called Fontations, as a new font system, with Skrifa
library being responsible for rendering in it.

Skrifa currently lacks any stem-darkening support¹, which is one of the
crucial parts of the lucidglyph project (see Details).

In Chromium 139.0.7258 the flag that was previously used to turn back the
FreeType rendering backend was completely removed² with one of the
contributors stating that they "...no longer intend to carry the FreeType
support."³.

There's nothing more I can do here until the Fontations stack matures enough to
support the required functionality other than suggest switching your browser of
choice to any non-chromium-based one or make use of scaling and zoom features.

For the software that is still based on older Chromium versions, you can switch
to FreeType rendering in several ways:

Command Line
Launch the software with the --disable-features flag:

shCopy
$ <software> --disable-features=FontationsFontBackend

Manual

1. Open this link: chrome://flags/#enable-fontations-backend
2. Set the flag to Disabled.
3. Restart the browser by closing the window.

You can track the detailed progress on this issue
here.

GNOME

While GNOME does use the grayscale anti-aliasing method by default, there are a
few Linux distributions that change this setting to the sub-pixel method,
making the font rendering appear incorrect after the tweaks from this project.

To check if your system is configured properly:

1. Open the terminal
2. Execute the command below to query the current configuration:

   bashCopy
   gsettings get org.gnome.desktop.interface font-antialiasing

3. If the output of the above command looks like this:

   bashCopy
   'rgba'

4. Then execute the command below to set a proper font anti-aliasing:

   bashCopy
   gsettings set org.gnome.desktop.interface font-antialiasing grayscale

To revert the above changes to a system defaults just execute this command:

bashCopy
gsettings reset org.gnome.desktop.interface font-antialiasing

KDE Plasma

By default, the vanilla Plasma desktop environment does follow the Fontconfig
rules, including the anti-aliasing settings, but in some cases this behavior
gets overwritten, causing an improper font rendering due to misconfigured
anti-aliasing parameters.

The problem arises due to a regression in the KDE Plasma text rendering stack,
which forces an incorrect configuration when fractional scaling is used.

This issue is already being tracked⁴ on the KDE tracker but still requires a
manual intervention.

To fix it:

1. Open the System Settings
2. Go to the "Appearance & Style" - "Text & Fonts"
3. Ensure that "Sub-pixel rendering" is set to "None"

Kitty Terminal

Rendering of some fonts dark (foreground) on light (background) (aka light
themes) in Kitty may discard most of the applied stem-darkening (see
Details) due to the nature of gamma correction. The lack of
darkening is easily visually detectable by very thin-appearing glyphs.

To remedy this issue, append this modified
text_composition_strategy
parameter to Kitty's user configuration file:

confCopy
text_composition_strategy 1.7 0

Decrease or increase the value 1.7 to decrease or increase the emboldening
effect, respectively.

Sway Window Manager

Sway Window Manager does not respect global font anti-aliasing settings,
resulting in subpixel anti-aliasing being used instead of grayscale.

To remedy this issue, append the following content to your window manager
configuration file:

confCopy
output * subpixel none

For a more detailed explanation of this entry, please refer to the official
SwayWM man page:

shellCopy
man --pager='less -p "output <name> subpixel"' sway-output

Details

• Environment variables:

  • FreeType stem-darkening for autofitter (including custom darkening
    values), type1, t1cid and cff drivers. This feature improves
    visibility of the medium and small-sized fonts. Especially helpful on the
    low pixel density (LowPPI) outputs.
    Basics Article
    and
    Usage Documentation.

  • Disable synthesized bold fonts in Qt-based software. There is an issue
    that causes bold glyphs to appear heavy in variable fonts.
    Reports:
    Red Hat Bugzilla,
    Fedora Tracker,
    Qt Report.

• Rules for Fontconfig:

  • Enforce grayscale anti-aliasing (disable sub-pixel). Grayscale
    anti-aliasing should be enforced in the system to make the stem-darkening
    from the above work properly.

  • Suggest the client to use the "Slight" font hinting style, which is the
    preferred style for both preserving the original geometry and providing
    legibility. Only applied if the target system misses any hinting
    configuration.

  • Additional emboldening. This rule supplements the main FreeType
    stem-darkening on very small glyph sizes by utilizing the built-in
    emboldening feature of Fontconfig. There is a significant chance that some
    software may not support this feature.

  • Automatic icon-type font detection. Switches off the Fontconfig emboldening
    and hinting for such fonts to prevent glyphs from stem-darkening
    "over-emboldening".

  • Manual icon-type font detection that temporarily supplements the automatic
    mode. Same goal, targeted approach.

  • Reject usage of "Droid Sans" family for Japanese and Chinese characters
    and force the environment to use other fonts. Stem-darkening does not work
    well with this typeface, causing characters over-emboldening.

Footnotes

1. https://github.com/googlefonts/fontations/issues/1407 ↩

2. https://chromiumdash.appspot.com/commit/2fc1ae192a45eb6f1716e232dd1626317f8d299e ↩

3. https://github.com/googlefonts/fontations/pull/1496#issuecomment-3004330901 ↩

4. https://bugs.kde.org/show_bug.cgi?id=501715 ↩