docs(appearance): document the Appearance page, theme presets, and color customizer

docs/content/admin/appearance/PRO__appearance.md

@@ -0,0 +1,74 @@
+---
+title: "Appearance"
+description: "Choose a theme preset and customize the colors of the DefectDojo Pro UI"
+weight: 1
+audience: pro
+---
+
+The Appearance page sets how the Pro UI looks for every user on your instance. You start from a **theme preset**, then customize any color on top of it. Changes save automatically and apply to everyone.
+
+Open it from **Settings > System > Appearance**.
+
+![The Appearance page](images/appearance_settings.png)
+
+## Theme
+
+The **Theme** control at the top of the page chooses between **System**, **Light**, and **Dark**. Unlike everything else on this page, it is a personal preference for your browser only. **System** follows your operating system, including when it switches between light and dark on its own.
+
+It also decides which mode you are editing: the Interface Colors section changes the mode that is currently on screen. Switch the Theme to edit the other one.
+
+## Theme preset
+
+The preset is the starting point for every color on the page.
+
+* **DefectDojo** is the current DefectDojo look: warm surfaces in light mode, deep teal in dark mode, and an orange accent.
+* **Legacy** is the previous blue and gray look.
+
+Colors you have customized are kept when you switch presets. **Reset All Colors** clears every customized color and returns to the preset, without changing which preset is selected.
+
+## Primary color
+
+The primary color is used for buttons, links, highlights, and focus states. You pick one color and a full range of lighter and darker shades is generated from it for both modes.
+
+The text shown on buttons is chosen for you so that it stays readable against the primary color you pick, in both light and dark mode.
+
+## Interface colors
+
+Interface colors are set separately for light mode and dark mode, so each mode can have its own look. The page edits whichever mode is on screen.
+
+| Group | What it changes |
+| --- | --- |
+| **Neutral Palette** | One tint that every shade of gray is built from. Components, borders, and hover states follow it, and so does the navigation frame unless you set a surface color below. |
+| **Surfaces** | The navigation frame, the page background, cards and panels, hover and raised areas, and borders. |
+| **Text** | Body text, and the quieter secondary text used for labels, captions, and navigation section headings. |
+| **Components** | Form field background and border, menus and dialogs, menu hover, and selection. |
+| **Operational Status** | The live status indicators on the Command Center: healthy, degraded, and down. These are separate from finding severity colors. |
+
+Each color shows **Preset** until you change it. Select **Use preset** under a customized color to return it to the preset, or use the reset button on a group to clear the whole group for the mode you are editing.
+
+## Legibility
+
+The **Legibility** section checks that text stays readable with your colors, in both light and dark mode. It measures the contrast between text and the surface it sits on against the WCAG 2.1 AA guidelines: at least 4.5:1 for text, and 3:1 for the primary color against the page.
+
+If a change would make text hard to read, the page still previews it, but does not save it. A banner at the top of the page explains why, and the failing check is marked in the Legibility section. Adjust the flagged colors and your changes save automatically. If you leave the page instead, the UI goes back to the last saved colors.
+
+Only problems your changes introduce stop a save. A preset's own default colors are shown in the Legibility section for reference but never block you.
+
+## Metric colors
+
+The severity, risk, grade, and CVSS score colors are the same in light and dark mode. They are used on tags, charts, and gauges throughout the Pro UI. Each group has its own reset button.
+
+## Reports and exports
+
+Everything DefectDojo prints follows these settings, always in light mode because reports are printed on a white page:
+
+* **Metrics and dashboard PDF exports** use your light-mode colors, even when the person exporting works in dark mode.
+* **Report Builder charts** use your preset, your metric colors, and your light-mode text colors, whether the report is generated from the browser, through the API, or on a schedule.
+* **Reports with no theme selected** take their colors from your primary color and your light-mode text colors. The primary color is darkened where needed so headings and table headers stay readable on white.
+* **New report themes** start from those same colors, so you only change what should differ from the instance.
+
+Existing report themes keep the colors they were saved with.
+
+## Automating appearance settings
+
+The same settings are available through the API as the `ui_color_theme` field of `/api/v2/system_settings/{id}/`. It is a partial object: include only what you want to customize, and send an empty object to return to the preset defaults. The API applies the same readability rule to text and surface colors stored together.

docs/content/admin/appearance/_index.md

@@ -0,0 +1,22 @@
+---
+title: "Appearance"
+description: "Choose a theme preset and customize the colors of the DefectDojo Pro UI for your instance"
+summary: ""
+date: 2026-09-23T00:00:00+00:00
+lastmod: 2026-09-23T00:00:00+00:00
+draft: false
+weight: 5
+chapter: true
+seo:
+  title: "" # custom title (optional)
+  description: "" # custom description (recommended)
+  canonical: "" # custom canonical URL (optional)
+  robots: "" # custom robot tags (optional)
+exclude_search: true
+---
+
+The Appearance settings control how the DefectDojo Pro UI looks for everyone on your instance: which theme preset it starts from, and any colors you customize on top of it.
+
+Appearance is a DefectDojo Pro feature. Open-source DefectDojo does not have an Appearance page.
+
+* [Appearance](./pro__appearance/): pick a theme preset, customize colors for light and dark mode, and check that text stays readable.

docs/content/metrics_reports/reports/PRO__report_builder.md

@@ -29,15 +29,15 @@ The Report Builder is made of four pieces, each available as a REST resource und
 
 A **Theme** controls the visual style and branding of a report: the colors, the header and footer imagery, and the footer text. By defining a Theme once, you can apply consistent corporate branding to every report you produce.
 
-A Theme has the following settings:
+A Theme has the following settings. A new Theme starts from the colors set on the [Appearance](/admin/appearance/pro__appearance/) page, and a report with no Theme selected uses those same colors.
 
 | Setting | Purpose | Default |
 |---------|---------|---------|
 | Name | A label for the Theme | — |
-| Primary color | Main brand color | `#1e3a5f` |
-| Secondary color | Supporting brand color | `#4a90a4` |
-| Accent color | Highlight color | `#e67e22` |
-| Text color | Body text color | `#333333` |
+| Primary color | Main brand color: headings and table headers | Your instance's primary color, darkened where needed to stay readable on white |
+| Secondary color | Supporting brand color | Your instance's secondary text color |
+| Accent color | Highlight color: the cover bar and table of contents numbers | Your instance's primary color |
+| Text color | Body text color | Your instance's body text color |
 | Background color | Page background color | `#ffffff` |
 | Footer text | Text shown in the page footer | — |
 | Show page numbers | Whether to print page numbers | On |