feat(release): add logo src capabilities

.changeset/real-comics-marry.md

@@ -0,0 +1,5 @@
+---
+"brand-shell": minor
+---
+
+introduce logo src for customizable logo addition

apps/docs/src/App.tsx

@@ -32,6 +32,8 @@ const DEFAULT_DETAILS: BrandDetails = {
   twitter: "https://x.com/example",
   email: "hello@example.com",
   tagline: "One shared brand shell across frameworks.",
+  logoSrc: "https://avatars.githubusercontent.com/u/9919?s=64&v=4",
+  logoAlt: "Brand Shell",
 };
 
 const DEFAULT_THEME: BrandTheme = {

schemas/brand-shell.schema.json

@@ -83,7 +83,9 @@
         "customSocialLinks": {
           "type": "array",
           "items": { "$ref": "#/$defs/CustomSocialLink" }
-        }
+        },
+        "logoSrc": { "type": "string", "minLength": 1 },
+        "logoAlt": { "type": "string", "minLength": 1 }
       }
     },
     "BrandTheme": {
@@ -101,7 +103,8 @@
         "borderRadius": { "type": "string", "minLength": 1 },
         "headerHeight": { "type": "string", "minLength": 1 },
         "footerPadding": { "type": "string", "minLength": 1 },
-        "secondaryButtonBg": { "type": "string", "minLength": 1 }
+        "secondaryButtonBg": { "type": "string", "minLength": 1 },
+        "logoHeight": { "type": "string", "minLength": 1 }
       }
     }
   }

src/Footer.tsx

