|
1 | | -# themes |
2 | | -Official Sable Themes Repo |
| 1 | +# Sable themes |
| 2 | + |
| 3 | +Official theme packages for [Sable](https://github.com/SableClient/Sable). Each theme ships as: |
| 4 | + |
| 5 | +| File | Purpose | |
| 6 | +|------|--------| |
| 7 | +| **`{name}.sable.css`** | Full theme: all tokens, imported at runtime when the user applies the theme. | |
| 8 | +| **`{name}.preview.sable.css`** | **Preview only**: a tiny subset of tokens so the catalog and chat can show a safe swatch without loading full CSS. | |
| 9 | + |
| 10 | +`catalog.json` in this repo lists theme pairs for the client (regenerated by CI). |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +## Creating a new theme |
| 15 | + |
| 16 | +### 1. Full theme file: `{basename}.sable.css` |
| 17 | + |
| 18 | +- Define the full set of `--sable-*` / `--tc-*` custom properties your design needs. |
| 19 | +- You may use any valid CSS. Sable injects the file as a stylesheet when the theme is applied. |
| 20 | + |
| 21 | +### 2. Preview file: `{basename}.preview.sable.css` |
| 22 | + |
| 23 | +The in-app **preview card** (settings catalog, favorites, chat embeds) does **not** load this file as a full stylesheet. Sable **parses** it and only applies a limited set of custom properties to a small UI sample (“Sample text”, Primary, Surface chips). |
| 24 | + |
| 25 | +**Include only these properties** and the metadata block in the preview file. The client allowlists exactly these names, anything else is ignored. |
| 26 | + |
| 27 | +| Property | Role in the preview strip | |
| 28 | +|----------|---------------------------| |
| 29 | +| `--sable-bg-container` | Background of the preview panel | |
| 30 | +| `--sable-bg-on-container` | Text on that background | |
| 31 | +| `--sable-surface-container` | “Surface” chip background | |
| 32 | +| `--sable-surface-container-line` | Panel border | |
| 33 | +| `--sable-surface-on-container` | Text on surface chip | |
| 34 | +| `--sable-primary-main` | “Primary” chip background | |
| 35 | +| `--sable-primary-on-main` | Text on primary chip | |
| 36 | + |
| 37 | +Use a `.sable-theme-preview { ... }` block so the file stays readable; only those lines matter to the parser. |
| 38 | + |
| 39 | +### 3. Metadata block |
| 40 | + |
| 41 | +Put this **first** in the preview file (and typically mirror the same block in the full `.sable.css` for consistency). The first block comment that contains `@sable-theme` is parsed (you can add a license comment **above** it, or put `@sable-theme` in the first block). |
| 42 | + |
| 43 | +``` |
| 44 | +/* |
| 45 | +@sable-theme |
| 46 | +id: my-theme-id |
| 47 | +name: Human Readable Name |
| 48 | +author: Your Name |
| 49 | +kind: light |
| 50 | +contrast: low |
| 51 | +tags: comma, separated, keywords |
| 52 | +fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/my-theme.sable.css |
| 53 | +*/ |
| 54 | +``` |
| 55 | + |
| 56 | +- **`kind`**: `light` or `dark`. |
| 57 | +- **`contrast`**: `low` or `high`. |
| 58 | +- **`fullThemeUrl`**: URL to the full `.sable.css` (used when linking from preview to install). |
| 59 | + |
| 60 | +Adjust `fullThemeUrl` to the upstream raw URL once the files are on GitHub, although you'll need to point to your fork or import the raw file for your testing. |
| 61 | + |
| 62 | +### 4. Naming and catalog |
| 63 | + |
| 64 | +- Basename must match between files: `my-theme.preview.sable.css` pairs with `my-theme.sable.css`. |
| 65 | +- After you add or rename files on `main`, CI will regenerate `catalog.json`. Do not modify it. |
0 commit comments