Skip to content

docs: replace FAB and Switch screenshots with live interactive examples - #5069

Open
hristototov wants to merge 2 commits into
mainfrom
hristototov/revisit-docs
Open

docs: replace FAB and Switch screenshots with live interactive examples#5069
hristototov wants to merge 2 commits into
mainfrom
hristototov/revisit-docs

Conversation

@hristototov

Copy link
Copy Markdown
Collaborator

Motivation

Parts of the documentation have drifted out of sync with the v6 modernisation effort. The FAB and Switch pages were still illustrated with screenshots captured before those components were reworked for the latest Material Design 3 spec, so they showed outdated naming and token references:

  • FAB had an "all modes" screenshot tab, but the component no longer has a mode prop — it's variant (six role-color presets) and size (three spec sizes) now.
  • Switch was documented with a four-way Android (enabled/disabled) / iOS (enabled/disabled) screenshot split, which no longer reflects reality: the modernised component renders the same MD3 visuals on both platforms.

Static images also can't show what these components actually do - the Switch handle animation, the Extended FAB expand/collapse transition - and they silently rot every time a component changes.

This PR drops those screenshots and inlines the real components instead, so the docs render live from

Related issue

Closes #4991

Implementation notes

A general mechanism rather than a one-off, so the remaining outdated pages can follow:

  • docs/src/data/liveExamples.ts - new registry mapping a component title to the example module and named exports to render. Adding an entry here automatically removes that component's screenshot tabs, so a component is documented either with screenshots or with live examples, never both. The invariant is enforced in one place in generatePageMDX.ts.
  • docs/src/components/InteractiveExample.tsx - shared shell for embedded demos. Paper components reach browser APIs through react-native-web, so the tree mounts client-only behind BrowserOnly with a same-sized placeholder during SSR to avoid layout shift, and the Paper theme is kept in sync with the active docs color mode. Follows the existing pattern in BannerExample.tsx.
  • FABExample.tsx / SwitchExample.tsx - the actual demos. The FAB variant and size lists mirror the Variant and Size unions in src/components/FAB/tokens.ts in order, so a spec change surfaces as a type error rather than a stale image.

Also includes one small runtime fix surfaced while building the demos: Switch's absoluteFill style was missing alignItems / justifyContent, so the unselected icon which is smaller than the SELECTED_ICON-sized iconWrap it sits in - was pinned to the top-left instead of centered. Snapshots updated accordingly.

Images

switch-after switch-before fab-after fab-before fab-extended-after fab-extended-before

@hristototov hristototov self-assigned this Aug 24, 2026
@hristototov hristototov changed the title Hristototov/revisit docs docs: revisit documentation structure and organization Aug 24, 2026
@hristototov hristototov changed the title docs: revisit documentation structure and organization docs: replace FAB and Switch screenshots with live interactive examples Aug 24, 2026
@hristototov
hristototov requested a review from satya164 August 24, 2026 12:02

@JKobrynski JKobrynski left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: revisit the documentation and update outdated sections

2 participants