@advantacode/brander 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AdvantaCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,371 @@
+# AdvantaCode Brander
+
+AdvantaCode Brander is a design token generator that produces consistent branding tokens for modern web applications.
+
+It converts a simple configuration into reusable outputs for multiple platforms including:
+
+* CSS variables
+* TypeScript tokens
+* Tailwind presets
+* Bootstrap / SCSS variables
+* Figma tokens
+
+AdvantaCode Brander uses OKLCH color space to generate perceptually consistent color scales.
+
+## Quick Start
+
+```bash
+npm install -D @advantacode/brander
+npx --package @advantacode/brander advantacode-brander setup --out src/brander --style src/style.css
+```
+
+This creates `brand.config.ts`, adds a `brand:generate` script, patches your stylesheet imports, and prepares the token output folder.
+
+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).
+
+## Features
+
+* Single source of truth for brand tokens
+* OKLCH color scaling
+* Multi-framework outputs
+* CLI tool usable across any JavaScript stack
+* Environment variable support
+* Tailwind integration
+* Design-tool exports for Figma
+
+## Installation
+
+Node.js 20 or newer is required.
+
+Recommended for app projects:
+
+```bash
+npm install -D @advantacode/brander
+```
+
+One-off usage with `npx`:
+
+```bash
+npx --package @advantacode/brander advantacode-brander
+```
+
+Global install:
+
+```bash
+npm install -g @advantacode/brander
+```
+
+Run:
+
+```bash
+advantacode-brander
+```
+
+## CLI Usage
+
+Examples:
+
+```text
+advantacode-brander --help
+advantacode-brander --version
+advantacode-brander --out src/tokens
+advantacode-brander --format css,tailwind,figma
+advantacode-brander --theme dark
+advantacode-brander --prefix ac
+advantacode-brander setup --out src/brander --style src/style.css
+advantacode-brander init --out src/brander
+```
+
+Supported flags:
+
+* `--out <dir>` writes generated files to a custom folder instead of `dist/brander`
+* `--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`
+* `--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 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
+
+Create a `brand.config.ts` file in your project root.
+
+Example:
+
+```ts
+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"
+  }
+};
+```
+
+Supported color inputs:
+
+* Tailwind-style tokens like `amber-500`
+* CSS color strings like `#f59e0b` or `rgb(245 158 11)`
+* OKLCH values like `oklch(0.76859 0.164659 70.08)`
+
+## Environment Variables
+
+Brander supports environment variables via `.env`.
+
+Example:
+
+```dotenv
+COMPANY_NAME="My Company"
+CSS_PREFIX=
+PRIMARY_COLOR=amber-500
+SECONDARY_COLOR=zinc-700
+NEUTRAL_COLOR=zinc-700
+ACCENT_COLOR=amber-400
+INFO_COLOR=sky-500
+SUCCESS_COLOR=green-500
+WARNING_COLOR=yellow-500
+DANGER_COLOR=red-500
+```
+
+## Generated Outputs
+
+Running the CLI with no flags generates all formats into `dist/brander` and writes both light and dark theme CSS.
+
+```text
+dist/
+  brander/
+    tokens.css
+    tokens.scss
+    tokens.ts
+    tokens.json
+    metadata.json
+    themes/
+      light.css
+      dark.css
+    adapters/
+      tailwind.preset.ts
+      bootstrap.variables.scss
+      figma.tokens.json
+```
+
+## CSS Variables
+
+Example generated `tokens.css`:
+
+```css
+:root {
+  --primary-500: oklch(0.65 0.2 45);
+  --neutral-50: oklch(0.97 0.02 95);
+}
+```
+
+Usage:
+
+```css
+:root {
+  --background: var(--neutral-50);
+  --text: var(--neutral-950);
+}
+```
+
+By default, Brander emits unprefixed variables for broader compatibility. If you want namespaced output, use `css.prefix` in `brand.config.ts`, `CSS_PREFIX` in `.env`, or `--prefix ac` on the CLI.
+
+## Theme Tokens
+
+Example:
+
+```css
+:root {
+  --background: var(--neutral-50);
+  --surface: var(--neutral-100);
+  --text: var(--neutral-950);
+  --muted: var(--neutral-100);
+  --card: var(--neutral-50);
+  --border: var(--neutral-200);
+  --primary: var(--primary-600);
+  --primary-foreground: var(--neutral-50);
+}
+
+[data-theme="dark"] {
+  --background: var(--neutral-950);
+  --surface: var(--neutral-900);
+  --text: var(--neutral-50);
+}
+```
+
+Core semantic tokens include `background`, `surface`, `text`, `muted`, `card`, `popover`, `border`, `input`, `ring`, `primary`, `secondary`, `accent`, `info`, `success`, `warning`, and `danger`, each with matching foreground tokens where appropriate.
+
+## TypeScript Tokens
+
+Generated file:
+
+```text
+dist/brander/tokens.ts
+```
+
+Usage:
+
+```ts
+import { tokens, metadata } from "./dist/brander/tokens";
+
+console.log(tokens.color.semantic.light.primary.value);
+console.log(metadata.adapters);
+```
+
+This output is intended for typed apps, scripts, and build-time tooling.
+
+## SCSS Tokens
+
+Generated file:
+
+```text
+dist/brander/tokens.scss
+```
+
+Usage:
+
+```scss
+@use "./dist/brander/tokens.scss" as tokens;
+
+.button {
+  background: tokens.$primary;
+  color: tokens.$primary-foreground;
+}
+```
+
+Light semantic tokens are emitted as Sass variables like `$background`, and dark semantic tokens are emitted as `$dark-background`. Prefixing works here too when configured.
+
+## Tailwind Integration
+
+Generated preset:
+
+```text
+dist/brander/adapters/tailwind.preset.ts
+```
+
+Usage:
+
+```ts
+import preset from "./dist/brander/adapters/tailwind.preset";
+
+export default {
+  presets: [preset]
+};
+```
+
+Use tokens in Tailwind:
+
+```text
+bg-primary
+text-danger
+border-secondary
+```
+
+## Bootstrap / SCSS Frameworks
+
+Generated file:
+
+```text
+dist/brander/adapters/bootstrap.variables.scss
+```
+
+Example output:
+
+```scss
+@use "../tokens.scss" as tokens;
+
+$primary: tokens.$primary;
+$secondary: tokens.$secondary;
+$info: tokens.$info;
+```
+
+## Figma Token Export
+
+Generated:
+
+```text
+dist/brander/adapters/figma.tokens.json
+```
+
+Example:
+
+```json
+{
+  "color": {
+    "primary": {
+      "value": "oklch(0.65 0.2 45)"
+    }
+  }
+}
+```
+
+This allows importing tokens into design tools.
+
+## Metadata
+
+Generated file:
+
+```text
+dist/brander/metadata.json
+```
+
+Example:
+
+```json
+{
+  "version": "0.1.0",
+  "generated": "2026-03-08T17:47:26.019Z",
+  "themes": ["light", "dark"],
+  "adapters": ["tailwind", "bootstrap", "figma"],
+  "artifacts": ["tokens.css", "themes/light.css", "themes/dark.css"],
+  "cssPrefix": ""
+}
+```
+
+## Ecosystem
+
+AdvantaCode Brander is part of the AdvantaCode ecosystem.
+
+```text
+@advantacode/brander
+advantacode-init
+advantacode-starter
+```
+
+This allows developers to bootstrap fully branded applications with a single command.
+
+## Contributing
+
+AdvantaCode Brander is maintained under a closed governance model.
+
+Issues and feature requests are welcome, but pull requests may not be accepted.
+
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for details.
+
+## Trademark Notice
+
+`AdvantaCode` and `AdvantaCode Brander` are trademarks of AdvantaCode.
+
+The MIT license for this package does not grant permission to use the AdvantaCode name, logos, package names, domains, or branding, or to imply endorsement or affiliation.
+
+See [docs/TRADEMARKS.md](docs/TRADEMARKS.md) for the trademark policy.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

