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;| Parameter | Type |
|---|---|
brand | BurgeeBrand |
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;| Parameter | Type |
|---|---|
colors | BurgeeColors |
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;| Parameter | Type |
|---|---|
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;| Parameter | Type |
|---|---|
brand | BurgeeBrand |
Returns Burgee
fieldId
A stable id for the field gradient, derived from the declaration.
function fieldId(brand: BurgeeBrand): string;| Parameter | Type |
|---|---|
brand | BurgeeBrand |
Returns string
opposedField
The field two colours imply.
function opposedField(colors: BurgeeColors, ground?: string): FieldStop[];| Parameter | Type |
|---|---|
colors | BurgeeColors |
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;| Parameter | Type |
|---|---|
markup | string |
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];burgee/config
Every export of burgee/config, with its signature and doc comment: ConfigError, envName, resolve, screaming, explain, plus 5 types.
burgee/contrast
Every export of burgee/contrast, with its signature and doc comment: mix, ratio, check, report, fieldColorAt, auditBurgee and 3 more, plus 2 types.