[docs] Fix broken link & update MUI packages explanation

[siriwatknp]

close #29493

Preview: https://deploy-preview-29583--material-ui.netlify.app/guides/understand-mui-packages/#main-content

• I have followed (at least) the PR section of the contributing guide.

[mui-pr-bot]

No bundle size changes

Generated by 🚫 dangerJS against 7d56777

[mbrookes]

styled-engine is the (unfortunate) name for the style library wrapper / adapter package, but there's no such thing as a "styled-engine" as a generic term. Should we stick to something like "style library adapter" when not referring to the styled-engine package specifically? It's quite confusing otherwise.

[mnajdova]

Should we stick to something like "style library adapter" when not referring to the styled-engine package specifically? It's quite confusing otherwise.

"style library adapter" sounds good to me.

[oliviertassinari]

styled-engine is the (unfortunate) name for the style library wrapper / adapter package, but there's no such thing as a "styled-engine" as a generic term.

@mbrookes We can agree not to agree (an nth time). When I read "styled-engine-sc" I think: "oh, styled-components is the engine that powers the styled() API". What name would you use?

Tl;dr

Is this capitalization correct? I'm used to seeing TL;DR with uppercases because it's an acyronms.

Other packages, such as @mui/utils and @mui/types, are used internally in the packages listed above.

This is not how we have been treating them so far. The private modules in utils are prefixed with unstable_. We put in these packages what we might need to share between @mui/base and @mui/system/@mui/styled-engine.

core -> base

there is no need to install @mui/core because it is a built in dependency the design system package, @mui/material.

This can be controversial. Yarn 2 doesn't even allow implicit transitive dependency. There is eslint rule that warns against them: https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-extraneous-dependencies.md. I think that it would be wiser not to say anything.

[siriwatknp]

Is this capitalization correct?

changed to TL;DR

This is not how we have been treating them so far

content removed.

core -> base

image updated.

This can be controversial

content removed.

[mnajdova]

LGTM

[oliviertassinari]

Are we sure about the size of the images?

For example, /static/images/packages/mui-packages.png displays blurry on my x2 screen. Its displayed size is 448px so I would assume that we can use an image with an intrinsic size of 896px (x2). It's currently 1381px. Same for docs/public/static/images/packages/mui-system.png. It definitely makes a visible difference in my screen display environment, but I don't know if it would also help developers with an x1 display.

BTW, I have purchased the latest MackBook Pro, only for the XDR display, so I can be pickier in the future with visual aesthetics 👼. Looks good otherwise

[siriwatknp]

Are we sure about the size of the images?

For example, /static/images/packages/mui-packages.png displays blurry on my x2 screen. Its displayed size is 448px so I would assume that we can use an image with an intrinsic size of 896px (x2). It's currently 1381px. Same for docs/public/static/images/packages/mui-system.png. It definitely makes a visible difference in my screen display environment, but I don't know if it would also help developers with an x1 display.

BTW, I have purchased the latest MackBook Pro, only for the XDR display, so I can be pickier in the future with visual aesthetics 👼. Looks good otherwise

The size looks correct to me, 1381px is more than 896px so wouldn't it give a similar result.

I can open a fix later.

[danilo-leal]

so I can be pickier in the future with visual aesthetics 👼.

👀 👀 👀 fancy!

[oliviertassinari]

1381px is more than 896px so wouldn't it give a similar result.

@siriwatknp Yeah, I don't know if this only helps people like me on macOS hardware or Windows developers with regular screens too. In the case of Apple, the CSS pixel is 448, so it uses 896 real pixels. Now, if the image is also 896 pixels, then the OS doesn't need to resize it 👌. With a larger image size, the OS has to resize it, the text loses its crispness, it becomes fuzzy, harder to read.

At the end of the day, does it make a difference? For macOS users, with x2 resolution, I can notice for sure, it looks easier to read. For Windows users, maybe it doesn't matter; I have no idea, I suspect it doesn't matter, unless 2px -> 1px yields better resize results than 2.3px -> 1px for the algorithms used. I could test that with my girlfriend's laptop.