package/dist/adapters/css.js

@@ -0,0 +1,39 @@
+import fs from "fs";
+import path from "path";
+import { scaleSteps } from "../engine/palette.js";
+import { semanticTokenNames } from "../engine/semantics.js";
+import { getVariableName, getVariableReference } from "./variables.js";
+export function writeCssArtifacts(outputDir, tokenModel, theme, variableOptions) {
+    const themesDir = path.join(outputDir, "themes");
+    const writtenArtifacts = ["tokens.css"];
+    fs.mkdirSync(themesDir, { recursive: true });
+    fs.writeFileSync(path.join(outputDir, "tokens.css"), renderPrimitiveTokens(tokenModel, variableOptions));
+    if (theme === "light" || theme === "both") {
+        fs.writeFileSync(path.join(themesDir, "light.css"), renderThemeCss(":root", tokenModel, "light", variableOptions));
+        writtenArtifacts.push("themes/light.css");
+    }
+    if (theme === "dark" || theme === "both") {
+        fs.writeFileSync(path.join(themesDir, "dark.css"), renderThemeCss('[data-theme="dark"]', tokenModel, "dark", variableOptions));
+        writtenArtifacts.push("themes/dark.css");
+    }
+    return writtenArtifacts;
+}
+function renderPrimitiveTokens(tokenModel, variableOptions) {
+    let css = ":root {\n";
+    for (const [colorName, scale] of Object.entries(tokenModel.color.primitive)) {
+        for (const step of scaleSteps) {
+            css += `  ${getVariableName(`${colorName}-${step}`, variableOptions)}: ${scale[step]};\n`;
+        }
+    }
+    css += "}\n";
+    return css;
+}
+function renderThemeCss(selector, tokenModel, themeName, variableOptions) {
+    let css = `${selector} {\n`;
+    for (const semanticTokenName of semanticTokenNames) {
+        const token = tokenModel.color.semantic[themeName][semanticTokenName];
+        css += `  ${getVariableName(semanticTokenName, variableOptions)}: ${getVariableReference(token.ref, variableOptions)};\n`;
+    }
+    css += "}\n";
+    return css;
+}

