Design a white-label theming CLI generating brand manifests, token diffs, and…
- User
Design a white-label theming CLI generating brand manifests, token diffs, and integration tests for customer onboarding.
Assistant
The user wants a "white-label theming CLI" that helps with customer onboarding. This is a specific request for a developer tool.
Deconstruct the Request:
- Core Functionality: A Command Line Interface (CLI).
- Domain: White-label theming (branding customizations for SaaS products).
- Key Features:
- Brand Manifests: Generating a definition of the brand (colors, typography, assets, etc.).
- Token Diffs: Comparing different versions of design tokens (e.g., standard theme vs. new client theme).
- Integration Tests: Generating visual or functional tests to ensure the theme applies correctly.
- Goal: Customer onboarding (automation, ease of use).
Target Audience: Developers or Product Engineers integrating a new client's brand into a platform.
Technology Stack:
- Language: TypeScript/Node.js (standard for CLIs).
- Libraries:
commanderoryargs(CLI framework).inquirer(interactive prompts).chalk(styling).difforjson-diff(for diffs).jestorplaywright(for generating test scaffolding).
Step-by-Step Design & Implementation Plan:
-
Project Structure: How should the project look?
src,templates,commands. -
The "Brand Manifest" (The Data Model): What data are we capturing?
- Name, ID.
- Colors (Primary, Secondary, etc.).
- Typography.
- Assets (Logo URLs).
-
Commands:
init: Start a new brand configuration.generate: Create the output files (CSS variables, JSON).diff: Compare two manifests.test: Scaffold integration tests.
-
Drafting the Code (Mental or Scratchpad):
- Entry point:
index.tsusingcommander. - Init command: Ask questions using
inquirer. Save tobrand.json. - Diff logic: Load
base.jsonandbrand.json. Iterate keys. Report differences. - Test logic: Output a Playwright test file that checks if CSS variables match the manifest.
- Entry point:
-
Refining the Solution:
- Instead of just showing raw code, I should explain the architecture.
- I need to provide a concrete example of the inputs and outputs.
- The "Integration Test" part needs to be specific. A simple snapshot test or a DOM check is best. Let's go with a Playwright visual regression or style check reference.
-
Structure of the Response:
- Conceptual Overview: High-level architecture.
- Data Schema: What does a "Manifest" look like?
- Implementation Guide (The Code):
- Setup (package.json).
- Command:
init(Interactive). - Command:
build(Token generation). - Command:
diff(Change detection). - Command:
verify(Testing).
- Example Usage: How it looks in the terminal.
- CI/CD Integration: How this fits into a pipeline.
Self-Correction/Review during thought process:
- Initial thought: Maybe use Python?
- Correction: No, the JavaScript/Node ecosystem is dominant for CLIs and Design Tokens (Style Dictionary, Tailwind, etc.). Stick to Node/TS.
- Feature check: The user asked for "Token Diffs". This implies a base theme exists. I need to make sure the logic compares the new customer manifest against a "Core" or "Default" manifest.
- Testing: Writing actual tests is hard in a CLI generator. The CLI should scaffold the tests. I will create a template for a Playwright test.
Detailed Code Structure:
src/cli.ts: Main entry.src/commands/init.ts: Prompts user.src/commands/build.ts: JSON -> CSS/SCSS.src/commands/diff.ts: Base vs New.src/templates/test.ts: Generates a spec file.
Let's write the response. I will structure it as a technical design document followed by a working prototype skeleton.
Focus on "White-label" context: This means taking one app and making it look like another. The CLI is the tool that bridges the design (Figma/Zeplin) to the Code.
Token Diff implementation: Use a deep-diff library. Output should be human-readable (CLI) or machine-readable (JSON).
Integration Tests: The best approach for a theme is Visual Regression Testing (VRT) or checking computed styles. I'll scaffold a Playwright test that navigates to a preview page and checks CSS variables.
Final Polish: Ensure the tone is professional and the code is clean TypeScript. Use
commanderandinquireras the industry standard choices.(Self-Correction on Output Format): The user asked to "Design" it. This implies architecture + code. I will provide a comprehensive design.
- Phase 1: Architecture & Schema
- Phase 2: The CLI Implementation (Node/TS)
- Phase 3: The Workflow
Let's assemble. This is a comprehensive design and implementation plan for a White-Label Theming CLI.
This tool is designed for SaaS platforms that need to onboard enterprise clients rapidly. It bridges the gap between design (Figma/StyleDictionary) and code, ensuring that every customer gets a unique, verified visual identity without engineering overhead.
1. System Architecture
The CLI acts as a compiler and a glue layer between your Design System and your Application Code.
Core Concepts:
- Source of Truth: A
theme.json(compatible with Style Dictionary) defining colors, typography, spacing, and assets. - The Manifest: A generated metadata file containing versioning, assets, and specific brand rules.
- The Diff: A comparison engine to detect breaking changes or updates between client versions.
- Visual Regression: An automated integration test suite using Playwright/Puppeteer to screenshot the themed app.
2. The Data Schema (Input)
The CLI expects a
brand-config.jsonfrom the customer or design team.{ "meta": { "customerId": "acme-corp", "version": "2.1.0", "logoUrl": "https://cdn.acme.com/logo.svg" }, "tokens": { "color": { "primary": { "value": "#FF5733" }, "background": { "value": "#FFFFFF" }, "text": { "value": "#121212" } }, "typography": { "fontFamily": { "value": "Inter, sans-serif" } } } }3. CLI Implementation (Node.js + TypeScript)
We will use
commanderfor the CLI framework,chalkfor styling, andstyle-dictionaryfor token processing.Setup
npm install commander chalk style-dictionary glob fs-extra deep-diffindex.ts(The Entry Point)#!/usr/bin/env node import { Command } from 'commander'; import { generateTheme } from './commands/generate'; import { diffThemes } from './commands/diff'; import { runTests } from './commands/test'; const program = new Command(); program .name('white-label-cli') .description('CLI to generate brand manifests and integration tests for onboarding'); program .command('generate <configPath>') .description('Generate CSS variables and brand manifest from a JSON config') .option('-o, --output <path>', 'Output directory', './dist/brand') .action(async (configPath, options) => { await generateTheme(configPath, options.output); }); program .command('diff <oldConfig> <newConfig>') .description('Generate a token diff report between two brand versions') .action(async (oldConfig, newConfig) => { await diffThemes(oldConfig, newConfig); }); program .command('test <url>') .description('Run integration visual regression tests against a URL') .option('--threshold <percent>', 'Visual diff threshold', '0.05') .action(async (url, options) => { await runTests(url, options); }); program.parse();
4. Command:
generateThis command transforms raw JSON tokens into usable assets (CSS/SCSS) and a Brand Manifest.
commands/generate.tsimport StyleDictionary from 'style-dictionary'; import fs from 'fs-extra'; import path from 'path'; import chalk from 'chalk'; export async function generateTheme(configPath: string, outputDir: string) { console.log(chalk.blue('🎨 Reading brand configuration...')); const rawConfig = await fs.readJson(configPath); const customerId = rawConfig.meta.customerId; // 1. Register a custom format for CSS Variables with fallbacks StyleDictionary.registerFormat({ name: 'css/variablesScoped', formatter: function({dictionary}) { return `:root { --brand-id: '${customerId}'; ${dictionary.allTokens.map(token => ` --${token.name}: ${token.value};` ).join('\n')} }`; } }); // 2. Initialize Style Dictionary const sd = StyleDictionary.extend({ tokens: rawConfig.tokens, platforms: { css: { transformGroup: 'css', buildPath: `${outputDir}/`, files: [{ destination: `${customerId}-tokens.css`, format: 'css/variablesScoped' }] }, json: { transformGroup: 'js', buildPath: `${outputDir}/`, files: [{ destination: `${customerId}-manifest.json`, format: 'json/flat' // Custom format logic omitted for brevity }] } } }); // 3. Build Assets await sd.buildAllPlatforms(); // 4. Generate the Brand Manifest (Metadata) const manifest = { id: customerId, generatedAt: new Date().toISOString(), version: rawConfig.meta.version, assets: { stylesheet: `${customerId}-tokens.css`, logo: rawConfig.meta.logoUrl }, theme: rawConfig.tokens // Flatten or keep structured as needed }; await fs.writeJson(path.join(outputDir, `${customerId}-manifest.json`), manifest, { spaces: 2 }); console.log(chalk.green('✅ Success! Assets generated at:'), outputDir); }
5. Command:
diffThis command compares the current client theme against a proposed new theme to highlight impact analysis during onboarding updates.
commands/diff.tsimport fs from 'fs-extra'; import { diff } from 'deep-diff'; import chalk from 'chalk'; export async function diffThemes(oldPath: string, newPath: string) { console.log(chalk.cyan('🔍 Comparing brand versions...')); const oldConfig = await fs.readJson(oldPath); const newConfig = await fs.readJson(newPath); const changes = diff(oldConfig.tokens, newConfig.tokens); if (!changes) { console.log(chalk.green('✅ No changes detected.')); return; } console.log(chalk.yellow(`ℹ️ Found ${changes.length} changes:`)); changes.forEach((change) => { // Structure specific logging const path = change.path.join('.'); if (change.kind === 'N') { console.log(`${chalk.green('+ ADD')} ${path}: ${change.rhs}`); } else if (change.kind === 'E') { console.log(`${chalk.yellow('~ MOD')} ${path}: ${chalk.red(change.lhs)} → ${chalk.green(change.rhs)}`); } else if (change.kind === 'D') { console.log(`${chalk.red('- DEL')} ${path}`); } }); }
6. Command:
test(Integration Tests)Generates a Playwright configuration and test script on the fly. This is crucial for ensuring the CSS injection worked correctly in the actual application.
commands/test.tsimport { chromium } from 'playwright'; import chalk from 'chalk'; export async function runTests(url: string, options: any) { console.log(chalk.magenta('🚀 Launching integration test...')); const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto(url); // 1. Verify Token Injection (Integration Test) // We assume the app has a root element where CSS variables are applied const primaryColor = await page.evaluate(() => { return getComputedStyle(document.documentElement).getPropertyValue('--color-primary').trim(); }); // This value would ideally come from the manifest generated in step 4 const expectedColor = '#FF5733'; if (primaryColor === expectedColor) { console.log(chalk.green('✅ CSS Variable Injection: PASSED')); } else { console.log(chalk.red(`❌ CSS Variable Injection: FAILED (Expected ${expectedColor}, got ${primaryColor})`)); await browser.close(); process.exit(1); } // 2. Visual Regression (Snapshot) // In a real CI/CD, this compares against a golden screenshot console.log(chalk.blue('📸 Taking screenshot...')); await page.screenshot({ path: `test-results/onboarding-snapshot.png`, fullPage: true }); await browser.close(); console.log(chalk.green('Test run complete.')); }
7. User Workflow (Onboarding Scenario)
Here is how a Customer Success Manager (CSM) or DevOps engineer would use this CLI to onboard
Client X.Step 1: Configuration
The CSM creates
client-x.jsonwith the brand colors provided by the client.Step 2: Build
The CSM runs the generator.
$ white-label generate ./client-x.json --output ./public/brands/client-xOutput:
client-x-tokens.css(The stylesheet to serve).client-x-manifest.json(The metadata for the backend).
Step 3: Diffing (Update Scenario)
Six months later, the client rebrands. The CSM creates
client-x-v2.json.$ white-label diff ./client-x.json ./client-x-v2.jsonOutput: Terminal logs showing exactly which hex codes changed, allowing engineers to assess UI breakage risks before deployment.
Step 4: Verification
The engineer deploys the staging environment with the new tokens and runs the integration test.
$ white-label test https://staging.myapp.com --customer client-xOutput: Confirmation that the CSS variables are loaded and a screenshot is saved to S3/GitHub Artifacts.
8. Advanced Features for Future Iteration
- Asset Processing: Extend the
generatecommand to download and optimize logo URLs into WebP/SVG formats locally usingsharp. - Tailwind Integration: Generate a
tailwind.preset.jsfile automatically alongside the CSS variables. - CI/CD Github Action: Wrap this CLI in a Docker container or GitHub Action so onboarding can be done via a Pull Request to a
brands/directory.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.