@advantacode/brander 0.1.5 → 0.2.1

package/README.md

@@ -21,6 +21,9 @@ npx --package @advantacode/brander advantacode-brander setup --out src/brander -
 
 This creates `brand.config.ts`, adds a `brand:generate` script, patches your stylesheet imports, and prepares the token output folder.
 
+During setup, Brander creates `brand.css` next to your main stylesheet, writes token/theme imports there, and adds a single `@import './brand.css';` to your main stylesheet.
+The generated `brand:generate` script preserves the setup generation flags you used, including `--out` and `--style`, so repeat runs keep writing to the same target and refresh the stylesheet wiring when needed.
+
 AdvantaCode Brander generates design tokens and framework adapters from a single brand configuration file. It allows applications, design systems, and design tools to share a consistent source of truth for colors and semantic tokens.
 
 For architecture, development, testing, and publishing workflows, see [docs/TECH_OVERVIEW.md](docs/TECH_OVERVIEW.md).
@@ -84,12 +87,13 @@ Supported flags:
 * `--format <list>` limits output to specific formats: `all`, `css`, `json`, `typescript` or `ts`, `scss`, `tailwind`, `bootstrap`, `figma`
 * `--theme <value>` limits theme CSS output to `light`, `dark`, or `both`
 * `--prefix <value>` applies a CSS variable prefix like `ac`, producing variables such as `--ac-primary`
+* `--style <path>` refreshes `brand.css` and the main stylesheet import during normal generation so package scripts can keep setup paths aligned
 * `--version`, `-v` prints the installed package version
 * `--help`, `-h` prints the CLI help text
 
 Setup commands:
 
-* `advantacode-brander setup` configures an existing app by creating `brand.config.ts` if needed, adding a `brand:generate` script, patching a stylesheet with token imports, and generating tokens
+* `advantacode-brander setup` configures an existing app by creating `brand.config.ts` if needed, adding a `brand:generate` script, creating or updating `brand.css` with token imports, patching a stylesheet to import `brand.css`, and generating tokens
 * `advantacode-brander init` runs the same setup flow for a freshly created app and is intended to be called by a higher-level scaffolder such as `advantacode-init`
 
 ## Configuration
@@ -277,6 +281,18 @@ text-danger
 border-secondary
 ```
 
+CommonJS Tailwind config:
+
+```js
+const brandPreset = require("./src/assets/brander/adapters/tailwind.preset");
+
+module.exports = {
+  presets: [brandPreset]
+};
+```
+
+This step should stay documented rather than auto-patched for now. Unlike stylesheet imports, Tailwind config shape varies across projects between CJS, ESM, TS, Vite plugins, and newer Tailwind entrypoints, so automatic mutation is riskier and easier to get wrong.
+
 ## Bootstrap / SCSS Frameworks
 
 Generated file:

package/dist/index.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
+import path from 'path';
 import { generateTokens, supportedFormats } from './generate-tokens.js';
-import { setupProject } from './setup.js';
+import { setupProject, syncStyleImports } from './setup.js';
 export async function runCli(args) {
     try {
         if (args.includes('--version') || args.includes('-v')) {
@@ -8,13 +9,13 @@ export async function runCli(args) {
             return 0;
         }
         const command = resolveCommand(args);
-        const commandArgs = command === 'generate' ? args : args.slice(1);
+        const commandArgs = command === "generate" && args[0] === "generate" ? args.slice(1) : command === "generate" ? args : args.slice(1);
         if (commandArgs.includes('--help') || commandArgs.includes('-h')) {
             console.log(getHelpText(command));
             return 0;
         }
         if (command === 'generate') {
-            await generateTokens(parseGenerateArgs(commandArgs));
+            await runGenerateCommand(parseGenerateArgs(commandArgs));
             return 0;
         }
         await setupProject(parseSetupArgs(command, commandArgs));
@@ -36,11 +37,20 @@ function resolveCommand(args) {
     if (!firstArg || firstArg.startsWith("-")) {
         return "generate";
     }
+    if (firstArg === "generate") {
+        return "generate";
+    }
     if (firstArg === "setup" || firstArg === "init") {
         return firstArg;
     }
     throw new Error(`Unknown command "${firstArg}". Use --help to see supported commands.`);
 }
+async function runGenerateCommand(options) {
+    await generateTokens(options);
+    if (options.stylePath) {
+        syncStyleImports(options.stylePath, options.outputDir ?? path.join('dist', 'brander'));
+    }
+}
 function parseGenerateArgs(args) {
     const options = {};
     for (let index = 0; index < args.length; index += 1) {
@@ -71,6 +81,11 @@ function parseGenerateArgs(args) {
             index += 1;
             continue;
         }
+        if (arg === "--style") {
+            options.stylePath = getNextArgValue(arg, args, index);
+            index += 1;
+            continue;
+        }
         if (arg.startsWith("-")) {
             throw new Error(`Unknown option "${arg}". Use --help to see supported flags.`);
         }
@@ -139,55 +154,57 @@ function normalizeFormat(value) {
 }
 function getHelpText(command) {
     if (command === "setup" || command === "init") {
-        return `AdvantaCode Brander
-
-Usage:
-  advantacode-brander ${command} [options]
-
-Setup options:
-  --out <dir>             Output directory (default: src/brander)
-  --style <path>          Stylesheet file to patch with token imports
-  --script-name <name>    package.json script to create (default: brand:generate)
-  --skip-imports          Do not patch a stylesheet with token imports
-  --skip-script           Do not add a package.json script
-  --skip-config           Do not create brand.config.ts when missing
-  --skip-generate         Do not run token generation after setup
-
-Generation options:
-  --format <list>         Comma-separated formats: all, css, json, typescript|ts, scss, tailwind, bootstrap, figma
-  --theme <value>         Theme CSS output: light, dark, or both (default: both)
-  --prefix <value>        CSS variable prefix. Use "" or omit for no prefix
-
-Examples:
-  advantacode-brander ${command}
-  advantacode-brander ${command} --out src/brander
-  advantacode-brander ${command} --style src/style.css
-  advantacode-brander ${command} --skip-imports --skip-generate
+        return `AdvantaCode Brander
+
+Usage:
+  advantacode-brander ${command} [options]
+
+Setup options:
+  --out <dir>             Output directory (default: src/brander)
+  --style <path>          Main stylesheet file to patch with a brand.css import
+  --script-name <name>    package.json script to create (default: brand:generate)
+  --skip-imports          Do not create/update brand.css or patch stylesheet imports
+  --skip-script           Do not add a package.json script
+  --skip-config           Do not create brand.config.js when missing
+  --skip-generate         Do not run token generation after setup
+
+Generation options:
+  --format <list>         Comma-separated formats: all, css, json, typescript|ts, scss, tailwind, bootstrap, figma
+  --theme <value>         Theme CSS output: light, dark, or both (default: both)
+  --prefix <value>        CSS variable prefix. Use "" or omit for no prefix
+
+Examples:
+  advantacode-brander ${command}
+  advantacode-brander ${command} --out src/brander
+  advantacode-brander ${command} --style src/style.css
+  advantacode-brander ${command} --skip-imports --skip-generate
 `;
     }
