> For the complete documentation index, see [llms.txt](https://docs.kouch.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kouch.dev/for-creators/creators/themes.md). # Make a theme Make a Kouch theme: a folder with theme.json, colours, backgrounds, sounds, music, fonts and device outlines. A Kouch theme is a **folder of data**: one `theme.json` plus the images, videos, sounds, music, fonts and SVG outlines it names. There's no CSS and no script. Kouch checks everything and applies it itself. The easiest start is **Settings › Theme › New theme**, which makes the folder for you from the theme you use now. See [Themes](/customize/themes.md#make-your-own). Edit the files, then **Reload theme**. ## Where themes live | | Folder | | ------------------ | -------------------------------------------- | | Windows | `%APPDATA%\kouch\themes\\theme.json` | | Steam Deck / Linux | `~/.config/kouch/themes//theme.json` | A folder name can use letters, digits, `-`, `_`, `.` and spaces, up to 64 characters, not starting with `.`. ## theme.json ```json { "kouch_theme": 2, "name": "Aurora", "author": "Someone", "version": "1.0.0", "description": "Deep blue night with soft glass cards.", "preview": "preview.webp", "schemes": ["black", "white"], "tokens": { "--k-radius-tile": "0.75rem", "--k-ease-spring": "cubic-bezier(0.3, 1.25, 0.6, 1)" }, "black": { "tokens": { "--k-accent": "#8AB4FF", "--k-bg": "#05060F", "--k-surface-1": "#0E1224", "--k-bg-gradient": "linear-gradient(180deg, #101A40, #05060F 70%)", "--k-card-shadow": "0px 8px 24px #00000099" } }, "white": { "tokens": { "--k-accent": "#1D4ED8" } }, "card_shape": "portrait", "background": { "image": "backgrounds/night.webm", "opacity": 0.35, "systems": { "my-system": "backgrounds/my-system.webp" } }, "ambient": { "enabled": true, "density": 0.4, "opacity": 0.05 }, "sounds": { "move": "sounds/move.ogg", "accept": "sounds/accept.ogg", "boot": "sounds/boot.ogg" }, "music": "music/menu-loop.ogg", "fonts": { "body": { "family": "Some Sans", "file": "fonts/some-sans.woff2" }, "display": { "family": "Some Display", "file": "fonts/some-display.woff2" } }, "silhouettes": { "pad-standard": "devices/pad.svg" }, "device_imagery": false } ``` Only `kouch_theme` (always `2`) and `name` are required. **Any key Kouch doesn't know is an error**, so a typo fails loudly instead of being quietly ignored. | Key | What it is | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Up to 48 characters. | | `author`, `version`, `description` | Optional: up to 48, 24 and 280 characters. | | `preview` | A picture for the theme list. | | `schemes` | Which of Kouch's looks the theme styles: `black`, `white` or both (default). | | `tokens` | Design values for both looks. `black.tokens` and `white.tokens` override them for one look. | | `card_shape` | `portrait`, `square` or `landscape` covers. | | `background.image` | An image or a looping video behind every screen. `background.opacity` 0–0.6. | | `background.systems` | A background per system, by system id. | | `ambient` | The floating shapes: `enabled`, `density` 0–1, `opacity` 0–0.2. The user's own switch still wins. | | `sounds` | Any of the 13 sounds: `move`, `accept`, `back`, `error`, `launch`, `page`, `sheet_open`, `sheet_close`, `pad_connected`, `pad_disconnected`, `player_joined`, `toast`, `boot`. Missing ones keep Kouch's. | | `music` | A menu music loop. Plays only if the user has turned music on. | | `fonts.body`, `fonts.display` | A `.woff2` font for text and for headings. | | `silhouettes` | Controller outlines for the Players screen (below). | | `device_imagery` | `true` if the theme shows real consoles or controllers (see the rules below). | {% hint style="info" %} **Library views:** older themes could suggest a Library view with `library_view`. The new Library ignores it; each system remembers the view its user picks. {% endhint %} ## Tokens Tokens are named design values. Kouch checks and rewrites every value, and passes nothing through as raw text. | Kind | Written as | Tokens | | ------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | Main colours | `#rrggbb` | `--k-accent`, `--k-bg`, `--k-text`, `--k-text-2`, `--k-text-3` | | Other colours | `#rrggbb` or `#rrggbbaa` | surfaces 1–4, `--k-text-disabled`, hairlines, `--k-outline`, `--k-scrim`, `--k-dim` | | Corner radii | `0.75rem` (0–1.5) | the four radii | | Durations | `220ms` (0–400) | animation times | | Numbers | a plain number | background and hero opacity (0–0.6), `--k-tile-focus-scale` (1–1.15), `--k-tile-press-scale` (0.9–1.1) | | Curves | `cubic-bezier(x1, y1, x2, y2)` | `--k-ease-out`, `--k-ease-in`, `--k-ease-spring` | | Gradient | `linear-gradient(deg, …)` or `radial-gradient(…)`, 2–6 colour stops | `--k-bg-gradient` | | Shadow | one or two `px px px [px] ` | `--k-card-shadow` | No `var()`, `url()`, `calc()` or named colours. **Kouch checks readability:** * The **accent** needs at least 4.5 : 1 contrast against the look's page colour, and enough colour in it to stand out. One that fails is dropped for that look, and Kouch uses the next accent in line. * **Text** colours need at least 4.5 : 1 against the background (3 : 1 for the faintest). A theme that fails is refused, with the reason. * With **reduced motion** on, a theme's durations and zooms are set back to calm values. ## Files All paths are relative to the theme folder and must stay inside it: no `..`, no drive letters, no links leading out, and nothing from the internet. | For | Types | Up to | | ----------- | ------------------------------ | --------------------- | | preview | png, jpg, webp, gif | 8 MB | | backgrounds | png, jpg, webp, gif; mp4, webm | 8 MB; 64 MB for video | | sounds | wav, ogg, mp3 | 2 MB each | | music | ogg, mp3 | 16 MB | | fonts | woff2 | 2 MB | | outlines | svg | 256 KB | `theme.json` itself is 256 KB at most. **SVG outlines** must be plain shapes: no scripts, embedded images or links to anything outside the file. Draw them in one colour (`currentColor` or black), and Kouch tints them with each player's colour. The names are: `pad-standard`, `pad-touchpad`, `pad-trackpad`, `pad-trackpad-2`, `pad-classic`, `phone`, `wand-pair`, `handheld`, `pad-pro`, `pad-pair`, `pad-half-left`, `pad-half-right`, `keyboard-mouse`, `remote` and `lan`. ## What a theme may show * Kouch's own theme never shows third-party consoles or controllers. **A theme from someone else may**, but it must set `"device_imagery": true`, and it's tagged that way on the Workshop. * **No game art for specific titles, and never games, BIOS or firmware.** ## Try it and share it * **Reload theme** in **Settings › Theme** re-reads your files. A theme with a problem shows greyed out, with the reason. * **Publish to Workshop**, with Kouch's Steam release. See [Workshop](/steam/steam/workshop.md). Or zip the folder and share it; people copy it into their themes folder. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kouch.dev/for-creators/creators/themes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.