Customization

Portal structure

The Dev Portal is composed of two main types of pages:

• Custom pages: Fully customizable pages built using Markdown and MDC syntax.
• Pre-defined pages: Standard pages such as Login, Register, as well as API specification and documentation pages. Application registration pages are also pre-defined, and are only available within Dev Portals that support authentication and application registration.

Custom pages and Markdown Components (MDC)

You can build custom pages in your developer portal using modular building blocks known as Markdown Components (MDC). These are ready-made UI components that make it easy to structure content and apply styling without writing custom code. For example, the PageHero component lets you add a hero section that you can tailor to match your Portal's look and feel.

Each component supports a range of configuration and styling options, so you can align the design with your brand. A set of commonly used components is available out of the box, giving you the flexibility to build most layouts or visual styles you need.

Design tokens

The Konnect Developer Portal uses design tokens, exposed via CSS Custom Properties, to manage styling primitives such as spacing, colors, and font styles. You can override these tokens to ensure the portal reflects your brand's identity while maintaining consistency across all components. A full list of supported design tokens is available here: Kong Design Tokens.

You may utilize any of the design tokens in MDC props, scoped MDC styles, or in Global CSS. This allows you to create a cohesive design language that aligns with your organization's branding by referencing the same tokens throughout the Dev Portal.

Here's an example of utilizing the Portal's primary (brand) color to customize the background color of a card component:

::card
---
color: "var(--kui-color-text-inverse)"
background-color: "var(--kui-color-background-primary)"
styles: |
  .portal-card-description {
    font-size: var(--kui-font-size-50);
    font-weight: var(--kui-font-weight-semibold);
  }
---
This card utilizes built-in design token colors.
::

Styling options

To control the appearance of your Portal, you can leverage:

• MDC Props: Each pre-built component has properties that allow you to customize its appearance, such as background color, text color, and more.
• Scoped MDC styles: You can style components in isolation to avoid conflicts with other styles.
• Global CSS: Apply styles consistently across the entire Portal. This is useful for defining typography, colors, and other design elements that should be uniform throughout the Portal.

When utilizing MDC Props and Scoped MDC styles, you can achieve a high degree of customization while maintaining the integrity of the component structure. This ensures that your customizations are less likely to break with future updates to the Dev Portal. As an added benefit, you can configure these customizations in a Snippet to reuse them across multiple pages.

Let's explore the available styling options in more detail.

MDC Props

Each component supports a set of configurable properties, or props, that control its appearance and behavior. These go beyond simple styling and include options like content alignment, image sources, button styles, and more.

Props are defined using a straightforward YAML-like syntax. Each component's documentation provides clear examples, and the Konnect Portal Editor makes it easy to experiment and preview changes as you go.

For more advanced customization, some components also support slots—placeholders for inserting custom content such as Markdown or other components. This allows you to extend functionality while still using the component's default layout and styling.

A complete list of supported props and usage examples is available in each component's reference docs. If you're just getting started, the live preview in the Konnect Portal Editor is a helpful way to test configurations and get familiar with how components behave.

To learn more about available components and their customizable properties, view the desired component's documentation page and look through the shared props documentation.

Scoped MDC styles

Each component includes a styles prop that allows you to apply custom CSS directly to the component. You can target both the component's root element and its internal child elements using standard CSS syntax (including nested CSS as well as CSS Custom Properties).

This makes it easy to align components with your brand's look and feel, adjusting things like spacing, typography, and colors without needing to override styles globally.

The styles property is especially useful when you want to make visual tweaks without creating a completely custom component. It's a quick and flexible way to adapt components to your needs while preserving their built-in structure and functionality.

Scoped styles example

::card
---
styles: |
  cursor: pointer;
  transition: box-shadow 0.3s ease-in-out, transform 0.2s ease-in-out;

  &:hover {
    transform: scale(1.01);
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  }

  .custom-container {
    font-size: 28px;
    font-weight: 600;
  }
---
  ::container
  ---
  class: "custom-container"
  ---
  Hover over this card to see the styles in action.
  ::
::

Inspecting the example above:

• The cursor, transition, and box-shadow styles apply to the root component element.
• The .custom-container class selector targets the element with the corresponding class inside the component's default slot, allowing you to change its font size.

Global CSS

The Global CSS section lets you define styles that apply across the entire Dev Portal. This is the ideal place to set consistent theming for foundational elements like page layouts, headers, footers, and typography, and global color overrides.

Use Global CSS sparingly to customize elements such as:

• Header, footer, and navigation
• Typography styles
• Logo sizing and placement
• Spacing and layout wrappers

Here's an example of how to use Global CSS to override a few of the Dev Portal's built-in design tokens. To try out, the CSS shown below should be stored in the Global CSS section of your Dev Portal configuration:

:root {
  /* Change border color across the entire Dev Portal */
  --kui-color-border: #45a8db;

  /* Change the background color utilized in the header,
   * scoped to the `.layout-header` class to prevent impacting other elements */
  .layout-header {
    --kui-color-background: #45a8db;
  }
}

Custom fonts

The utilize custom fonts in your Dev Portal, you can import and configure them in the Portal's Global CSS configuration.

1. Start by utilizing an @import rule within your Global CSS (e.g. from Google Fonts or a custom font URL).
2. Next, configure the built-in design tokens to use the imported font(s):

/* Importing the `Inter` and `JetBrains Mono` font families from Google Fonts. */
@import url('https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&display=swap');

:root {
  --kui-font-family-text: 'Inter', Roboto, Helvetica, sans-serif;
  --kui-font-family-heading: 'Inter', Roboto, Helvetica, sans-serif;
  --kui-font-family-code: 'JetBrains Mono', Consolas, monospace;
}

Note that not all elements/components inherit these global font styles automatically. When necessary, you may need to apply the font-family directly to specific MDC styles to ensure consistency.

Responsive design tips

When customizing elements such as headings, layout spacing, and typography, it's important to keep responsive design at the top of mind.

The Konnect Portal Editor includes a built-in preview feature that lets you inspect your Portal layout at multiple viewport sizes. This is especially helpful when designing for responsiveness, as it allows you to see how components and layouts adapt across different viewport widths.

By testing different screen widths early in the customization process, you can catch layout issues such as overlapping content, misaligned elements, or components that don't scale as expected. Keep in mind that while many components are designed to be responsive by default, certain customizations like fixed widths, image sizes, or complex nested layouts, may require additional styling adjustments to behave well across different breakpoints.

Using clamp() for typography

The Dev Portal supports modern CSS features like clamp(), which allows you to create flexible, scalable styles that automatically adapt to different screen sizes. This helps maintain a consistent and accessible experience across all devices.

The clamp() function allows you to define a responsive value with a minimum, preferred, and maximum size. This is particularly useful for font sizes and line heights in headings or hero sections.

::page-hero
---
title-font-size: "clamp(36px, 5vw, 70px)"
title-line-height: "clamp(36px, 5vw, 74px)"
---
::

The configuration above ensures:

• The value will not shrink below 36px
• Will scale dynamically with 5vw (5% of the viewport width)
• Will cap at 70px (or 74px for line height)

This gives you precise control over how elements behave across devices, from mobile phones to large desktops.