Source Files and Editing Guide

Relevant source files

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

• README.md
• scripts/generate-assets.ts
• scripts/create-preview.ts
• export.config.json
• scripts/types.ts
• scripts/svgo.config.ts
• source/fonts/Manrope/OFL.txt

This guide describes how to manage, edit, and generate branding assets for FOSSBilling. The project maintains SVG master files and uses an automated pipeline to produce optimized web assets and raster images.

The repository separates files into three main areas:

• source/: Contains editable master SVG files and typography components.
• assets/: Stores optimized SVGs intended for distribution.
• dist/: Holds temporary generated files including PNGs, favicons, and the asset manifest.

Sources: README.md:1-40, export.config.json

Editable Master Files

The source/ directory contains the master SVG files. You edit these files using vector graphics software like Inkscape or Adobe Illustrator.

SVG Variants

The project provides two primary background variants:

1. Light Background: Uses a black wordmark and wallet icon.
2. Dark/Black Background: Uses a white wordmark and a muted wallet outline.

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

Typography and Font Management

The wordmark utilizes the Manrope variable font.

• Font Weights: "FOSS" uses weight 700; "Billing" uses weight 450.
• Variable Font Support: Use software with variable-font support to edit fossbilling-logo-text.svg.
• Path Conversion: After editing text, save a copy as fossbilling-logo.svg with all lettering converted to paths. The asset pipeline rejects SVGs containing live text elements to ensure consistent rendering.

Sources: README.md:32-40, README.md:52-57, scripts/generate-assets.ts:108

Asset Generation Pipeline

The generation script automates the transformation of master files into production-ready formats. It optimizes SVG code, renders PNGs at multiple scales, and creates web icons.

The diagram above shows the flow from source vector files to final distribution assets via optimization and rasterization.

Configuration

The file export.config.json controls the generation parameters. It defines output paths, required image dimensions, and source file mappings.

Option	Type	Description
assetsOutput	string	Directory for optimized SVGs.
output	string	Directory for PNGs, favicons, and manifest.
iconSizes	number[]	Pixel dimensions for square icon exports.
logoWidths	number[]	Widths for logo PNG exports.
variants	object	Mappings for icon and logo source paths per variant.

Sources: export.config.json:1-21, scripts/generate-assets.ts:79-100

Processing Logic

1. Validation: The script checks that SVGs use outlined paths instead of live text.
2. Optimization: svgo processes every master SVG using a specific allowlist of plugins to remove editor metadata without altering coordinates or transforms.
3. Rasterization: sharp renders PNG files. It uses a density-based approach to render vectors at high resolution before downsampling to the target width.
4. Square Conversion: For favicons and icons, the script calculates the viewBox to center the artwork within a square viewport.
5. ICO Creation: The script generates an .ico file containing multiple PNG frames (16px, 32px, 48px).

Sources: scripts/generate-assets.ts:31-61, scripts/generate-assets.ts:108-115, scripts/svgo.config.ts:1-19

Automated Preview and Manifest

The pipeline generates a preview.png and a manifest.json to facilitate asset discovery.

Preview Generation

The create-preview.ts script builds a comprehensive reference sheet. It composites various logo and icon versions against light, dark, and black background strips. It uses the bundled Manrope font to render labels directly onto the preview image.

Sources: scripts/create-preview.ts:11-53

Asset Manifest

The manifest records metadata for every generated file. This enables external tools to identify available variants and their properties.

The diagram above illustrates the structure of the JSON manifest produced during asset generation.

Sources: scripts/types.ts:1-24, scripts/generate-assets.ts:157-160

Editing Procedures

Follow these steps to update the branding assets:

1. Install Font: Install the Manrope variable font from source/fonts/Manrope/.
2. Modify Masters: Open the relevant SVG in source/ and perform edits.
3. Convert Text: If changing typography, ensure all text is converted to paths in the final master file.
4. Synchronize Icons: If you change the icon, update it in both the standalone icon file and the logo file for all variants.
5. Run Generation: Execute npm run generate to refresh the assets/ and dist/ directories.
6. Verify: Check the preview.png in the output folder to confirm visual consistency.

Sources: README.md:32-48, package.json:5-9

Colors and Branding Constraints

Technical implementations must adhere to the defined color palette and usage rules.

Element	Hex Code
Card	#0785BC
Chip	#FAC965
Chip divisions	#94712D
Dark-background wallet outline	#83909E
Primary Wordmark (Light)	#000000
Secondary Wordmark (Dark)	#FFFFFF

Sources: README.md:52-61

The project prohibits modifying the logo's proportions, changing the capitalization of "FOSSBilling", or placing assets over busy backgrounds with low contrast.

Sources: README.md:83-93

This guide ensures that branding assets remain consistent across all FOSSBilling platforms. By following the automated pipeline, developers maintain high-quality vector and raster assets with minimal manual effort.