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

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, 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 beginning at line 72.

// 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 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.

Page Hero Banner Styling Options

Arc-kit provides pre-designed hero banners for different sections of the documentation site, controlled through 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:

---
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.

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.

%%{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 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, 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.

@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 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.

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

Available themes include gaia, default, and custom CSS files. The presentation guide in 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 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, "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)
2. Include it after theme.css and 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, 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, activated through the heroClass frontmatter property.
• Diagram theming supports Mermaid (themeVariables in xyChart.md) and PlantUML (built-in themes listed in styling-guide.md), plus custom Wardley-style CSS examples.
• Presentation styling utilizes Marp CLI themes (gaia, default, etc.) documented in presentation.md with templates in arckit-paperclip/templates/.
• Customization is achieved through additive CSS overrides; create a 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 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. 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.

What hero banner variants are available in arc-kit?

Arc-kit provides nine pre-configured hero banner styles defined in 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) and include it in your HTML templates after the default theme.css and 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. This ensures that your targeted overrides (such as modifying .app-page-hero--home gradients or changing color variables) take precedence while maintaining core functionality.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}