create-quilltap-theme 1.0.6 → 2.0.0

package/dist/index.js

@@ -96,13 +96,64 @@ function copyTemplate(templateName, destPath, config, destName) {
   const content = processTemplate(templatePath, config);
   fs.writeFileSync(finalDestPath, content, "utf-8");
 }
-async function scaffold(config) {
+async function scaffoldBundle(config) {
+  const destPath = path.resolve(process.cwd(), config.themeId);
+  if (fs.existsSync(destPath)) {
+    error(`Directory "${config.themeId}" already exists.`);
+    process.exit(1);
+  }
+  heading("Creating your Quilltap theme bundle...");
+  fs.mkdirSync(destPath, { recursive: true });
+  success(`Created ${config.themeId}/`);
+  copyTemplate("bundle/theme.json.template", destPath, config, "theme.json");
+  success("Created theme.json");
+  copyTemplate("tokens.json.template", destPath, config, "tokens.json");
+  success("Created tokens.json");
+  if (config.includeCssOverrides) {
+    copyTemplate("bundle/styles.css.template", destPath, config, "styles.css");
+    success("Created styles.css");
+  }
+  copyTemplate("bundle/README.md.template", destPath, config, "README.md");
+  success("Created README.md");
+  const fontsDir = path.join(destPath, "fonts");
+  fs.mkdirSync(fontsDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(fontsDir, ".gitkeep"),
+    "# Place custom .woff2 font files here and reference them in theme.json\n",
+    "utf-8"
+  );
+  success("Created fonts/");
+  heading("Done! Next steps:");
+  log(`  ${colors.dim}# Edit your theme:${colors.reset}`);
+  log(`  ${colors.cyan}cd ${config.themeId}${colors.reset}`);
+  log(`  ${colors.dim}# Edit tokens.json to customize colors, typography, and spacing${colors.reset}`);
+  if (config.includeCssOverrides) {
+    log(`  ${colors.dim}# Edit styles.css for advanced component styling${colors.reset}`);
+  }
+  log("");
+  log(`  ${colors.dim}# To install in Quilltap:${colors.reset}`);
+  log(`  ${colors.cyan}cd ${config.themeId} && zip -r ../${config.themeId}.qtap-theme .${colors.reset}`);
+  log(`  ${colors.dim}# Then upload the .qtap-theme file in Settings > Appearance > Install Theme${colors.reset}`);
+  log("");
+  log(`  ${colors.dim}# Or install via CLI:${colors.reset}`);
+  log(`  ${colors.cyan}quilltap themes install ${config.themeId}.qtap-theme${colors.reset}`);
+  log("");
+  log(`  ${colors.dim}# Validate your bundle:${colors.reset}`);
+  log(`  ${colors.cyan}quilltap themes validate ${config.themeId}.qtap-theme${colors.reset}`);
+  log("");
+  info("No build tools required \u2014 just edit JSON and CSS files!");
+  log("");
+}
+async function scaffoldPlugin(config) {
   const destPath = path.resolve(process.cwd(), config.themeName);
   if (fs.existsSync(destPath)) {
     error(`Directory "${config.themeName}" already exists.`);
     process.exit(1);
   }
   heading("Creating your Quilltap theme plugin...");
+  log(`  ${colors.yellow}Note: npm plugin format is deprecated. Consider using bundle format instead.${colors.reset}`);
+  log(`  ${colors.dim}Run without --plugin to create a .qtap-theme bundle.${colors.reset}`);
+  log("");
   fs.mkdirSync(destPath, { recursive: true });
   success(`Created ${config.themeName}/`);
   copyTemplate("package.json.template", destPath, config, "package.json");
@@ -170,20 +221,23 @@ function parseArgs() {
   let themeName;
   let help = false;
   let yes = false;
+  let plugin = false;
   for (const arg of args) {
     if (arg === "-h" || arg === "--help") {
       help = true;
     } else if (arg === "-y" || arg === "--yes") {
       yes = true;
+    } else if (arg === "--plugin") {
+      plugin = true;
     } else if (!arg.startsWith("-")) {
       themeName = arg;
     }
   }
-  return { themeName, help, yes };
+  return { themeName, help, yes, plugin };
 }
 function showHelp() {
   log(`
-${colors.bold}create-quilltap-theme${colors.reset} - Scaffold a new Quilltap theme plugin
+${colors.bold}create-quilltap-theme${colors.reset} - Scaffold a new Quilltap theme
 
 ${colors.bold}Usage:${colors.reset}
   npm init quilltap-theme [theme-name] [options]
@@ -193,38 +247,45 @@ ${colors.bold}Arguments:${colors.reset}
   theme-name    Name for your theme (e.g., "sunset", "ocean-breeze")
 
 ${colors.bold}Options:${colors.reset}
-  -y, --yes     Skip prompts and use defaults
-  -h, --help    Show this help message
+  -y, --yes       Skip prompts and use defaults
+  --plugin        Create an npm plugin theme (deprecated, use bundle instead)
+  -h, --help      Show this help message
 
 ${colors.bold}Examples:${colors.reset}
-  npm init quilltap-theme my-theme
-  npx create-quilltap-theme sunset --yes
-  npm init quilltap-theme
+  npm init quilltap-theme my-theme          # Create a .qtap-theme bundle (recommended)
+  npx create-quilltap-theme sunset --yes    # Bundle with defaults
+  npx create-quilltap-theme sunset --plugin # Legacy npm plugin format
+
+${colors.bold}Bundle format (default):${colors.reset}
+  <theme-name>/
+  \u251C\u2500\u2500 theme.json      # Theme manifest
+  \u251C\u2500\u2500 tokens.json     # Design tokens
+  \u251C\u2500\u2500 styles.css      # CSS overrides (optional)
+  \u251C\u2500\u2500 fonts/          # Custom fonts (optional)
+  \u2514\u2500\u2500 README.md       # Documentation
+
+  No build tools required! Just edit JSON/CSS and zip to install.
 
-${colors.bold}What gets created:${colors.reset}
+${colors.bold}Plugin format (deprecated):${colors.reset}
   qtap-plugin-theme-<name>/
-  \u251C\u2500\u2500 package.json          # npm package config
-  \u251C\u2500\u2500 manifest.json         # Quilltap plugin manifest
-  \u251C\u2500\u2500 tokens.json           # Theme design tokens
-  \u251C\u2500\u2500 index.ts              # Plugin entry point
-  \u251C\u2500\u2500 styles.css            # CSS overrides (optional)
-  \u251C\u2500\u2500 tsconfig.json         # TypeScript config
-  \u251C\u2500\u2500 esbuild.config.mjs    # Build config
-  \u251C\u2500\u2500 README.md             # Documentation
-  \u251C\u2500\u2500 docs/                 # Development guide
-  \u2502   \u2514\u2500\u2500 THEME_PLUGIN_DEVELOPMENT.md
-  \u2514\u2500\u2500 .storybook/           # Storybook setup (optional)
+  \u251C\u2500\u2500 package.json, manifest.json, index.ts, tokens.json, ...
+  Requires npm, esbuild, TypeScript. Use --plugin flag.
 `);
 }
 async function main() {
-  const { themeName: argThemeName, help, yes } = parseArgs();
+  const { themeName: argThemeName, help, yes, plugin } = parseArgs();
   if (help) {
     showHelp();
     process.exit(0);
   }
+  const mode = plugin ? "plugin" : "bundle";
   log("");
   log(`${colors.bold}${colors.blue}  create-quilltap-theme${colors.reset}`);
-  log(`${colors.dim}  Scaffold a new Quilltap theme plugin${colors.reset}`);
+  if (mode === "bundle") {
+    log(`${colors.dim}  Scaffold a new Quilltap theme bundle (.qtap-theme)${colors.reset}`);
+  } else {
+    log(`${colors.dim}  Scaffold a new Quilltap theme plugin ${colors.yellow}(deprecated)${colors.reset}`);
+  }
   log("");
   const rl = readline.createInterface({
     input: process.stdin,
@@ -258,10 +319,10 @@ async function main() {
       authorEmail = await prompt(rl, "Author email", "you@example.com");
       primaryColor = await prompt(rl, "Primary color (HSL)", "hsl(220 90% 50%)");
       includeCssOverrides = await promptYesNo(rl, "Include CSS overrides (styles.css)?", true);
-      includeStorybook = await promptYesNo(rl, "Include Storybook setup?", false);
+      includeStorybook = mode === "plugin" ? await promptYesNo(rl, "Include Storybook setup?", false) : false;
     }
     const config = {
-      themeName: packageName,
+      themeName: mode === "bundle" ? themeId : packageName,
       packageName,
       themeId,
       displayName,
@@ -270,9 +331,14 @@ async function main() {
       authorEmail,
       primaryColor,
       includeCssOverrides,
-      includeStorybook
+      includeStorybook,
+      mode
     };
-    await scaffold(config);
+    if (mode === "bundle") {
+      await scaffoldBundle(config);
+    } else {
+      await scaffoldPlugin(config);
+    }
   } finally {
     rl.close();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quilltap-theme",
-  "version": "1.0.6",
+  "version": "2.0.0",
   "description": "Scaffold a new Quilltap theme plugin",
   "main": "dist/index.js",
   "bin": {
@@ -35,7 +35,7 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.19.7",
+    "@types/node": "^24.10.13",
     "esbuild": "^0.27.0",
     "typescript": "^5.0.0"
   }

package/templates/bundle/README.md.template

@@ -0,0 +1,46 @@
+# {{DISPLAY_NAME}}
+
+A custom theme for Quilltap.
+
+## Format
+
+This is a `.qtap-theme` bundle — a simple directory (or zip archive) containing design tokens, CSS overrides, and optional font files. No build tools, npm packages, or JavaScript code required.
+
+## Structure
+
+```
+{{THEME_ID}}/
+├── theme.json      # Theme manifest with metadata
+├── tokens.json     # Design tokens (colors, typography, spacing, effects)
+├── styles.css      # CSS overrides (optional)
+├── fonts/          # Custom font files (optional)
+└── README.md       # This file
+```
+
+## Editing
+
+- **Colors**: Edit `tokens.json` → `colors.light` and `colors.dark` sections
+- **Typography**: Edit `tokens.json` → `typography` section
+- **Spacing/Radius**: Edit `tokens.json` → `spacing` section
+- **Component styles**: Edit `styles.css` for custom CSS overrides
+- **Custom fonts**: Add `.woff2` files to `fonts/` and reference them in `theme.json`
+
+## Installing
+
+### From directory
+Zip this directory and upload the `.qtap-theme` file in Quilltap Settings > Appearance > Install Theme.
+
+### From CLI
+```bash
+# Pack as .qtap-theme
+cd {{THEME_ID}} && zip -r ../{{THEME_ID}}.qtap-theme .
+
+# Install
+quilltap themes install {{THEME_ID}}.qtap-theme
+```
+
+## Validating
+
+```bash
+quilltap themes validate {{THEME_ID}}.qtap-theme
+```

package/templates/bundle/styles.css.template

@@ -0,0 +1,33 @@
+/**
+ * {{DISPLAY_NAME}} - CSS Overrides
+ *
+ * Custom CSS overrides for the {{DISPLAY_NAME}} theme.
+ * These styles are applied on top of the design tokens defined in tokens.json.
+ *
+ * Available CSS custom properties (set from tokens.json):
+ *   --qt-bg, --qt-fg, --qt-primary, --qt-accent, etc.
+ *   --qt-font-sans, --qt-font-serif, --qt-font-mono
+ *   --qt-radius-sm, --qt-radius-md, --qt-radius-lg
+ *   --qt-shadow-sm, --qt-shadow-md, --qt-shadow-lg
+ *
+ * Tips:
+ * - Use qt-* CSS custom properties for theme-aware styling
+ * - Override specific components by targeting their qt-* class names
+ * - Keep overrides minimal; prefer tokens.json for color/spacing changes
+ */
+
+/* Example: custom heading styles */
+/*
+.qt-heading {
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+}
+*/
+
+/* Example: custom card styling */
+/*
+.qt-card {
+  border: 2px solid var(--qt-border);
+  box-shadow: var(--qt-shadow-md);
+}
+*/

package/templates/bundle/theme.json.template

@@ -0,0 +1,14 @@
+{
+  "format": "qtap-theme",
+  "formatVersion": 1,
+  "id": "{{THEME_ID}}",
+  "name": "{{DISPLAY_NAME}}",
+  "description": "{{DESCRIPTION}}",
+  "version": "1.0.0",
+  "author": "{{AUTHOR_NAME}}",
+  "license": "MIT",
+  "supportsDarkMode": true,
+  "tags": [],
+  "tokensPath": "tokens.json",
+  "stylesPath": "styles.css"
+}