create-bl-theme 1.0.4 → 1.0.5

package/README.md

@@ -42,7 +42,8 @@ create-bl-theme validate https://github.com/username/theme-repo
 ```
 
 The validator checks:
-- Required files (metadata.json, style.css, images/)
+- Required files (metadata.json, style.rics or style.css, images/)
+- RICS syntax validation (for .rics files)
 - Valid JSON structure and required fields
 - Image integrity (detects corrupted files)
 - Image dimensions (recommends 1280x720, but other sizes work fine)
@@ -52,7 +53,7 @@ The validator checks:
 ```
 my-theme/
 ├── metadata.json    # Theme metadata (required)
-├── style.css        # Your CSS styles (required)
+├── style.rics       # Your styles in RICS format (required)
 ├── DESCRIPTION.md   # Rich description (optional, takes precedence)
 ├── shader.json      # Shader config (if enabled)
 ├── README.md        # Theme documentation
@@ -60,6 +61,33 @@ my-theme/
     └── preview.png
 ```
 
+## RICS
+
+Themes use [RICS](https://github.com/better-lyrics/rics) - a lightweight CSS preprocessor with full CSS parity. RICS adds variables, nesting, and mixins while staying close to standard CSS.
+
+**Any valid CSS is also valid RICS**, so you can write plain CSS if you prefer.
+
+```scss
+$accent: #ff6b6b;
+
+.lyrics-container {
+  background: rgba(0, 0, 0, 0.8);
+
+  .lyrics-line {
+    color: $accent;
+
+    &.active {
+      font-weight: bold;
+    }
+  }
+}
+```
+
+- **Playground:** https://rics.boidu.dev
+- **RICS Docs:** https://github.com/better-lyrics/rics
+
+> **Note:** Both `.rics` and `.css` files are supported. The validator prefers `.rics` if both exist.
+
 ### Theme Description Options
 
 You can provide your theme description in two ways:
@@ -77,7 +105,7 @@ Better Lyrics supports **GitHub Flavored Markdown (GFM)** in DESCRIPTION.md, so
 
 ## Theme Development
 
-1. **Edit `style.css`** - Add your custom styles. Use browser DevTools to inspect Better Lyrics elements and find the right selectors.
+1. **Edit `style.rics`** - Add your custom styles using RICS or plain CSS. Use browser DevTools to inspect Better Lyrics elements and find the right selectors.
 
 2. **Add screenshots** - Place at least one preview image in `images/`. Recommended size: 1280x720 (16:9 aspect ratio).
 
@@ -85,10 +113,13 @@ Better Lyrics supports **GitHub Flavored Markdown (GFM)** in DESCRIPTION.md, so
 
 4. **Test locally** - Install your theme via "Install from URL" in Better Lyrics using your local path or GitHub repo URL.
 
+**Resources:**
+- [Styling Guide](https://github.com/better-lyrics/better-lyrics/blob/master/STYLING.md) - Available selectors and styling reference
+
 ## Submitting to Theme Store
 
 1. Push your theme to a GitHub repository
-2. Fork [better-lyrics-themes](https://github.com/better-lyrics/better-lyrics-themes)
+2. Fork [themes](https://github.com/better-lyrics/themes)
 3. Add your theme to `index.json`:
    ```json
    {

package/bin/cli.js

@@ -8,6 +8,7 @@ import os from "os";
 import { fileURLToPath } from "url";
 import { imageSize } from "image-size";
 import { execSync } from "child_process";
+import { compileWithDetails } from "rics";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -212,12 +213,12 @@ Any special instructions for using this theme.
     fs.writeFileSync(path.join(fullPath, "DESCRIPTION.md"), descriptionMd);
   }
 
