burgee
API reference

burgee/brand

Every export of burgee/brand, with its signature and doc comment: opposedField, burgeeFlagPath, fieldId, chargeTransform, chargeRotation, placeCharge and 8 more, plus 7 types.

burgee/brand — a brand declares itself once; every identity surface is that declaration read by a different reader.

import { opposedField, burgeeFlagPath, fieldId, … } from 'burgee/brand';

Functions

burgeeBody

Field, charge and optional bordure — everything inside the viewBox.

function burgeeBody(brand: BurgeeBrand, id?: string, moving?: boolean): string;
ParameterType
brandBurgeeBrand
id (optional)string
moving (optional)boolean

Returns string

burgeeFlagPath

The flag silhouette, as SVG path data.

function burgeeFlagPath(): string;

Returns string

chargeGroup

The two Interlace bars, rotated and placed as the charge.

function chargeGroup(colors: BurgeeColors, scale?: number): string;
ParameterType
colorsBurgeeColors
scale (optional)number

Returns string

chargeRotation

The angle the charge is rotated by, as an SVG transform.

function chargeRotation(): string;

Returns string

chargeTransform

Where the charge sits, as an SVG transform. Exported because consumers that hand-write the flag (a React component, say) must place it identically, and recomputing it at the call site is how the two drift apart.

function chargeTransform(scale?: number): string;
ParameterType
scale (optional)number

Returns string

defineBurgee

Declare a brand. Everything on the returned object is a projection of it.

const brand = defineBurgee({
  name: 'burgee',
  mark: { lead: '#a84c17', follow: '#0a6b47' },
  field: [
    { offset: 0, color: '#0a6b47' },
    { offset: 0.5, color: '#0a0a0a' },
    { offset: 1, color: '#a84c17' },
  ],
});
writeFileSync('icon.svg', brand.favicon());
function defineBurgee(brand: BurgeeBrand): Burgee;
ParameterType
brandBurgeeBrand

Returns Burgee

fieldId

A stable id for the field gradient, derived from the declaration.

function fieldId(brand: BurgeeBrand): string;
ParameterType
brandBurgeeBrand

Returns string

opposedField

The field two colours imply.

function opposedField(colors: BurgeeColors, ground?: string): FieldStop[];
ParameterType
colorsBurgeeColors
ground (optional)string

Returns FieldStop[]

placeCharge

Place any charge markup where the charge belongs, at the charge's scale.

function placeCharge(markup: string, scale?: number): string;
ParameterType
markupstring
scale (optional)number

Returns string

Constants

BURGEE_ANGLE

const BURGEE_ANGLE: number;

BURGEE_FLAG

const BURGEE_FLAG: readonly Point[];

CHARGE

The charge occupies this fraction of the flag, and sits here within it.

const CHARGE: {
    readonly scale: 0.4;
    readonly x: 42;
    readonly y: 50;
};

DEFAULT_GROUND

The midpoint a field falls through when none is given. Near-black.

const DEFAULT_GROUND = "#0a0a0a";

FIELD_AXIS

The gradient axis: the direction the two bars are stacked on, traversed backwards — hoist-top to fly-bottom, in mark-space coordinates.

const FIELD_AXIS: {
    readonly x1: 25;
    readonly y1: 6.7;
    readonly x2: 75;
    readonly y2: 93.3;
};

Interfaces

Bordure

One band of the outline.

interface Bordure {
    color: string;
    /** Visible thickness, in mark-space units. */
    width: number;
}

Burgee

Everything one brand declaration projects into.

interface Burgee {
    /** The flag alone, square, at any size. */
    flag(size?: number): string;
    /**
     * The same mark with its sheen sweeping across it, for a page that can afford
     * motion — a site header, a docs hero. Identical to {@link Burgee.flag} when
     * no `sheen` is declared, and parked still under `prefers-reduced-motion`.
     */
    alive(size?: number): string;
    /** Favicon master. One file serves both themes — the flag carries its own field. */
    favicon(size?: number): string;
    /** Social card, 1200×630. */
    og(options?: CardOptions): string;
    /** Article cover, 1000×420. */
    cover(options?: CardOptions): string;
    /** Flag and wordmark, laid out horizontally. */
    lockup(options?: CardOptions): string;
    /** The gradient id this brand emits, for callers that need to match it. */
    fieldId(): string;
}

BurgeeBrand

interface BurgeeBrand {
    /** Accessible name for the flag. Without one the flag is decorative. */
    name?: string;
    /**
     * The charge, as a two-colour bar pair. Ignored when {@link BurgeeBrand.charge}
     * is given — that is the escape hatch for a CLI bringing its own glyph.
     */
    mark: BurgeeColors;
    /**
     * Your own charge instead of the bars: SVG markup drawn in a 0 0 100 100 box,
     * which burgee places and scales for you. Everything else — the swallowtail,
     * the reversed field, the sizes — still comes from this one declaration.
     */
    charge?: string;
    /**
     * Your own silhouette instead of the swallowtail: SVG path data in the same
     * `0 0 100 100` box, filled with the field and carrying the charge exactly as
     * the flag does. For a sibling brand whose name is not a flag — a roundel is
     * rings, a parrot is a parrot — the shape is the whole point, and drawing it
     * here keeps every other projection (favicon, lockup, OG, cover) intact.
     */
    shape?: string;
    /**
     * A sheen: a soft highlight laid across the field, `0` to `1`, where the
     * number is how bright its brightest point is. Depth, not decoration — a flat
     * gradient reads as printed ink, and one light source makes the same shape
     * read as an object with a front.
     */
    sheen?: number;
    /**
     * A bevel: how strongly the mark's own edge catches the light, `0` to `1`.
     */
    bevel?: number;
    /**
     * Markings: SVG markup in the same `0 0 100 100` box as {@link BurgeeBrand.shape},
     * drawn over the field and under the charge.
     */
    markings?: string;
    /**
     * The field, as gradient stops along {@link FIELD_AXIS}. One stop is a flat
     * field. Keep a dark stop under the charge or the mark will not read.
     */
    field: readonly FieldStop[];
    /**
     * The outline, outermost band first.
     */
    bordure?: Bordure | readonly Bordure[];
}

BurgeeColors

interface BurgeeColors {
    /** Leading bar, hoist side. */
    lead: string;
    /** Following bar, fly side. */
    follow: string;
}

CardOptions

interface CardOptions {
    width?: number;
    height?: number;
    /** Large line. Defaults to the brand name. */
    title?: string;
    /** Small line under it; wraps. */
    subtitle?: string;
    theme?: 'light' | 'dark';
    background?: string;
    foreground?: string;
    muted?: string;
}

FieldStop

One gradient stop: how far along the axis, and what colour.

interface FieldStop {
    offset: number;
    color: string;
}

Types

Point

A point in the mark space.

type Point = readonly [number, number];

On this page