material-ui
material-ui copied to clipboard
mui
[website] Add Toolpad to products' showcase
- [x] I have followed (at least) the PR section of the contributing guide.
Closes https://github.com/mui/mui-toolpad/issues/2396
Preview: https://deploy-preview-38604--material-ui.netlify.app/
Netlify deploy preview
https://deploy-preview-38604--material-ui.netlify.app/
Bundle size report
No bundle size changes (Toolpad) No bundle size changes
Generated by :no_entry_sign: dangerJS against e7654a1bd3c3db05aa77a42bba19cc61a7e3a5f6
Quick feedback:
- The design doesn't work on my screen 14" sceeen, I need to scroll down to click on Toolpad
but then it's truncated.
- I don't feel the section gives clarity to visitors about what Toolpad is about. I think showing the low-code editor in action could be one way to make it clear.
Nice one! I had quickly experimented with adding Toolpad before when y'all opened the issue and anticipated Olivier's point 1 there. Looking at it again, this might be the opportunity to remove the Design kits + Templates from there (as something on the same level as Core & X) and add them as sections within the Material UI page (and later on, similar ones for Joy UI). That way, we gain way more space for the products that sit at the same level, and therefore, Toolpad!
I can make this one in parallel ⎯ @oliviertassinari; we discussed doing this in the past, but I just want to reiterate and see we're still on the same page.
About point 2, yeah,I think that at least a video would be great. A static image doesn't communicate much...
-
his might be the opportunity to remove the Design kits + Templates from there (as something on the same level as Core & X) and add them as sections within the Material UI page (and later on, similar ones for Joy UI).
It makes sense.
Base UI could likely benefit from templates as well. We don't have any, but we might in the future.
- https://retool.com/ like could maybe work better
https://github.com/mui/material-ui/assets/3165635/a705bced-339b-4127-bb5c-9b779b6631b6
Bringing this PR back into the discussion:
-
With Templates and design kit now inside the Material UI page, can we accommodate Toolpad here? Also, will it be just Core, X and Toolpad? With the recent introduction of new products on core side, is there something additional that we want to showcase here?
-
With the introduction of Toolpad core, we should not show a drag and drop UI, instead a finished admin panel and the use of data providers in code. I'll check this part.
With Templates and design kit now inside the Material UI page, can we accommodate Toolpad here? Also, will it be just Core, X and Toolapd? With the recent introduction of new products on core side, is there something additional that we want to showcase here
I want to remove "MUI Core" at some point and replace it with everything inside this conceptual umbrella: Material UI, Base UI, Pigment CSS, and possibly Joy UI (to be defined after we scope out v7). We'll probably need to redesign this section a bit to pull that off. However, I'm visualizing a more holistic website redesign this year to go alongside the brand stuff we're carrying out with the consultancy. That's why I'm not necessarily pushing to do that immediately.
In any case, for now, if we want to add Toolpad there, I'd potentially drop Templates and Design kits and replace them with a Store item, which encapsulates both of them (at least for now). That'd keep us with a four-item section, which fits well with the current design. Hope this perspective helps!
potentially drop Templates and Design kits and replace them with a Store item, which encapsulates both of them (at least for now).
Great! This will help. Thanks. We'll work on the Toolpad core landing page changes, screenshot, and code snippet in the coming weeks. We can close it then, for now, the perspective helps 🤝
@danilo-leal We're looking to get this done inside the Toolpad team, and I noted your suggestion of a common entry for the Design Kits and Templates. Does it still make sense to do this? I'm asking because we wouldn't be able to link to https://mui.com/templates/ from this section anymore (we would instead link to the Store) and would need to create a new combined design asset
Does it still make sense to do this?
I think so, yes! Is there any concern regarding swapping out the Design Kits/Templates item for a Store item? How does this impact Toolpad specifically?
I'm asking because we wouldn't be able to link to https://mui.com/templates/ from this section anymore (we would instead link to the Store) and would need to create a new combined design asset
How does this impact Toolpad specifically?
The question in my mind is essentially, what do we put in these red boxes for the combined store item and who comes up with them:
Ah, gotcha. No need to worry about it; I'll take on the design. I'll add commits soon to the PR if that's the case.
@bharatkashyap & @prakhargupta1, in terms of design, I feel like this PR is ready to go! But we could potentially discuss content and whether what we're displaying on the Toolpad section is what's most relevant for visitors to learn about Toolpad, as we briefly discussed above months ago 😅
@bharatkashyap & @prakhargupta1, in terms of design, I feel like this PR is ready to go! But we could potentially discuss content and whether what we're displaying on the Toolpad section is what's most relevant for visitors to learn about Toolpad, as we briefly discussed above months ago 😅
@danilo-leal thanks for your work on this one! We discussed this PR in our weekly and felt like we could quickly experiment with a couple of options: either removing the code altogether since it can seem a bit out of context with the image, or add a path to supply more context. I'll add a couple screenshots on the thread and ask for feedback
Option 1
- Add path to the code file to provide some context on how the code connects with the UI
https://github.com/mui/material-ui/assets/19550456/109e535b-d6bc-4822-b8ac-2dca827dd606
Option 2
- Add a larger image and remove the code
Option 1 looks much better to me, but the code is still a bit obscure. Like it's clear we're fetching users from Prisma and whatnot, but maybe adding comments will help contextualize what it is actually doing in terms of feeding the Toolpad interface? Also, a bit of a design nit, it'd be cool to have a dark mode screenshot so we can use that when the website is also in dark mode.
I think if we want to show code, we need to clearly show the connection it has with the UI. Otherwise I think it will only confuse the audience. IMO we're better off showing no code if we don't show it in function of the UI. I think for users the most important thing to to understand about Toolpad is that the single source of truth for the UI is a simple file that updates as they drag things around in the designer. Secondary thing to show is that we intend to integrate that seamlessly with your existing code, both on the frontend and on the backend.
Some mock up videos of what I would love to see:
Show the connection between building UI and the underlying configuration on disk:
https://github.com/mui/material-ui/assets/2109932/ec00fa2a-fbd5-4504-992b-d45e7d21d8ab
Show how you can customize realtime the React components that you include in the page:
https://github.com/mui/material-ui/assets/2109932/fc94ebc1-5864-4815-a18c-042cbac9f6aa
Show how you can load data from by just calling your own backend code:
https://github.com/mui/material-ui/assets/2109932/d5baa1a0-855b-4706-acc7-f44a6b4b8f72
to be clear, I'm not proposing to use these exact videos. just illustrating that if we show code it must be relevant to the what's happening in the visual designer.
I prefer the third video the most as it shows data grid (the most powerful component) and usage of a backend function. My only concern is that a video in this section may not go very well, I would suggest speeding it up and putting it as a <10 sec autoplay gif.
Not sure I'd go for a video—maybe a GIF would be better, so it's much, much faster. And totally agree with the code needing to be meaningful to the illustration. I'd potentially consider picking the most common use case?
@bharatkashyap uhm... I'm not loving the GIF 😬 😅 It renders somewhat slowly for me, and the ScreenStudio zoom in and out can be a bit dizzying in this tight space.
Maybe resorting back to an image + code block is better and more consistent, but we experiment with working the image out a bit more. Can you send me some screenshots of the Toolpad UI we show on the GIF? I want to do a magnifying glass zoom sort of thing in the Data Provider select, assuming that, that zoomed in with the code, visitors would be able to parse that it's a product where you can connect a data source to a custom UI that you've built right there.
@bharatkashyap uhm... I'm not loving the GIF 😬 😅 It renders somewhat slowly for me, and the ScreenStudio zoom in and out can be a bit dizzying in this tight space.
@danilo-leal Fair enough; the slow first load was the best compromise between quality and file size I could reach with the GIF; about the motion blurring and zooms, those are definitely fixable and can be reduced.
I like the GIF because it's able to represent what the product does more than what an image could, and for that reason the Toolpad team was internally on board to let the slow first load pass as an acceptable compromise. Regardless, I'll share the images you wanted to see what alternatives could like.
Proposing another option here from the backlog grooming session: we add some hotspots to the screenshot. Each has a popover with a short explanation, and clicking them reveals a code snippet below. this ties the snippets closer with the screenshot, and adds context.
example screenshot made from the existing one, the real one needs a custom component instead of the form
-
Hotspot on the hierarchy explorer. Here we show a snippet of the yaml file that makes up this page. We highlight the local nature of the tool:
Popover: Your application configuration is stored locally in yaml files. Changes in the visual editor are synced to the files, and vice versa. You can version control them however you want.
-
Hotspot on the datagrid rows. Here we show a snippet of a simple data provider backend module that calls a prisma ORM. We highlight the tight integration with server:
Popover: You can write serverless functions that have access to your project code. Use your own ORM, database connections, serverside secrets. Toolpad will handle linking your data with UI components.
-
Hotspot on a custom component. Here we show a snippet of a simple custom component with a editable property. Here we highlight the tight integration with frontend.
Popover: Bring your own react components, compose them with drag&drop in the canvas. Define properties you can edit visually in Toolpad Studio.
Unless I'm missing something, I think technically we can build this with the tabs already we have. Only we overlay some buttons with popovers on the image that can also switch tabs.
Pushed a commit where I quickly iterated on the new changes. Overall, I’m not fully loving it yet for two main reasons:
- It is generally too busy— too much information and interactions here. The pulsating buttons can be a bit distracting, and there’s too much text in each popover.
- I don’t love that as you click on the Toolpad item in the Products section, a popover opens and locks my scrolling. I need to give an extra click or tap to solve that.
So, I'd probably go with a simpler approach that also allows us to display multiple Toolpad features:
- Each tab would also change the code snippet, normally, the same as clicking around the popover does now.
- We could add a paragraph (smaller and not in a popover) to contextualize/explain the code/feature. But this may not be fully needed, though, as we'd have the tab button label, which might be enough.
- Image-wise, to piggy-back on what I said in my previous comment (https://github.com/mui/material-ui/pull/38604#issuecomment-2125713646), we can edit the image to be something similar to this to highlight the piece of Toolpad's UI that resonates with the feature name and code.
What I like about this approach is that we can have more custom-tailored images, making it more interesting, and the visitor is more free to interact. It's also more consistent with the tab approach that we're using in these showcase sections. What do you all think?
- What's good with the hotspots is the additional context it provides through the pop-over text, but it makes it cluttered given its already a tight space.
- What's good with the tabs design is that it's consistent with MUI Core tabs.
We could add a paragraph (smaller and not in a popover) to contextualize/explain the code/feature. But this may not be fully needed, though, as we'd have the tab button label, which might be enough.
I think, just the tabs button label might not be able to fully explain the concept and doing this through a paragraph+magnifier on image will make it even more complex/cluttered.
Also, we may change this section in the future to showcase Toolpad core and that's where the tabs design will fit well. So, I would suggest we keep it simple and go ahead with what Danilo suggested. 👍
I think, just the tabs button label might not be able to fully explain the concept
Thought of highlighting this part just because I feel like it's okay not to fully explain things here! 😬 There's an argument to be made that this whole section (not just the Toolpad "tab") can be even simpler. The goal really is just a high-level presentation of the products, showcasing one or two cool things about them to prompt the visitor to check it out in more detail somewhere else—be it on its dedicated landing page or already within its docs.
It is generally too busy— too much information and interactions here. The pulsating buttons can be a bit distracting, and there’s too much text in each popover. I don’t love that as you click on the Toolpad item in the Products section, a popover opens and locks my scrolling. I need to give an extra click or tap to solve that.
Agreed on both, but not sold on the alternative. The big problem is that there is no connection between the screenshot and the code. I still believe that if we don't somehow make this relation visible, the whole is more confusing that showing the screenshot without code. We would be better off just showing a screenshot.
In the core example, when you hover over certain parts of the UI, the relevant code highlights. I want to create a similar effect, but for the Toolpad, so that the relation between code and output is visible. How about:
- we remove the animation of the screenshot indicators.
- we don't show popovers, instead we add a comment at the top of the code file. We shorten the text.
- hovering the circle displays the corresponding code tab. We add an "active" state to the circles so that it's clear which one the current tab belongs to.
- clicking the tabs does the opposite, setting the active state of the corresponding circle. Essentially, the circles act as a tab header.
it's okay not to fully explain things here!
Absolutely, and we shouldn't, but whatever we show, it must be coherent. The screenshot + code without any context about how they relate is just confusing.
I was thinking we could be much simpler than this, and the screenshot <> code relation could be done purely by highlighting, in the image, what the code is touching on—something like:
This feels much better than just a screenshot of the entire UI, where I don't know where to focus my eyes. This is the problem we were trying to solve with the pulsating buttons! Still, we could then add a small, two-line sentence to contextualize the image to code even more if that feels really needed. Overall, I'd avoid relying on more interactions to understand the concept (at a high level). The Material tab works well without the interactions; they're purely icing on the top of the cake. Similarly to the Data Grid example.
I was thinking we could be much simpler than this, and the screenshot <> code relation could be done purely by highlighting, in the image, what the code is touching on—something like
For my understanding, are you proposing to have the image change in sync with the code tab? And to have a highlight on the image that relates to the code?
Each tab would present a different image and code snippet, and the images instead would have this magnifying glass thingy built-in (it wouldn't be something that appears based on an interaction). We could have something highlighting the code, yeah, but I was thinking the entire code snippet we showcase there should be relevant to the highlighted part of the app's UI. Does this make sense?
Does this make sense?
Yes, we're aligned. It's exactly what I'd want, just with the right design-sauce over it 🙂.
Okay—just pushed the structure/design for the tabs approach! Let me know (feel free to send it over via Slack) the images we want to use in each tab panel (if possible, it'd be great to have one for light and dark mode, as opposed to just a light one), and in what part of it I should add the magnifying thingy on. Also, feel free to change the code snippets and tab names! 👍 Getting finally closer to wrapping this PR up!