-  // Create style.css from template
-  const cssTemplate = fs.readFileSync(
-    path.join(TEMPLATES_DIR, "style.css"),
+  // Create style.rics from template
+  const ricsTemplate = fs.readFileSync(
+    path.join(TEMPLATES_DIR, "style.rics"),
     "utf-8"
   );
-  fs.writeFileSync(path.join(fullPath, "style.css"), cssTemplate);
+  fs.writeFileSync(path.join(fullPath, "style.rics"), ricsTemplate);
 
   // Create shader.json if needed
   if (response.hasShaders) {
@@ -261,7 +262,7 @@ MIT
   console.log();
   console.log(pc.bold("  Next steps:"));
   console.log(`  ${pc.dim("1.")} cd ${dir}`);
-  console.log(`  ${pc.dim("2.")} Edit ${pc.cyan("style.css")} with your theme styles`);
+  console.log(`  ${pc.dim("2.")} Edit ${pc.cyan("style.rics")} with your theme styles`);
   console.log(
     `  ${pc.dim("3.")} Add a preview screenshot to ${pc.cyan("images/preview.png")}`
   );
@@ -277,9 +278,15 @@ MIT
   console.log(
     `  ${pc.dim(`${stepNum}.`)} Push to GitHub and submit to the theme store`
   );
-  console.log(
-    `      ${pc.dim("https://github.com/boidushya/better-lyrics-themes")}`
-  );
+  console.log();
+  console.log(pc.bold("  Resources:"));
+  console.log(`  ${pc.cyan("RICS")} is a lightweight CSS preprocessor with full CSS parity.`);
+  console.log(`  It adds variables, nesting, and mixins - but plain CSS works too!`);
+  console.log();
+  console.log(`  ${pc.dim("Playground:")}     https://rics.boidu.dev`);
+  console.log(`  ${pc.dim("RICS Docs:")}      https://github.com/better-lyrics/rics`);
+  console.log(`  ${pc.dim("Styling Guide:")}  https://github.com/better-lyrics/better-lyrics/blob/master/STYLING.md`);
+  console.log(`  ${pc.dim("Submit Theme:")}   https://github.com/better-lyrics/themes`);
   console.log();
   console.log(
     pc.dim("  Validate your theme with: ") + pc.cyan(`npx create-bl-theme@latest validate ${dir}`)
@@ -411,12 +418,41 @@ async function validate(dir) {
     }
   }
 
-  // Check style.css
-  const stylePath = path.join(fullPath, "style.css");
-  if (!fs.existsSync(stylePath)) {
-    errors.push("style.css is missing");
-  } else {
-    const css = fs.readFileSync(stylePath, "utf-8");
+  // Check for style.rics or style.css (prefer .rics)
+  const ricsPath = path.join(fullPath, "style.rics");
+  const cssPath = path.join(fullPath, "style.css");
+  const hasRics = fs.existsSync(ricsPath);
+  const hasCss = fs.existsSync(cssPath);
+
+  if (!hasRics && !hasCss) {
+    errors.push("Missing required file: style.rics or style.css");
+  } else if (hasRics) {
+    const ricsSource = fs.readFileSync(ricsPath, "utf-8");
+    if (ricsSource.trim().length === 0) {
+      warnings.push("style.rics is empty");
+    } else {
+      // Validate RICS syntax
+      try {
+        const result = compileWithDetails(ricsSource);
+        if (result.errors && result.errors.length > 0) {
+          for (const err of result.errors) {
+            const location = err.start
+              ? ` (line ${err.start.line}, column ${err.start.column})`
+              : "";
+            errors.push(`style.rics: ${err.message}${location}`);
+          }
+        }
+        if (result.warnings && result.warnings.length > 0) {
+          for (const warn of result.warnings) {
+            warnings.push(`style.rics: ${warn.message || warn}`);
+          }
+        }
+      } catch (e) {
+        errors.push(`style.rics: Failed to compile - ${e.message}`);
+      }
+    }
+  } else if (hasCss) {
+    const css = fs.readFileSync(cssPath, "utf-8");
     if (css.trim().length === 0) {
       warnings.push("style.css is empty");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bl-theme",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "CLI tool to scaffold Better Lyrics themes",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
   "dependencies": {
     "image-size": "^2.0.2",
     "picocolors": "^1.1.1",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "rics": "^0.3.7"
   }
 }

package/templates/style.rics

@@ -0,0 +1,11 @@
+/*
+ * Better Lyrics Theme
+ *
+ * This file uses RICS - a lightweight CSS preprocessor with full CSS parity.
+ * RICS adds variables, nesting, and mixins while staying close to standard CSS.
+ * Any valid CSS is also valid RICS, so you can write plain CSS if you prefer.
+ *
+ * RICS Playground: https://rics.boidu.dev
+ * RICS Docs:       https://github.com/better-lyrics/rics
+ * Styling Guide:   https://github.com/better-lyrics/better-lyrics/blob/master/STYLING.md
+ */

package/templates/style.css

@@ -1,6 +0,0 @@
-/*
- * Better Lyrics Theme
- *
- * For available selectors and styling guide, see:
- * https://github.com/better-lyrics/better-lyrics/blob/master/STYLING.md
- */