4.0.0-alpha.8.rc

4.0.0-alpha.8.rc: 2026-05-03

Note

WIP Notice: This is a heavily work-in-progress upcoming version of Mastodon Bird UI. This version is part of the ongoing major rewrite (see issue #172) and is finally fully modularized.
💀 Compatibility: Mastodon v4.6.0-alpha.7-2026-05-02 (nightly from Mastodon main after 2026-05-02)

This version will not support older Mastodon versions deployed before 2026-05-02. For older Mastodon servers, use previous Mastodon Bird UI versions designed for those releases - each release candidate is dated to match its equivalent Mastodon version state.

ested against Mastodon main at v4.6.0-alpha.7.

What changed

New: auto bundle that follows Mastodon's Appearance radios

A new mastodon-bird-ui-auto theme replaces the per-scheme theme files in the dropdown. It wraps the light tokens in [data-color-scheme="light"] and falls back to prefers-color-scheme: light when the attribute is absent (logged-out browsing). High contrast was already wrapped in html[data-contrast="high"] so it activates automatically. Mastodon's own Color scheme (Auto / Light / Dark) and Contrast (Auto / High) radios in Appearance settings now drive Bird UI directly. See #182.

Theme dropdown is now slim

install-to-mastodon.sh no longer generates these duplicate theme entries:

• mastodon-bird-ui-dark (use Color scheme = Dark instead)
• mastodon-bird-ui-light (use Color scheme = Light instead)
• mastodon-bird-ui-contrast (use Contrast = High instead)
• mastodon-bird-ui-dark-change-to-stars
• hide-finnish, hide-finnish-change-to-stars, hide-translate-links
• mastodon-bird-ui-light-hide-finnish, mastodon-bird-ui-light-hide-finnish-change-to-stars, mastodon-bird-ui-light-hide-translate-links
• mastodon-bird-ui-accessible-hide-finnish

After upgrading and re-running the install script, the dropdown is down to four entries: Mastodon Bird UI, Mastodon (Dark), Mastodon Bird UI (Accessible), Mastodon Bird UI (Accessible Plus).

Bug fixes

• Star icon and counter alignment fixed when reduce-motion is enabled. Sparkle and ring pseudo-element animations now fire in both motion modes since they are decorative, not transform animations. Closes #149.
• Refactored :is() complex selector in mobile sign-out CSS to a plain comma list so PostCSS no longer emits "Complex selectors" warnings during Mastodon's Vite build. Closes #178.
• Likely also closes #186 as a side-effect: the old _variables-light.scss wrapper applied light tokens even when data-color-scheme="dark" was set, which caused notification colors to disappear when the OS preferred light but Mastodon was set to dark. The new auto bundle scopes light tokens correctly.

Impact by install method

Custom CSS users (paste CSS into Mastodon admin)

No changes have been made for the workflow of Custom CSS users. The compiled dist/mastodon-bird-ui.css ships and behaves identically.

If you want a forced-light or forced-stars or hide-Finnish-translate-links bundle, the SCSS sources stay in src/:

• src/mastodon-bird-ui-light.scss
• src/mastodon-bird-ui-stars.scss and src/mastodon-bird-ui-light-stars.scss
• src/micro-interactions/_star.scss
• src/variants/_hide-finnish.scss
• src/variants/_hide-translate-links.scss

Build them yourself with npx parcel build src/<entry>.scss --dist-dir dist --no-source-maps --no-optimize and paste the resulting CSS into Mastodon admin.

Mastodon admins running install-to-mastodon.sh

After git pull on the Bird UI clone and re-running the install script, your themes.yml will shrink to four entries (or two if you skip variations). Users who had selected one of the removed theme entries fall back to the default Mastodon Bird UI auto theme without crashing (Mastodon's current_theme helper validates setting_theme against Themes.instance.names on every render). The user's stored theme value stays in their settings until they save a new Appearance setting.

To restore a previous look:

• Was on mastodon-bird-ui-light -> select Mastodon Bird UI and set Color scheme = Light.
• Was on mastodon-bird-ui-contrast -> select Mastodon Bird UI and set Contrast = High.
• Was on a *-stars or *-hide-finnish / *-hide-translate-links variant -> compile the matching SCSS source (see Custom CSS section above) and paste into Mastodon admin Custom CSS.

The old per-variant entry SCSS files (mastodon-bird-ui-light.scss, hide-finnish.scss, etc.) will remain on disk in app/javascript/styles/ as orphans. They are not referenced from themes.yml so Mastodon will not compile them; remove them at your leisure.

Heads up for mementomori-social/mastodon fork users

If you run the mementomori-social fork, the stars / hide-Finnish / hide-all-translate-links variants are now exposed as user-preference checkboxes in Appearance settings instead of separate themes. See the fork repo for the wiring (Ruby setting + getter + html class + view checkbox + locale): https://github.com/mementomori-social/mastodon/tree/mementomods-2026-05-02

4.0.0-alpha.7: 2026-05-02

4.0.0-alpha.7: 2026-05-02

Note

WIP Notice: This is a heavily work-in-progress upcoming version of Mastodon Bird UI. This version is part of the ongoing major rewrite (see issue #172) and is finally fully modularized.
💀 Compatibility: Mastodon v4.6.0-alpha.7-2026-05-02 (nightly from Mastodon main after 2026-05-02)

This version will not support older Mastodon versions deployed before 2026-05-02. For older Mastodon servers, use previous Mastodon Bird UI versions designed for those releases - each release candidate is dated to match its equivalent Mastodon version state.

• Fix duplicate profile buttons after upstream class name change while keeping desktop buttons positioned at top right of the header bar, Closes #185
• Remove padding-top from account__header__buttons on viewports under 420px
• Apply --font-size variable to various elements that are hardcoded in pixels, so accessible themes scale up those font sizes
• Fix inconsistent private mention styles between conversations and notifications, Closes #181
• Add border-bottom to follow_requests-unlocked_explanation
• Fix profile buttons and number fields on mobile under 420px
• Fix profile header image height only on viewports above 760px
• Fix profile buttons staying at top right on all viewports
• Adjust profile field font size and row gap for mobile under 700px
• Fix threaded line content alignment
• Fix profile spacing for familiar followers, number fields and field list
• Fix status content paragraph margin-bottom to 18px
• Fix dropdown menu button hover and focus background color
• Use font size and line height variables for accessible theme compatibility
• Map --color-text-brand to --color-accent for consistent link colors
• Fix profile badge and username spacing

4.0.0-alpha.6: 2026-04-06

4.0.0-alpha.6: 2026-04-06

Note

WIP Notice: This is a heavily work-in-progress upcoming version of Mastodon Bird UI. This version is part of the ongoing major rewrite (see issue #172) and is finally fully modularized.
💀 Compatibility: Mastodon v4.6.0-alpha.6-2026-04-06 (nightly from Mastodon main after 2026-04-06)

This version will not support older Mastodon versions deployed before 2026-04-06. For older Mastodon servers, use previous Mastodon Bird UI versions designed for those releases - each release candidate is dated to match its equivalent Mastodon version state.

• Fix translate button color not matching link color
• Fix extra border-left showing up in mobile devices
• Lint build for 4.6.0-alpha.3
• Fix install scripts for mementomods-2026-02-21, Ref: mastodon/mastodon#37612
• Fix focusable background color standing out too much for account name
• Fix install script for Mastodon 2026-03-21 common.scss removal
• Fully modularize _base.scss into 40+ focused module files #172
• Fix Browsersync CSS hot reload by stripping CSP headers from proxied responses
• Support new profile page structure #183
• Remove calendar icon for "Joined" field that are no longer in the new profile, Ref: #183
• Style new account_timeline_components_redesign__handleHelp, Ref: #183
• Fix profile button colors, Ref: #183
• Update Mastodon Bird UI theme tokens with latest design system tokens, Closes #184
• Remove select hack as it is fixed in upstream already, ref: mastodon/mastodon#37332
• Fix install script for new profile subdirectories

4.0.0-alpha.0-4

4.0.0-alpha.0-4: 2026-01-24

Note

WIP Notice: This is a heavily work-in-progress upcoming version of Mastodon Bird UI. This version is part of the ongoing major rewrite (see issue #172) and isn't yet fully modularized. It's functional with the latest mainline version, though.
💀 Compatibility: Mastodon v4.6.0-alpha.3-2026-01-24 (nightly from Mastodon main after 2026-01-15)

This version will not support older Mastodon versions deployed before 2026-01-15. For older Mastodon servers, use previous Mastodon Bird UI versions designed for those releases - each release candidate is dated to match its equivalent Mastodon version state.

• Migrate to Mastodon v4.6.0-alpha.3-2026-01-24 file-based theme system (Fixes #177, Ref: mastodon/mastodon#37477)
• Replace data-user-theme and body.theme-* selectors with :root, html[data-color-scheme], html[data-contrast]
  (mastodon/mastodon#37523)
• Add v4.6.0 semantic token overrides for light theme
• Fix missing search icon

4.0.0-alpha.0-3

4.0.0-alpha.0-3: 2026-01-11

Note

WIP Notice: This is a heavily work-in-progress upcoming version of Mastodon Bird UI. This version is part of the ongoing major rewrite (see issue #172) and isn't yet fully modularized. It's functional with the latest mainline version, though.
💀 Compatibility: Mastodon v4.6.0-alpha.1-2026-01-11 (nightly from Mastodon main after 2026-01-11)

This version will not support older Mastodon versions. For older Mastodon servers, use previous Mastodon Bird UI versions designed for those releases - each release candidate is dated to match its equivalent Mastodon version state.

• Remove dead code: fade in list panels no longer functional
• Remove CSS properties and icons that are no longer in use since Mastodon 4.2 (replaced by buttons and drop downs, deprecated in older versions, etc.): --icon-share-detailed-status-action-bar, --color-light-fuchsia-pink, --icon-follow-hashtag', --icon-unfollow-hashtag, --icon-star, --icon-share, _--compose-form-linear-gradient. --active-header-box-shadow, --icon-users-column-link, --icon-plus-red, --icon-cross-green, --icon-cog, --icon-genderless-pronouns, --icon-verified`
• Make dev mode authentic by using only data-user-theme attribute instead of artificial .mastodon-bird-ui class
• BrowserSync conf improvements
• Split legacy/ to base.scss and start modularization work
• Add layouts/_advanced-web-interface.scss
• Upgrade stylelint to v16
• Add stylelint-value-no-unknown-custom-properties to detect undefined CSS custom properties
• Add custom plugin/no-unused-custom-properties to detect unused CSS custom properties
• Fix accessible theme background not applying due to nested body selector losing specificity
• Fix hide-finnish and hide-translate-links variant selectors to match updated Mastodon HTML structure
• Add --color-text-brand override for all themes to use Bird UI accent colors
• Fix .compose-form__warning styles
• Fix issue with image margin in compose form media item
• Move all body.embed rules outside main selector with @at-root
• Advanced web interface: Slimmer drawer selections in 4.6.0+
• Release install-to-mastodon.sh workflow
• Fix styles leaking to admin
• Improve install script, add y/n for variations and default theme
• Fix install script breaking existing Mastodon installations by auto-detecting update vs new install mode
• Add --no-optimize to Parcel so Custom CSS users can have unminified CSS
• Further improve workflow for indexes that both MastoAdmin install script and the SCSS structure use
• Fix styles for .button--plain
• Support Wrapstodon
• Migrate accessible themes as part of mastodon-bird-ui instead of just README.md snippets
• Fix video under text layer while scrolling, Fixes #173
• Fix npm run: browsersync scripts

4.0.0rc1

4.0.0rc1: 2025-11-09

Note

WIP Notice: This is a heavily work in progress, upcoming version of Mastodon Bird UI.
💀 Compatibility: Mastodon 4.6.0-alpha.1-2025-11-09 (nightly from main after 2025-11-092)

This version will not support Mastodon versions prior v4.5.0 / 2025-11-08! For older Mastodon servers, use older Mastodon Bird UI versions that support older Mastodon versions, each rc version is dated to their own equivalent version state.

• Fix .announcements__root background-color in v4.6.0-alpha.1+2025-11-09

3.0.0

3.0.0: 2025-11-07

Note

⚠️ Compatibility: This release supports v.4.5.0 and v4.6.0-alpha.0 (2025-11-07)

This version will not support Mastodon versions prior v4.5.0! (2025-11-06) For older Mastodon servers, use older Mastodon Bird UI versions that support older Mastodon versions, each tag and rc version is dated to their own equivalent version state.

Mastodon v4.5.0 release documentation

• Bump version for Mastodon v4.5.0 stable
• Fix profile links and alignments in v4.5.0-beta.2-2025-10-22
• Fix double bell icon and other profile icons in v4.5.0-beta.2-2025-10-22
• Fix misaligned popper for Quote Posts
• Fix quote author button misalignment in v4.4.4 and v4.5.0-alpha.2
• Fix disabled quote post button in v4.4.4 and v4.5.0-alpha.2
• Improve status__quote--error being to high, update min-height
• Fix min-height for default quote status that is not unavailable
• Fix quoted status inside a notification
• Fix disabled styles quote poost selection that is disabled
• Improved UI for the new quote posts popper
• Add more extensive styles for the upcoming Quote Posts feature, requires 4.5.0-alpha.2-2025-08-24 or later with EXPERIMENTAL_FEATURES=inbound_quotes,outgoing_quotes flag enabled
• Remove the separator dot redundant since 4.3
• 4.5.0-alpha.2: Fix margin for quote posts that have media inside of them
• Fix performance-expensive transitions
• Fix audio embed overflow, Fixes #167
• Improve modal accessibility, update background color
• Reset margin under logo, fixed in 4.5.0-alpha.1

2.3.4rc8

2.3.4rc8: 2025-10-22

Note

WIP Notice: This is a heavily work in progress, upcoming version of Mastodon Bird UI.
💀 Compatibility: Mastodon 4.5.0-beta.2-2025-10-22 (nightly from main after 2025-10-22)

This version will not support Mastodon versions prior v4.5.0-beta.2 / 2025-10-22! For older Mastodon servers, use older Mastodon Bird UI versions that support older Mastodon versions, each rc version is dated to their own equivalent version state.

• Fix profile links and alignments in v4.5.0-beta.2-2025-10-22
• Fix double bell icon and other profile icons in v4.5.0-beta.2-2025-10-22

2.3.4rc6

2.3.4rc6: 2025-08-30

Note

WIP Notice: This is a heavily work in progress, upcoming version of Mastodon Bird UI.
💀 Compatibility: Mastodon 4.5.0-alpha.2-2025-08-30 (nightly from main after 2025-08-30)

This version will not support Mastodon versions prior v4.5.0-alpha.2! For older Mastodon servers, use older Mastodon Bird UI versions that support older Mastodon versions, each rc version is dated to their own equivalent version state.

• Fix min-height for default quote status that is not unavailable
• Fix quoted status inside a notification
• Fix disabled styles quote poost selection that is disabled
• Improved UI for the new quote posts popper

2.3.4rc5: 2025-08-25

2.3.4rc5: 2025-08-25

Note

WIP Notice: This is a heavily work in progress, upcoming version of Mastodon Bird UI.
💀 Compatibility: Mastodon 4.5.0-alpha.2-2025-08-24 (nightly from main after 2025-08-24)

This version will not support Mastodon versions prior v4.5.0-alpha.2! For older Mastodon servers, use older Mastodon Bird UI versions that support older Mastodon versions, each rc version is dated to their own equivalent version state.

• Add more extensive styles for the upcoming Quote Posts feature, requires 4.5.0-alpha.2-2025-08-24 or later with EXPERIMENTAL_FEATURES=inbound_quotes,outgoing_quotes flag enabled
• Remove the separator dot redundant since 4.3