@super-ic/brand-contracts

The brand plane for Sandbrock Share and NeighborShare: tenant identity objects, semantic aliases, the shared brand palette expressed as CSS custom-property references, the type foundation, brand marks and the approved illustration style.

The root exports tenant data contracts. The optional @super-ic/brand-contracts/superic-logo subpath exports the pure React SuperICLogo outlined mark and its prop types; it uses the existing React peer and inherited foundation color roles. The package ships no CSS of its own. UI palette aliases resolve through @super-ic/foundation. The illustration contract separately records the approved artwork swatches; they are not UI text or status tokens.

Illustration style

Everyday together is the owner-approved style for all SuperIC-authored illustrations. SBR and NeighborShare share it. The actual approved artwork is included in this package, with the complete illustration guide.

import { SupericIllustrationStyle, SharedTableIllustration } from "@super-ic/brand-contracts";
const artwork = import.meta.resolve(SupericIllustrationStyle.reference.import);

The public asset is @super-ic/brand-contracts/assets/illustrations/shared-table.png. Attach it as the actual style reference for future illustrations. Match the natural people, flat organic shapes, restrained ink detail, paper texture and forest/sage/ochre/clay palette. This is artwork, not evidence of real residents or exchanges. Keep typography and useful product structure unchanged.

Install

npm install @super-ic/brand-contracts @super-ic/foundation

@super-ic/foundation is a peer dependency (^0.2.0). Install it yourself; this package will not pull it in.

The two mandatory setup steps

Both are required. Skipping either leaves every palette variable empty, and var(--brand-sage) silently resolves to nothing rather than throwing.

1. Import the token stylesheet once

import "@super-ic/foundation/tokens.css";

Import it once, at the application root, before any component renders. It defines the :root layer that the semantic aliases point at (--primary, --surface, --border, --foreground, --ring, --primary-foreground) as well as the tenant pack described below.

2. Put a data-brand ancestor above anything that uses the palette

The brand palette does not live on :root. It lives on a tenant-pack selector, so a Sandbrock surface must have an ancestor element carrying the tenant attribute:

<div data-brand="sandbrock">
  {/* --brand-sage, --brand-gold, --primary, --ring, --font-heading resolve here */}
</div>

The tenant pack in @super-ic/foundation/tokens.css binds on any of:

• [data-brand="sandbrock"]
• [data-brand="neighborshare"]
• [data-tenant="sandbrock"]

Both brands bind the same pack today; identity differs at the mark, not at the colour plane. Inside that subtree the pack sets the eleven --brand-* values exported through SbrBrandPalette, and it also overrides --primary, --primary-foreground, --secondary, --ring, --font-heading and --font-body. Dark mode is handled by the same pack through [data-theme="dark"] or a .dark ancestor. No second import.

Two consequences worth knowing:

• Outside a data-brand / data-tenant subtree, SbrBrandPalette.sage and its siblings evaluate to nothing. There is no fallback.
• SandbrockSemanticAliases["brand.accent"], "brand.accent.strong" and "brand.accent.quiet" point at the tenant's explicit sage accent, dark sage accent and quiet accent surface. Use action.primary.background (--primary) for neutral controls and the brand aliases for explicit community or identity context. Focus rings remain neutral in both themes.

Usage

import {
  SandbrockTenant,
  SandbrockLogos,
  SbrBrandPalette,
  SbrTypeFoundation,
  sandbrockSemanticAlias,
} from "@super-ic/brand-contracts";

sandbrockSemanticAlias("action.primary.background"); // "var(--primary)"
SandbrockTenant.dataTenant;                          // "sandbrock"
SandbrockLogos.wordmark.asset;                       // "assets/sandbrock-share-logo.svg"

assertTenantDisplayProjection throws unless authority === "display-only". Tenant projections from this package are display-only and never authorize anything; authorization stays in the product.

Reaching a brand mark

