create-quilltap-theme 1.0.6 → 2.0.1

package/README.md

@@ -1,27 +1,31 @@
 # create-quilltap-theme
 
-Scaffold a new Quilltap theme plugin with a single command.
+Scaffold a new Quilltap theme with a single command.
 
 ## Usage
 
-### Using npm init (recommended)
+### Bundle format (default, recommended)
 
 ```bash
-npm init quilltap-theme my-theme
+npx create-quilltap-theme my-theme
 ```
 
-### Using npx
+This creates a `.qtap-theme` bundle directory — a simple, declarative format with JSON tokens, CSS, and fonts. No build tools, npm packages, or TypeScript required.
+
+### Legacy plugin format (deprecated)
 
 ```bash
-npx create-quilltap-theme my-theme
+npx create-quilltap-theme my-theme --plugin
 ```
 
+Creates an npm-based theme plugin. This format is deprecated; use bundles for new themes.
+
 ### Interactive mode
 
 Run without arguments for interactive prompts:
 
 ```bash
-npm init quilltap-theme
+npx create-quilltap-theme
 ```
 
 ### Skip prompts
@@ -29,11 +33,24 @@ npm init quilltap-theme
 Use `-y` or `--yes` to use defaults:
 
 ```bash
-npm init quilltap-theme my-theme --yes
+npx create-quilltap-theme my-theme --yes
 ```
 
 ## What gets created
 
+### Bundle format (default)
+
+```
+my-theme/
+├── theme.json            # Theme manifest with metadata and tokens
+├── tokens.json           # Design tokens (colors, fonts, spacing)
+├── styles.css            # CSS component overrides
+├── fonts/                # Custom font files (add .woff2 files here)
+└── README.md             # Documentation
+```
+
+### Plugin format (--plugin)
+
 ```
 qtap-plugin-theme-my-theme/
 ├── package.json          # npm package configuration
@@ -57,6 +74,7 @@ qtap-plugin-theme-my-theme/
 
 | Option | Description |
 |--------|-------------|
+| `--plugin` | Create a legacy npm plugin instead of a bundle |
 | `-y, --yes` | Skip prompts and use default values |
 | `-h, --help` | Show help message |
 
@@ -69,38 +87,49 @@ When run without `--yes`, you'll be asked:
 3. **Author name** - Your name
 4. **Author email** - Your email
 5. **Primary color** - Main theme color in HSL format
-6. **Include CSS overrides?** - Whether to create styles.css
-7. **Include Storybook?** - Whether to set up Storybook for development
+6. **Include CSS overrides?** - Whether to create styles.css (bundle and plugin)
+7. **Include Storybook?** - Whether to set up Storybook for development (plugin only)
 
 ## Next steps after scaffolding
 
+### Bundle themes
+
 ```bash
-cd qtap-plugin-theme-my-theme
-npm install
-npm run build
+cd my-theme
+# Edit theme.json, tokens.json, and styles.css
+# Then install into Quilltap:
+npx quilltap themes install .
+# Or validate first:
+npx quilltap themes validate .
 ```
 
-To preview in Storybook (if included):
+### Plugin themes (deprecated)
 
 ```bash
-npm run storybook
+cd qtap-plugin-theme-my-theme
+npm install
+npm run build
+npm publish --access public
 ```
 
-To publish:
+## Managing themes via CLI
 
 ```bash
-npm publish --access public
+npx quilltap themes list                    # List all installed themes
+npx quilltap themes install my.qtap-theme   # Install a bundle
+npx quilltap themes validate my.qtap-theme  # Validate without installing
+npx quilltap themes export earl-grey        # Export any theme as a bundle
+npx quilltap themes search "dark"           # Search registries
+npx quilltap themes update                  # Check for updates
 ```
 
 ## Documentation
 
-Every scaffolded theme includes a complete development guide at `docs/THEME_PLUGIN_DEVELOPMENT.md`.
-
 For the latest online documentation:
 
-- [Theme Plugin Development Guide](https://github.com/foundry-9/quilltap/blob/main/docs/THEME_PLUGIN_DEVELOPMENT.md)
+- [Theme Plugin Development Guide](https://github.com/foundry-9/quilltap/blob/main/docs/THEME_PLUGIN_DEVELOPMENT.md) (legacy plugin format)
 - [Plugin Manifest Reference](https://github.com/foundry-9/quilltap/blob/main/docs/PLUGIN_MANIFEST.md)
-- [@quilltap/theme-storybook](https://www.npmjs.com/package/@quilltap/theme-storybook)
+- [@quilltap/theme-storybook](https://www.npmjs.com/package/@quilltap/theme-storybook) (for plugin development with Storybook)
 
 ## License
 

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.1",
   "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": "^22.19.15",
     "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"
+}

package/templates/docs/THEME_PLUGIN_DEVELOPMENT.md.template

@@ -560,7 +560,7 @@ For advanced customization, create `styles.css` with component overrides. This u
 | `.qt-button`, `.qt-button-primary`, `.qt-button-secondary`, `.qt-button-ghost`, `.qt-button-destructive` | Button variants |
 | `.qt-button-sm`, `.qt-button-lg`, `.qt-button-icon` | Button sizes |
 | `.qt-card`, `.qt-card-header`, `.qt-card-body`, `.qt-card-footer` | Card components |
-| `.qt-card-interactive`, `.qt-entity-card`, `.qt-panel` | Card variants |
+| `.qt-card-interactive`, `.qt-entity-card`, `.qt-character-card`, `.qt-panel` | Card variants |
 | `.qt-input`, `.qt-textarea`, `.qt-select` | Form inputs |
 | `.qt-badge`, `.qt-badge-primary`, `.qt-badge-secondary`, `.qt-badge-outline` | Badges |
 | `.qt-avatar`, `.qt-avatar-sm`, `.qt-avatar-lg`, `.qt-avatar-xl` | Avatars |
@@ -588,6 +588,7 @@ Override these variables for consistent component styling:
 --qt-card-padding
 --qt-card-shadow
 --qt-card-border
+--qt-character-card-padding
 
 /* Inputs */
 --qt-input-radius