Scripts: Preview Generation
Relevant source files
The following files were used as context for generating this wiki page:
The preview generation system creates a comprehensive visual reference sheet for FOSSBilling branding assets. It produces a single preview.png file that displays all logo and icon variants across multiple background treatments. This process ensures visual consistency and provides a quick verification tool for designers and developers.
Sources: scripts/create-preview.ts:1-12, README.md:14-16
Architecture and Workflow
The preview generation integrates into the main asset pipeline. The generate-assets.ts script acts as the orchestrator, while create-preview.ts handles the specific composition logic. The system uses the sharp library for image processing and the Manrope font for labeling.
Generation Flow
The following flowchart illustrates the steps taken to generate the preview asset:
The workflow begins by parsing configuration and ends by writing a composite PNG and updating the project manifest.
Sources: scripts/generate-assets.ts:79-130, scripts/create-preview.ts:15-62
Preview Composition Logic
The createPreview function constructs the image by stacking visual layers. It calculates the total canvas height dynamically based on the number of background rows required by the configured variants.
Canvas Layout Specifications
The preview canvas follows a strict width and a variable height.
| Component | Specification |
|---|---|
| Canvas Width | 1200 px |
| Canvas Height | 130 + (number of rows * 250) px |
| Header Text | "FOSSBilling Branding Asset Preview" (Size 26) |
| Row Backgrounds | White (#FFFFFF), Dark (#171C24), or Black (#000000) |
| Label Font | Manrope (Variable Font) |
Sources: scripts/create-preview.ts:28-30, scripts/create-preview.ts:40-42
Layer Generation
- Labels: The script generates text buffers using
sharp's text operations, utilizing theManrope-VariableFont_wght.ttffile. - Artwork: Vector assets (logos and icons) are rasterized at specific widths using a helper function to maintain high quality during downsampling.
- Composition: All elements are placed at absolute coordinates using the
compositemethod insharp.
Sources: scripts/create-preview.ts:33-40, scripts/generate-assets.ts:117-122
Data Structures
The system relies on standardized interfaces to pass asset data between the optimization and preview modules.
Variant Interface
The Variant object contains the optimized SVG strings for a specific branding theme.
export interface Variant {
name: string; // e.g., 'light-background'
icon: string; // Optimized SVG string
logo: string; // Optimized SVG string
square: string; // Icon with adjusted square viewBox
}
Sources: scripts/types.ts:1-6
Row Mapping
The preview logic maps configuration variants to specific background rows.
Sources: scripts/create-preview.ts:21-27
Validation and Testing
The test/generate-assets.test.ts file verifies the integrity of the generated preview. Tests ensure that:
- The output image dimensions match the expected calculations (e.g., 1200x880 for two standard variants).
- The image contains the correct number of color channels (RGB, no alpha).
- Specific pixels match the branding colors (e.g.,
#0785BCfor the card element). - The
manifest.jsoncorrectly includes thepreview.pngentry with all relevant metadata.
Sources: test/generate-assets.test.ts:98-124, scripts/generate-assets.ts:133-140
Asset Manifest Integration
After createPreview returns the image buffer, generate-assets.ts adds the preview metadata to the global manifest. This allows external tools to identify the available variants within the preview.
| Field | Description |
|---|---|
path | Always set to preview.png |
type | Set to preview |
variant | Always null |
variants | Array of strings listing included theme names (e.g., ["light-background", "dark-background"]) |
Sources: scripts/generate-assets.ts:131-133, scripts/types.ts:8-17
The preview generation script serves as the final visual audit in the branding pipeline, combining optimized vector source files and system typography into a single high-resolution raster document.