Vai al contenuto principale

Lavoro a BeeBEEP circa 20 ore a settimana, ed è gratis per te. Sostienilo

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 instance property int touchTargetSize: platform === "android" ? 48 : 44.
  • windowClass -- the window's width class: 0 compact (under 600), 1 medium (600 to 839), 2 expanded (840 to 1199), 3 large (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 -- true when 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

  1. Copy the file and keep the copy: it is your way back.
  2. Edit the values after the colon. Keep every line's shape: the word property, a type, the name, a colon and the value.
  3. 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 #AARRGGBB with 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, reducedMotion or systemFontPointSize: BeeBEEP sets them. A size may read them. A new property does nothing until a screen reads it by name.
  • Keep the import QtQuick line and the outer QtObject { }.

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

TokenLightDarkWhat it colors
backgroundColor#F4F6F8#0F1418The window's background, behind every screen, and the ground of Settings cards and the search field.
surfaceColor#FFFFFF#171D23A list or card on top of the background: chat and contact rows, Settings cards, popups.
headerColor#FFFFFF#1C242BThe app's chrome: screen headers, the bottom tab bar, the side rail of a wide window, the message composer bar.
chatBackgroundColor#EDF1F4#0F1418The background of the message list, tinted so that a received bubble stands out.
dividerColor#E3E7EB#2A343DThin separator lines between list rows and under headers.
dialogColor#FFFFFF#2B353EWhat 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#3A4651The edge of those dialogs and menus.
modalDimColor#52000000#80000000The 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

TokenLightDarkWhat it colors
textPrimaryColor#14202B#E8EDF1Ordinary readable text: names, message text, titles, header icons.
textSecondaryColor#5C6B78#98A6B3Muted text: timestamps, captions, delivery status, list previews, placeholders.
textDisabledColor#9AA6B1#5F6E7BInactive text: a disabled control's label, the ring of an unselected radio button.

Brand

TokenLightDarkWhat it colors
accentColor#026DAD#4FC3F7BeeBEEP's blue: the plus button, links, the selected tab, the arrow of the jump-to-unread chip, read ticks.
accentStrongColor#01579B#81D4FAThe accent while pressed or hovered.
accentSoftColor#E3F2FB#123B52A 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#0F1418Text and icons drawn on the accent, such as the arrow of the send button.
honeyColor#F5B301#FFC93CThe 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#3A2E0FA soft honey fill: the end-to-end encryption chip.
textOnHoneyColor#3A2A00#FFE9A8Text and icons drawn on the soft honey fill.

Networks

TokenLightDarkWhat it colors
networkFirstColor#F5B301#FFC93CThe 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#4FC3F7The second network asked, the same way.
networkThirdColor#7E57C2#B39DDBThe third network asked, the same way; a fourth takes the first color again.

Message bubbles

TokenLightDarkWhat it colors
bubbleOwnColor#D7ECFA#1D4B66The fill of a message you sent.
bubbleReceivedColor#FFFFFF#232C34The fill of a message someone else sent.
bubbleBorderColor#E3E7EB#2A343DThe thin border of a received bubble; your own bubbles have none.
searchMatchColor#FFD54F#7A5C00The fill behind a word found by the search inside a chat.

Voice notes

TokenLightDarkWhat it colors
voiceWaveformPlayedColor#026DAE#4FC3F7The waveform bars already played, and the playhead dot.
voiceWaveformUnplayedColor#9DB2C2#5E7282The waveform bars still to play.
voiceBadgeUnplayedColor#F5B301#FFC93CThe microphone badge on a received voice note nobody has played yet.
voiceBadgeUnplayedIconColor#3A2A00#3A2A00The microphone glyph on that badge.
voiceBadgePlayedColor#E3E7EB#2A343DThe microphone badge once the note is played, and always on your own notes.
voiceBadgePlayedIconColor#5F6B76#9AA7B2The microphone glyph on that badge.

Status

TokenLightDarkWhat it colors
successColor#2E9E5B#4CC276A completed state drawn as a shape: a check mark, a chosen tile.
successTextColor#237745#5FC985The same state where it is words, such as a finished transfer.
warningColor#E08A00#F2A93BA warning or in-progress state drawn as a shape: the icon of a banner.
warningTextColor#965C00#F2A93BThe same state where it is words, such as a transfer still waiting.
dangerColor#BE3939#EF6B6BA failed state, such as a failed transfer, and the offline banner.
importantColor#F5B301#FFC93CThe star of a message marked as important.

