Writing a theme
How to restyle BeeBEEP by editing its theme file, and what every token in that file controls.
Per: sviluppatori · Da BeeBEEP 6.0.0 · Aggiornata il
Alcune pagine sono solo in inglese.
BeeBEEP's whole look -- every color, corner radius, size and font size, in the light and the dark version -- lives in one QML file. This page is for a graphic designer or a developer who wants to restyle BeeBEEP: it says where the file is, how to edit it safely and what each token controls. No code needs to change.
How the theme works
The theme is the file assets/themes/beebeep-custom-theme.qml of the source tree: a single QtObject with one property per token. BeeBEEP reads it when it starts, and every screen takes its colors and sizes from it.
Both palettes are in the same file. Every color is written with the dark value first and the light value second:
property color surfaceColor: dark ? "#171D23" : "#FFFFFF"
The property dark is set by BeeBEEP, never by you. It follows the choice in Settings > Appearance > Theme: Follow the system theme (the default; it switches together with the device), Light or Dark. The change is immediate, with no restart. To restyle the light theme edit the second value of a line, to restyle the dark theme the first.
Some tokens have a single value that holds for both themes (the unread badge, the splash screen).
Three more properties are set by BeeBEEP, for a size or an animation to read:
platform-- the system BeeBEEP runs on:"android","ios","macos","windows"or"linux". A size may follow its platform's own guideline, for instanceproperty int touchTargetSize: platform === "android" ? 48 : 44.windowClass-- the window's width class:0compact (under 600),1medium (600 to 839),2expanded (840 to 1199),3large (from 1200), counted in the device's own pixels (dp on Android, points on Apple). It changes as the window is resized or the device turned, so a tablet's size is written once for every tablet of that width, whatever its system:property int avatarHeaderSize: windowClass >= 1 ? 44 : 40.reducedMotion--truewhen the system asks for reduced motion, an accessibility setting. Every animation of BeeBEEP reads it and cross-fades at most, or does not move at all. There is nothing to set: it only tells the theme what the person asked for.
Where the file is
BeeBEEP looks for beebeep-custom-theme.qml in a folder named themes next to its executable (on macOS, in its data folder: see below). If the file is there and loads, it is used; otherwise BeeBEEP uses the copy of the same file built into the program.
A build from source puts themes next to the executable it builds, and refreshes the copy from assets/themes whenever that file changes (on macOS it rebuilds the copy built into the program instead).
Windows
The portable zip carries the folder as themes beside beebeep.exe, in the folder you unpacked. The setup and the MSI install it as C:\Program Files\BeeBEEP\themes\beebeep-custom-theme.qml, which needs administrator rights to edit, and every later installation of a new version puts that version's file back over yours: keep your copy outside the BeeBEEP folder.
macOS
An app on macOS is signed, and nothing inside it may be changed, so the themes folder is not in the app. Create it in BeeBEEP's data folder, ~/Library/Application Support/net.beebeep.beebeep/themes, and copy the file there (the folder given with --data-folder, if BeeBEEP starts with one).
Linux
The tar.gz package carries the folder as themes beside the beebeep executable. The deb package installs it as /usr/lib/beebeep/themes/beebeep-custom-theme.qml, which needs administrator rights to edit.
Editing the theme
- Copy the file and keep the copy: it is your way back.
- Edit the values after the colon. Keep every line's shape: the word
property, a type, the name, a colon and the value. - Save and start BeeBEEP again. Use Settings > Appearance > Theme to look at both palettes.
Rules:
- A color is a name Qt knows (
white,gray) or a hex string,#RRGGBB, or#AARRGGBBwith the transparency first (#8814213A). - A radius or a size is a number of pixels.
- A font size is in points, written relative to the system's own text size (
baseFontPointSize + 9), so that the whole app follows the text size the device is set to. Do not turn it into a fixed number. - Do not add, remove or rename a property, and do not touch
dark,platform,windowClass,reducedMotionorsystemFontPointSize: BeeBEEP sets them. A size may read them. A new property does nothing until a screen reads it by name. - Keep the
import QtQuickline and the outerQtObject { }.
Token catalog
Every token of the file, with its default. A token whose default is the same in both columns has one value for both themes.
An icon takes the color of the token that colors it. On macOS, the iPhone and the iPad most icons are the system's own symbols, colored by the same tokens as the icons elsewhere.
Surfaces
| Token | Light | Dark | What it colors |
|---|---|---|---|
backgroundColor | #F4F6F8 | #0F1418 | The window's background, behind every screen, and the ground of Settings cards and the search field. |
surfaceColor | #FFFFFF | #171D23 | A list or card on top of the background: chat and contact rows, Settings cards, popups. |
headerColor | #FFFFFF | #1C242B | The app's chrome: screen headers, the bottom tab bar, the side rail of a wide window, the message composer bar. |
chatBackgroundColor | #EDF1F4 | #0F1418 | The background of the message list, tinted so that a received bubble stands out. |
dividerColor | #E3E7EB | #2A343D | Thin separator lines between list rows and under headers. |
dialogColor | #FFFFFF | #2B353E | What stands above everything else: a dialog, a message's menu. In the dark theme lighter than any bubble or card, so it reads as raised above them. |
dialogBorderColor | #E3E7EB | #3A4651 | The edge of those dialogs and menus. |
modalDimColor | #52000000 | #80000000 | The veil a dialog lays over the rest of the window; stronger in the dark theme, or it would not show on a near-black ground. |
Text
| Token | Light | Dark | What it colors |
|---|---|---|---|
textPrimaryColor | #14202B | #E8EDF1 | Ordinary readable text: names, message text, titles, header icons. |
textSecondaryColor | #5C6B78 | #98A6B3 | Muted text: timestamps, captions, delivery status, list previews, placeholders. |
textDisabledColor | #9AA6B1 | #5F6E7B | Inactive text: a disabled control's label, the ring of an unselected radio button. |
Brand
| Token | Light | Dark | What it colors |
|---|---|---|---|
accentColor | #026DAD | #4FC3F7 | BeeBEEP's blue: the plus button, links, the selected tab, the arrow of the jump-to-unread chip, read ticks. |
accentStrongColor | #01579B | #81D4FA | The accent while pressed or hovered. |
accentSoftColor | #E3F2FB | #123B52 | A soft accent fill: the selected tab's pill, a selected filter, the icon tile of a Settings row, the file card in a bubble. |
textOnAccentColor | #FFFFFF | #0F1418 | Text and icons drawn on the accent, such as the arrow of the send button. |
honeyColor | #F5B301 | #FFC93C | The honey signature color, used sparingly: the end-to-end encryption chip, the activity dot on the file transfers icon, the important star, the badge of an unplayed voice note, the border of the current match of a search. |
honeySoftColor | #FFF4D6 | #3A2E0F | A soft honey fill: the end-to-end encryption chip. |
textOnHoneyColor | #3A2A00 | #FFE9A8 | Text and icons drawn on the soft honey fill. |
Networks
| Token | Light | Dark | What it colors |
|---|---|---|---|
networkFirstColor | #F5B301 | #FFC93C | The first network the question asks about: its hexagon (a soft fill and the icon in it are derived from this color) and its hexagon in the counter at the top. |
networkSecondColor | #0277BD | #4FC3F7 | The second network asked, the same way. |
networkThirdColor | #7E57C2 | #B39DDB | The third network asked, the same way; a fourth takes the first color again. |
Message bubbles
| Token | Light | Dark | What it colors |
|---|---|---|---|
bubbleOwnColor | #D7ECFA | #1D4B66 | The fill of a message you sent. |
bubbleReceivedColor | #FFFFFF | #232C34 | The fill of a message someone else sent. |
bubbleBorderColor | #E3E7EB | #2A343D | The thin border of a received bubble; your own bubbles have none. |
searchMatchColor | #FFD54F | #7A5C00 | The fill behind a word found by the search inside a chat. |
Voice notes
| Token | Light | Dark | What it colors |
|---|---|---|---|
voiceWaveformPlayedColor | #026DAE | #4FC3F7 | The waveform bars already played, and the playhead dot. |
voiceWaveformUnplayedColor | #9DB2C2 | #5E7282 | The waveform bars still to play. |
voiceBadgeUnplayedColor | #F5B301 | #FFC93C | The microphone badge on a received voice note nobody has played yet. |
voiceBadgeUnplayedIconColor | #3A2A00 | #3A2A00 | The microphone glyph on that badge. |
voiceBadgePlayedColor | #E3E7EB | #2A343D | The microphone badge once the note is played, and always on your own notes. |
voiceBadgePlayedIconColor | #5F6B76 | #9AA7B2 | The microphone glyph on that badge. |
Status
| Token | Light | Dark | What it colors |
|---|---|---|---|
successColor | #2E9E5B | #4CC276 | A completed state drawn as a shape: a check mark, a chosen tile. |
successTextColor | #237745 | #5FC985 | The same state where it is words, such as a finished transfer. |
warningColor | #E08A00 | #F2A93B | A warning or in-progress state drawn as a shape: the icon of a banner. |
warningTextColor | #965C00 | #F2A93B | The same state where it is words, such as a transfer still waiting. |
dangerColor | #BE3939 | #EF6B6B | A failed state, such as a failed transfer, and the offline banner. |
importantColor | #F5B301 | #FFC93C | The star of a message marked as important. |
Badges and presence
| Token | Light | Dark | What it colors |
|---|---|---|---|
unreadBadgeColor | #0277BD | #0277BD | The unread-count pill on a chat row, on the Chats tab and on the jump-to-unread chip. |
textOnUnreadBadgeColor | #FFFFFF | #FFFFFF | The number inside the unread-count pill. |
onlineStatusColor | #2E9E5B | #4CC276 | The dot next to a contact who is online, on their details, and the count on the Users tab. |
onlineTextColor | #237745 | #4CC276 | The word "Online" and the relayed line in the user list. |
textOnOnlineBadgeColor | #06140B | #06140B | The number inside the count on the Users tab. |
offlineStatusColor | #C3CCD4 | #4A5866 | The dot next to a contact who is offline, and the track of a switch that is off. |
notRespondingStatusColor | #8E99A4 | #7C8A97 | The dot of a contact who is online but has stopped answering. |
Input and tabs
| Token | Light | Dark | What it colors |
|---|---|---|---|
inputFieldColor | #FFFFFF | #232C34 | The fill of the message composer and of text fields. |
inputBorderColor | #D5DCE2 | #2A343D | The border of the same. |
tabActiveColor | #0277BD | #4FC3F7 | The icon and label of the selected tab. |
tabInactiveColor | #6B7A87 | #8A98A5 | The icon and label of every other tab. |
Avatars
| Token | Light | Dark | What it colors |
|---|---|---|---|
colorSwatchBorderColor | #40000000 | #30FFFFFF | The thin border around an avatar or a color swatch. |
Banners
| Token | Light | Dark | What it colors |
|---|---|---|---|
infoBannerColor | #E3F2FB | #123B52 | The background of an information or action bar: mark all as read, the copy confirmation, the multi-select bar, the reply bar, the file transfers banner. |
infoBannerBorderColor | #CFE4F5 | #1B4A63 | The border of the same bars. |
pinnedBannerColor | #FFF4D6 | #3A2E0F | The background of the pinned-message bar. |
pinnedBannerBorderColor | #F0E0B0 | #4A3C14 | The border of the pinned-message bar. |
warningBannerColor | #FFF3E0 | #3A2A0F | The background of the security-key warning at the top of a private chat. |
warningBannerBorderColor | #FFCC80 | #6B4E1A | The border of that warning. |
criticalBannerColor | #FDECEC | #4A1C1C | The background of a critical notice, such as your profile open on another device. |
criticalBannerBorderColor | #D9534F | #B84444 | The border of a critical notice. |
criticalTextColor | #B03434 | #F28080 | The icon of a critical notice and the words and outline of its buttons. |
Splash screen
| Token | Light | Dark | What it colors |
|---|---|---|---|
splashTopColor | #0B2A3F | #0B2A3F | The top of the splash screen's gradient. |
splashBottomColor | #071A28 | #071A28 | The bottom of the splash screen's gradient. |
splashTextColor | #FFFFFF | #FFFFFF | The name and main text on the splash screen. |
splashMutedTextColor | #9FB6C6 | #9FB6C6 | The tagline, the word "Version" and the smaller lines on the splash screen; faded, the outline of a loading cell not filled yet. |
splashHoneyColor | #FFC93C | #FFC93C | The honey of the splash screen: the second half of the name, the border of the bee's cell, the lit cells of the honeycomb, the loading cells and the version number. |
splashCombColor | #1C4A66 | #1C4A66 | The thin walls of the honeycomb drawn over the splash screen's ground. |
splashCellColor | #0F3852 | #0F3852 | The inside of the large cell the bee sits in. |
Font sizes
| Token | Default | What it sets |
|---|---|---|
fontSizeSmall | Math.min( fontSizeCaption, Math.max( 11, system size - 4 ) ) | The smallest print: a message's time and the words beside it, a voice note's duration. Four points under the system's size, never under 11 nor over fontSizeCaption. |
fontSizeCaption | system size - 1 | Small print: captions, status labels, tab labels. |
fontSizeBody | system size | Ordinary text: message text, list row titles. |
fontSizeTitle | system size + 9 | The big title of a tab screen. |
Shapes
| Token | Default | What it sets |
|---|---|---|
bubbleRadius | 16 | The corner radius of a message bubble. |
cardRadius | 14 | The corner radius of a card and of the message input box. |
chipRadius | 10 | The corner radius of a chip: a filter, the date in a chat, the encryption chip. |
iconTileRadius | 9 | The corner radius of the small square behind a Settings row's icon. |
buttonRadius | 8 | The corner radius of every button with a word: Open, Accept, Share, a page's large buttons. |
buttonBorderWidth | 1 | The width of a button's outline; a button with the keyboard's focus draws it twice as wide. |
Sizes
| Token | Default | What it sets |
|---|---|---|
touchTargetSize | 48 on Android, 44 elsewhere | The minimum width and height of anything you tap: header buttons, the send button, a switch, a row. A control drawn smaller keeps its look; only the area that takes the tap grows. |
popupEdgeMargin | 12 | The least distance between the window's edge and a small popup that follows a control, such as an icon button's word. |
avatarListSize | 48 | The avatar's diameter on a list row. |
avatarHeaderSize | 40 | The avatar's diameter in a conversation's header. |
avatarProfileSize | 104 | The avatar's diameter on the You screen. |
iconSize | 24 | The size of header and toolbar icons. |
tabIconSize | 24 on Android, 26 elsewhere | The size of tab bar and side rail icons. |
tabBarHeight | 64 on Android, 55 elsewhere | The bottom tab bar's least height, above the system's own bar. A larger text makes the bar taller; it never cuts its words. |
pageMargin | 24 from a medium window (windowClass 1 and up), 16 below it | A screen's side margin: from the window's edge to the text of its rows and headers. |