package/dist/adapters/figma.js

@@ -0,0 +1,28 @@
+import fs from "fs";
+import path from "path";
+import { scaleSteps } from "../engine/palette.js";
+import { semanticTokenNames, themeNames } from "../engine/semantics.js";
+export function writeFigmaAdapter(outputDir, tokenModel) {
+    const adaptersDir = path.join(outputDir, "adapters");
+    const figmaTokens = {
+        color: {
+            primitive: Object.fromEntries(Object.entries(tokenModel.color.primitive).map(([colorName, scale]) => [
+                colorName,
+                Object.fromEntries(scaleSteps.map((step) => [step, { value: scale[step] }]))
+            ])),
+            semantic: Object.fromEntries(themeNames.map((themeName) => [
+                themeName,
+                Object.fromEntries(semanticTokenNames.map((semanticTokenName) => [
+                    semanticTokenName,
+                    {
+                        value: tokenModel.color.semantic[themeName][semanticTokenName].value,
+                        ref: tokenModel.color.semantic[themeName][semanticTokenName].ref
+                    }
+                ]))
+            ]))
+        }
+    };
+    fs.mkdirSync(adaptersDir, { recursive: true });
+    fs.writeFileSync(path.join(adaptersDir, "figma.tokens.json"), JSON.stringify(figmaTokens, null, 2));
+    return ["adapters/figma.tokens.json"];
+}

package/dist/adapters/json.js

@@ -0,0 +1,10 @@
+import fs from "fs";
+import path from "path";
+export function writeTokenModelJson(outputDir, tokenModel) {
+    fs.writeFileSync(path.join(outputDir, "tokens.json"), JSON.stringify(tokenModel, null, 2));
+    return ["tokens.json"];
+}
+export function writeMetadataJson(outputDir, metadata) {
+    fs.writeFileSync(path.join(outputDir, "metadata.json"), JSON.stringify(metadata, null, 2));
+    return ["metadata.json"];
+}

package/dist/adapters/scss.js

