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".
Mastodon Bird UI version format: semver + Mastodon version, for example: 1.5.8rc4-mastodon-4.1.2-stable
. First, check the Mastodon version you're running, then choose the version for Mastodon Bird UI. If you're running Mastodon 4.1.2 stable, choose the version mastodon-4.1.2-stable
. If you're running Mastodon 4.1.2 nightly, choose the version mastodon-4.1.2-nightly
.
- Why would anyone want Mastodon to look like Twitter?
- Features
- Installation for Mastodon instance admins
- Make Mastodon Bird UI as optional by integrating it as 'Site theme' in settings for all users
- Installation for regular users, contributing and testing
- Updating instructions
- Other tweaks and customizations
- FAQ
- I want to make changes to the UI, can I do that?
- Can you implement feature X?
- I want background-color to the compose form
- Why don't you just create an app?
- Why don't you just run Mastodon Bird UI in a separate URL?
- Is the advanced web interface styled
- Why the admin interface is not styled?
- Can you add background-color for compose form box area?
- Can you change compose form height and font-size?
- Can you add this/that feature as default?
- Can you make it look like this by default?)?
- Goals
- Accessibility
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. Or go to the hellsite if you really love it so much.
Here are some of the UI things Mastodon Bird UI is trying to solve (read the Mastodon post):
- 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
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
- Missing alt text indicators
- 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
- Copy the contents of layout-single-column.css and layout-multiple-columns.css and paste them (or one of them) to the Custom CSS in the Appearance settings in your instance (https://yourinstance/admin/settings/appearance). It might be recommended using the single layout CSS as "base" and use the advanced view CSS with browser extension (as it's desktop only anyway).
Mastodon Bird UI can be integrated as a Site theme for all instance users as optional.
If you'd like a different branding for your instance like "Elephant" without any mention of birds, use Bird UI Theme Admins by @stux. Otherwise read along.
If you cd to your Mastodon directory (usually $HOME/live) you can run these bash commands (Please note: These add Mastodon Bird UI as name "Mastodon Bird UI (Dark)" + variants as default, while retaining the original themes as secondary themes):
# First, define version
export MASTODON_VERSION_FOR_BIRD_UI="mastodon-4.1.2-nightly"
# Create a new folder for the theme
mkdir -p app/javascript/styles/mastodon-bird-ui
# Download the CSS file for single column layout
wget https://raw.githubusercontent.com/ronilaukkarinen/mastodon-bird-ui/$MASTODON_VERSION_FOR_BIRD_UI/layout-single-column.css -O app/javascript/styles/mastodon-bird-ui/layout-single-column.scss
# Download the CSS file for multiple column layout
wget https://raw.githubusercontent.com/ronilaukkarinen/mastodon-bird-ui/$MASTODON_VERSION_FOR_BIRD_UI/layout-multiple-columns.css -O app/javascript/styles/mastodon-bird-ui/layout-multiple-columns.scss
# Replace theme-contrast with theme-mastodon-bird-ui-contrast for single column layout
sed -i 's/theme-contrast/theme-mastodon-bird-ui-contrast/g' app/javascript/styles/mastodon-bird-ui/layout-single-column.scss
# Replace theme-mastodon-light with theme-mastodon-bird-ui-light for single column layout
sed -i 's/theme-mastodon-light/theme-mastodon-bird-ui-light/g' app/javascript/styles/mastodon-bird-ui/layout-single-column.scss
# Replace theme-contrast with theme-mastodon-bird-ui-contrast for multiple column layout
sed -i 's/theme-contrast/theme-mastodon-bird-ui-contrast/g' app/javascript/styles/mastodon-bird-ui/layout-multiple-columns.scss
# Replace theme-mastodon-light with theme-mastodon-bird-ui-light for multiple column layout
sed -i 's/theme-mastodon-light/theme-mastodon-bird-ui-light/g' app/javascript/styles/mastodon-bird-ui/layout-multiple-columns.scss
# Create high contrast theme file
echo -e "@import 'contrast/variables';\n@import 'application';\n@import 'contrast/diff';\n@import 'mastodon-bird-ui/layout-single-column.scss';\n@import 'mastodon-bird-ui/layout-multiple-columns.scss';" > app/javascript/styles/mastodon-bird-ui-contrast.scss
# Create light theme file
echo -e "@import 'mastodon-light/variables';\n@import 'application';\n@import 'mastodon-light/diff';\n@import 'mastodon-bird-ui/layout-single-column.scss';\n@import 'mastodon-bird-ui/layout-multiple-columns.scss';" > app/javascript/styles/mastodon-bird-ui-light.scss
# Create dark theme file
echo -e "@import 'application';\n@import 'mastodon-bird-ui/layout-single-column.scss';\n@import 'mastodon-bird-ui/layout-multiple-columns.scss';" > app/javascript/styles/mastodon-bird-ui-dark.scss
# Overwrite mastodon/config/themes.yml with new settings, Mastodon Bird UI dark as default
echo -e "default: styles/mastodon-bird-ui-dark.scss\nmastodon-bird-ui-light: styles/mastodon-bird-ui-light.scss\nmastodon-bird-ui-contrast: styles/mastodon-bird-ui-contrast.scss\nmastodon-dark: styles/application.scss\nmastodon-light: styles/mastodon-light.scss\ncontrast: styles/contrast.scss" > config/themes.yml
After this you need to edit localisations in config/locales/en.yml
(nano config/locales/en.yml
) and add these lines:
themes:
contrast: Mastodon (High contrast)
default: Mastodon Bird UI (Dark)
mastodon-bird-ui-light: Mastodon Bird UI (Light)
mastodon-bird-ui-contrast: Mastodon Bird UI (High contrast)
mastodon-light: Mastodon (Light)
mastodon-dark: Mastodon (Dark)
Same for the localizations of your choice, for example config/locales/fi.yml
(nano config/locales/fi.yml
):
themes:
contrast: Mastodon (Korkea kontrasti)
default: Mastodon Bird UI (Tumma)
mastodon-bird-ui-light: Mastodon Bird UI (Vaalea)
mastodon-bird-ui-contrast: Mastodon Bird UI (Korkea kontrasti)
mastodon-light: Mastodon (Vaalea)
mastodon-dark: Mastodon (Tumma)
And you're done!
- Install Live CSS Editor (or any other extension like Stylus that allows you to inject CSS into web pages) or use Unite for macOS or use the user.js by eg
- Copy the contents of layout-single-column.css and layout-multiple-columns.css
- Open extension and paste the contents of both CSS files into the editor
- If you use Live CSS Editor, click ๐-icon so the styles will be remembered for the domain or if you want just to use it as needed, activate styles from the extension's popup
If you are using Custom CSS, just copy and paste the new version to Custom CSS textarea in the Appearance settings in your instance (https://yourinstance/admin/settings/appearance). If you are using Mastodon Bird UI as option, get the latest changes to your instance, first cding to live folder (or to wherever your Mastodon root is), then:
# First, define version
export MASTODON_VERSION_FOR_BIRD_UI="mastodon-4.1.2-nightly"
# Download the CSS file for single column layout
wget --no-cache https://raw.githubusercontent.com/ronilaukkarinen/mastodon-bird-ui/$MASTODON_VERSION_FOR_BIRD_UI/layout-single-column.css -O app/javascript/styles/mastodon-bird-ui/layout-single-column.scss
# Download the CSS file for multiple column layout
wget --no-cache https://raw.githubusercontent.com/ronilaukkarinen/mastodon-bird-ui/$MASTODON_VERSION_FOR_BIRD_UI/layout-multiple-columns.css -O app/javascript/styles/mastodon-bird-ui/layout-multiple-columns.scss
# Replace theme-contrast with theme-mastodon-bird-ui-contrast for single column layout
sed -i 's/theme-contrast/theme-mastodon-bird-ui-contrast/g' app/javascript/styles/mastodon-bird-ui/layout-single-column.scss
# Replace theme-mastodon-light with theme-mastodon-bird-ui-light for single column layout
sed -i 's/theme-mastodon-light/theme-mastodon-bird-ui-light/g' app/javascript/styles/mastodon-bird-ui/layout-single-column.scss
# Replace theme-contrast with theme-mastodon-bird-ui-contrast for multiple column layout
sed -i 's/theme-contrast/theme-mastodon-bird-ui-contrast/g' app/javascript/styles/mastodon-bird-ui/layout-multiple-columns.scss
# Replace theme-mastodon-light with theme-mastodon-bird-ui-light for multiple column layout
sed -i 's/theme-mastodon-light/theme-mastodon-bird-ui-light/g' app/javascript/styles/mastodon-bird-ui/layout-multiple-columns.scss
After this commit changes to your Mastodon fork if you have one, then:
RAILS_ENV=production bundle exec rails assets:precompile
sudo service mastodon-web reload
That's it!
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.
If you like bigger link previews, please implement this.
Edit this line and recompile assets with yarn build:production
.
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;
}
There is currently no proper thread support in replies on Mastodon core. There's an issue about it that I have commented. You should also see the discussion on issue #4.
- Implement this. Tested and online at mementomori.social. This changes the HTML structure so that creating threaded lines is possible.
- Enable Mastodon Bird UI 1.3.8 or later
- It works!
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.
Twitter likes | Twitter fave star (2015) |
---|---|
![]() |
![]() |
If you like the heart, just remove everything between Star animation micro-interactions start (depends on the heart icon above)
and Star animation micro-interactions end
.
I get many questions about this UI, so here I'm going to answer to them.
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.
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.
See the end of this comment.
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.
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.
Yes! From version 1.5.4 multiple columns are supported. Apply layout-multiple-columns.css to your Custom CSS or style extension to enable.
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.
Aesthetically I prefer left and right sides to be "floaty" and I follow the design language from Twitter even if the compose form is there inside the center column. See this issue for the decision not to have it there by default.
You can add it yourself by adding this to your Custom CSS:
/* Add background color for the compose form */
/* stylelint-disable-next-line no-duplicate-selectors */
.layout-single-column .compose-form .compose-form__autosuggest-wrapper,
.layout-single-column .compose-form .compose-form__buttons-wrapper {
background-color: var(--color-mud);
border-color: var(--color-mud);
padding-top: 0;
}
/* Fixes to bottom row when there's a background */
.layout-single-column .compose-form .compose-form__buttons-wrapper {
padding-bottom: calc(var(--gap-default) / 2);
}
Yes YOU can. But they're not there by default, see this post. Box size has been set to a certain max-height because it helps the people who use assistive on-screen keyboard (suggestion from @rmattila74). For this reason I'm not going to increase height or make it resize too much by default. You can do these modifications for yourself, here's the code for you:
.layout-single-column .compose-form .autosuggest-textarea__textarea {
font-size: 18px;
min-height: 300px;
}
Tweak the values as you like.
Mastodon Bird UI is CSS only, so I can't add any features. Please send your Mastodon feature ideas here.
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!
- CSS only. This means some pseudos and modern CSS hacks. The intent is to have the code base as simple and extendable as possible. The styles should be easily modifiable. Ready-made code works when placed in Custom CSS box in {yourinstance.social/admin/settings/appearance}
- Dependency free. No JavaScript, no build process, no nothing. Just plain CSS. Linting is optional and just here to make sure the code quality is good.
Mastodon Bird UI is built accessibility in mind. Please note that many "features" are 100% the same than 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.