add tweaks and refractor

Author: 7w1

.github/pull_request_template.md

@@ -1,9 +1,15 @@
 ## Summary
 
-<!-- Briefly describe new themes or changes. -->
+<!-- Briefly describe new themes, tweaks, or other changes. -->
 
-## Theme PR checklist
+## Theme PR checklist (`themes/`)
 
-- [ ] `{name}.sable.css` and `{name}.preview.sable.css` share the same basename.
-- [ ] Preview file contains **only** the seven preview tokens (see **Creating a new theme** in [README](README.md)), plus `@sable-theme` metadata.
-- [ ] `fullThemeUrl` in metadata points at the correct raw URL of the full theme file once merged.
+- [ ] Files live under **`themes/`** (not the repo root).
+- [ ] `themes/{name}.sable.css` and `themes/{name}.preview.sable.css` share the same basename.
+- [ ] Preview file contains **only** the seven preview tokens (see **Themes** in [README](README.md)), plus `@sable-theme` metadata.
+- [ ] `fullThemeUrl` in metadata points at **`…/main/themes/{name}.sable.css`** once merged.
+
+## Tweak PR checklist (`tweaks/`)
+
+- [ ] Single file under **`tweaks/`**: `tweaks/{name}.sable.css` (no `.preview` file).
+- [ ] Metadata block uses **`@sable-tweak`** with at least **`name`** and **`description`** (see [README](README.md)).

.github/workflows/catalog.yml

@@ -4,7 +4,8 @@ on:
   push:
     branches: [main]
     paths:
-      - '**.css'
+      - 'themes/**'
+      - 'tweaks/**'
       - 'catalog.json'
       - 'scripts/build-catalog.mjs'
       - '.github/workflows/catalog.yml'

README.md

@@ -1,24 +1,49 @@
 # Sable themes
 