@@ -53,7 +53,15 @@ export function Footer({ details, theme, className, renderLink }: FooterProps) {
       <div className="brand-shell-footer__inner">
         <div className="brand-shell-footer__top">
           <div className="brand-shell-footer__brand">
-            <p className="brand-shell-footer__name">{normalizedDetails.name}</p>
+            {normalizedDetails.logoSrc ? (
+              <img
+                src={normalizedDetails.logoSrc}
+                alt={normalizedDetails.logoAlt ?? normalizedDetails.name}
+                className="brand-shell-footer__logo"
+              />
+            ) : (
+              <p className="brand-shell-footer__name">{normalizedDetails.name}</p>
+            )}
             {normalizedDetails.tagline && <p className="brand-shell-footer__tagline">{normalizedDetails.tagline}</p>}
           </div>
           {navLinks.length > 0 && (

src/Header.tsx

@@ -55,17 +55,27 @@ export function Header({ details, theme, className, renderLink }: HeaderProps) {
         <a href={href} className={cls} aria-label={ariaLabel} target={target} rel={rel}>{children}</a>
       );
 
+  const logoContent = normalizedDetails.logoSrc ? (
+    <img
+      src={normalizedDetails.logoSrc}
+      alt={normalizedDetails.logoAlt ?? normalizedDetails.name}
+      className="brand-shell-header__logo"
+    />
+  ) : (
+    normalizedDetails.name
+  );
+
   const brandIdentity = normalizedDetails.homeHref ? (
     <LinkEl
       href={normalizedDetails.homeHref}
       className="brand-shell-header__name"
       aria-label={`${normalizedDetails.name} home`}
       target="_self"
     >
-      {normalizedDetails.name}
+      {logoContent}
     </LinkEl>
   ) : (
-    <span className="brand-shell-header__name">{normalizedDetails.name}</span>
+    <span className="brand-shell-header__name">{logoContent}</span>
   );
 
   return (

src/core/shell.ts

@@ -64,6 +64,8 @@ export function normalizeBrandDetails(details: BrandDetails): NormalizedBrandDet
     primaryAction: normalizedPrimaryAction,
     secondaryAction: normalizedSecondaryAction,
     customSocialLinks: normalizeCustomSocialLinks(details.customSocialLinks),
+    logoSrc: normalizeSafeHref(details.logoSrc),
+    logoAlt: details.logoAlt,
   };
 }
 

src/core/theme.ts

@@ -25,6 +25,7 @@ export function themeToCssVariables(theme?: BrandTheme | null): ThemeVariables {
   if (theme.headerHeight != null) style[`--${THEME_VAR_PREFIX}-header-height`] = theme.headerHeight;
   if (theme.footerPadding != null) style[`--${THEME_VAR_PREFIX}-footer-padding`] = theme.footerPadding;
   if (theme.secondaryButtonBg != null) style[`--${THEME_VAR_PREFIX}-button-secondary`] = theme.secondaryButtonBg;
+  if (theme.logoHeight != null) style[`--${THEME_VAR_PREFIX}-logo-height`] = theme.logoHeight;
   return style;
 }
 

src/core/types.ts

@@ -71,6 +71,10 @@ export interface BrandDetails {
   tagline?: string;
   /** Additional social links for custom platforms (Bluesky, Mastodon, YouTube, etc.) */
   customSocialLinks?: CustomSocialLink[];
+  /** URL to logo image shown in header/footer. Replaces the text name visually. */
+  logoSrc?: string;
+  /** Alt text for the logo. Defaults to `name` if omitted. */
+  logoAlt?: string;
 }
 
 /**
@@ -102,4 +106,6 @@ export interface BrandTheme {
   footerPadding?: string;
   /** Secondary button background color → --brand-button-secondary */
   secondaryButtonBg?: string;
+  /** Logo image height (e.g. "2rem", "32px") → --brand-logo-height */
+  logoHeight?: string;
 }

src/core/validation.test.ts

@@ -75,6 +75,52 @@ describe("validateBrandDetails", () => {
     expect(result.valid).toBe(false);
     expect(result.errors).toContain("details.email must be a valid email or mailto URL.");
   });
+
+  it("accepts valid logoSrc and logoAlt", () => {
+    const result = validateBrandDetails({
+      name: "Brand Shell",
+      logoSrc: "https://example.com/logo.svg",
+      logoAlt: "Brand Shell logo",
+    });
+
+    expect(result.valid).toBe(true);
+    expect(result.normalized?.logoSrc).toBe("https://example.com/logo.svg");
+    expect(result.normalized?.logoAlt).toBe("Brand Shell logo");
+  });
+
+  it("accepts relative logoSrc", () => {
+    const result = validateBrandDetails({
+      name: "Brand Shell",
+      logoSrc: "/images/logo.svg",
+    });
+
+    expect(result.valid).toBe(true);
+    expect(result.normalized?.logoSrc).toBe("/images/logo.svg");
+    expect(result.normalized?.logoAlt).toBeUndefined();
+  });
+
+  it("rejects unsafe logoSrc protocols", () => {
+    const result = validateBrandDetails({
+      name: "Brand Shell",
+      logoSrc: "javascript:alert(1)",
+    });
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain(
+      "details.logoSrc must use a safe URL/path (http, https, mailto, tel, or relative path).",
+    );
+  });
+
+  it("accepts logoSrc without logoAlt, logoAlt defaults to name", () => {
+    const result = validateBrandDetails({
+      name: "Acme Corp",
+      logoSrc: "https://example.com/logo.png",
+    });
+
+    expect(result.valid).toBe(true);
+    expect(result.normalized?.logoSrc).toBe("https://example.com/logo.png");
+    expect(result.normalized?.logoAlt).toBeUndefined();
+  });
 });
 
 describe("validateBrandTheme", () => {

src/core/validation.ts

@@ -18,6 +18,7 @@ const THEME_KEYS = new Set<keyof BrandTheme>([
   "headerHeight",
   "footerPadding",
   "secondaryButtonBg",
+  "logoHeight",
 ]);
 
 type ValidationErrorPath = string;
@@ -64,6 +65,9 @@ export function validateBrandDetails(details: unknown): BrandValidationResult<No
   validateOptionalString(details.discord, "details.discord", errors);
   validateSafeHref(details.discord, "details.discord", errors);
   validateOptionalString(details.tagline, "details.tagline", errors);
+  validateOptionalString(details.logoSrc, "details.logoSrc", errors);
+  validateSafeHref(details.logoSrc, "details.logoSrc", errors);
+  validateOptionalString(details.logoAlt, "details.logoAlt", errors);
 
   if (details.navLinks != null) {
     if (!Array.isArray(details.navLinks)) {

src/web/index.ts

@@ -305,6 +305,14 @@ function createHeader(
   const identity = details.homeHref
     ? createAnchor(details.homeHref, "brand-shell-header__name", details.name, `${details.name} home`, "_self", undefined, linkFactory)
     : createSpan("brand-shell-header__name", details.name);
+  if (details.logoSrc) {
+    const img = document.createElement("img");
+    img.src = details.logoSrc;
+    img.alt = details.logoAlt ?? details.name;
+    img.className = "brand-shell-header__logo";
+    identity.textContent = "";
+    identity.append(img);
+  }
   inner.append(identity);
 
   const actions = document.createElement("div");
@@ -349,7 +357,15 @@ function createFooter(
 
   const brand = document.createElement("div");
   brand.className = "brand-shell-footer__brand";
-  brand.append(createParagraph("brand-shell-footer__name", details.name));
+  if (details.logoSrc) {
+    const img = document.createElement("img");
+    img.src = details.logoSrc;
+    img.alt = details.logoAlt ?? details.name;
+    img.className = "brand-shell-footer__logo";
+    brand.append(img);
+  } else {
+    brand.append(createParagraph("brand-shell-footer__name", details.name));
+  }
   if (details.tagline) {
     brand.append(createParagraph("brand-shell-footer__tagline", details.tagline));
   }

styles/default.css

@@ -109,6 +109,18 @@
   color: var(--_primary);
 }
 
+.brand-shell-header__logo {
+  height: var(--brand-logo-height, 2rem);
+  width: auto;
+  display: block;
+  object-fit: contain;
+}
+
+/* Hide decorative dot when logo is present */
+.brand-shell-header__name:has(.brand-shell-header__logo)::before {
+  display: none;
+}
+
 .brand-shell-header__name:focus-visible {
   outline: 2px solid var(--_primary);
   outline-offset: 3px;
@@ -437,6 +449,14 @@
   margin: 0 0 var(--brand-space-sm) 0;
 }
 
+.brand-shell-footer__logo {
+  height: calc(var(--brand-logo-height, 2rem) * 0.75);
+  width: auto;
+  display: block;
+  object-fit: contain;
+  margin-bottom: var(--brand-space-sm);
+}
+
 .brand-shell-footer__nav {
   display: flex;
   align-items: center;