# Comprehensive Styling Options in Arc-Kit: Themes, CSS, and Diagram Customization

> Explore Arc-kit styling options: global themes, hero banners, diagram themes for Mermaid and PlantUML, Marp, and custom CSS. Tailor your documentation and diagrams with ease.

- Repository: [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit)
- Tags: how-to-guide
- Published: 2026-04-19

---

**Arc-kit provides flexible styling options including global dark/light mode themes, hero banner variants, Mermaid and PlantUML diagram themes, Marp presentation themes, and custom CSS overrides across the documentation and diagram generation pipeline.**

The `tractorjuice/arc-kit` repository ships with a modular styling system that controls the visual appearance of generated documentation, web interfaces, diagrams, and presentations. These **styling options in arc-kit** are distributed across dedicated CSS files and configuration references, allowing you to customize everything from site-wide color schemes to individual diagram themes without modifying core logic.

## Global Site Themes and Dark Mode

The foundation of arc-kit's visual design lives in [`docs/theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/theme.css), which defines the color palette, typography, and component styling inspired by GOV.UK design principles.

### Implementing Dark Mode in Arc-Kit

Arc-kit supports automatic dark mode toggling through CSS class manipulation. The system applies the `dark-mode` or `light-mode` class to the `<html>` element, triggering cascade changes defined in [`docs/theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/theme.css) beginning at line 72.

```javascript
// Toggle dark mode – adds the `dark-mode` class to <html>
const toggle = document.querySelector('.app-theme-toggle')
toggle.addEventListener('click', () => {
  document.documentElement.classList.toggle('dark-mode')
})

```

These rules override global colors, background values, text contrasts, and border colors while preserving the structural layout.

### GOV.UK Component Styling

The [`theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/theme.css) file also overrides standard GOV.UK component colors to align with arc-kit's branding. These rules are additive, meaning they layer on top of existing inline styles without destructive replacement, as noted in the CSS comments at line 2 of [`docs/theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/theme.css).

## Page Hero Banner Styling Options

Arc-kit provides pre-designed hero banners for different sections of the documentation site, controlled through [`docs/heroes.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/heroes.css).

### Pre-Styled Hero Variants

Each page type can declare a specific hero class that applies gradient backgrounds, overlay patterns, and responsive padding. The available variants include:

- **Commands**: `.app-page-hero--commands`
- **Guides**: `.app-page-hero--guides`
- **Roles**: `.app-page-hero--roles`
- **Projects**: `.app-page-hero--projects`
- **Getting Started**: `.app-page-hero--getting-started`
- **Home**: `.app-page-hero--home`
- **Viewer**: `.app-page-hero--viewer`
- **Contributors**: `.app-page-hero--contributors`

To apply a hero style, add the `heroClass` property to your page frontmatter:

```markdown
---
title: "ArcKit Commands"
heroClass: "app-page-hero--commands"
---

```

The page generator creates the element `<section class="app-page-hero app-page-hero--commands">`, which triggers the gradient and pattern rules defined at line 40 of [`docs/heroes.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/heroes.css).

## Diagram Theming in Arc-Kit

Arc-kit integrates with Mermaid and PlantUML for diagram generation, offering extensive theme configuration for both libraries.

### Mermaid Theme Configuration

Mermaid diagrams support global theme selection and granular color overrides through the `themeVariables` object. Configuration is defined in the diagram initialization block.

```mermaid
%%{init: { "theme": "base", "themeVariables": { "primaryColor":"#4da3ff", "secondaryColor":"#a0a8b0" } } }%%
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Proceed]
    B -->|No| D[Stop]

```

The `themeVariables` syntax documentation resides in [`arckit-paperclip/skills/mermaid-syntax/references/xyChart.md`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-paperclip/skills/mermaid-syntax/references/xyChart.md) at line 146. Available themes include `base`, `forest`, `dark`, and others.