@@ -0,0 +1,59 @@
+import fs from "fs";
+import path from "path";
+import { scaleSteps } from "../engine/palette.js";
+import { semanticTokenNames } from "../engine/semantics.js";
+import { getSassVariableName } from "./variables.js";
+export function writeScssArtifacts(outputDir, tokenModel, options) {
+    const adaptersDir = path.join(outputDir, "adapters");
+    const writtenArtifacts = [];
+    const tokensScss = renderTokensScss(tokenModel, options.variableOptions);
+    const bootstrapScss = `@use "../tokens.scss" as tokens;
+
+$body-bg: tokens.${getSassVariableName("background", options.variableOptions)};
+$body-color: tokens.${getSassVariableName("text", options.variableOptions)};
+$border-color: tokens.${getSassVariableName("border", options.variableOptions)};
+$primary: tokens.${getSassVariableName("primary", options.variableOptions)};
+$secondary: tokens.${getSassVariableName("secondary", options.variableOptions)};
+$info: tokens.${getSassVariableName("info", options.variableOptions)};
+$success: tokens.${getSassVariableName("success", options.variableOptions)};
+$warning: tokens.${getSassVariableName("warning", options.variableOptions)};
+$danger: tokens.${getSassVariableName("danger", options.variableOptions)};
+$card-bg: tokens.${getSassVariableName("surface", options.variableOptions)};
+`;
+    fs.mkdirSync(adaptersDir, { recursive: true });
+    if (options.includeTokensScss || options.includeBootstrapAdapter) {
+        fs.writeFileSync(path.join(outputDir, "tokens.scss"), tokensScss);
+        writtenArtifacts.push("tokens.scss");
+    }
+    if (options.includeBootstrapAdapter) {
+        fs.writeFileSync(path.join(adaptersDir, "bootstrap.variables.scss"), bootstrapScss);
+        writtenArtifacts.push("adapters/bootstrap.variables.scss");
+    }
+    return writtenArtifacts;
+}
+function renderTokensScss(tokenModel, variableOptions) {
+    let scss = "";
+    for (const [colorName, scale] of Object.entries(tokenModel.color.primitive)) {
+        for (const step of scaleSteps) {
+            scss += `${getSassVariableName(`${colorName}-${step}`, variableOptions)}: ${scale[step]};\n`;
+        }
+    }
+    scss += "\n";
+    for (const semanticTokenName of semanticTokenNames) {
+        scss += `${getSassVariableName(semanticTokenName, variableOptions)}: ${tokenModel.color.semantic.light[semanticTokenName].value};\n`;
+    }
+    scss += `\n${getSassVariableName("theme-light", variableOptions)}: (\n`;
+    for (const semanticTokenName of semanticTokenNames) {
+        scss += `  "${semanticTokenName}": ${getSassVariableName(semanticTokenName, variableOptions)},\n`;
+    }
+    scss += ");\n\n";
+    for (const semanticTokenName of semanticTokenNames) {
+        scss += `${getSassVariableName(`dark-${semanticTokenName}`, variableOptions)}: ${tokenModel.color.semantic.dark[semanticTokenName].value};\n`;
+    }
+    scss += `\n${getSassVariableName("theme-dark", variableOptions)}: (\n`;
+    for (const semanticTokenName of semanticTokenNames) {
+        scss += `  "${semanticTokenName}": ${getSassVariableName(`dark-${semanticTokenName}`, variableOptions)},\n`;
+    }
+    scss += ");\n";
+    return scss;
+}

package/dist/adapters/tailwind.js

@@ -0,0 +1,18 @@
+import fs from "fs";
+import path from "path";
+import { semanticTokenNames } from "../engine/semantics.js";
+import { getVariableReference } from "./variables.js";
+export function writeTailwindAdapter(outputDir, tokenModel, variableOptions) {
+    const adaptersDir = path.join(outputDir, "adapters");
+    let preset = `export default {\n  theme: {\n    extend: {\n      colors: {\n`;
+    fs.mkdirSync(adaptersDir, { recursive: true });
+    for (const semanticTokenName of semanticTokenNames) {
+        if (!tokenModel.color.semantic.light[semanticTokenName]) {
+            continue;
+        }
+        preset += `        "${semanticTokenName}": "${getVariableReference(semanticTokenName, variableOptions)}",\n`;
+    }
+    preset += "      }\n    }\n  }\n};\n";
+    fs.writeFileSync(path.join(adaptersDir, "tailwind.preset.ts"), preset);
+    return ["adapters/tailwind.preset.ts"];
+}

