fess-themes

A collection of Fess static themes, each generated from a design specification. Every theme is a self-contained vanilla-JS SPA that talks to the Fess /api/v2/* endpoints and is installable by uploading a ZIP via the Fess admin UI (/admin/theme/).

The goal of this repository is to keep design-driven themes in one place, so a theme can be reviewed, re-skinned, or used as a starting point for a new one.

Themes

Theme	Description
codesearch	Source-code-search-optimised static theme — dark-first IDE aesthetic, inline qualifier syntax (repo: / org: / path: / file: / lang:), per-file code cards with line-number gutters, query-refining facet rail, grounded Ask-AI panel. Requires Fess 15.9+ and query.additional.api.response.fields. Ships its DESIGN.md.
docuforge	Documentation-style theme on the DocuForge design system — blue/purple/gray palette, persistent facet sidebar, docs-grade typography, no Bootstrap. Ships its DESIGN.md spec.
helpdesk	FAQ / support site. Answers expand inline in an accordion — no navigation. Featured answers, category tiles, optional AI escalation. Ships its DESIGN.md spec.
docsearch	Documentation search — ⌘K command palette, grouped results, breadcrumb cards, optional cited Ask-AI. DocSearch design language: indigo/slate palette, self-hosted Inter + JetBrains Mono, FOUC-safe light/dark mode, no Bootstrap.
nomadkit	Free-spirited theme on the NomadKit design system — warm sand / ocean / forest palette, persistent facet sidebar, accessible (AA) contrast, no Bootstrap. Ships its DESIGN.md spec.
semanticlens	Hybrid keyword + semantic search theme — per-result searcher badges (Keyword / Semantic / Hybrid) with source-colored card spines (teal / violet / amber) and a "Matched by …" microcopy line; a Search Composition band above results showing a proportional keyword/semantic/hybrid bar and a plain-language verdict; and a count-free unified filter sidebar (File type / Updated / Size from /api/v2/ui/config) that stays present even for semantic-only queries, with a caption stating that filtering falls back to keyword-only search; and an advanced "semantic-space" home/landing hero with an animated vector-constellation canvas, converging amber/violet beams, a typewriter search-box, and three match-type preview cards. Requires Fess 15.9+ with core semantic search enabled (content_chunker.*) and query.additional.api.response.fields=searcher. Ships its DESIGN.md.
mosaic	Thumbnail-first visual gallery for multimodal (image + text) search. Requires Fess 15.9+. Ships its DESIGN.md.
storefront	EC / product-search theme — every result is a product card (photo, price, star rating, stock badge, brand) with no text snippet, and facet counts are drawn as proportional count bars so a price band shows how many products fall in it at a glance. Grid only. Requires Fess 15.9+, an externally supplied index mapping (price as double, rating as float) and query.additional.* configuration — see its README.md. Ships its DESIGN.md.
rawblock	Brutalist anti-design theme on the RawBlock design system — raw black-on-white, thick borders (1/3/5px), sharp 0px corners, no shadows, full color-inversion hover/active states, no Bootstrap. Ships its DESIGN.md spec.
voicebox	Bold, magazine-style editorial theme on the VoiceBox design system — high-contrast black/white with a single red accent, flat (no shadows), sharp 0px corners, thick 2px borders, Archivo Black headlines, no Bootstrap. Ships its DESIGN.md spec.

Repository layout

fess-themes/
├── README.md
├── LICENSE                  # Apache-2.0
├── scripts/
│   ├── package.sh           # zip a theme into dist/<name>-<version>.zip for upload
│   ├── stage-maven.sh       # deploy job's staging step (see "Installing a theme")
│   ├── verify-versions.sh   # CI: fail a PR that ships theme changes without a version bump
│   ├── verify-bundles.mjs   # CI: locale-bundle contract (i18n + help parity)
│   └── lib/
│       └── version.sh       # shared theme.yml#version reader, sourced by the scripts above
└── themes/
    └── <name>/
        ├── theme.yml        # manifest (apiVersion: fess.codelibs.org/v1, kind: StaticTheme)
        ├── index.html       # SPA shell
        ├── assets/          # JS modules + CSS
        ├── i18n/            # messages.<locale>.json
        ├── help/            # help/<locale>.json
        ├── DESIGN.md        # optional: the design spec the theme was built from
        └── README.md

A theme may include an optional thumbnail.png (≤512KB, ≤512×512) plus a thumbnail: thumbnail.png line in theme.yml to show a preview in the admin UI. Capture it from a running instance of the theme so it stays accurate.

Installing a theme

Either download a published ZIP, or package one from this repository — packaging from a checkout always works, whether or not anything has been published yet.

From the distribution repository: published theme releases live under https://maven.codelibs.org/release/org/codelibs/fess/themes/<name>/<version>/, each holding that version's ZIP; a maven-metadata.xml one level up (.../themes/<name>/maven-metadata.xml) lists every version actually published for that theme, and .../themes/theme-index.txt names every theme, one per line. Together those two answer "which themes are there, and which versions of each" without depending on a directory listing, which the server generates on a schedule and does not serve for a tree it has not caught up with. Once a version is published, fetch it by replacing <name> and <version>:

curl -O https://maven.codelibs.org/release/org/codelibs/fess/themes/<name>/<version>/<name>-<version>.zip

A 404 here means that exact <name>/<version> hasn't been published (yet, or ever) — check that theme's maven-metadata.xml for the versions that do exist, or package from a checkout instead.

From a checkout:

./scripts/package.sh docuforge
# → dist/docuforge-15.9.5.zip

Then open Admin → Theme (/admin/theme/) in Fess, upload the ZIP and activate it (or bind it to a virtual host).

A theme is served at /themes/<name>/ where <name> is theme.yml#name, and the asset paths inside index.html (e.g. themes/docuforge/assets/styles.css) are relative, resolved against the <base href> Fess inserts — so they still have to match the theme's own directory name, just without a leading slash.

Adding a new theme

1. Create themes/<name>/ (copy an existing theme as a starting point).
2. Set theme.yml#name / #displayName to <name>, and update every themes/<old>/… path in index.html to themes/<name>/… (assets/*.js carries no theme-name paths, so nothing to change there).
3. Set theme.yml#version to the current Fess line's first patch — "15.9.0" today — and theme.yml#minFessVersion to match ("15.9"); see Versioning.
4. Add a row to the Themes table above.

Versioning

A theme's version states which Fess line it targets: <Fess major.minor>.<patch>. Every theme in this repository is currently on the 15.9 line, so the newest version of each is 15.9.x, and theme.yml#minFessVersion is "15.9".

Changing a theme's shipped files means bumping that theme's patch number in the same commit. Edits confined to README.md / DESIGN.md ship nothing and need no bump. A change without a bump is never distributed — see CLAUDE.md.

Requirements

• Fess 15.9+ (static-theme support; see each theme's theme.yml#minFessVersion).

License

Apache-2.0 — see LICENSE.