A calm light and dark theme for FreshRSS, inspired by shadcn/ui — and eight further readings of it.
Atelier gives FreshRSS a neutral palette, a clear reading hierarchy, soft radii, and subtle motion. It follows your operating system's light or dark setting on its own, and everything it needs ships with the theme — no web fonts, no scripts, nothing loaded from an external service while you read.
Atelier is the theme. The eight Atelier-* folders are readings of it in another neutral, taken from Tailwind CSS 4.3 — the same theme, told in a different grey.
They differ in exactly one thing: that ramp. Everything else — layout, typography, the accent hues for success, warning and error — is identical. Install one, or install several and switch between them in FreshRSS.
| Theme | Neutral |
|---|---|
Atelier |
Grey without a hue, on Tailwind Neutral |
Atelier-Slate |
A cool grey with a blue cast |
Atelier-Gray |
A neutral grey, faintly blue |
Atelier-Zinc |
A grey with a trace of violet |
Atelier-Stone |
A warm grey |
Atelier-Taupe |
A grey-brown that leans red |
Atelier-Mauve |
A grey with a muted purple cast |
Atelier-Mist |
A cool grey with a trace of cyan |
Atelier-Olive |
A grey-green that leans yellow |
Every one of them clears the same contrast bars, in light and dark alike; see Development.
- Nine neutral palettes, each a self-contained theme
- Light and dark interfaces that follow your system preference automatically
- Layouts for desktop and mobile, including a collapsible sidebar
- Locally bundled Lucide icons, so nothing is fetched from a CDN
- Visible focus states and support for reduced-motion settings
- Right-to-left layout support
FreshRSS 1.29.1. That is the version Atelier is built and tested against. Other versions will most likely work, but the theme follows FreshRSS's markup closely, so a larger FreshRSS update may need a matching theme update.
A browser from 2024 or later. Atelier uses modern CSS — nesting, :has(), subgrid, color-mix() and :dir() — which in practice means Chrome or Edge 120+, Firefox 121+, or Safari 17.2+. Older browsers will render the page, but parts of the layout will look wrong.
Copy Atelier — or any of the Atelier-* palette folders — into p/themes/ inside your FreshRSS installation, and pick it in the settings. Each folder is complete on its own — there is nothing to build, and nothing outside the folder it needs.
Keep the folder names as they are. FreshRSS stores the folder name as the theme's identity, so renaming Atelier-Stone later resets the theme selection of everyone using it.
- Download the repository as a ZIP archive and unpack it.
- Move
Atelierand anyAtelier-*palette folders you want into<FreshRSS>/p/themes/. Take one, take all nine — they sit beside each other without interfering.
The unpacked archive also contains src/, scripts/ and palettes/. Those build the themes; FreshRSS has no use for them, so leave them out of p/themes/.
Clone anywhere and copy the folders across:
git clone https://github.com/mbieh/Atelier.git ~/atelier
cp -r ~/atelier/Atelier /path/to/FreshRSS/p/themes/Mount the folders you want, one volume each. Read-only (:ro) keeps the container from writing to them:
services:
freshrss:
volumes:
- /absolute/path/to/Atelier:/var/www/FreshRSS/p/themes/Atelier:ro
- /absolute/path/to/Atelier-Stone:/var/www/FreshRSS/p/themes/Atelier-Stone:roRestart the container afterwards.
Open FreshRSS and choose Configuration → Display → Theme, then what you installed — Atelier, or one of the palettes such as Atelier Mist.
Pull or download the new version and copy the folders over the installed ones:
cd ~/atelier && git pull
cp -r ~/atelier/Atelier /path/to/FreshRSS/p/themes/Then reload FreshRSS. If the page still looks unchanged, force-reload it with Ctrl/Cmd + Shift + R.
Switch to another theme under Configuration → Display, then delete the <FreshRSS>/p/themes/Atelier* folders you no longer want.
Atelier follows your operating system's appearance setting, as long as FreshRSS is set to let it. Configuration → Display → Automatic dark mode carries that permission and ships as Auto; set it to No and the theme stays light whatever the system says. Switch your system to dark mode and FreshRSS turns dark on the next page load. Nothing else is stored, and there is no separate switch.
A theme folder differs from its siblings in one file: _palette.css, a neutral ramp of eleven steps. Everything else is byte-for-byte identical — Atelier and Atelier-Stone are not two themes, they are one theme on two ramps.
That works because no component ever names a color. Every rule asks for a role — background, foreground, border, accent — and src/_variables.css maps those roles onto steps of the ramp. Which step a role gets is decided by the contrast it needs, so a different palette keeps the theme readable instead of only recoloring it.
The icons cannot be tokens, because they are files rather than CSS: an external SVG cannot inherit the page's currentColor, so each one carries a literal stroke. They are authored once in Neutral, the ramp Atelier itself carries, and re-rendered into each folder's ramp by the build.
The preview each folder shows in the theme picker is drawn by hand, one per palette, and the build neither writes nor removes it. A screenshot re-tinted from one canonical rendering only approximates what a palette looks like, which is exactly what a preview is there to answer.
Add its OKLCH steps to palettes/ramps.json and rebuild:
python3 scripts/build_themes.py
python3 scripts/check_theme.pyThe first writes a tenth folder; the second tells you whether the new ramp holds every contrast bar the theme promises, in light and dark. If it does not, that is a real answer — not every neutral is usable at every step.
Atelier does not show up in the theme list. Check that <FreshRSS>/p/themes/Atelier/metadata.json exists — with the folder you installed in place of Atelier — and that your web server user is allowed to read the folder.
The page looks unstyled or the layout is broken. Usually an outdated browser — see Requirements. Otherwise force-reload the page.
Dark mode does not turn on. Atelier follows the system setting, not a FreshRSS setting. Check your operating system's appearance preference.
Some pages still look like the previous theme. Force-reload the page; browsers hold on to stylesheets aggressively.
The theme selection reset itself after updating to 1.4.0. Atelier-Neutral is called Atelier now, and FreshRSS identifies a theme by its folder name. Copy the new folder into p/themes/, select Atelier once, and delete the old folder.
The shared source lives in src/; the nine theme folders are generated from it and committed, so that installing means copying a folder rather than running a build. Which folder a palette is built into is stated in palettes/ramps.json — the Neutral ramp carries a folder of its own, which is why it ships as Atelier and not Atelier-Neutral.
python3 scripts/build_themes.py # regenerate the nine folders from src/
python3 scripts/build_themes.py --check # fail if a folder has drifted from its source
python3 scripts/check_theme.py # the release checks
npm install && npm run stylelint # the CSS conventions FreshRSS lints withThe build and the release checks need nothing but Python 3. The stylelint step is the exception, and it exists for one reason: FreshRSS lints every theme under p/themes/ with the configuration in .stylelintrc.json, which is a verbatim copy of the one that repository publishes. Holding the source to it here is what keeps a folder copyable into a FreshRSS installation — or into FreshRSS itself.
Atelier answers direction inside one stylesheet: a declaration that reads differently in Arabic or Hebrew carries a :dir(rtl) rule beside it, and check_theme.py rejects any that does not. That is why atelier.rtl.css and atelier-ui.rtl.css can be copies rather than translations.
FreshRSS generates its own *.rtl.css files with rtlcss and verifies them in CI. That tool does not know about :dir() and would flip both halves of every mirrored pair, so each sheet opens with /*rtl:begin:ignore*/ and closes with /*rtl:end:ignore*/ — rtlcss's own control comments, which turn its pass into the copy the mirror already is. The build writes each mirror as the source minus those two lines, which is exactly what rtlcss leaves behind.
Edit src/, never a theme folder — a folder is overwritten by the next build. The one exception is thumbs/, which holds the hand-drawn preview for the theme picker: the build leaves it alone, and check_theme.py only insists that every folder has one.
check_theme.py runs the same checks as CI: CSS structure, metadata, links, icon licenses, a guard that rejects direction-sensitive CSS before it can reach a right-to-left copy, and a WCAG contrast check that resolves every semantic role against the surfaces it is painted on — for all nine palettes, in both color schemes, which is 756 pairings.
This repository is a mirror: development happens on a private Forgejo instance and is pushed here. A pull request therefore cannot be merged into it, though it is still the clearest way to show me a patch — I apply it by hand and credit you in the changelog. Issues are unaffected.
See CHANGELOG.md for release notes and docs/component-coverage.md for the component matrix.
Atelier is derived from the official Mapco theme by Thomas Guesnon and the FreshRSS project, and is distributed under the GNU Affero General Public License v3.
The bundled Lucide icons keep their lucide-static 1.31.0 ISC headers; the full Lucide and Feather notices are in src/icons/LICENSE, and beside the icons in every theme folder. See THIRD-PARTY.md for detailed attribution.
Thanks to Thomas Guesnon and the FreshRSS project for Mapco, to the Lucide contributors and to Cole Bemis and the Feather contributors for the icons, and to shadcn/ui and Tailwind CSS as design and color references.