package/dist/adapters/typescript.js

@@ -0,0 +1,13 @@
+import fs from "fs";
+import path from "path";
+export function writeTypeScriptArtifacts(outputDir, tokenModel, metadata) {
+    const source = `export const metadata = ${JSON.stringify(metadata, null, 2)} as const;
+
+export const tokens = ${JSON.stringify(tokenModel, null, 2)} as const;
+
+export type Metadata = typeof metadata;
+export type Tokens = typeof tokens;
+`;
+    fs.writeFileSync(path.join(outputDir, "tokens.ts"), source);
+    return ["tokens.ts"];
+}

package/dist/adapters/variables.js

@@ -0,0 +1,21 @@
+export function normalizeVariablePrefix(prefix) {
+    if (!prefix) {
+        return "";
+    }
+    return prefix.trim().replace(/^-+/, "").replace(/-+$/, "");
+}
+export function getVariableName(tokenName, options) {
+    const normalizedTokenName = tokenName.replace(".", "-");
+    return options.prefix
+        ? `--${options.prefix}-${normalizedTokenName}`
+        : `--${normalizedTokenName}`;
+}
+export function getVariableReference(tokenName, options) {
+    return `var(${getVariableName(tokenName, options)})`;
+}
+export function getSassVariableName(tokenName, options) {
+    const normalizedTokenName = tokenName.replace(".", "-");
+    return options.prefix
+        ? `$${options.prefix}-${normalizedTokenName}`
+        : `$${normalizedTokenName}`;
+}

package/dist/engine/color-parser.js

@@ -0,0 +1,64 @@
+import { converter } from "culori";
+import { tailwindColors } from "../tailwind-colors.js";
+const toOklch = converter("oklch");
+export const baseColorNames = [
+    "primary",
+    "secondary",
+    "accent",
+    "info",
+    "success",
+    "warning",
+    "danger",
+    "neutral"
+];
+const defaultBaseColors = {
+    primary: "amber-500",
+    secondary: "zinc-700",
+    accent: "amber-400",
+    info: "sky-500",
+    success: "green-500",
+    warning: "yellow-500",
+    danger: "red-500",
+    neutral: "zinc-700"
+};
+export function resolveBaseColors(colors) {
+    const mergedColors = {
+        ...defaultBaseColors,
+        ...colors,
+        neutral: colors.neutral ?? colors.secondary ?? defaultBaseColors.neutral
+    };
+    return Object.fromEntries(Object.entries(mergedColors).map(([colorName, colorValue]) => [colorName, normalizeColorValue(colorName, colorValue)]));
+}
+function normalizeColorValue(colorName, colorValue) {
+    const resolvedColorValue = resolveTailwindColorToken(colorValue) ?? colorValue;
+    const oklchColor = toOklch(resolvedColorValue);
+    if (!oklchColor) {
+        throw new Error(`Unable to parse color "${colorName}" with value "${colorValue}". Use a valid CSS color, OKLCH string, or Tailwind-style token like "amber-500".`);
+    }
+    return formatOklchColor(oklchColor);
+}
+function resolveTailwindColorToken(colorValue) {
+    const match = colorValue.match(/^([a-z]+)-(\d{2,3})$/);
+    if (!match) {
+        return undefined;
+    }
+    const [, colorName, rawScale] = match;
+    const colorScale = Number(rawScale);
+    const palette = tailwindColors[colorName];
+    return palette?.[colorScale];
+}
+function formatOklchColor(color) {
+    const lightness = roundComponent(color.l, 6) ?? "none";
+    const chroma = roundComponent(color.c, 6) ?? "none";
+    const hue = roundComponent(color.h, 3) ?? "none";
+    const alpha = roundComponent(color.alpha, 3);
+    return alpha !== undefined && alpha < 1
+        ? `oklch(${lightness} ${chroma} ${hue} / ${alpha})`
+        : `oklch(${lightness} ${chroma} ${hue})`;
+}
+function roundComponent(value, precision) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return Number(value.toFixed(precision));
+}