Skip to main content

Gesso Theme Documentation

Overview​

The Gesso Theme extends Material-UI's theming system to provide a comprehensive design system for your applications. Built on Material-UI's createTheme function, it offers extensive customization options while maintaining consistent design patterns.

Core Features​

  • Extended Material-UI Theme: Enhances the base Material-UI theme with additional functionality
  • Comprehensive Token System: Centralized design tokens for colors, typography, spacing, and more
  • Component Defaults: Pre-configured component styles for consistency
  • TypeScript Support: Full type definitions for theme customization
  • Fluid Typography: Automatically scales text based on viewport width

Theme Structure​

1. Core Theme Interface​

The Gesso theme extends Material-UI's base theme with additional properties:

interface Theme extends MaterialTheme {
  tokens: Tokens;
  palette: Palette;
  typography: Typography;
  componentDefaults: ComponentDefaults;
  name: string;
}

2. Design Tokens​

Design tokens are the foundation of the theme system, organized into categories:

Visual Tokens​

interface Tokens {
  borderWidths: {
    thin: string;
    fine: string;
    medium: string;
    thick: string;
    [key: string]: string;
  };
  colors: {
    palettePrimaryMain: string;
    palettePrimaryDark: string;
    palettePrimaryLight: string;
    // ... other color tokens
  };
  radii: {
    small: string;
    medium: string;
    large: string;
    pill: string;
  };
  // ... other token categories
}

Typography Tokens​

interface FontSizes {
  h1: string;
  h1Min: string;
  body1: string;
  body1Min: string;
  // ... other font sizes
}

interface Typography extends MaterialTypography {
  h1Small: CSSProperties;
  lead: CSSProperties;
  buttonLarge: CSSProperties;
  // ... other typography variants
}

Extended Palette​

interface Palette extends MaterialPalette {
  text: TypeText;
  inverse: MaterialPaletteColor;
  tertiary: MaterialPaletteColor;
  quaternary: MaterialPaletteColor;
  border: GessoBorderPaletteColor;
}

Usage​

Basic Theme Setup​

import { createGessoTheme } from "@acromedia/gesso";
import tokens from "./tokens";

const theme = createGessoTheme({
  tokens,
  // Optional overrides
  palette: {
    primary: {
      main: "#1976d2",
    },
  },
  typography: {
    fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
  },
  componentDefaults: {
    Button: {
      variant: "contained",
    },
  },
});

Using Theme Tokens​

import { useTheme } from "@acromedia/gesso";
import type { Theme } from "@acromedia/gesso/dist/themes/Gesso/Gesso.types";

const MyComponent = () => {
  const theme = useTheme<Theme>();

  return (
    <div
      style={{
        color: theme.palette.primary.main,
        padding: theme.tokens.spacing.md,
        borderRadius: theme.tokens.radii.medium,
      }}
    >
      Content
    </div>
  );
};

Theme File Locations​

The theme files are divided between the design system and the frontend application for modularity and reusability.

When creating a new Gesso design system or frontend application, the starter theme is used to provide a base configuration for the theme tokens. This starter theme uses the createGessoTheme function from the @acromedia/gesso package and includes tokens such as borderWidths, colors, delays, and more. Below is an example of the starter theme:

Design System Theme​

Used when creating a new Gesso design system:

import { createGessoTheme } from "@acromedia/gesso";
import borderWidths from "../../tokens/borderWidths";
// ... other token imports

const theme = createGessoTheme({
  borderWidths,
  colors,
  // ... other tokens
});

Frontend Project Theme​

Used in frontend applications, with flexible token overrides:

import { createGessoTheme, Tokens } from "@acromedia/gesso";
import borderWidths from "../tokens/borderWidths";
// ... other token imports

const tokens: Partial<Tokens> = {
  ...(borderWidths ? { borderWidths } : {}),
  ...(colors ? { colors } : {}),
  // ... other conditional token spreads
};

const theme = createGessoTheme(tokens);

Token Categories​

Layout Tokens​

  • spacing: Standard spacing units
  • mediaQueries: Breakpoint definitions
  • zIndices: Z-axis stacking order values

Animation Tokens​

  • delays: Animation delay timings
  • durations: Animation duration values
  • easings: Easing functions for animations

Typography Tokens​

  • fontFamilies: Available font families
  • fontSizes: Text size scale
  • fontWeights: Font weight variations
  • letterSpacings: Character spacing options
  • lineHeights: Text line height values

Visual Tokens​

  • colors: Complete color palette
  • borderWidths: Border thickness values
  • radii: Border radius values
  • opacities: Opacity/transparency values

Customization Guide​

Key Modifiable Pieces​

Typography Adjustments​

Located in the typography section within createGessoTheme. This section allows you to change font sizes, line heights, and font weights for different elements like headers, buttons, and body text.

Color Palette Changes​

The color palette is defined in the palette section of the theme. You can add new colors or modify existing palettes like primary, secondary, or custom ones like tertiary and quaternary.

Component Style Overrides​

We have a dedicated components section for overriding MUI components. This section can be used to modify default component styles, such as MuiOutlinedInput for text fields.

Theme Tokens​

  1. All token files are typically auto-generated from design tools (like Figma) using tools like Figmagic
  2. Each token category is imported separately for better code organization and maintainability
  3. The createGessoTheme function combines all these tokens into a single, cohesive theme object
  4. Token values should be kept in their respective files and not hardcoded in components

example:

  1. Colors
// tokens/colors.ts
export default {
  palettePrimaryMain: "#1976d2",
  palettePrimaryLight: "#42a5f5",
  palettePrimaryDark: "#1565c0",
  // ... other colors
};
  1. Typography
// tokens/fontSizes.ts
export default {
  h1: "3.052rem",
  h1Min: "2.441rem",
  body1: "1rem",
  body1Min: "0.875rem",
  // ... other sizes
};

Component Style Overrides​

const theme = createGessoTheme({
  components: {
    MuiButton: {
      styleOverrides: {
        root: {
          borderRadius: "8px",
          textTransform: "none",
        },
      },
    },
  },
});

How the Theme is Used on Pages​

The theme is applied globally using MUI's ThemeProvider. In our Gesso setup, the theme wraps the entire application in the main entry file (e.g., App.tsx). Components throughout the application will automatically inherit the theme configurations, including typography, color palette, and spacing, without needing additional configurations.

To ensure consistency, always make use of components from the design system or theme-aware components. Custom components should be styled with the useTheme hook or styled utility to access the Gesso theme properties directly.

Best Practices​

Do's​

  • ✅ Use theme tokens for all design values
  • ✅ Maintain design tokens in a centralized location
  • ✅ Override component defaults through the theme when possible
  • ✅ Use the useTheme hook from @acromedia/gesso
  • ✅ Define custom component styles using theme tokens

Don'ts​

  • ❌ Import MUI components directly (use Gesso's wrapped versions)
  • ❌ Hardcode values that could be tokens
  • ❌ Mix different theming approaches
  • ❌ Duplicate token definitions

Important Usage Note​

❗ Critical: Never import directly from '@mui/material' or other MUI packages. Always use Gesso's wrapped versions:

// ✅ Correct usage
import { useTheme } from "@acromedia/gesso";
import type { Theme } from "@acromedia/gesso/dist/themes/Gesso/Gesso.types";

const MyComponent = () => {
  const theme = useTheme<Theme>(); // Returns enhanced Gesso theme
  return <></>;
};

// ❌ Incorrect usage
import { useTheme } from "@mui/material"; // Don't do this!

Getting Help​

  • Check the MUI documentation
  • Review the Gesso source code
  • Contact the Gesso maintainers

Resources​