Contributing Guidelines

Relevant source files

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

• README.md
• scripts/generate-assets.ts
• test/generate-assets.test.ts
• export.config.json
• scripts/svgo.config.ts
• package.json

This document outlines the procedures for contributing to the FOSSBilling branding assets and technical automation scripts. It covers master file editing, asset generation workflows, and technical constraints for visual assets.

Introduction

The FOSSBilling branding repository manages official logos, icons, and automated export pipelines. Contributors update SVG master files in the source/ directory and use TypeScript-based scripts to generate optimized assets and distribution files. All contributions must adhere to specific branding limitations to maintain visual consistency across the project.

Sources: README.md:1-12, README.md:120-130

Visual Identity Standards

Contributors must follow specific color and typography rules when modifying brand assets.

Color Palette

The following hex codes define the official FOSSBilling colors:

Element	Color Hex
Wallet & Light wordmark	#000000
Card	#0785BC
Chip	#FAC965
Chip divisions	#94712D
Clasp separator	#FFFFFF
Dark wallet outline	#83909E

Sources: README.md:43-52

Typography

The wordmark uses the Manrope font.

• FOSS: Weight 700.
• Billing: Weight 450.
• Spacing: Default letter spacing.

Sources: README.md:54-56

Editing Source Assets

Editable masters are located in source/*-background/.

1. Vector Editing: Use Inkscape or Adobe Illustrator for SVG files.
2. Typography Changes: Install the Manrope variable font. Edit fossbilling-logo-text.svg first, then save a copy as fossbilling-logo.svg with text converted to paths.
3. Path Requirements: The generation script rejects SVGs containing <text> elements. You must convert all lettering to paths before submission.
4. Consistency: When updating icons, you must update the standalone icon, logo files, and text versions for both background variants.

Sources: README.md:33-41, scripts/generate-assets.ts:107-108

Technical Workflow

The repository uses a Node.js-based pipeline to process source SVGs into optimized distribution assets.

The asset generation process validates inputs, optimizes vectors, and renders raster formats.
Sources: scripts/generate-assets.ts:98-150

Environment Setup

You must use Node.js version 24 or newer.

1. Install dependencies: npm ci
2. Check types: npm run typecheck
3. Run tests: npm test
4. Generate assets: npm run generate

Sources: README.md:58-63, package.json:10-15

Configuration

Asset generation behavior is controlled by export.config.json.

Parameter	Type	Description
assetsOutput	String	Directory for optimized SVGs.
output	String	Directory for PNGs, favicons, and manifest.
iconSizes	Array	Integer sizes for icon exports (1-4096).
logoWidths	Array	Widths for logo PNG exports.
variants	Object	Defines source paths for different background styles.

Sources: export.config.json:1-20, scripts/generate-assets.ts:25-27

Quality Control and Validation

The project employs automated checks to ensure asset integrity.

Script Validation Logic

The generate-assets.ts script performs the following checks:

• Outlined Text: Scans for <text> or tspan tags in SVGs to ensure font independence.
• Dimensions: Verifies that SVGO optimization does not alter the original viewBox dimensions.
• File Overwrites: Prevents the script from overwriting source files with generated outputs.
• ViewBox Integrity: Requires a valid viewBox on the root SVG element for icon squaring.

Sources: scripts/generate-assets.ts:33-45, scripts/generate-assets.ts:113-116, scripts/generate-assets.ts:168-172

SVGO Configuration

Optimization is conservative to prevent visual regressions. The configuration explicitly allows attributes while stripping editor metadata.

export default {
  multipass: false,
  plugins: [
    'removeDoctype',
    'removeMetadata',
    'removeEditorsNSData',
    'convertStyleToAttrs',
    'convertColors',
  ],
}

Sources: scripts/svgo.config.ts:6-21

Testing Requirements

New contributions should not break existing asset generation. The test suite verifies:

1. Manifest Accuracy: Ensures all generated files are logged in manifest.json with correct dimensions.
2. Obsolete Cleanup: Confirms that removing a size or variant from the config successfully deletes old files.
3. Preview Integrity: Validates that preview.png contains the correct background colors and rendered artwork.

Sources: test/generate-assets.test.ts:40-100

Submission Guidelines

1. File Naming: Use lowercase with hyphens (e.g., fossbilling-logo.svg).
2. Commit Contents: Commit the source masters in source/ AND the regenerated optimized SVGs in assets/.
3. Ignored Files: Do not commit the dist/ directory; it is generated during the CI/CD build process.

Sources: README.md:72-74, scripts/generate-assets.ts:101-103

The branding repository relies on strict adherence to the vector-to-raster pipeline to ensure high-quality, font-independent assets across all platforms. Contributions that follow these guidelines ensure the project's visual identity remains professional and easily distributable.