🐦 Mastodon with modern birdsite-like UI

Blasphemy! Yes, I know, but I just had to do this. I wanted to see if it's possible to get Mastodon default user interface to resemble Twitter, but be a lot better than it ever was.

Please note that this started as a personal experiment for fun, but then got more serious.

See my original Mastodon post.
Read the blog post: The day I decided to build my own "Twitter".

Live demo on mementomori.social

Table of contents

1. Why would anyone want Mastodon to look like Twitter?
2. Features
3. List of instances that use Mastodon Bird UI
4. Installation for Mastodon instance admins
5. Make Mastodon Bird UI as optional by integrating it as 'Site theme' in settings for all users
6. Installation for regular users, contributing and testing
7. Development
8. Updating instructions
9. Other tweaks and customizations
   1. Status bar color on Android PWA
   2. Hide translate link for multiple languages
   3. Thread lines
   4. Micro-interactions
10. FAQ
    1. I want to make changes to the UI, can I do that?
    2. Can you implement feature X?
    3. Why don't you just create an app?
    4. Why don't you just run Mastodon Bird UI in a separate URL?
    5. Is the advanced web interface styled
    6. Why the admin interface is not styled?
    7. Can you add feature x?
    8. Can you make it look like this by default?
    9. How to get to settings or faves on mobile?
    10. Automatic dark/light mode possible?
    11. I like it so much, why it can't be the default Mastodon UI
11. Goals
12. Accessibility
    1. How to install an Accessible version built for people with serious vision impairment

Why would anyone want Mastodon to look like Twitter?

Because you can? Let's face it, we're kinda used to it, Mastodon already resembles the birdsite. Twitter UI is not bad, it's just that it's not for everyone. Twitter (in my opinion) made some bad choices with the new UI for example with the typography, so in a sense I wanted to see if I could make Mastodon look like Twitter, but better.

This is why I have defaulted Mastodon deep purple colors in this "theme", if you will. If you really want the vanilla birdsite-look, please modify the colors yourself.

Here are some of the UI things Mastodon Bird UI is trying to solve (read the Mastodon post):

More screenshots

• Dark version on mobile
• Light version on mobile
• Dark version on Linux desktop
• Dark version of the profile on Linux desktop
• Light version on Linux desktop
• Dark profile on macOS desktop
• Light version on macOS desktop
• Twitter colors on desktop (outdated)
• Advanced web interface with multiple columns

Features

As this is CSS-only, they are not really "features" but more like aesthetic changes.

