Meta tags:
description=This document is an introduction to theming in Mastodon. It s primarily aimed at theme creators, but also contains useful information for anyone interested in working on Mastodon s styles.;

Headings (most frequently used words):

creating, themes, the, groundwork, custom, styles, respecting, color, scheme, and, contrast, preferences, sponsored, by,

Text of the page (most frequently used words):
the (31), mastodon (19), and (17), theme (16), your (14), admin (13), styles (11), color (11), for (8), my_theme (8), contrast (7), #scheme (7), dark (7), you (7), preferences (7), scss (7), this (6), tokens (6), default (6), light (6), themes (6), new (6), with (6), black (5), server (5), setting (4), that (4), data (4), folder (4), app (4), instance (4), profile (4), account (4), api (4), oauth (4), using (4), design (3), background (3), white (3), can (3), use (3), css (3), auto (3), high (3), are (3), settings (3), once (3), done (3), change (3), create (3), javascript (3), entrypoint (3), file (3), but (3), custom (3), from (3), application (3), creating (3), search (3), apps (3), reports (3), accounts (3), source (2), list (2), available (2), reference (2), component (2), also (2), will (2), reflected (2), mode (2), respecting (2), example (2), copy (2), config (2), yml (2), duplicate (2), assets (2), services (2), own (2), groundwork (2), notificationpolicy (2), filter (2), report (2), quote (2), domainblock (2), notifications (2), trends (2), collections (2), domain_blocks (2), security (2), environment (2), implementing (2), posts (2), machine (2), installing (2), features (2), configuring (2), running (2), imprint, view, blog, join, sponsored, last, updated, may, 2026, improve, page, generally, recommend, handling, dependent, level, see, our, function, achieve, same, result, always, resolved, actually, displayed, option, current, values, html, attributes, they, used, scope, newly, user, options, prior, variations, like, had, implemented, separate, has, changed, where, these, were, made, independent, defined, files, changes, should, _light, _dark, _base, duplicated, open, replace, need, one, referenced, import, instead, original, could, now, entire, start, tweaking, things, only, want, colours, enough, steps, above, completed, created, its, identical, administration, users, appearance, selectable, after, rebuild, restart, docker, container, rails_env, production, bundle, exec, rails, precompile, located, add, entry, document, introduction, theming, primarily, aimed, creators, contains, useful, information, anyone, interested, working, webpushsubscription, translation, token, termsofservice, tag, suggestion, statussource, statusedit, status, shallowtag, shallowquote, scheduledstatus, rule, role, relationshipseveranceevent, relationship, reaction, quoteapproval, privacypolicy, previewcardauthor, previewcard, poll, notificationrequest, notificationfallback, notification, mediaattachment, marker, identityproof, filterstatus, filterresult, filterkeyword, featuredtag, featureapproval, familiarfollowers, extendeddescription, error, customemoji, conversation, context, collectionwithaccounts, collectionitem, collection, asyncrefresh, appeal, annualreport, announcement, measure, ipblock, emaildomainblock, domainallow, dimension, cohort, canonicalemailblock, accountwarning, entities, streaming, markers, lists, conversations, timelines, scheduled_statuses, polls, media, statuses, proofs, oembed, push, directory, custom_emojis, announcements, health, grouped, async_refreshes, emails, annual, retention, measures, ip_blocks, email_domain_blocks, domain_allows, dimensions, canonical_email_blocks, tags, suggestions, mutes, followed_tags, follow_requests, filters, featured_tags, favourites, endorsements, bookmarks, blocks, methods, rate, limits, scopes, guidelines, best, practices, datetime, formats, rest, bearcaps, microformats, webfinger, activitypub, spec, compliance, styling, state, management, components, frontend, guide, issues, responsible, disclosure, routes, code, structure, dev, technical, overview, contributing, libraries, implementations, logging, obtaining, client, access, playing, public, getting, started, developing, roles, webhooks, database, index, corruption, troubleshooting, errors, moderation, actions, scaling, migrating, backing, upgrading, release, cli, single, sign, captcha, onion, object, storage, optional, full, text, preparing, official, ios, android, moving, leaving, externally, more, set, promoting, yourself, others, dealing, unwanted, content, quoting, other, network, posting, signing, what, documentation,