Marks are static SVG files, not React components. They are exported under the ./assets/* subpath, so a bundler or Node resolver reaches them directly:

// Resolve to a file URL (Node, ESM)
const url = import.meta.resolve("@super-ic/brand-contracts/assets/sandbrock-share-logo.svg");

// Bundler asset import (Vite, webpack, Next.js)
import wordmark from "@super-ic/brand-contracts/assets/sandbrock-share-logo.svg";

The asset field on every BrandMark is the subpath tail, so a set can be walked generically:

const href = (mark: BrandMark) =>
  new URL(import.meta.resolve(`@super-ic/brand-contracts/${mark.asset}`));

Shipped marks:

| Export | Asset | Ground | Minimum height | | --- | --- | --- | --- | | SandbrockLogos.wordmark | assets/sandbrock-share-logo.svg | light | 44px | | SandbrockLogos.wordmarkOnDark | assets/sandbrock-share-logo-on-dark.svg | dark | 44px | | SandbrockLogos.icon | assets/sandbrock-share-icon.svg | light | 16px | | NeighborShareLogos.wordmark | assets/neighborshare-logo.svg | light | 44px | | NeighborShareLogos.wordmarkOnDark | assets/neighborshare-logo-on-dark.svg | dark | 44px | | NeighborShareLogos.icon | assets/neighborshare-icon.svg | any | 16px |

The compact paired arches are the owner-selected shared symbol. SBR keeps its existing green (#318050); NeighborShare keeps its live yellow (#F4AE39). The four outlined wordmark paths, their fills, and the lockup viewBoxes are unchanged. Use a full lockup at 44px height or larger; use the icon where the available space is smaller.

Additional exports through the existing asset wildcard:

• assets/sandbrock-share-icon-on-dark.svg: white SBR symbol.
• assets/neighborshare-icon-on-dark.svg: yellow NS symbol.
• assets/shared-neighbor-mark.svg: editable canonical geometry in currentColor.

BrandLogoSet.iconOnDark identifies the dedicated dark-ground icon. All eight brand variants derive from the same 460 by 320 vector path. In the source repo, run node scripts/generate-neighborhood-brand.mjs after an approved geometry change and node scripts/generate-neighborhood-brand.mjs --check to verify both package and public copies. The generator changes only symbol paths in full lockups, retaining the existing outlined type. It never embeds a bitmap.

Rules these marks carry:

• Use the file as supplied. Never redraw, recolour, stretch, crop, or replace a mark with text.
• On a dark ground use the dedicated wordmarkOnDark asset. Never reach the dark variant with a CSS filter or an inversion.
• Pin height inline (style={{ height, width: "auto" }}) so container image sizing cannot distort the mark, and never render below the minHeight in the table above.

Fonts

This package names the type families. @super-ic/foundation supplies the self-hosted font files and their public CSS entrypoints. Import @super-ic/foundation/fonts/tenants.css for the SBR and NeighborShare faces. The illustration refinement does not change typography.

SbrTypeFoundation declares:

• heading: "Plus Jakarta Sans", ui-sans-serif, system-ui, sans-serif
• body: "Inter", ui-sans-serif, system-ui, sans-serif

Within a tenant, display and heading roles bind to --font-heading; body, label, button and numeric roles bind to --font-body. Outside a tenant the foundation retains its Geist/Inter Display roles. If the named faces are not available, these roles fall back to system fonts.

Self-host rather than hot-linking a font CDN, so rendering stays deterministic and no third-party request leaks a visitor. A minimal setup:

@font-face {
  font-family: "Plus Jakarta Sans";
  src: url("/fonts/plus-jakarta-sans-variable.woff2") format("woff2");
  font-weight: 200 800;
  font-display: swap;
}
@font-face {
  font-family: "Inter";
  src: url("/fonts/inter-variable.woff2") format("woff2");
  font-weight: 100 900;
  font-display: swap;
}

Load that stylesheet after @super-ic/foundation/tokens.css. Preload the two faces used above the fold; the remaining families are fallback-tolerant.

Each family carries its own upstream licence (Plus Jakarta Sans, Inter, Geist and Inter Display are each distributed under the SIL Open Font License at time of writing). Confirm the terms for your distribution before you self-host.

Composition and motion

FRAME.md is a global design-system parameter, parallel to visual design guidance. It defines narrative, timing, directed motion, playback, responsive behavior, accessibility and delivery budgets. Tenant files inherit those invariants and specialize identity, media and narrative:

• @super-ic/brand-contracts/FRAME.md
• @super-ic/brand-contracts/frames/sandbrock/FRAME.md
• @super-ic/brand-contracts/frames/neighborshare/FRAME.md

Import GlobalFrameContract, SandbrockFrameContract and NeighborShareFrameContract from the package root for machine-readable values. Storybook registers the global frame parameter, supplies frameProfiles and exposes Foundations / Frame. These are design parameters; each media asset's manifest and product evidence establish readiness or release status separately.

IllustrationLibrary supplies original art metadata, exact hashes, intrinsic dimensions, alt text and placement guidance. Foundations / Illustration shows the current collection. The public ILLUSTRATION-STYLE.md, ILLUSTRATION-PROMPTS.md and MEDIA-GUIDANCE.md describe how to extend it, distinguish illustrations from actual listing photos, and integrate realistic Higgsfield footage with reviewed posters and accessible playback.

Versioning

BRAND_CONTRACT_VERSION is exported and tracks this package's own version. The palette, the alias set, and the mark filenames are the contract surface; a change to any of them is a breaking change.

Tenant CSS validation in Node

TENANT_OVERRIDABLE_TOKENS is the frozen, ordered 41-name compatibility array exported from the package root. TENANT_DARK_OVERRIDABLE_TOKENS separately lists the five dark overrides. Both are generated from the canonical foundation emission sequences; run npm run tenant-contract:generate after approved source changes. generate:check rejects missing or stale generated arrays.

import { assertTenantPack } from "@super-ic/brand-contracts/tenant-validation";
const result = assertTenantPack(css, { tenantId: "wengrover" });
// { tenantId: "wengrover", ruleCount: 1, declarationCount: 8 }

This Node-only helper parses CSS with PostCSS and validates tenant scoping and allowed declaration names. Each rule must use a simple data-brand or data-tenant attribute compound, optionally with data-theme="light" or data-theme="dark". All rules must identify the same tenant. The helper rejects at-rules, nested rules, global or descendant selectors, ordinary properties, unknown tokens, duplicate declarations within a rule, empty values and !important. Omit tenantId to infer the single identity from the CSS.

The helper does not approve palettes or treat declaration values as a security sandbox. Keep it in build or Node validation code. Its subpath has no browser export; importing root data contracts does not import either parser.