-Official theme packages for [Sable](https://github.com/SableClient/Sable). Each theme ships as:
+Official theme packages for [Sable](https://github.com/SableClient/Sable). This repo is split into two top-level folders:
 
-| File | Purpose |
-|------|--------|
-| **`{name}.sable.css`** | Full theme: all tokens, imported at runtime when the user applies the theme. |
-| **`{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. |
+| Folder | Contents |
+|--------|----------|
+| themes/ | Full themes: each basename has `{name}.sable.css` + `{name}.preview.sable.css`. |
+| tweaks/ | Optional overlays: one `{name}.sable.css` per tweak (no preview file). |
 
-`catalog.json` in this repo lists theme pairs for the client (regenerated by CI).
+`catalog.json` at the repo root lists **theme pairs** and **tweaks** for the client (regenerated by CI).
 
 ---
 
-## Creating a new theme
+## Tweaks (`tweaks/*.sable.css`)
 
-### 1. Full theme file: `{basename}.sable.css`
+Tweaks are **single-file** CSS overlays: they stack on top of whichever full theme is active. There is no `.preview.sable.css`. The app loads the full file once, parses metadata from it, caches the CSS, and shows a text description in the catalog instead of a color swatch.
+
+Add one file per tweak under `tweaks/` (e.g. `tweaks/my-tweak.sable.css`).
+
+### Metadata: `@sable-tweak`
+
+The first block comment containing `@sable-tweak` is parsed:
+
+```
+/*
+@sable-tweak
+id: my-tweak
+name: Human Readable Name
+description: One line explaining what changes (shown in the catalog).
+author: Your Name
+tags: comma, separated, keywords
+*/
+```
+
+CI will regenerate the catalog.json. Do not modify it.
+
+---
+
+## Themes (`themes/`)
+
+### 1. Full theme file: `themes/{basename}.sable.css`
 
 - Define the full set of `--sable-*` / `--tc-*` custom properties your design needs.
 - You may use any valid CSS. Sable injects the file as a stylesheet when the theme is applied.
 
-### 2. Preview file: `{basename}.preview.sable.css`
+### 2. Preview file: `themes/{basename}.preview.sable.css`
 
 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).
 
@@ -38,7 +63,7 @@ Use a `.sable-theme-preview { ... }` block so the file stays readable; only thos
 
 ### 3. Metadata block
 
-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).
+Put this **first** in the preview file (and mirror the same block in the full `.sable.css`). The first block comment that contains `@sable-theme` is parsed.
 
 ```
 /*
@@ -49,17 +74,14 @@ author: Your Name
 kind: light
 contrast: low
 tags: comma, separated, keywords
-fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/my-theme.sable.css
+fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/themes/my-theme.sable.css
 */
 ```
 
 - **`kind`**: `light` or `dark`.
 - **`contrast`**: `low` or `high`.
-- **`fullThemeUrl`**: URL to the full `.sable.css` (used when linking from preview to install).
-
-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.
+- **`fullThemeUrl`**: Raw URL to the full file under `themes/` (used when linking from preview to install).
 
-### 4. Naming and catalog
+Adjust `fullThemeUrl` to match this repo layout: `…/main/themes/{basename}.sable.css` once the files are on `main`.
 
-- Basename must match between files: `my-theme.preview.sable.css` pairs with `my-theme.sable.css`.
-- After you add or rename files on `main`, CI will regenerate `catalog.json`. Do not modify it.
+CI will regenerate the catalog.json. Do not modify it.

scripts/build-catalog.mjs

@@ -8,47 +8,72 @@ const REPO_ROOT = path.join(__dirname, '..');
 
 const PREVIEW_SUFFIX = '.preview.sable.css';
 const FULL_SUFFIX = '.sable.css';
+const THEMES_DIR = 'themes';
+const TWEAKS_DIR = 'tweaks';
 
 const repo =
   process.env.GITHUB_REPOSITORY?.trim() ||
   process.env.CATALOG_REPOSITORY?.trim() ||
   'SableClient/themes';
 const ref = process.env.GITHUB_REF_NAME?.trim() || process.env.CATALOG_REF?.trim() || 'main';
 
-function rawFileUrl(fileName) {
-  return `https://raw.githubusercontent.com/${repo}/${ref}/${fileName}`;
+function rawFileUrl(relativePath) {
+  return `https://raw.githubusercontent.com/${repo}/${ref}/${relativePath}`;
 }
 
 function buildCatalog() {
-  const files = fs.readdirSync(REPO_ROOT);
+  const themesPath = path.join(REPO_ROOT, THEMES_DIR);
+  if (!fs.existsSync(themesPath) || !fs.statSync(themesPath).isDirectory()) {
+    console.warn(`missing ${THEMES_DIR}/ directory`);
+  }
+  const files = fs.existsSync(themesPath) ? fs.readdirSync(themesPath) : [];
   const previewFiles = files.filter((f) => f.endsWith(PREVIEW_SUFFIX));
 
   const themes = [];
   for (const previewName of previewFiles) {
     const basename = previewName.slice(0, -PREVIEW_SUFFIX.length);
     const fullName = `${basename}${FULL_SUFFIX}`;
     if (!files.includes(fullName)) {
-      console.warn(`skip ${previewName}: missing ${fullName}`);
+      console.warn(`skip ${THEMES_DIR}/${previewName}: missing ${fullName}`);
       continue;
     }
+    const prevRel = `${THEMES_DIR}/${previewName}`;
+    const fullRel = `${THEMES_DIR}/${fullName}`;
     themes.push({
       basename,
-      previewUrl: rawFileUrl(previewName),
-      fullUrl: rawFileUrl(fullName),
+      previewUrl: rawFileUrl(prevRel),
+      fullUrl: rawFileUrl(fullRel),
     });
   }
 
   themes.sort((a, b) => a.basename.localeCompare(b.basename));
 
+  const tweaks = [];
+  const tweaksPath = path.join(REPO_ROOT, TWEAKS_DIR);
+  if (fs.existsSync(tweaksPath) && fs.statSync(tweaksPath).isDirectory()) {
+    for (const name of fs.readdirSync(tweaksPath)) {
+      if (!name.endsWith(FULL_SUFFIX)) continue;
+      const basename = name.slice(0, -FULL_SUFFIX.length);
+      tweaks.push({
+        basename,
+        fullUrl: rawFileUrl(`${TWEAKS_DIR}/${name}`),
+      });
+    }
+    tweaks.sort((a, b) => a.basename.localeCompare(b.basename));
+  }
+
   return {
     version: 1,
     repository: repo,
     ref,
     themes,
+    tweaks,
   };
 }
 
 const catalog = buildCatalog();
 const outPath = path.join(REPO_ROOT, 'catalog.json');
 fs.writeFileSync(outPath, `${JSON.stringify(catalog, null, 2)}\n`, 'utf8');
-console.log(`Wrote ${outPath} (${catalog.themes.length} theme pairs)`);
+console.log(
+  `Wrote ${outPath} (${catalog.themes.length} theme pairs, ${catalog.tweaks.length} tweaks)`
+);

accord.preview.sable.css themes/accord.preview.sable.cssaccord.preview.sable.css renamed to themes/accord.preview.sable.css

@@ -6,7 +6,7 @@ author: kr0nst
 kind: dark
 contrast: low
 tags: dark
-fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/accord.sable.css
+fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/themes/accord.sable.css
 */
 
 .sable-theme-preview {
@@ -18,3 +18,4 @@ fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/accord.s
   --sable-primary-main: #5865f2;
   --sable-primary-on-main: #fff;
 }
+

accord.sable.css themes/accord.sable.cssaccord.sable.css renamed to themes/accord.sable.css

@@ -6,7 +6,7 @@ author: kr0nst
 kind: dark
 contrast: low
 tags: dark
-fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/accord.sable.css
+fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/themes/accord.sable.css
 */
 
 body.sable-remote-theme {
@@ -99,3 +99,4 @@ body.sable-remote-theme {
   --mx-uc-7: hsl(40, 100%, 75%);
   --mx-uc-8: hsl(0, 100%, 75%);
 }
+

black.preview.sable.css themes/black.preview.sable.cssblack.preview.sable.css renamed to themes/black.preview.sable.css

@@ -6,7 +6,7 @@ author: Elec3137
 kind: dark
 contrast: high
 tags: dark, oled
-fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/black.sable.css
+fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/themes/black.sable.css
 */
 
 .sable-theme-preview {
@@ -18,3 +18,4 @@ fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/black.sa
   --sable-primary-main: #bdb6ec;
   --sable-primary-on-main: #1b1a21;
 }
+

black.sable.css themes/black.sable.cssblack.sable.css renamed to themes/black.sable.css

@@ -6,7 +6,7 @@ author: Elec3137
 kind: dark
 contrast: high
 tags: dark, oled
-fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/black.sable.css
+fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/themes/black.sable.css
 */
 
 body.sable-remote-theme {
@@ -88,3 +88,4 @@ body.sable-remote-theme {
   --sable-shadow: rgba(0, 0, 0, 0.4);
   --sable-overlay: rgba(15, 14, 18, 0.85);
 }
+

butter.preview.sable.css themes/butter.preview.sable.cssbutter.preview.sable.css renamed to themes/butter.preview.sable.css

@@ -6,7 +6,7 @@ author: Sable
 kind: dark
 contrast: low
 tags: dark, warm
-fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/butter.sable.css
+fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/themes/butter.sable.css
 */
 
 .sable-theme-preview {
@@ -18,3 +18,4 @@ fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/butter.s
   --sable-primary-main: #e3ba91;
   --sable-primary-on-main: #1a1916;
 }
+

butter.sable.css themes/butter.sable.cssbutter.sable.css renamed to themes/butter.sable.css

@@ -6,7 +6,7 @@ author: Sable
 kind: dark
 contrast: low
 tags: dark, warm
-fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/butter.sable.css
+fullThemeUrl: https://raw.githubusercontent.com/SableClient/themes/main/themes/butter.sable.css
 */
 
 body.sable-remote-theme {
@@ -88,3 +88,4 @@ body.sable-remote-theme {
   --sable-shadow: rgba(0, 0, 0, 0.6);
   --sable-overlay: rgba(15, 14, 12, 0.9);
 }
+