Text of the page (random words):
creating themes mastodon documentation what is mastodon using mastodon signing up for an account setting up your profile posting to your profile using the network features quoting other posts dealing with unwanted content promoting yourself and others set your preferences more settings using mastodon externally moving or leaving accounts official ios and android apps running your own server running mastodon preparing your machine installing from source configuring your environment configuring full text search installing optional features object storage onion services captcha single sign on setting up your new instance using the admin cli upgrading to a new release backing up your server migrating to a new machine scaling up your server moderation actions troubleshooting errors database index corruption webhooks roles developing mastodon apps getting started with the api playing with public data obtaining client app access logging in with an account libraries and implementations implementing quote posts implementing collections contributing to mastodon technical overview setting up a dev environment code structure routes security issues and responsible disclosure frontend guide components state management css and styling creating themes design tokens reference spec compliance activitypub webfinger security microformats oauth bearcaps rest api datetime formats guidelines and best practices oauth tokens oauth scopes rate limits api methods accounts blocks bookmarks domain_blocks endorsements favourites featured_tags filters follow_requests followed_tags mutes preferences reports suggestions tags admin accounts canonical_email_blocks dimensions domain_allows domain_blocks email_domain_blocks ip_blocks measures reports retention trends annual reports apps emails oauth async_refreshes collections grouped notifications health instance announcements custom_emojis directory trends notifications push oembed profile proofs search statuses media polls scheduled_statuses timelines conversations lists markers streaming api entities account accountwarning admin account admin canonicalemailblock admin cohort admin dimension admin domainallow admin domainblock admin emaildomainblock admin ip admin ipblock admin measure admin report announcement annualreport appeal application asyncrefresh collection collectionitem collectionwithaccounts context conversation customemoji domainblock error extendeddescription familiarfollowers featureapproval featuredtag filter filterkeyword filterresult filterstatus identityproof instance list marker mediaattachment notification notificationfallback notificationpolicy notificationrequest poll preferences previewcard previewcardauthor privacypolicy profile quote quoteapproval reaction relationship relationshipseveranceevent report role rule scheduledstatus search shallowquote shallowtag status statusedit statussource suggestion tag termsofservice token translation v1 filter v1 instance v1 notificationpolicy webpushsubscription creating themes this document is an introduction to theming in mastodon it s primarily aimed at theme creators but also contains useful information for anyone interested in working on mastodon s styles the groundwork custom styles respecting color scheme and contrast preferences the groundwork the entrypoint of the default mastodon theme is located at app javascript styles application scss to create your own theme duplicate this file and add a new entry for it to the file config themes yml for example default styles application scss my_theme styles my_theme scss after this rebuild assets rails_env production bundle exec rails assets precompile and restart the mastodon services or docker container once this is done your custom theme will be selectable for users from preferences appearance theme as the server s default theme from administration server settings design custom styles with the steps above completed you ve created a new theme entrypoint but its styles are identical to the default mastodon theme you could now go on to duplicate the entire app javascript styles mastodon css folder and start tweaking things but if you only want to change the colours of the mastodon ui it s enough to create a copy of the mastodon theme folder once that s done you need to change your entrypoint file the one referenced in config themes yml to import your copy of the theme folder instead of the original example if you ve duplicated the mastodon theme folder to app javascript styles my_theme open my_theme scss and replace use mastodon theme with use my_theme once that s done you can change the theme tokens defined in the files my_theme _base scss my_theme _dark scss and my_theme _light scss to create a new color theme and the changes should be reflected in the ui respecting color scheme and contrast preferences prior to mastodon 4 6 theme variations like light mode dark mode and high contrast had to be implemented as separate themes this has changed in 4 6 where these preferences were made independent settings the newly available user options are color scheme auto light or dark contrast auto or high current values are reflected in the html attributes data color scheme and data contrast so that they can be used to scope your styles component color black background black data color scheme dark color white background black the auto setting will always be resolved to the actually displayed option for color scheme that s light or dark for contrast it s default or high you can also use the light dark css function to achieve the same result component color light dark black white background light dark white black generally we recommend handling color scheme and contrast dependent styles at the level of theme tokens see our design tokens reference for a list of tokens available by default last updated may 29 2026 improve this page sponsored by join mastodon blog view source cc by sa 4 0 imprint