Skip to main content

Brand packages and course sites

The theme ships no institution’s identity. Everything that makes a site look like it belongs to a particular university (palette, logos, the footer’s legal links and regulatory lines, an acknowledgement) is data. Sites can pass all of that as props and CSS directly. But once two sites share an institution, it’s worth packaging the data once as a brand package installed alongside the theme.

Institutional brand assets are usually trademarked, so brand packages tend to live on an institution’s own Git host rather than on a public registry. The theme doesn’t care where the package comes from; only that it exports the two halves below.

Anatomy of a brand package

A brand package is a plain npm package with no build step. Two exports do the work:

A stylesheet that overrides the palette. Because the theme declares its tokens inside @layer at.tokens, unlayered declarations win the cascade regardless of import order, so the file is just custom properties:

/* brand.css */
:root {
  --at-primary: #7c2d12;
  --at-secondary: #0e7490;
  --at-tertiary: #6d28d9;
}

Every semantic colour on the web side derives from --at-primary; --at-tertiary colours info callouts, and --at-secondary reaches only the deck tint scales (see customisation). A brand with hand-tuned link or hover colours pins those tokens in the same file.

A branding object shaped to spread straight into BaseLayout or defineSiteConfig. It carries the props the theme renders only when given:

// index.ts
import type { SiteConfig } from "astro-theme-university/types";
import lockup from "./assets/lockup.svg";
import lockupDark from "./assets/lockup-white.svg";
import crest from "./assets/crest.svg";
import favicon from "./assets/favicon.svg";

export const exampleBranding = {
  logo: lockup,
  logoDark: lockupDark,
  logoCompact: crest,
  favicon,
  legalLinks: [
    { text: "Copyright", href: "https://www.example.edu/copyright" },
    { text: "Privacy", href: "https://www.example.edu/privacy" },
  ],
  meta: ["Example University, Springfield | Provider ID: EX-0000"],
  acknowledgement: {
    title: "Acknowledgement",
    text: "Example University acknowledges the traditional custodians of the land on which it stands.",
    logo: lockupDark,
    logoAlt: "Example University",
  },
} satisfies Partial<SiteConfig>;

logoCompact matters when the lockup is a wide horizontal mark: the nav swaps to it below the 640px breakpoint instead of wrapping. See the Nav docs. partnerships adds a logo band to the footer’s dark strip.

The package’s package.json needs "type": "module", an exports map naming ., ./brand.css, and ./assets/*, and a files list covering them. Because the object imports SVGs, the package is consumed through Astro’s Vite pipeline like any other source, so there’s nothing to compile.

Consuming a brand package

Install it next to the theme, pinned to an exact tag of wherever your institution hosts it. (Any Git host works; the &path: suffix is only needed when the package sits in a subdirectory of its repo.)

pnpm add "git+https://git.example.edu/brand/example-brand.git#vX.Y.Z"

Then wire the two halves:

// astro.config.ts
import { defineConfig } from "astro/config";
import universityTheme from "astro-theme-university";

export default defineConfig({
  integrations: [universityTheme({ brandCss: "example-brand/brand.css" })],
});
// src/site-config.ts
import { defineSiteConfig } from "astro-theme-university/types";
import { exampleBranding } from "example-brand";

export const siteConfig = defineSiteConfig({
  ...exampleBranding,
  name: "My Research Group",
  links: [{ text: "Home", href: "/" }],
});

brandCss imports the stylesheet on every page, so a site that spreads the branding into its site config never touches the brand package again. The alternative, import "example-brand/brand.css" in a layout, is equivalent for pages that use that layout but doesn’t reach deck routes, which astromotion renders without it. brandCss does: Astro injects it into every page module, injected routes included. Props placed after the spread win, so a site with its own logo spreads the branding and then overrides logo.

For decks, import the brand stylesheet after the theme’s deck styles in the deck theme file:

/* src/decks/theme.css */
@import url("astro-theme-university/styles/deck.css");
@import url("example-brand/brand.css");

A brand package can also ship deck partials (a closing logo slide, say) that any deck includes by bare module specifier; see lecture decks.

Course sites

A course website is a themed site plus a content model. That model lives in astro-course-university, a brand-neutral package that provides:

The three packages stack without knowing about each other: the theme renders, the course package models and validates, and a brand package supplies the identity. A minimal astro.config.ts for a course site is:

import { defineConfig } from "astro/config";
import universityTheme from "astro-theme-university";
import courseGraph from "astro-course-university";
import { courseCollections } from "./src/course-collections";

export default defineConfig({
  site: process.env.SITE_URL,
  base: process.env.BASE_PATH,
  integrations: [
    universityTheme({
      defaultLayout: "src/layouts/PageLayout.astro",
      brandCss: "example-brand/brand.css",
      decks: true,
    }),
    // the same spec object src/content.config.ts builds its collections from
    courseGraph({ collections: courseCollections }),
  ],
});

The collections are declared once, in a plain module both config files import; the course package’s README documents that spec, refs, spec: lists and the generated API. Institutions that maintain a brand package usually keep a course-site starter beside it, already wired to all three.