4.0.0

4.0.0: 2026-06-19

Note

🎉 This is the first stable release of the major Mastodon Bird UI rewrite #172. The old monolithic CSS file is now splitted to tinier, focused module files, themes use Mastodon's file-based theme system, and the design tokens track upstream.
💀 Compatibility: Mastodon 4.6.0 stable and 4.7.0-alpha.1 (built from mastodon/main)

For older Mastodon servers (pre-4.6.0), use an earlier dated release.

After a long run of alphas and betas, the Bird UI rewrite lands as stable. 4.0.0 is built for Mastodon 4.6.0 stable (and forward-compatible with 4.7.0-alpha.1), ships the new modular SCSS architecture, styles everything Mastodon changed during the 4.6 cycle (the new profile structure, the account_header/tab_list module classes, and the Collections feature), and adds first-class support for forks that ship their own native favourite animation.

Highlights

• Stable rewrite (#172). _base.scss split into ~40 module files; themes migrated to Mastodon's file-based theme system; design tokens aligned with upstream's 4.6.0 semantic tokens.
• One auto theme. mastodon-bird-ui-auto responds to data-color-scheme and prefers-color-scheme, replacing the separate Dark/Light/Contrast entries (driven by Mastodon's Appearance radios).
• Mastodon 4.6.0 stable + 4.7.0-alpha.1 support, including Collections and the rebuilt profile page.
• Native favourite animation support for forks. If the target Mastodon ships its own favourite star/heart SVG (see mementomori-social/mastodon#10, the install script detects it and Bird UI steps aside for the favourite button while keeping its navigation and sidebar/notification icons.
• Long-standing fixes. Closes #188 and #175, plus #187, #185, #184, #182, #181, #178, #149.

What changed

The rewrite (#172)

• Modularized the old base CSS into tinier focused component/layout/variable partials.
• Migrated to Mastodon's file-based theme system (:root, html[data-color-scheme], html[data-contrast]), no more data-user-theme / body.theme-* selectors.
• Updated theme tokens to the latest upstream design-system tokens.
• Added a stylelint plugin to catch unused custom properties, and tightened linting.

Mastodon 4.6.0 / 4.7.0-alpha.1 compatibility

• Adapted profile styles to the new _comp_account_header__* and _comp_tab_list__* module classes (upstream renames in mastodon/mastodon#38863, mastodon/mastodon#38920): avatar size, badges, tabs, name, handle help, familiar followers.
• Styled the new Collections feature: side-nav icon, account-list badges ("Follows you", verified link), flush badge spacing.
• Rebuilt support for the new profile page structure (#183).
• Updated the install script for upstream's common.scss removal and theme-system changes (mastodon/mastodon#37612, mastodon/mastodon#37477, mastodon/mastodon#37523).

Native favourite animation support (forks)

• The install script detects a native favourite component (app/javascript/mastodon/components/favourite_star.tsx) in the target Mastodon.
• When found, Bird UI's own favourite styling (_heart.scss / _star.scss) is replaced by a small fallback that only re-shows the native SVG and themes the sidebar/notification favourite icons, so the fork's native star/heart burst shows instead of Bird UI's sprite.
• The navigation/layout that used to be bundled inside _heart.scss was moved to its own always-loaded module, so dropping the favourite styling never breaks the layout.

Fixes

• Closes #188: dropdown menu background no longer breaks under the Bird UI theme.
• Closes #175: pop-out (picture-in-picture) video player can be closed again (z-index fixed).
• Closes #187: main navigation items no longer render side by side after upstream wrapped them in list items.
• Closes #185: duplicate profile buttons after upstream class change.
• Closes #184: theme tokens updated to the latest design system.
• Closes #181: consistent private-mention styles between conversations and notifications.
• Closes #178: PostCSS complex-selector warning in mobile sign-out CSS.
• Closes #149: star icon alignment with reduce-motion; sparkle pseudo-element animations ungated.

Impact by install method

Custom CSS users (paste CSS into Mastodon admin)

The compiled dist/mastodon-bird-ui.css ships updated. Re-paste it into Settings → Administration → Appearance → Custom CSS after upgrading your Mastodon server to 4.6.0 stable (or a 4.7.0-alpha.1 build).

Mastodon admins running install-to-mastodon.sh

git pull the Bird UI clone, re-run sudo bash scripts/install-to-mastodon.sh --path /path/to/mastodon, then recompile assets and restart. The script rebuilds themes.yml and locale entries, and now auto-detects a native favourite animation in the target.

Full changelog (3.0.0 to 4.0.0)

4.0.0: 2026-06-19

• Compatible with Mastodon 4.6.0 stable and 4.7.0-alpha.1
• Indent the collection preview card in feeds so it aligns with the status content (full width in single posts)
• Fix the heart favourite burst alignment in the single post view
• Fix the white, unreadable native select options dropdown on settings pages (#188)
• Detect a native favourite animation and leave the favourite button alone so the fork's own star/heart shows (mementomori-social/mastodon#10)
• Hide the native search clear glyph so only the Bird UI X shows, not a second white one
• Remove the border from the stuck mobile profile buttons bar
• Raise account timeline filters above the profile header
• Raise visible status text above the display name so the first row stays clickable
• Use the solid secondary background for the avatar follow badge hover
• Cap dropdown menus to the viewport height and make them scrollable on short or zoomed screens
• Add z-index to status display name so the avatar follow badge stays clickable
• Drop trends to 2 items on screen heights below 830px (4 items fit above that)
• Remove the trends section top margin
• Make the navigation menu scrollbar minimal (Firefox thin, WebKit 4px) to match the Bird UI aesthetic
• Compact the navigation items (font-size 17px, gap 7px) on screen heights below 1080px
• Compatible with Mastodon 4.6.0 stable and 4.7.0-alpha.1
• Indent the collection preview card in feeds so it aligns with the status content (full width in single posts)
• Fix the heart favourite burst alignment in the single post view
• Fix the white, unreadable native select options dropdown on settings pages (#188)
• Detect a native favourite animation and leave the favourite button alone so the fork's own star/heart shows (mementomori-social/mastodon#10)
• Hide the native search clear glyph so only the Bird UI X shows, not a second white one
• Remove the border from the stuck mobile profile buttons bar
• Raise account timeline filters above the profile header
• Raise visible status text above the display name so the first row stays clickable
• Use the solid secondary background for the avatar follow badge hover
• Cap dropdown menus to the viewport height and make them scrollable on short or zoomed screens
• Add z-index to status display name so the avatar follow badge stays clickable
• Drop trends to 2 items on screen heights below 830px (4 items fit above that)
• Remove the trends section top margin
• Make the navigation menu scrollbar minimal (Firefox thin, WebKit 4px) to match the Bird UI aesthetic
• Compact the navigation items (font-size 17px, gap 7px) on screen heights below 1080px
• Tighten badge spacing in account list items (override core padding on all badges, nudge Follows you down)
• Style the verified link badge in account list items (e.g. collections) the same as profile field verified links
• Style the Follows you badge in account list items (e.g. collections) the same as in profiles
• Show the Collections nav icon (was hidden by the column-link icon path reset)
• Move Notifications to the second slot in the navigation menu
• Remove border-bottom from the trends heading
• Hide the follows-you badge icon and nudge the badge with transform translate(-1px, 1px) for alignment
• Scope the larger 133.5px profile avatar to viewports 760px and up so mobile keeps the smaller size
• Restore navigation menu order after upstream wrapped items in list elements: Lists and Followed tags sit at the bottom with More last
• Adapt profile styles to the new account_header module classes and restore avatar size, badge spacing, and bar layout after upstream removed the old classes in #38920
• Update profile tabs, name, avatar wrapper, badges, handle help, and familiar followers selectors to the new _comp_account_header__* and _comp_tab_list__* module classes (upstream rename in #38863)
• Restore even profile tab distribution at all viewport widths
• Add explicit margin-bottom: 16px on familiar followers under the new module class so spacing stays consistent when no role badges are rendered
• Override object-fit to cover on video previews when a content warning placeholder is shown, so portrait videos no longer letterbox the spoiler image
• Fix main navigation items appearing side by side after upstream wrapped them in list items, Closes #187
• Hide the navigation list-item separators that replaced the old hr elements
• Reduce navigation panel right padding to 10px so long menu labels fit better
• Add mastodon-bird-ui-auto theme that responds to data-color-scheme and prefers-color-scheme, ref #182
• Drop redundant Dark, Light, and Contrast theme entries (the auto bundle covers them via Mastodon's Appearance radios), ref #182
• Stop generating stars, hide-finnish, hide-translate-links, and combination theme entries (toggleable on forks or via Custom CSS)
• Rename vanilla Mastodon theme label to "Mastodon" (key unchanged for back-compat)
• Refactor :is() in mobile sign-out CSS to comma list to silence PostCSS Complex selectors warning, Closes #178
• Fix star icon alignment with reduce-motion and ungate sparkle pseudo-element animations, Closes #149
• Users on removed themes fall back to default Mastodon Bird UI auto without crashing
• 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
• 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
• Fix trends item name layout for new structure
• Remove border from profile edit avatar
• Migrate to Mastodon v4.6.0-alpha.3-2026-01-24 file-based theme system ([#177](#177), [mastodon#37477](mastodon/mastodon#37477))
• Replace data-user-theme and body.theme-* selectors with :root, html[data-color-scheme], html[data-contrast] ([mastodon#37523](mastodon/mastodon#37523))
• Add v4.6.0 semantic token overrides for light theme
• 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
• Revert and rewrite over-engineered modularization
• Components override for Mastodon v4.6.0+, disable top border/padding for tabs-bar wrapper
• Fixes to placeholder styles
• Add npm run dev:mementomods to test styles against mementomori.social
• Add npm run dev:mastodon to test against mastodon.social
• Start proper modularization based on Mastodon core
• Add unified mastodon-bird-ui.scss entry point for both layouts
• Rename _multiple-columns-styles.scss to _advanced-web-interface.scss
• Add build:custom-css and build:mastodon-core npm scripts
• Add theme variants: accessible, accessible-plus, stars, hide-finnish, hide-translate-links
• Add scripts/install-to-mastodon.sh for Mastodon core installation
• Migrate to Mastodon v4.6.0+ semantic token system
• Create src/common/theme/ with _base.scss, _dark.scss, _light.scss, _utils.scss
• Replace old custom CSS variables with Mastodon semantic tokens throughout codebase
• Add support for prefers-color-scheme system theme preference
• Add support for high contrast mode overrides
• Fix unwanted border-top on .tabs-bar__wrapper introduced in Mastodon v4.6.0
• Update stylelint config for SCSS support
• Add scss/comment-no-loud rule to enforce SCSS-style comments
• Convert all CSS comments to SCSS comments
• Add lint:watch to dev workflow for real-time linting
• Update GitHub workflow to use npm scripts and build process
• Split CSS custom properties into modular files
• Fixes to heart position
• Update README.md installation instructions for unified build output
• Add Parcel bundler for SCSS compilation
• Add Browsersync for live development with CSS hot-reloading
• Add npm scripts for development workflow (npm run dev, npm run build)
• Add automatic version banner injection from package.json to built CSS
• Migrate from plain CSS to modular SCSS with @use imports
• Create src/ directory structure with organized partials:
  • src/common/ - Variables, themes (dark, light, high-contrast)
  • src/components/ - UI components (buttons, cards, navigation, status, etc.)
  • src/layouts/ - Layout-specific styles (multiple columns)
• Extract CSS custom properties into dedicated _variables.scss
• Maintain single-file CSS output in dist/ for backward compatibility
• Fix .announcements__root background-color in v4.6.0-alpha.1+2025-11-09