Working With This Template¶

This design system site is the master reference for all KMG corporate design. The site itself is the design — it uses the same Argon Dashboard framework, color palette, typography, and components that all internal applications must follow.

This guide explains how a designer can work with this repository to maintain, evolve, and showcase the KMG design language.

How the Site Works¶

The site is a Python/Flask application that renders Markdown files into styled pages. There is no database — every piece of content lives as a .md file in the content/ directory. This means:

You edit text files to change content
You edit CSS files to change how things look
You edit HTML templates to change page structure
You run docker compose up --build to see your changes

Repository Structure at a Glance¶

design.kmg.group/
│
├── content/                  ← CONTENT: What the pages say
│   ├── blog/                 ← Blog posts
│   ├── getting-started/      ← Getting started guides
│   ├── guidelines/           ← Color, typography, spacing docs
│   ├── components/           ← Component documentation
│   ├── accessibility/        ← Accessibility standards
│   ├── cicd/                 ← CI/CD pipeline guides
│   ├── docker/               ← Docker best practices
│   └── start/                ← Start section pages (this page)
│
├── static/                   ← DESIGN: How things look
│   ├── css/
│   │   ├── argon-dashboard.min.css   ← Base framework (do not edit)
│   │   ├── kmg-custom.css            ← KMG overrides (edit this)
│   │   ├── nucleo-icons.css          ← Icon font styles
│   │   └── nucleo-svg.css            ← SVG icon styles
│   ├── js/
│   │   ├── argon-dashboard.min.js    ← Framework JS (do not edit)
│   │   └── mousetrap.min.js          ← Keyboard shortcuts library
│   ├── fonts/                        ← Self-hosted icon fonts
│   └── img/                          ← Images and logos
│
├── templates/                ← STRUCTURE: How pages are laid out
│   ├── base.html             ← Master layout (sidebar, header, footer)
│   ├── index.html            ← Start page
│   ├── section.html          ← Section listing (cards grid)
│   ├── page.html             ← Single content page with TOC sidebar
│   ├── settings.html         ← Settings page
│   ├── keyboard_bindings.html← Keyboard shortcuts page
│   ├── changelog.html        ← Changelog (GitLab integration)
│   ├── 404.html              ← Error page
│   ├── blog/
│   │   ├── list.html         ← Blog listing
│   │   └── post.html         ← Single blog post
│   └── components/
│       └── page.html         ← Component page (with copy button)
│
├── app.py                    ← APPLICATION: Routes and logic
├── requirements.txt          ← Python dependencies
├── Dockerfile                ← Container build
└── docker-compose.yml        ← Local development

File-by-File Reference¶

Files You Will Edit Often¶

File	What It Controls	When to Edit
`static/css/kmg-custom.css`	All KMG-specific styling: colors, typography sizes, spacing, dark mode, code blocks, component previews	Changing the visual design
`content/*/.md`	Page content: text, examples, code snippets	Updating documentation
`templates/base.html`	Sidebar navigation, page header, footer, CSS/JS includes	Adding nav items, changing global layout
`templates/index.html`	Start page layout and featured cards	Updating the landing page
`static/img/`	Logos, brand images	Updating brand assets

Files You Will Edit Occasionally¶

File	What It Controls	When to Edit
`templates/section.html`	How section listing pages look (card grid)	Changing how sections display their child pages
`templates/page.html`	Single content page layout with TOC sidebar	Changing content page structure
`templates/components/page.html`	Component doc pages (includes copy-to-clipboard)	Changing how component examples display
`app.py` (nav section)	Navigation items and their icons	Adding or reordering navigation

Files You Should Not Edit¶

File	Why
`static/css/argon-dashboard.min.css`	Base framework — override in `kmg-custom.css` instead
`static/css/nucleo-icons.css`	Icon font definitions — replace the font files to update
`static/js/argon-dashboard.min.js`	Framework JavaScript
`static/js/mousetrap.min.js`	Keyboard shortcut library

How to Change Typography¶

All typography overrides live in static/css/kmg-custom.css.

Heading Sizes¶

Find and edit these rules:

.content-body h1 { font-size: 1.75rem; font-weight: 700; }
.content-body h2 { font-size: 1.4rem; font-weight: 600; }
.content-body h3 { font-size: 1.15rem; font-weight: 600; }

Body Text¶

.content-body {
  font-size: 0.95rem;    /* Change base text size */
  line-height: 1.7;       /* Change line spacing */
  color: #344767;          /* Change body text color */
}

Font Family¶

The font stack is defined in argon-dashboard.min.css (Open Sans). To override it:

body, .content-body {
  font-family: "Your Font", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
}

If using a custom font, place the font files in static/fonts/ and add @font-face rules to kmg-custom.css.

How to Change Colors¶

Brand Colors¶

The Argon Dashboard defines colors via CSS variables and utility classes. To override the primary color palette, add to kmg-custom.css:

/* Override primary color */
.bg-gradient-primary {
  background-image: linear-gradient(310deg, #YOUR_DARK, #YOUR_LIGHT);
}

.text-primary {
  color: #YOUR_PRIMARY !important;
}

.btn-primary {
  background-color: #YOUR_PRIMARY;
  border-color: #YOUR_PRIMARY;
}

Updating the Color Documentation¶

After changing colors, update the color palette documentation:

Edit content/guidelines/colors.md
Update the hex values in the table
Update the inline color swatches

Dark Mode Colors¶

Dark mode styles are in kmg-custom.css under the body.dark-mode section:

body.dark-mode {
  background-color: #1a1a2e !important;  /* Page background */
}

body.dark-mode .card {
  background-color: #1f2937 !important;  /* Card background */
  color: #e2e8f0 !important;             /* Card text */
}

How to Add Content¶

Adding a New Page to an Existing Section¶

Create a new .md file in the appropriate content/ subdirectory
Add frontmatter at the top:

---
title: My New Page
description: A short description shown on the section listing
order: 5
---

# My New Page

Your content here...

The page is automatically available at /{section}/{filename} (without the .md extension)

Example: Creating content/guidelines/logos.md makes it available at /guidelines/logos

Adding a Blog Post¶

Create a new .md file in content/blog/ (e.g., content/blog/2026-03-new-colors.md)
Use this frontmatter:

---
title: We Updated Our Color Palette
date: "2026-03-15"
author: Design Team
summary: A brief summary shown on the blog listing.
tags:
  - update
  - colors
---

Post content here...

The post appears on /blog automatically, sorted by date (newest first)

Adding a New Component¶

Create a new .md file in content/components/ (e.g., content/components/modals.md)
Include HTML previews directly in the markdown:

---
title: Modals
description: Modal dialog patterns and usage
order: 7
---

# Modals

## Basic Modal

<div class="component-preview">
  <!-- Live HTML example here -->
</div>

\```html
<!-- Copyable code snippet here -->
\```

## Usage Guidelines

- When to use modals
- Accessibility considerations

The component-preview class adds a bordered container for live examples. Code blocks are shown as copyable snippets.

Adding a New Section¶

This requires editing app.py:

Create a new directory under content/ (e.g., content/patterns/)
Add routes in app.py:

@app.route("/patterns")
def patterns():
    pages = load_section_pages("patterns")
    return render_template("section.html", section_title="Patterns", pages=pages, section="patterns")

@app.route("/patterns/<slug>")
def patterns_page(slug):
    content = load_content("patterns", slug)
    if not content:
        abort(404)
    return render_template("page.html", content=content, section_title="Patterns", section="patterns")

Add the nav item in app.py under inject_nav():

{"title": "Patterns", "url": "/patterns", "icon": "ni ni-ruler-pencil"},

How to Change Page Layout¶

The sidebar is defined in templates/base.html. It loops over nav_items defined in app.py. To reorder, add, or remove navigation items, edit the inject_nav() function in app.py.

Available Nucleo icon names can be found in static/css/nucleo-icons.css — search for .ni- class names.

Page Templates¶

Template	Used By	Layout
`page.html`	Individual content pages	Content (9 cols) + TOC sidebar (3 cols)
`section.html`	Section landing pages	Grid of cards linking to child pages
`index.html`	Start page	Welcome card + feature cards + quick links
`blog/list.html`	Blog listing	Post cards (8 cols) + about sidebar (4 cols)
`blog/post.html`	Single blog post	Post content (8 cols) + TOC sidebar (4 cols)
`components/page.html`	Component docs	Content (9 cols) + TOC sidebar (3 cols), with copy button JS

To change the column layout of any page, edit the col-lg-* classes in the template. Bootstrap uses a 12-column grid.

How to Preview Changes¶

Quick Preview (content only)¶

Since the content/ directory is volume-mounted in Docker, content changes are reflected immediately — just refresh the browser. No rebuild needed.

docker compose up -d
# Edit any content/*.md file
# Refresh the browser

Full Rebuild (CSS, templates, or Python changes)¶

docker compose down
docker compose up --build -d

Running Tests¶

# Inside the container
docker compose exec app pytest tests/ -v

# Or locally with the venv
./venv/bin/pytest tests/ -v

Workflow for Designers¶

Typical Workflow¶

Clone the repository and run docker compose up --build -d
Open http://localhost:5055 in your browser
Edit markdown files in content/ for text changes (live reload)
Edit static/css/kmg-custom.css for visual changes (requires rebuild)
Rebuild with docker compose up --build -d
Test with docker compose exec app pytest tests/ -v
Commit your changes and push to GitLab

What to Test Before Committing¶

All pages render without errors (the test suite checks this)
Color contrast meets WCAG AA standards (see /accessibility)
Typography hierarchy is clear and consistent
Component examples render correctly
Dark mode still works if you changed colors
Mobile/responsive layout still works (resize your browser)

Markdown Cheat Sheet¶

Content pages use standard Markdown with some extras:

Syntax	Result
`# Heading 1`	Page title
`## Heading 2`	Section heading (gets border-bottom)
`### Heading 3`	Sub-section heading
`bold`	bold text
`italic`	italic text
`code`	Inline code
```lang	Fenced code block with syntax highlighting
`[text](url)`	Link
`\| A \| B \|`	Table
`- item`	Unordered list
`1. item`	Ordered list

HTML in Markdown¶

You can use raw HTML directly in markdown files. This is how component previews work:

<div class="component-preview">
  <button class="btn btn-primary">Click me</button>
</div>

The component-preview class provides a bordered container. Use any Argon Dashboard classes inside it.