-    return `AdvantaCode Brander
-
-Usage:
-  advantacode-brander [options]
-  advantacode-brander setup [options]
-  advantacode-brander init [options]
-
-Commands:
-  setup                   Configure an existing app to use Brander
-  init                    Initialize a new app for Brander-driven tokens
-
-Options:
-  -h, --help              Show this help output
-  -v, --version           Show the installed package version
-  --out <dir>             Output directory (default: dist/brander)
-  --format <list>         Comma-separated formats: all, css, json, typescript|ts, scss, tailwind, bootstrap, figma
-  --theme <value>         Theme CSS output: light, dark, or both (default: both)
-  --prefix <value>        CSS variable prefix. Use "" or omit for no prefix
-
-Examples:
-  advantacode-brander
-  advantacode-brander --out src/tokens
-  advantacode-brander setup --out src/brander --style src/style.css
-  advantacode-brander init --out resources/brander --skip-imports
+    return `AdvantaCode Brander
+
+Usage:
+  advantacode-brander [options]
+  advantacode-brander setup [options]
+  advantacode-brander init [options]
+
+Commands:
+  setup                   Configure an existing app to use Brander
+  init                    Initialize a new app for Brander-driven tokens
+
+Options:
+  -h, --help              Show this help output
+  -v, --version           Show the installed package version
+  --out <dir>             Output directory (default: dist/brander)
+  --format <list>         Comma-separated formats: all, css, json, typescript|ts, scss, tailwind, bootstrap, figma
+  --theme <value>         Theme CSS output: light, dark, or both (default: both)
+  --prefix <value>        CSS variable prefix. Use "" or omit for no prefix
+  --style <path>          Main stylesheet file to patch with a brand.css import
+
+Examples:
+  advantacode-brander
+  advantacode-brander --out src/tokens
+  advantacode-brander --out src/brander --style src/style.css
+  advantacode-brander setup --out src/brander --style src/style.css
+  advantacode-brander init --out resources/brander --skip-imports
 `;
 }

package/dist/setup.js

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import { generateTokens } from "./generate-tokens.js";
 const defaultSetupOutputDir = path.join("src", "brander");
+const brandStylesheetFileName = "brand.css";
 const defaultStyleCandidates = [
     path.join("src", "style.css"),
     path.join("src", "main.css"),
@@ -42,6 +43,9 @@ export async function setupProject(options) {
         console.log(`  - ${note}`);
     }
 }
+export function syncStyleImports(stylePath, outputDir) {
+    return ensureStyleImports(stylePath, outputDir);
+}
 function ensureBrandConfig() {
     const configPath = path.resolve(process.cwd(), "brand.config.js");
     if (fs.existsSync(configPath)) {
@@ -77,19 +81,49 @@ function ensureStyleImports(stylePath, outputDir) {
             message: "Skipped stylesheet imports because no stylesheet was found. Use --style <path> to target a file explicitly."
         };
     }
+    const brandStylesheetPath = path.join(path.dirname(resolvedStylePath), brandStylesheetFileName);
+    const brandStylesheetImports = [
+        buildImportLine(brandStylesheetPath, path.join(outputDir, "tokens.css")),
+        buildImportLine(brandStylesheetPath, path.join(outputDir, "themes", "light.css")),
+        buildImportLine(brandStylesheetPath, path.join(outputDir, "themes", "dark.css"))
+    ];
+    const brandStylesheetContents = `${brandStylesheetImports.join("\n")}\n`;
+    const hasBrandStylesheet = fs.existsSync(brandStylesheetPath);
+    const existingBrandStylesheet = hasBrandStylesheet ? fs.readFileSync(brandStylesheetPath, "utf8") : "";
+    if (existingBrandStylesheet !== brandStylesheetContents) {
+        fs.writeFileSync(brandStylesheetPath, brandStylesheetContents);
+    }
     const styleFileContents = fs.readFileSync(resolvedStylePath, "utf8");
-    const importLines = [
+    const legacyTokenImports = [
         buildImportLine(resolvedStylePath, path.join(outputDir, "tokens.css")),
         buildImportLine(resolvedStylePath, path.join(outputDir, "themes", "light.css")),
         buildImportLine(resolvedStylePath, path.join(outputDir, "themes", "dark.css"))
     ];
-    const missingImports = importLines.filter((importLine) => !styleFileContents.includes(importLine));
-    if (missingImports.length === 0) {
-        return { message: `Kept existing token imports in ${path.relative(process.cwd(), resolvedStylePath)}.` };
-    }
-    const nextContents = `${missingImports.join("\n")}\n${styleFileContents}`;
-    fs.writeFileSync(resolvedStylePath, nextContents);
-    return { message: `Added token imports to ${path.relative(process.cwd(), resolvedStylePath)}.` };
+    const brandImportLine = buildImportLine(resolvedStylePath, brandStylesheetPath);
+    const styleLineEnding = styleFileContents.includes("\r\n") ? "\r\n" : "\n";
+    const styleLines = styleFileContents.split(/\r?\n/);
+    const legacyImportCandidates = new Set();
+    for (const importLine of legacyTokenImports) {
+        legacyImportCandidates.add(importLine);
+        legacyImportCandidates.add(importLine.replace(/'/g, '"'));
+    }
+    let nextStyleLines = styleLines.filter((line) => !legacyImportCandidates.has(line.trim()));
+    const hasBrandImport = nextStyleLines.some((line) => line.trim() === brandImportLine || line.trim() === brandImportLine.replace(/'/g, '"'));
+    if (!hasBrandImport) {
+        nextStyleLines = [brandImportLine, ...nextStyleLines];
+    }
+    while (nextStyleLines[0] === "") {
+        nextStyleLines = nextStyleLines.slice(1);
+    }
+    const nextStyleContents = `${nextStyleLines.join(styleLineEnding)}${styleLineEnding}`;
+    if (nextStyleContents !== styleFileContents) {
+        fs.writeFileSync(resolvedStylePath, nextStyleContents);
+    }
+    const brandStylesheetStatus = hasBrandStylesheet ? "Updated" : "Created";
+    const mainStylesheetStatus = nextStyleContents === styleFileContents ? "Kept" : "Updated";
+    return {
+        message: `${brandStylesheetStatus} ${path.relative(process.cwd(), brandStylesheetPath)} and ${mainStylesheetStatus.toLowerCase()} ${path.relative(process.cwd(), resolvedStylePath)} to import it.`
+    };
 }
 function resolveStylePath(stylePath) {
     if (stylePath) {
@@ -130,24 +164,27 @@ function buildGenerateCommand(options) {
     if (options.prefix) {
         commandParts.push("--prefix", options.prefix);
     }
+    if (options.stylePath) {
+        commandParts.push("--style", options.stylePath);
+    }
     return commandParts.join(" ");
 }
 function getDefaultBrandConfigTemplate() {
-    return `export default {
-  name: process.env.COMPANY_NAME || "My Company",
-  css: {
-    prefix: process.env.CSS_PREFIX ?? ""
-  },
-  colors: {
-    primary: process.env.PRIMARY_COLOR || "amber-500",
-    secondary: process.env.SECONDARY_COLOR || "zinc-700",
-    neutral: process.env.NEUTRAL_COLOR || process.env.SECONDARY_COLOR || "zinc-700",
-    accent: process.env.ACCENT_COLOR || "amber-400",
-    info: process.env.INFO_COLOR || "sky-500",
-    success: process.env.SUCCESS_COLOR || "green-500",
-    warning: process.env.WARNING_COLOR || "yellow-500",
-    danger: process.env.DANGER_COLOR || "red-500"
-  }
-};
+    return `export default {
+  name: process.env.COMPANY_NAME || "My Company",
+  css: {
+    prefix: process.env.CSS_PREFIX ?? ""
+  },
+  colors: {
+    primary: process.env.PRIMARY_COLOR || "amber-500",
+    secondary: process.env.SECONDARY_COLOR || "zinc-700",
+    neutral: process.env.NEUTRAL_COLOR || process.env.SECONDARY_COLOR || "zinc-700",
+    accent: process.env.ACCENT_COLOR || "amber-400",
+    info: process.env.INFO_COLOR || "sky-500",
+    success: process.env.SUCCESS_COLOR || "green-500",
+    warning: process.env.WARNING_COLOR || "yellow-500",
+    danger: process.env.DANGER_COLOR || "red-500"
+  }
+};
 `;
 }

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "@advantacode/brander",
-  "version": "0.1.5",
-  "description": "AdvantaCode Design System Brand Generator",
-  "type": "module",
-  "files": [
-    "dist/**/*.js",
-    "docs/*.md",
-    "README.md",
-    "LICENSE"
-  ],
-  "bin": {
-    "advantacode-brander": "./dist/cli-wrapper.js"
-  },
-  "scripts": {
-    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && tsc && chmod +x dist/cli-wrapper.js",
-    "cli": "node --import tsx/esm dist/cli-wrapper.js",
-    "lint": "eslint --max-warnings=0 src test",
-    "pretest": "npm run build",
-    "test": "node --import tsx/esm --test",
-    "release:check": "npm run lint && npm test && npm pack --dry-run",
-    "tokens": "tsx src/generate-tokens.ts",
-    "prepack": "npm run build",
-    "brand:generate": "advantacode-brander --out src/brander",
-    "brand:test": "node ./dist/cli-wrapper.js --out src/brander"
-  },
-  "license": "MIT",
-  "author": "Anthony Penn",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/advantacode/advantacode-brander.git"
-  },
-  "homepage": "https://github.com/advantacode/advantacode-brander#readme",
-  "bugs": {
-    "url": "https://github.com/advantacode/advantacode-brander/issues"
-  },
-  "keywords": [
-    "design-tokens",
-    "branding",
-    "oklch",
-    "tailwind",
-    "cli"
-  ],
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^25.3.3",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.56.1",
-    "eslint": "^8.0.0",
-    "typescript": "^5.3.0"
-  },
-  "dependencies": {
-    "culori": "^4.0.2",
-    "dotenv": "^17.3.1",
-    "tsx": "^4.21.0"
-  }
-}
+{
+  "name": "@advantacode/brander",
+  "version": "0.2.1",
+  "description": "AdvantaCode Design System Brand Generator",
+  "type": "module",
+  "files": [
+    "dist/**/*.js",
+    "docs/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "advantacode-brander": "./dist/cli-wrapper.js"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc && chmod +x dist/cli-wrapper.js",
+    "cli": "node --import tsx/esm dist/cli-wrapper.js",
+    "lint": "eslint --max-warnings=0 src test",
+    "pretest": "npm run build",
+    "test": "node --import tsx/esm --test",
+    "release:check": "npm run lint && npm test && npm pack --dry-run",
+    "tokens": "tsx src/generate-tokens.ts",
+    "prepack": "npm run build",
+    "brand:generate": "advantacode-brander --out src/brander",
+    "brand:test": "node ./dist/cli-wrapper.js --out src/brander"
+  },
+  "license": "MIT",
+  "author": "Anthony Penn",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/advantacode/advantacode-brander.git"
+  },
+  "homepage": "https://github.com/advantacode/advantacode-brander#readme",
+  "bugs": {
+    "url": "https://github.com/advantacode/advantacode-brander/issues"
+  },
+  "keywords": [
+    "design-tokens",
+    "branding",
+    "oklch",
+    "tailwind",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "dependencies": {
+    "culori": "^4.0.2",
+    "dotenv": "^17.3.1",
+    "tsx": "^4.21.0"
+  }
+}