olive-css - NFHN Reader

Utility-class vanilla CSS framework inspired by Tailwind syntax, easy to learn and hack, written in Lisp (Guile Scheme)

You can use this in any web project, Scheme or not, and it serves as a kind-of drop-in replacement for Tailwind.

This project is licensed under the Lesser GNU General Public License v3 or later.

You can read more about Olive CSS's features and syntax here, in the documentation page:

/jjba23/olive-css/src/branch/trunk/docs/olive/olive.org

You can also find olive-css technical Guile Scheme API documentation here:

https://jointhefreeworld.org/api-docs/olive-css/API.html

You can use Olive CSS like any other utility-class CSS framework, like this:

<div class="m-2 px-4 py-6 bg-jeans-blue-500 md:bg-asparagus-300 hover:bg-tawny-700">
  <span class="text-white font-bold font-serif">Hello Olive CSS!</span>
</div>

If you like my work, please support me by buying me a cup of coffee ☕ so I can continue with a lot of motivation.

Licensing

olive-css and all of its source code are free software, licensed under the GNU Lesser General Public License v3 (or newer at your convenience).

https://www.gnu.org/licenses/lgpl-3.0.html

The showcase site, documentation and examples, including this document, which are provided with olive-css, are all licensed under the GNU Free Documentation License v1.3 (or newer at your convenience).

https://www.gnu.org/licenses/fdl-1.3.html

Installing and Using

Installing and using Olive CSS is as simple as downloading a pre-built version from resources/css/ directory, or building your own, and serving it via HTTP (of course also loading it in a <link> tag in your HTML.

About bundle size: Keep in mind that the default olive.min.css is pretty large, since it contains all classes and variants and media queries of classes. It is recommended before going to production, to create your own custom optimized build of Olive CSS, by disabling certain features.

Some factors that can drastically affect the size of the production CSS style sheet are the amount of colors you enable and amount of media queries/breakpoints.

A rule of thumb is to disable xl and/or 2xl queries if you won't use them, and only choose some colors. This is made easy thanks to Guile Scheme's powerful parameterize syntax and helpers, allowing you to override pretty much anything. It can also be useful to disable dark mode since that will save a lot of complexity. See scripts/olive-css-gen.scm for more.

It's also important to ensure that your web server efficiently caches CSS files and compresses them with GZIP or Brotli.

Customizing Olive CSS

Customization is a first-class feature in Olive CSS. Thanks to the power of Guile Scheme, you can enable/disable features, tweak sizes, colors, and easily add your own utility rules.

Key customization points:

Choose which screen breakpoints to include (sm, md, lg, xl, 2xl)
Enable or disable dark mode with parameterize
Customize your color palette and choose some colors for your project

You can also generate your own responsive or hover-based variants with addmq and addhover

See scripts/olive-css-gen.scm and src/olive-css/main.scm and the API docs for more.

Philosophy

Olive CSS is not another Tailwind clone. It is simply inspired by it, and its design is based on these principles:

Hackability: You can extend or modify anything via Scheme code.
Freedom: 100% Free Software, licensed under the LGPLv3+ and FDL 1.3+.
Self-contained: Minimal dependencies and lightweight fast builds.
Expressiveness: Easily add support for ANY CSS feature and your own palettes and rules/declarations.

It is built to encourage learning and experimentation, rather than hiding complexity behind rigid inflexible tooling.

Projects that use Olive CSS

Code of conduct

This project adheres to the jointhefreeworld code of conduct. Find it here:

https://jointhefreeworld.org/blog/articles/personal/jointhefreeworld-code-of-conduct/index.html

In summary, we foster an inclusive, respectful, and cooperative environment for all contributors and users of this free software project. Inspired by the ideals of the GNU Project, we strive to uphold freedom, equality, and community as guiding principles. We believe that collaboration in a community of mutual respect is essential to creating excellent free software.

Olive CSS Project

Contributing to free software is a uniquely beautiful act because it embodies principles of generosity, collaboration, and empowerment.

We welcome everyone to feel invited to the olive-css Project, and encourage active contribution in all forms, to improve it and/or suggest improvements, brainstorm with me, make it more modular/flexible, etc, feel free to contact me <jjbigorra@gmail.com> to chat, discuss or report feedback.

Find here the Backlog and Kanban boards for olive-css: https://lucidplan.jointhefreeworld.org/tickets/olive-css

Comparison with Tailwind CSS

Feature	Tailwind CSS	Olive CSS
Written in	JavaScript	λ Guile Scheme
Customization	- average (via CSS config)	✔️ extensive (via code and expressive DSL)
Functional API	❌	✔️
Output control	Limited, JIT compiler is restricting	Full (generate exactly what you want)
Free Software	- (MIT, not copyleft)	✔️ (LGPL v3 + FDL)
Paid features	❌ Enterprise/Tailwind UI behind paywall	✔️ All included in the source code for everyone

Olive CSS is especially appealing if you want a completely libre, hackable, expressive and transparent alternative to Tailwind.

Tree Shaking

One of the interesting things about modern tooling and frameworks like Tailwind is indeed its ability to "tree-shake" and get rid of classes which are not used in the project.

This is something really useful and interesting for Olive CSS.

The mindset is that the developer should first of all, before creating an optimized production build, make some optimization choices (like what media queries to support, dark mode or not, which colors to support). That already helps a lot and leads to better and more performant project.

Currently the tree shaking in Olive CSS then scans all the .html files in ./public/, and compares matches to the contents of your optimized build (.css file, for now base-stylesheet-path set to "resources/css/olive.min.css") and remove lines with rules/selectors that are not used, producing a new optimized one (you might see amazing gains, like 3MiB going to 13KiB!). So actually it is a "targeted deletion" of things.

There is a Maak task to do tree-shaking, so it's as easy as maak tree-shake.

Troubleshooting

Common issues and solutions:

Output is too large: Disable unused breakpoints, variants, or colors in your build script.

Class not found: Make sure you generated the build after adding the class logic.

Dark mode not working: Ensure you are using the correct data-theme="dark" in the HTML element, and that dark mode queries were included in your build.

Invalid CSS: Double-check your custom rule definitions, especially when formatting oklch colors.