Badges and presence

TokenLightDarkWhat it colors
unreadBadgeColor#0277BD#0277BDThe unread-count pill on a chat row, on the Chats tab and on the jump-to-unread chip.
textOnUnreadBadgeColor#FFFFFF#FFFFFFThe number inside the unread-count pill.
onlineStatusColor#2E9E5B#4CC276The dot next to a contact who is online, on their details, and the count on the Users tab.
onlineTextColor#237745#4CC276The word "Online" and the relayed line in the user list.
textOnOnlineBadgeColor#06140B#06140BThe number inside the count on the Users tab.
offlineStatusColor#C3CCD4#4A5866The dot next to a contact who is offline, and the track of a switch that is off.
notRespondingStatusColor#8E99A4#7C8A97The dot of a contact who is online but has stopped answering.

Input and tabs

TokenLightDarkWhat it colors
inputFieldColor#FFFFFF#232C34The fill of the message composer and of text fields.
inputBorderColor#D5DCE2#2A343DThe border of the same.
tabActiveColor#0277BD#4FC3F7The icon and label of the selected tab.
tabInactiveColor#6B7A87#8A98A5The icon and label of every other tab.

Avatars

TokenLightDarkWhat it colors
colorSwatchBorderColor#40000000#30FFFFFFThe thin border around an avatar or a color swatch.

Banners

TokenLightDarkWhat it colors
infoBannerColor#E3F2FB#123B52The 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#1B4A63The border of the same bars.
pinnedBannerColor#FFF4D6#3A2E0FThe background of the pinned-message bar.
pinnedBannerBorderColor#F0E0B0#4A3C14The border of the pinned-message bar.
warningBannerColor#FFF3E0#3A2A0FThe background of the security-key warning at the top of a private chat.
warningBannerBorderColor#FFCC80#6B4E1AThe border of that warning.
criticalBannerColor#FDECEC#4A1C1CThe background of a critical notice, such as your profile open on another device.
criticalBannerBorderColor#D9534F#B84444The border of a critical notice.
criticalTextColor#B03434#F28080The icon of a critical notice and the words and outline of its buttons.

Splash screen

TokenLightDarkWhat it colors
splashTopColor#0B2A3F#0B2A3FThe top of the splash screen's gradient.
splashBottomColor#071A28#071A28The bottom of the splash screen's gradient.
splashTextColor#FFFFFF#FFFFFFThe name and main text on the splash screen.
splashMutedTextColor#9FB6C6#9FB6C6The tagline, the word "Version" and the smaller lines on the splash screen; faded, the outline of a loading cell not filled yet.
splashHoneyColor#FFC93C#FFC93CThe 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#1C4A66The thin walls of the honeycomb drawn over the splash screen's ground.
splashCellColor#0F3852#0F3852The inside of the large cell the bee sits in.

Font sizes

TokenDefaultWhat it sets
fontSizeSmallMath.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.
fontSizeCaptionsystem size - 1Small print: captions, status labels, tab labels.
fontSizeBodysystem sizeOrdinary text: message text, list row titles.
fontSizeTitlesystem size + 9The big title of a tab screen.

Shapes

TokenDefaultWhat it sets
bubbleRadius16The corner radius of a message bubble.
cardRadius14The corner radius of a card and of the message input box.
chipRadius10The corner radius of a chip: a filter, the date in a chat, the encryption chip.
iconTileRadius9The corner radius of the small square behind a Settings row's icon.
buttonRadius8The corner radius of every button with a word: Open, Accept, Share, a page's large buttons.
buttonBorderWidth1The width of a button's outline; a button with the keyboard's focus draws it twice as wide.

Sizes

TokenDefaultWhat it sets
touchTargetSize48 on Android, 44 elsewhereThe 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.
popupEdgeMargin12The least distance between the window's edge and a small popup that follows a control, such as an icon button's word.
avatarListSize48The avatar's diameter on a list row.
avatarHeaderSize40The avatar's diameter in a conversation's header.
avatarProfileSize104The avatar's diameter on the You screen.
iconSize24The size of header and toolbar icons.
tabIconSize24 on Android, 26 elsewhereThe size of tab bar and side rail icons.
tabBarHeight64 on Android, 55 elsewhereThe bottom tab bar's least height, above the system's own bar. A larger text makes the bar taller; it never cuts its words.
pageMargin24 from a medium window (windowClass 1 and up), 16 below itA screen's side margin: from the window's edge to the text of its rows and headers.

Tutte le pagine della guida