--- title: "Theming guide — Mango Documentation" description: "Create Mango themes with complete single- and multi-variant JSON examples, a live color map, and a reference for every palette field." url: "https://mangoirc.chat/docs/theming" language: "en" --- Appearance · Theming # Forty choices. One coherent window. A Mango theme is a small JSON file with one or more appearances inside. This guide shows the exact file shapes, what every field changes, and how the colors meet in the app. **2**package schema **1+**Light or Dark looks **40**palette choices Plain JSON. No build tools required. 01 File format ## Start with a package. Mango currently exports every ` .mangotheme ` as a schema-2 package. One appearance means one item in ` themes `; a Light + Dark family usually means two, and larger families can carry as many independent looks as they need. example-night.mangotheme ``` { "schemaVersion": 2, "themes": [ { "schemaVersion": 1, "id": "custom.example-night", "name": "Example Night", "author": "Your Name", "description": "A deep plum theme with a soft lilac accent.", "version": "1.0", "variant": "dark", "palette": { "windowBackground": "#1A1825", "paneBackground": "#201D2D", "sidebarTint": "#26233A8C", "textPrimary": "#E6E1EC", "textSecondary": "#908CA6", "textTertiary": "#5D586D", "textLink": "#C4A7E7", "hairline": "#FFFFFF0F", "hairlineStrong": "#FFFFFF1C", "accent": "#C4A7E7", "accentSoft": "#C4A7E724", "accentSoftStrong": "#C4A7E73D", "unreadPillForeground": "#F6C177", "unreadPillBackground": "#F6C1772E", "userHighlightBackground": "#9CCFD81C", "warningForeground": "#EB6F92", "warningBackground": "#EB6F9224", "replyContextForeground": "#9CCFD8", "operatorForeground": "#A8D6B5", "operatorBackground": "#9BC4A82E", "voiceForeground": "#A4CFDB", "voiceBackground": "#9CCFD829", "mentionBackground": "#DCA7A829", "mentionForeground": "#EBBCBA", "statusOn": "#8EB89A", "statusPending": "#D4A574", "statusOff": "#5D586D", "actionForeground": "#C4A7E7", "eventForeground": "#6E6A86", "eventBackground": "#FFFFFF0A", "kbdBackground": "#FFFFFF12", "kbdBorder": "#FFFFFF1A", "hoverBackground": "#FFFFFF0A", "hoverBackgroundStrong": "#FFFFFF12", "fieldBackground": "#FFFFFF08", "fieldBackgroundFocused": "#FFFFFF14", "vibrancy1": "#C4A7E729", "vibrancy2": "#9CCFD81C", "vibrancy3": "#EBBCBA17", "nickPalette": [ "#C4A7E7", "#9CCFA8", "#EBBCBA", "#9CCFD8", "#F6C177", "#D8B4D8" ] } } ] } ``` package ### ` schemaVersion: 2 ` The outer object is the file container. Use ` 2 `, even with one theme. appearance ### ` schemaVersion: 1 ` Every item in ` themes ` is one independent Light or Dark appearance. compatibility ### Bare v1 still opens. Older files may contain the theme object directly, with no package wrapper. Mango still imports them, then exports them as schema 2 next time. ` id ` A stable identity used for re-imports and updates. Give every variant its own ID. A ` custom. ` prefix is preserved as-is; other IDs are namespaced on import. ` name ` The label shown in Mango’s theme grid. Variant names such as “Example Night” and “Example Day” are welcome. ` author `optional Your display name. Carried with the file and shown in theme details. ` description `optional A short note about the look, provenance, or intended palette. ` version `defaults to 1 Your content version. Mango compares dotted numeric parts, so ` 1.10 ` is newer than ` 1.2 `. Keep the same ID and bump this when publishing an update. ` variant ` Exactly ` light ` or ` dark `. This places the appearance in the matching picker slot. ` palette ` The complete color object below. Seven fields are optional: ` fieldBackgroundFocused ` plus the six newer semantic overrides for unread pills, selected users, warnings, and quoted replies. #C4A7E7opaque #C4A7E72414% alpha Colors use **` #RRGGBB `** or **` #RRGGBBAA `**. Alpha comes last—not first. JSON comments and trailing commas are not valid. 02 Visual color map ## See where every color lands. Switch variants, then choose any palette row. The matching part of the window is outlined in the preview; the swatches always show the active variant’s real values. Locating` accent ` **Accent** Active controls, selected tab marks, unread emphasis, focus details, and send/progress accents. ### Surfaces & lines The large planes first. If these are right, the theme already feels coherent. ### Text Four levels cover nearly every label in Mango. Test all four against both large surfaces. ### Accent & interaction The accent family carries selection and focus without turning the whole app into one loud color. ### Member roles, status & warnings Role chips, connection dots, and warning banners need to stay legible at very small sizes. ### Chat details These colors separate mentions, replies, selections, unread state, actions, events, and code from ordinary messages. ### Atmosphere & nicknames The finishing layer: soft color in the chrome and a readable identity palette for busy rooms. 03 Make, test, share ## The short route from JSON to Mango. 1. 1 ### Start from a working theme. Export one from Mango or copy the complete example above. Change a few related colors at a time and keep every required key. 2. 2 ### Save plain UTF-8 JSON. Use the ` .mangotheme ` extension. Keep at least one color in ` nickPalette `, and remember that reordering it changes which color a nickname receives. 3. 3 ### Open it and confirm. Double-click in Finder, open from Files, or tap a shared ` .mangotheme ` link. Mango previews the import and asks before applying or overwriting it. 4. 4 ### Test the awkward corners. Check selected and hovered rows, unread and warning pills, quoted replies, a focused composer, links, mentions, role chips, connecting states, and both sidebar styles—not only a quiet transcript. Contrast ### Read first, decorate second. ` textPrimary ` should remain clear on both window and pane backgrounds. Tertiary text still needs to survive a dim display. Transparency ### Let soft colors stay soft. Hairlines, hover fills, washes, and role backgrounds are usually translucent. Fully opaque values make the interface feel stacked and heavy. Updates ### Identity is the contract. Keep the same ` id `, raise ` version `, and Mango can recognize the file as an update instead of an unrelated copy. Prefer color wells to curly braces? ## Mango has a live editor too. Create a custom theme inside Settings, adjust every role with an immediate preview, then export it when it’s ready to share. [Browse the Theme Store](https://mangoirc.chat/themes)