v1.2.6
Theme
Colors
Canopy exposes a single theme block in canopy.yml to control the site-wide accent palette, gray palette, and base appearance. These values generated CSS variables ship with your project so your user interface and MDX components stay in sync and accessible. Modify the canopy.yml file in the root of your project to adjust these settings. Updating this configuration will require a rebuild of your project to take effect. Here is an example configuration:
theme: appearance: dark accentColor: bronze grayColor: sandappearanceflips the design token ramp (lightordark).accentColordrives buttons, links, checkboxes, and focus rings.grayColorsets the base neutral ramp used for page backgrounds, card borders, and typography.
Color scales
Accent and gray ramps from the active theme.
Accent color palette options
Primary color steps used for buttons, links, and highlights.
Gray color palette options
Neutral color steps used for backgrounds, borders, and text.
Typography
In many cases, you may want to adjust the base typography styles to suit your branding. To do so, modify the standard CSS entry point (app/styles/index.css) to customize the theme. Here is an example of setting custom font families and max-width utilities. In this case we set the default sans-serif font to Inter, set the --font-sans variable as default, and modify the base font size and weight.
@layer properties { :root, :host { --font-sans: "Inter", system-ui, "Segoe UI", Helvetica, Arial, sans-serif; --font-serif: Georgia, "Times New Roman", serif; --font-mono: "ui-monospace", Menlo, Consolas, monospace; --default-font-family: var(--font-sans); }} @utility max-w-content { max-width: 1080px;} @utility max-w-wide { max-width: 1300px;} @layer base { html { font-size: 100%; font-weight: 400; } body { background: var(--color-gray-50); color: var(--color-gray-900); }}In addition to modifying the base styles, you will also want to ensure your font files are included in the project. You can easily do this with web fonts like Google Fonts by adding the appropriate <link> tags to your content/_app.mdx head block.
export function Head() { return ( <> <Meta siteTitle="Manu's Great Flood" /> <Stylesheet /> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap" rel="stylesheet"> </> );}Styling
Implementers can easily customize their Canopy projects by adding their own CSS rules that extend or override the default styles. Many Canopy components accept className and other valid HTML attributes so you can apply scoped changes without overriding the global theme. You can author these in your custom CSS files that extend the base styles.
First, ensure your custom CSS files are imported in the main stylesheet (app/styles/index.css):
@import "tailwindcss";@import "@canopy-iiif/app/ui/styles/index.css";@import "./custom.css";`CSS Variables
You can then add your own CSS rules in app/styles/_custom.css or new files you import to extend or override existing styles. This can include modifying CSS variables, adding new classes, or defining more complex selectors. For example, a Northwestern University digital project might include the following customizations to match institutional brand.
/* Northwestern Brand *//* https://www.northwestern.edu/brand/visual-identity/color-palettes/ */ @layer properties { :root, :host { /* Northwestern Purple */ --color-accent-50: #ffffff; --color-accent-100: #e4e0ee; /* Purple 10 */ --color-accent-200: #ccc4df; /* Purple 20 */ --color-accent-300: #b6acd1; /* Purple 30 */ --color-accent-400: #a495c3; /* Purple 40 */ --color-accent-500: #9380b6; /* Purple 50 */ --color-accent-600: #765da0; /* Purple 70 */ --color-accent-700: #4e2a84; /* Northwestern Purple */ --color-accent-800: #401f68; /* Purple 120 */ --color-accent-900: #200b48; /* Purple 160 */ /* Northwestern Rich Black */ --color-gray-50: #ffffff; --color-gray-100: #d8d6d6; /* Rich Black 10% */ --color-gray-200: #bbb8b8; /* Rich Black 20% */ --color-gray-300: #a29f9e; /* Rich Black 30% */ --color-gray-400: #8a8585; /* Rich Black 40% */ --color-gray-500: #716c6b; /* Rich Black 50% */ --color-gray-600: #484342; /* Rich Black 70% */ --color-gray-700: #342f2e; /* Rich Black 80% */ --color-gray-800: #1a1817; /* Rich Black 90% */ --color-gray-900: #000000; /* Rich Black */ /* Additional Variables */ --color-northwestern-purple: var(--color-accent-700); --color-accent-default: var(--color-northwestern-purple); --color-gray-default: var(--color-gray-900); --color-gray-muted: var(--color-gray-700); }}Overrides
You can also override existing styles by targeting specific classes. For example, to modify the default button styles across your project, you can add the following CSS rules:
/* overrides default button styling */.canopy-button { border-radius: 0;}<Button href="/search" label="Browse Works" />Custom classes
Implementers can easily add their own custom CSS classes like custom-button to modify button styles.
/* adds custom soft button styling */.custom-button { font-weight: 700; background: linear-gradient( 135deg, var(--color-accent-50) 0%, var(--color-accent-200) ); color: var(--color-accent-800); border: 2px solid var(--color-accent-300); box-shadow: 2px 2px 5px var(--color-accent-200);}<Button className="custom-button" href="/bibliography" label="Bibliography" />Complex selectors
You can also extend existing button classes by explicitly defining new selectors like this example with the added data-color="crimson" attribute.
/* adds custom crimson shaded button */.canopy-button[data-color="crimson"] { background-color: #df3478; &:hover, &:focus { background-color: #cb1d63; }}<Button data-color="crimson" href="/exhibit" label="Explore Exhibit" />