Asset Variants (Light vs Dark)

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• scripts/generate-assets.ts
• scripts/types.ts
• export.config.json
• scripts/create-preview.ts
• test/generate-assets.test.ts

Asset variants provide tailored branding graphics optimized for different background environments. The FOSSBilling branding system separates assets into two primary categories: light-background and dark-background. These variants ensure high contrast and legibility by adjusting the treatment of the wordmark and specific icon elements based on the intended usage context.

Sources: README.md:14-25, export.config.json:11-20

Visual Treatment and Specifications

The system defines specific color treatments for each variant to maintain brand identity across different themes. The primary difference lies in the wordmark color and the wallet outline.

Element	Light Background Variant	Dark/Black Background Variant
Wordmark	Black (#000000)	White (#FFFFFF)
Wallet Body	Black (#000000)	Black (#000000)
Wallet Outline	N/A (Transparent)	Muted Grey (#83909E)
Card Element	Blue (#0785BC)	Blue (#0785BC)
Chip Element	Gold (#FAC965)	Gold (#FAC965)

Sources: README.md:20-25, README.md:43-51

Typography

Both variants use the Manrope font family. The wordmark is constructed with "FOSS" at weight 700 and "Billing" at weight 450. In production assets, these fonts are converted to paths to ensure consistent rendering without requiring local font installation.

Sources: README.md:53-56, scripts/generate-assets.ts:114-115

Architectural Pipeline

The generation script processes source SVG masters into optimized assets and multiple raster formats for each configured variant.

The diagram shows how the build system transforms source SVG masters into variant-specific optimized SVGs and raster files.
Sources: scripts/generate-assets.ts:104-180, scripts/create-preview.ts:10-15

Configuration and Management

Variants are defined in the export.config.json file. This configuration maps internal variant names to their respective source SVG files for both icons and full logos.

Configuration Structure

The Variant interface and the configuration file define how assets are grouped:

{
  "variants": {
    "light-background": {
      "icon": "source/light-background/fossbilling-icon.svg",
      "logo": "source/light-background/fossbilling-logo.svg"
    },
    "dark-background": {
      "icon": "source/dark-background/fossbilling-icon.svg",
      "logo": "source/dark-background/fossbilling-logo.svg"
    }
  }
}

Sources: export.config.json:11-20, scripts/types.ts:1-6

Processing Logic

1. Validation: The script ensures variant names follow the ^[a-z0-9]+(?:-[a-z0-9]+)*$ pattern and checks that source SVGs use outlined lettering rather than live text.
2. Optimization: Each variant's SVG is processed via svgo using a conservative allowlist to remove metadata without altering coordinates or clipping.
3. Rasterization: The system uses the sharp library to render PNGs at various widths (e.g., 600w, 1200w for logos) and icon sizes (e.g., 128px, 256px, 512px).
4. Cleanup: If a variant or size is removed from the configuration, the script identifies and deletes the now-obsolete files from the assets/ and dist/ directories.

Sources: scripts/generate-assets.ts:108-115, scripts/generate-assets.ts:192-212, test/generate-assets.test.ts:75-90

Asset Manifest and Metadata

Every generation run produces a manifest.json that catalogs all generated files. This manifest tracks the relationship between files and their respective variants.

The diagram represents the data structure of the asset manifest used to track variants and their exported properties.
Sources: scripts/types.ts:8-21, scripts/generate-assets.ts:182-184

Preview Generation

A composite preview.png is generated to provide a visual reference of how variants appear on different backgrounds.

• Light Background Variant: Rendered on a white background (#FFFFFF) with a dark foreground label.
• Dark Background Variant: Rendered twice—once on a dark grey background (#171C24) and once on a pure black background (#000000) to demonstrate contrast.

Sources: scripts/create-preview.ts:18-28, test/generate-assets.test.ts:133-145

Summary

Asset variants in FOSSBilling Branding allow the project to maintain visual integrity across different UI themes. By utilizing a configuration-driven generation script, the system ensures that both light and dark variants are consistently optimized, rasterized, and cataloged for production use.

Sources: README.md:28-31, scripts/generate-assets.ts:223-225