• Respects the profile Site theme setting and sets dark/light based on this alone
• Subtle deep purple ribbon in the right corner for private messages
• CSS variables for everything
• Threaded replies (limited, see issue #4)
• Avatars on the left in feed view
• Unified transparent backgrounds
• Dark patterns for dropdowns and other pop overs like emoji picker
• Tinted deep purple, subtle beautiness
• Action bar in the bottom on mobile
• Micro-interaction in the like/favourite icon (see more about this)
• Circling boost animation
• Support for RTL languages
• Hide lists by default, show them on hover
• Carefully polished UI with hand picked/designed icons based on open source versions of Iconoir, Ionicons and Feather
• Show added follows in green, indicate unfollow with red
• Show added to list in green, indicate removing with red

List of instances that use Mastodon Bird UI

The following instances have enabled Mastodon Bird UI for their users, based on this inquiry. Do you use this theme? Let me know or send a PR that adds your instance.

Instance	Implementation method	Theme name	User count	Default
mementomori.social	Site theme	Mastodon Bird UI	100+	Yes
dvm.community	Custom CSS	N/A	200+	Yes
muri.network	Site theme	Mastodon Bird UI	100+	Yes
suomi.social	Custom CSS	N/A	10+	Yes
mstdn.social	Site theme	Elephant	40000+	No
bolha.one	Custom CSS	N/A	10+	Yes
indieweb.social	Custom CSS	N/A	1900+	Yes
egirl.social	Custom CSS	N/A	1	Yes
qdon.space	Site theme	Mastodon Bird UI	1100+	No
bakedbean.xyz	Custom CSS	N/A	100+	Yes
wien.rocks	Site theme	BirdUI	1100+	No
climatejustice.global	Site theme	BirdUI	100+	No
climatejustice.social	Site theme	BirdUI	1800+	No
climatejustice.rocks	Site theme	BirdUI	1	No
fedi.at	Site theme	BirdUI	160+	No
mtg.garden	Site theme	BirdUI	20+	No
social.fairphone.community	Site theme	BirdUI	5	No
kawakawa.fun	Custom CSS	N/A	1	Yes
mastodonsuomi.fi	Custom CSS	N/A	20+	Yes
mastodon.ktachibana.party	Site theme	Bird UI	100+	No
techhub.social	Site theme	Elephant	14000+	No
social.noleron.com	Site theme	Elephant	10+	Yes
masto.es	Site theme	Bird UI	5400+	Yes
mast.lat	Modified Custom CSS	N/A	1900+	Yes
tkz.one	Modified Custom CSS	N/A	3500+	Yes
mastodonsweden.se	Custom CSS	N/A	130+	Yes
mindly.social	Site theme	Elephant	4800+	No
vmst.io	Site theme	Elephant	650+	No
some.tehy.fi	Custom CSS	N/A	3	Yes
pug.ninja	Custom CSS	N/A	1	Yes
aus.social	Site theme	Elephant	5700+	No
tyrol.social	Site theme	BirdUI	40+	No
social.ferrocarril.net	Custom CSS	N/A	20+	Yes
social.braydmedia.de	Custom CSS	N/A	1	Yes
mastodon.sg	Custom CSS	N/A	100+	Yes
krassestegang.social	Site theme	Elephant	3	Yes
artsculture.media	Site theme	Mastodon Bird UI	60+	No
gayfr.social	Site theme	Mastodon Bird UI	230+	No
furry.energy	Site theme	Elephant	90+	Yes
vkl.world	Modified Custom CSS	N/A	2000+	Yes
duk.space	Site theme	Bird UI	80+	No
supebase.com	Site theme	Bird UI Modified	1	Yes
buddyverse.xyz	Site theme	Mastodon Bird UI	6+	Yes
mastodon.bsd.cafe	Site theme	Mastodon Bird UI	70+	Yes
jkpg.rocks	Site theme	Mastodon Bird UI	2+	Yes
convo.casa	Site theme	Mastodon Bird UI	5000+	No
social.kryta.app	Custom CSS	Mastodon Bird UI	<100	Yes
social.vivaldi.net	Site theme	Mastodon Bird UI	6700+	No
wxw.moe	Site theme	Mastodon Bird UI	3500+	Yes
mastodon.com.pl	Site theme	Mastodon Bird UI	100+	No
mastodon.sg	Custom CSS	Mastodon Bird UI	100+	Yes
FaithTree.social	Site theme	Mastodon Bird UI	19+	Yes
mustard.blog	Site theme	Mastodon Bird UI	2000+	Yes
c.im	Site theme	Mastodon Bird UI	2000+	No
datasci.social	Custom CSS	Mastodon Bird UI	80+	Yes
billys.mom	Custom CSS	N/A	10+	Yes
circlewithadot.net	Custom CSS	Mastodon Bird UI	3	Yes
erica.moe	Site theme	Mastodon Bird UI	20+	Yes

Installation for Mastodon instance admins

1. Copy the contents of dist/mastodon-bird-ui.css and paste it to the Custom CSS in the Appearance settings in your instance (https://yourinstance/admin/settings/appearance). This single file covers both single-column and multiple-columns (advanced web interface) layouts. It is a dark theme; if you want Bird UI to follow each user's light or dark choice in the Appearance settings, use dist/mastodon-bird-ui-auto.css instead.

   Other prebuilt variants live in dist/ for Custom CSS users: mastodon-bird-ui-auto.css (follows each user's light/dark color scheme from the Appearance settings), mastodon-bird-ui-stars.css (a yellow Twitter-style star favourite instead of the heart), mastodon-bird-ui-light.css (always light), mastodon-bird-ui-accessible.css and mastodon-bird-ui-accessible-plus.css. Use whichever one you prefer. Rebuild a variant with npx parcel build src/<entry>.scss --dist-dir dist (for example src/mastodon-bird-ui-stars.scss).

Make Mastodon Bird UI as optional by integrating it as 'Site theme' in settings for all users

Mastodon Bird UI can be integrated as a Site theme for all instance users as optional.

Please note: This requires Mastodon v4.6.0+ and modifies Mastodon's styles directory. Do this at your own risk! I recommend testing in a development environment first.

If you'd like a different branding for your instance like "Elephant" without any mention of birds, use Bird UI Theme Admins by @stux.

Using the install script

Clone this repository and run the install script:

git clone https://github.com/ronilaukkarinen/mastodon-bird-ui.git
cd mastodon-bird-ui
npm install
sudo bash scripts/install-to-mastodon.sh --path /path/to/mastodon

The script will:

• Copy Bird UI source files to app/javascript/styles/mastodon-bird-ui/
• Generate theme entry points for all variants (dark, light, contrast, accessible, etc.)
• Update config/themes.yml with the new themes

After running the script, rebuild assets and restart services:

# Production
RAILS_ENV=production bundle exec rails assets:precompile
sudo systemctl restart mastodon-web

# Development
RAILS_ENV=development bundle exec rails assets:precompile

Users can now select Bird UI themes in Preferences > Appearance.

Installation for regular users

1. Install Live CSS Editor or Stylus browser extension
2. Copy the contents of dist/mastodon-bird-ui.css
3. Paste the CSS into the browser extension
4. Click the pin icon so the styles persist for the domain

Development and contributing

Testing on any Mastodon instance (including mastodon.social)

The easiest way to test changes without running a local Mastodon instance:

1. Fork and clone this repository
2. Install nvm and run nvm install to get the correct Node.js version
3. Install dependencies: npm install
4. Build CSS: npm run build
5. Install Stylus browser extension
6. Navigate to any Mastodon instance (e.g., mastodon.social)
7. Paste the contents of dist/mastodon-bird-ui.css into the extension
8. Edit SCSS files in src/, run npm run build, and refresh to see changes

Local development with hot-reload

For the best development experience with instant CSS injection, use a local Mastodon instance:

Prerequisites

• nvm installed, then run nvm install to get the correct Node.js version
• A running Mastodon instance (default: mementomori.test, configure in bs-config.js)
• Dependencies: npm install

Start development

npm run dev

This will:

1. Parcel - Watch your CSS files and recompile on changes to dist/
2. Browsersync - Proxy your Mastodon instance and inject the compiled CSS

Open http://localhost:3999 instead of your Mastodon instance directly. Any changes you make to SCSS files will be reflected immediately without page reload.

Available commands

# Development with hot-reload (watch + browsersync + lint)
npm run dev                      # Default dark theme
npm run dev:stars                # Stars animation variant
npm run dev:accessible           # Accessible variant
npm run dev:accessible-plus      # Accessible plus variant
npm run dev:accessible-hide-finnish  # Accessible + hide Finnish translate

# Individual tools
npm run watch                    # Parcel watch only
npm run sync                     # Browsersync only
npm run lint                     # Run stylelint

# Production
npm run build                    # Build for Custom CSS (minified, with version banner)
npm run clean                    # Remove dist/ and .parcel-cache/

Configuration

• Parcel configuration: .parcelrc - Controls CSS compilation and optimization
• Browsersync configuration: bs-config.js - Configure proxy settings, injection rules, and other options

If your Mastodon instance is not at mementomori.test, edit bs-config.js and change the proxy value.

Contributing

1. Fork this repository
2. Create a feature branch: git checkout -b my-feature
3. Make your changes in src/
4. Test using one of the methods above
5. Commit your changes
6. Push to your fork and open a Pull Request

Updating instructions

If you are using Custom CSS, just copy and paste the new version of dist/mastodon-bird-ui.css to Custom CSS textarea in the Appearance settings in your instance (https://yourinstance/admin/settings/appearance).

If you are using Mastodon Bird UI as a site theme, update to the latest version:

cd mastodon-bird-ui
git pull
sudo bash scripts/install-to-mastodon.sh --path /path/to/mastodon

Then rebuild assets and restart:

RAILS_ENV=production bundle exec rails assets:precompile
sudo systemctl restart mastodon-web

Other tweaks and customizations

While Mastodon Bird UI works perfectly fine out of the box, there are some things you might want to modify to make it look even better.

Status bar color on Android PWA

Edit this line and recompile assets with yarn build:production.

Hide translate link for multiple languages

If you're a polyglot like me, you can hide the translate link on other languages than default by adding this at the end of the Custom CSS (this example is for people who understand Finnish and German):

.status__content__text[lang="de"].translate ~ .status__content__read-more-button,
.status__content__text[lang="fi"].translate ~ .status__content__read-more-button {
  display: none;
}

Thread lines

There is support for threads available for the nightly version since (see PR #24549) and if you want to use the native threaded lines, just use main branch from Mastodon. There's a related issue about it that I have commented. You should also see the discussion on a Mastodon Bird UI issue #4.

Micro-interactions

There are two micro-interaction animations in this UI, both are inspired by the Twitter's original UI animation. The star is originally a work of a Twitter designer Brian Waddington. The heart is by Twitter design team. Both animations have been completely re-created by me, frame by frame. The star animation itself contains 100 hand made frames.

Bird UI uses the heart by default. The star variant lives in src/micro-interactions/_star.scss; forks can expose a setting to switch to it, and Custom CSS users can swap it in.

Native favourite animations: if your Mastodon already ships its own favourite animation as a real SVG component, like the mementomori.social fork (PR #10) which renders a native star/heart burst (heart by default, star as an opt-in setting), the install script detects it and Bird UI steps aside for the favourite button so the native animation shows. Bird UI keeps styling the navigation and the sidebar/notification favourite icons, so nothing else changes and no configuration is needed.

FAQ

I get many questions about this UI, so here I'm going to answer to them.

I want to make changes to the UI, can I do that?

Of course! This is all open source, customizable and extendable. You can fork this repo and make changes to the CSS. You can also use the Custom CSS box in {yourinstance.social/admin/settings/appearance} to add your own styles directly.

Can you implement feature X?

Not everything is possible via CSS only. In fact, some of the tweaks I had to do to the Mastodon core, see my fork here and the tweaks above.

However, even if they were possible, I won't implement all requests. My opinionated choices are not the only answer, but I'm not willing to add every possible customization to this UI as default. I want to keep it simple and extendable.

Why don't you just create an app?

I'm not a software developer. I'm a front end developer (and a bit of a designer) and my expertise is in CSS, UX and HTML. I don't know how to create a Mastodon app for Android, iOS or web and while I know a bit of python, JavaScript, Ruby and other programming languages, I don't have time and patience to create an app from scratch right now.

There are other people who are working on magnificent apps for Mastodon, so I'm not going to reinvent the wheel. I simply like the Twitter-ish UI and Mastodon default web back-end and I want to have these combined on my instance. As CSS is the language I live and breathe daily, it's really easy and fast for me to create a UI like this.

Also, Mastodon web UI works as an app already. See my answer here.

Why don't you just run Mastodon Bird UI in a separate URL?

See the previous answer. Mastodon Bird UI is not an app, it's a CSS file that you can use with any Mastodon instance. You don't need to run a separate instance just for this UI and perhaps you shouldn't either.

If you really would want this to run in a separate URL, you could in theory set up another nginx host for a subdomain and just use ngx_http_sub_module to load up a CSS file. I haven't tried this and it might not be even possible, but it's worth a try.

Is the advanced web interface styled?

Yes! The unified mastodon-bird-ui.css covers both single-column and multiple-columns (advanced web interface) layouts automatically.

Why the admin interface is not styled?

We don't spend much time in the admin interface and it's not a priority for me to style it. It would mean too much work and it's not worth it right now.

Can you add feature x?

Mastodon Bird UI is CSS only, so I can't add any features. Please send your Mastodon feature ideas here.

Can you make it look like this by default?

Probably yes, but I'm not here to please everyone. Suggestions like this are very important and there has been many pull requests and issues already that have helped me to make the UI better. While saying this I'm not going to implement every single suggestion, because there are too many different opinions out there.

If you like, you can always suggest something or create a pull request. You are welcome to create your own fork and modify the UI as you prefer. I hope you have fun with it!

How to get to settings or faves on mobile?

Use the navigation menu (the bottom navigation / hamburger), where Favourites, Bookmarks, Lists and Settings live. Older Bird UI versions relied on swiping the bottom bar; that no longer applies since Mastodon rebuilt its mobile navigation.

Automatic dark/light mode possible?

Not at the moment, for following reasons:

1. Original Mastodon themes were built using CSS classes in body level, Mastodon Bird UI merely follows this logic.
2. @media (prefers-color-scheme: dark/light) does not support @import in SCSS inside them, so it's not currently possible to implement new themes with one file. I'm not going to create separate files for dark and light themes, because it would be too much work to maintain.
3. Many choose to use either dark or light theme.

I like it so much, why it can't be the default Mastodon UI?

As I have explained here and in other threads, I do not want it to be the default UI. There are numerous reasons for this.

1. I would not be responsible for it. I do this as a side hobby and for fun, it would get too professional and time consuming for me to be responsible "alone" for the UI infrastructure of the official Mastodon core. It would need some arrangement so it would not bring extra pressure to me personally. More maintainers, etc. I have a time consuming day job as an entrepreneur and UI in this scale needs more housekeeping than I can provide.
2. The Mastodon core CSS/SCSS needs to be rewritten. It's not practical to have two code bases, I think Mastodon Bird UI cannot be just "added" to the core, it's CSS-only and does not follow the current Mastodon SCSS framework. At very least the SCSS variables should be replaced with CSS variables. It's quite a lot of work to rewrite a complete UI codebase.
3. Hacky micro animations and SVG-CSS icons should be replaced with real things. Right now it's like a stamp on a letter. We need the new letter for this to be official.
4. The idea and looks behind Mastodon Bird UI is hugely inspired by Twitter UI. If the popular attitude is that Mastodon should not resemble Twitter in any way, that needs to change first.

Goals

• CSS only output. The compiled output is pure CSS with no JavaScript runtime. Ready-made CSS works when placed in Custom CSS box in {yourinstance.social/admin/settings/appearance}
• Modular SCSS source. The source code uses SCSS with a modular architecture for easier maintenance and contributions. The build process compiles everything into single CSS files for distribution.

Accessibility

Mastodon Bird UI is built with accessibility in mind. Please note that many "features" are 100% the same as in the original Mastodon, because this is not a separate app but merely consists of modifications in styles. There is a High contrast version available just like in the original Mastodon.

Programmatically everything is as accessible as Mastodon, color-wise "Pretty good" (WCAG A-AA). Please open an issue or a Mastodon issue, if you have accessibility concerns. Thank you.

How to install an Accessible version built for people with serious vision impairment

My wife has Retinitis Pigmentosa and a form of Achromatopsia so it was her wish to be able to use Mastodon better with some accessibility features. When High contrast theme is not enough, you can use the version with:

• Larger font sizes all around
• Contrast to the max
• More accessible colors
• Different colors for links, mentions and hashtags

Accessible themes are included in the installation scripts since Mastodon 4.6.0.