Branding

Source contract

@lemn-ltd/brand-contract@1.0.0 defines one canonical source contract:

{
  "$schema": "https://schemas.ui.le-mn.com/branding/v1.json",
  "schemaVersion": 1,
  "name": "Example identity",
  "metadata": { "tags": [], "externalReferences": {} },
  "assets": {},
  "typography": {},
  "defaultModeId": "light",
  "modes": { "light": {}, "dark": {} },
  "runtimeSelection": {
    "selectable": true,
    "allowedModeIds": ["light", "dark"]
  }
}

The abbreviated typography and mode bodies are illustrative. A valid BrandingDefinition contains governed root typography plus complete colors, shape, elevation, spacing/density, motion, visualization, iconography, accessibility, and component-appearance sections for every mode. It has no inheritance family or application lifecycle identity.

Deterministic compiler

import { compileBrandingDefinition } from "@lemn-ltd/brand-contract";

const result = await compileBrandingDefinition(definition);
if (!result.ok) throw new Error("Branding is invalid");

The compiler emits a deeply immutable artifact with schema/compiler compatibility, definition/compiled/mode hashes, complete mode projections, scoped CSS, font resources/preloads, asset references, component appearance, and provider-neutral visualization settings plus Recharts/ECharts adapters. Canonical input ordering produces byte-identical semantic output.

System brandings

The separate Node-safe catalog contains exactly versioned immutable starting points:

import {
  getSystemBrandingTemplate,
  systemBrandingTemplates,
} from "@lemn-ltd/brand-contract/system-brandings";

const verdant = getSystemBrandingTemplate("verdant-ledger", 1);
const editableCopy = structuredClone(verdant.definition);

Selecting a template copies the complete exact definition. A future catalog release never mutates existing drafts or active Workspaces.

Brand Studio

pnpm add @lemn-ltd/brand-contract@1.0.0 @lemn-ltd/brand-studio@2.0.0

import { systemBrandingTemplates } from "@lemn-ltd/brand-contract/system-brandings";
import { BrandStudio } from "@lemn-ltd/brand-studio";
import "@lemn-ltd/brand-studio/styles.css";

<BrandStudio
  draft={draftContext}
  value={definition}
  onChange={setDefinition}
  onIntent={handleAuthorizedIntent}
  systemBrandings={systemBrandingTemplates}
  previewTargets={authorizedTargets}
/>

Studio edits one controlled definition and emits validate, save, compare, preview, archive/restore, publish, and exact-template-selection intents. It does not fetch, persist, route, authenticate, authorize, publish, or activate.

Font policy

Typography uses a curated catalog rather than arbitrary family strings. System fonts require no download. Managed immutable WOFF2 fonts are self-hosted, integrity-bound, and always declare a system emergency fallback. preferred uses optional loading; required uses preload plus the browser block period. SSR cannot embed a font into pixels: the browser still downloads managed font bytes, so CSP, CORS, integrity, caching, and failure fallback remain required.

Evolution and authority

Namespaced JSON-only extensions allow additive evolution without arbitrary CSS or behavior flags. Incompatible meaning/removal requires a new schema major. AgentOps owns mutable drafts, publication, activation, previews, and audit; this repository owns only contracts, compilation, runtime consumption, and visual authoring controls.