For Wardley-style maps specifically, arc-kit includes example CSS in [`tests/mermaid-wardley/wardley-style.css`](https://github.com/tractorjuice/arc-kit/blob/main/tests/mermaid-wardley/wardley-style.css), demonstrating how to apply custom CSS to achieve Wardley Mapping aesthetics.

### PlantUML Theme Options

PlantUML diagrams support both built-in themes and custom theme files. Built-in options include `cerulean`, `blueprint`, `plain`, and `sketchy-outline`.

```plantuml
@startuml
!theme cerulean
Alice -> Bob: Hello
@enduml

```

The complete list of built-in themes is documented in [`arckit-paperclip/skills/plantuml-syntax/references/styling-guide.md`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-paperclip/skills/plantuml-syntax/references/styling-guide.md) starting at line 145. For custom themes, use the `!theme <name> from <path>` directive to load external theme files.

## Presentation Styling with Marp

When generating presentations from markdown, arc-kit utilizes Marp CLI, which supports theme selection via command-line flags.

```bash
marp --theme gaia --pdf my-presentation.md

```

Available themes include `gaia`, `default`, and custom CSS files. The presentation guide in [`docs/guides/presentation.md`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/presentation.md) (line 33) documents these options. Templates for presentations reside in `arckit-paperclip/templates/`, allowing you to create standardized slide decks with consistent styling.

## Custom CSS Overrides and Extensions

Arc-kit's styling system is designed for extension. Because all styles are pure CSS, you can create a [`custom.css`](https://github.com/tractorjuice/arc-kit/blob/main/custom.css) file in your project and reference it after the default stylesheets.

The default rules are additive, meaning they layer onto existing inline styles without destructive replacement. As noted in the comments at line 2 of [`docs/theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/theme.css), "Additive CSS overrides — existing inline styles remain untouched." This architecture ensures that your customizations apply predictably without breaking base functionality.

To override specific components:

1. Create your custom stylesheet (e.g., [`custom.css`](https://github.com/tractorjuice/arc-kit/blob/main/custom.css))
2. Include it after [`theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/theme.css) and [`heroes.css`](https://github.com/tractorjuice/arc-kit/blob/main/heroes.css) in your HTML template
3. Target specific classes (e.g., `.app-page-hero--home`) to modify gradients, colors, or spacing

## Summary

- **Global theming** is controlled via [`docs/theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/theme.css), supporting dark/light mode toggling through the `dark-mode` and `light-mode` classes on the `<html>` element.
- **Hero banners** offer nine pre-styled variants (Commands, Guides, Roles, etc.) defined in [`docs/heroes.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/heroes.css), activated through the `heroClass` frontmatter property.
- **Diagram theming** supports Mermaid (`themeVariables` in [`xyChart.md`](https://github.com/tractorjuice/arc-kit/blob/main/xyChart.md)) and PlantUML (built-in themes listed in [`styling-guide.md`](https://github.com/tractorjuice/arc-kit/blob/main/styling-guide.md)), plus custom Wardley-style CSS examples.
- **Presentation styling** utilizes Marp CLI themes (`gaia`, `default`, etc.) documented in [`presentation.md`](https://github.com/tractorjuice/arc-kit/blob/main/presentation.md) with templates in `arckit-paperclip/templates/`.
- **Customization** is achieved through additive CSS overrides; create a [`custom.css`](https://github.com/tractorjuice/arc-kit/blob/main/custom.css) file and load it after defaults to modify any component without breaking core styles.

## Frequently Asked Questions

### How do I enable dark mode in arc-kit?

Dark mode is toggled by adding or removing the `dark-mode` class from the `<html>` element using JavaScript. The color variables and component overrides are defined in [`docs/theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/theme.css) starting at line 72. When the class is present, the CSS cascade automatically switches background colors, text contrasts, and border values to their dark-theme equivalents.

### Can I use custom themes with Mermaid diagrams in arc-kit?

Yes, Mermaid diagrams support both built-in themes and fine-grained customization via the `themeVariables` object in the `%%{init}%%` block. You can specify colors for nodes, edges, and backgrounds as documented in [`arckit-paperclip/skills/mermaid-syntax/references/xyChart.md`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-paperclip/skills/mermaid-syntax/references/xyChart.md). Additionally, you can apply custom CSS to diagram containers by referencing a stylesheet like the Wardley-style example in [`tests/mermaid-wardley/wardley-style.css`](https://github.com/tractorjuice/arc-kit/blob/main/tests/mermaid-wardley/wardley-style.css).

### What hero banner variants are available in arc-kit?

Arc-kit provides nine pre-configured hero banner styles defined in [`docs/heroes.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/heroes.css): Commands, Guides, Roles, Projects, Getting-Started, Home, Viewer, and Contributors. Each variant uses a specific CSS class (e.g., `.app-page-hero--commands`) that applies unique gradient backgrounds and overlay patterns. To use a variant, set the `heroClass` property in your page's frontmatter to the corresponding class name.

### How do I apply custom CSS overrides to arc-kit?

To customize arc-kit's appearance, create a separate stylesheet (e.g., [`custom.css`](https://github.com/tractorjuice/arc-kit/blob/main/custom.css)) and include it in your HTML templates after the default [`theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/theme.css) and [`heroes.css`](https://github.com/tractorjuice/arc-kit/blob/main/heroes.css) files. The default styles are additive, meaning they layer onto existing inline styles without destructive replacement, as noted in the comments at line 2 of [`docs/theme.css`](https://github.com/tractorjuice/arc-kit/blob/main/docs/theme.css). This ensures that your targeted overrides (such as modifying `.app-page-hero--home` gradients or changing color variables) take precedence while maintaining core functionality.