-
-
Notifications
You must be signed in to change notification settings - Fork 353
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Toolkit] Introduce the UX Toolkit ✨ #2539
base: 2.x
Are you sure you want to change the base?
Conversation
Let's get to work! 👏 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
First comments on "form" only, just to warn early about some details
Wow, that's a awesome PR! 👏 |
I really like the component idea, but is there any particular reason to store components source code in a json file rather than going through stubs files? I'm afraid it's going to be hard to maintain because you'll have to remember to explicitly include line breaks, indentation and proper escaping! Wouldn't it be better to have the code directly in Unless json are automatically generated 🤔? |
@ker0x yes, all JSON files are automatically generated from the Relying on JSON files may evolve, but for now, it is the simplest and most sustainable solution we've found. It allows for easy discoverability of components, and generating the files is very straightforward. That being said, if we find a way to eliminate the need for them entirely, this approach may change. |
@Halleck45 Thanks for the clarification! I hadn't seen the . But if they're automatically generated, then I don't see any problem in using this format 👍 |
Are you planning to make a component accessible like this: Do you need any help? I can offer some time to contribute to this awesome PR. Thanks for your work! |
This looks very interesting. Thanks! A quick question: how can third-party bundles (e.g. SonataAdmin or EasyAdmin) install and use these UI components to build their interfaces? |
@nfacciolo For now, yes (or rather twig:Button simply). In the future, the syntax might eventually evolve to on its own, but that's something to discuss, think about, etc., in another PR. Yes, help is very welcome, that would be great! We need to adjust quite a few things, but there are tons of components left to build and a lot of documentation to write. The easiest way is probably to connect on the Symfony Slack.
@javiereguiluz Hi! I'm not sure I fully understand the question. As it stands, the components will be freely available for everyone to use and will be 100% customizable. Any Symfony project will be able to integrate them. Was that the intent of your question? |
@Halleck45 let me explain what I mean. You said that using elements from this UI toolkit will be as easy as: (1) Run this command OK. Now, I'm developing a third-party bundle (e.g. EasyAdmin) that has a lot of UI features and I want to use this button from UX toolkit. So, I run the command In those cases, can third-party bundles just copy+paste some files manually from the UX repository to use those components or does this need more configuration + wiring? Thanks |
Hey @javiereguiluz, indeed the command But we will also provide a manual installation (copy/paste) for each components, that will be visible on ux.symfony.com. |
Hi @Halleck45 |
Yes it wil be tightly coupled to Tailwind (since we re-use examples from Shadcn). Thanks to the "pull" system we are implementing (like Shadcn does), the code you download will be yours and so open to fully customization. If you want to drop Tailwind for something else, you can, and yes CVA will make things easier on this point. Also, surely in the future, we may propose other "themes" that can be based on another CSS framework, like Bootstrap for example. |
I'm curious to see some components like dialog or dropdown 😊. |
Thanks @Halleck45 for this change. I tested some of the components (simple copy & paste) and saw that there needs to be additional configuration for Tailwind. There are currently no defined theme variables for things like |
Hi ! We are planning two things:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for your work, here are my final review comments. After, I believe we would be ready to merge the PR and continue to iterate on Toolkit.
Thanks!
src/Toolkit/templates/default/examples/Breadcrumb/BreadcrumbDefault.html.twig
Outdated
Show resolved
Hide resolved
src/Toolkit/templates/default/examples/Card/CardBasic.html.twig
Outdated
Show resolved
Hide resolved
src/Toolkit/templates/default/examples/Table/TableDefault.html.twig
Outdated
Show resolved
Hide resolved
Ok, I'll give it another look and see how it feels once you've had a chance to make some changes - just let me know! |
Sorry about that, I've finally got a bit of breathing room again. Wow, the discussions really moved forward all of a sudden! Thank you! It’s great to see that this PR sparked such a rich discussion — it means the time spent was worthwhile 🙏 I hope I didn’t miss any messages. To bounce back on what was said:
Yes, that’s more of a leftover than a deliberate decision — simplifying makes sense. However, I do think it’s important to keep the possibility for a theme (or template, whatever we call it) to come from somewhere other than Symfony, and to be downloadable from multiple sources.
Thanks @Kocal ! Really sorry for the delay — I’m available this evening if you want to chat.
The idea of "publishing" a component is really interesting — it does seem like a good solution for the user. |
So guys IF you need anything from me i'll have a look at minor things tomorrow
Not sure if the word 'publish" comes from this comment of something you guys already played with, but i ver y strongly advocates we use words like install / publish / update / for anything but what they are generally used for.
AS i echooed a small discussion we had around Vienna: if you dont' want to lose time on it, no problem let's change the name and be done 😆 But these thing are not something we can (and should) so let's deal with problems before we make them :) |
Maybe interesting here https://x.com/shadcn/status/1905688710894481498?s=46 |
Funny, two days ago I started rewriting our registry system for a “flat” version, what a coincidence :D About tokens, CSS vars, Tailwind layers (...), IMO it is too early to think about it. Let's keep focusing on UI components and later introduce "snippets" (like what @kbond and @weaverryan brainstormed) |
💯 one step at a time so that we can actually take those steps |
Quick updates on what I've commited these 3 last days, but not pushed yet because I didn't finish:
{% block meta %}
title: Avatar
description: The Avatar component displays a user's profile picture or a fallback representation when no image is available.
{% endblock %}
{% block examples %}
## Avatar with Image
\```twig
<twig:Avatar>
<twig:Avatar:Image src="https://github.com/symfony.png" alt="@symfony" />
</twig:Avatar>
\```
## Avatar with Fallback
\```twig
<twig:Avatar>
<twig:Avatar:Fallback>JF</twig:Avatar:Fallback>
</twig:Avatar>
\```
{% endblock %}
Also, after some discussions with Simon this afternoon:
|
b065d90
to
295ad70
Compare
Great stuff @Kocal! When it's ready for a review, please let me know! |
@weaverryan sure! If you still want to review right now, please ignore the
Typically, this is what I should explain in the PR description |
Nice, so we can easily add a |
Exactly! |
b0504a8
to
c7e6644
Compare
A few updates:
# Alert
The Alert component is used to display important messages or notifications to users, with support for different styles and variants.
## Examples
### Basic Alert
\```twig
<twig:Alert>
This is an alert message.
</twig:Alert>
\```
### Alert with Custom Class
\```twig
<twig:Alert class="bg-red-100 text-red-800">
This is a custom styled alert.
</twig:Alert>
\```
Enregistrement.de.l.ecran.2025-04-06.a.20.38.32.movNext! Implement more and more components from Shadcn and enhance examples. |
Super clever, I love it! |
…itecture, and value-objects - The registry system and JSON serialization were fully reworked, no more useless compilation to JSON - Rename "default" theme to "shadcn" - The "theme" term is now known as "kit" useless JSON serialization - Abuse ValueObjects usage for File, Example, Dependency, ... - Add binary for vendors
// Decrease headings level (e.g.: "# Alert" to "## Alert", "## Examples" to "### Examples", etc...) | ||
$markdownContent = $markdownContent->replaceMatches('/^(#{1,5})\s+(.+)$/m', '#$1 $2'); | ||
|
||
// Wrap each "```twig" code block with a HTML tab system containing the code and the component preview |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is it possible there could be twig code that we don't want converted to this tab system?
Maybe this should be twig+example
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes! I improved the component's doc rendering these two last days and it's already supported with "```twig {"preview":true}" (JSON is more easier to parse), but I didn't push yet :)
It will be especially useful for an "Usage" section where you only want to display the Twig code without preview (done in "Examples" section)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also: I wonder if some of this code could be simpler as a common mark extension?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep, this is exactly what I did :D
Following numerous discussions with various people, I'm opening this PR as a draft for a potential ux-toolkit component. This is the result of a joint reflection with @Kocal and @smnandre .
I’m not speaking on their behalf, but summarizing my interpretation of our discussions. Of course, @Kocal and @smnandre, feel free to correct, adjust, or add anything as needed.
Why?
Saving time
Creating Twig components like Badge or Button seems to be a very common step. The same work appears to be done over and over again, with minor differences from one company to another.
Providing a "packaged" toolkit would allow these companies and developers to save time by starting from ready-made templates.
Simplifying the process
Today, a beginner coming to Symfony has a lot to learn. Onboarding on a Symfony project can feel overwhelming, so it makes sense to offer them the most pleasant experience possible—including making it as easy as possible to create a clean and visually appealing web page.
Improving quality and accessibility
By providing a toolkit, we can leverage an entire community to gradually enhance the quality of components, including their digital accessibility. Accessibility is a major challenge, and we can aim to provide components that help companies and developers better support it.
How?
By providing:
symfony console ux:toolkit:install Button
command that will generate the corresponding Twig component in the user's project. If necessary, this command will also install any required dependencies (if a component relies on another one).Components will be unique.
It will be possible for the community to distribute unofficial components: for example, the command could accept
symfony console ux:toolkit:install github.com/MyRemote/UiKit:Button
The website https://ux.symfony.com/ will include:
Philosophy
Since the web is constantly evolving, it would be difficult to commit to maintaining components that require frequent updates.
An approach similar to shadcn seems more suitable: components are generated locally on demand by the developer, who will handle updates if necessary.
This approach likely offers the greatest flexibility: the developer can customize their component as they see fit, add their own variants, and adapt it to their specific needs.
The list of components could be based on the OpenUI initiative, which already provides a solid selection.
The symfony/ux-toolkit package will not be responsible for installing the CSS required for the components to function. It remains the developer's responsibility to manage their assets.
Next steps
There’s still a lot of work to do, which @Kocal will outline shortly. But it would be great to get feedback on the approach.
There is a lot of work to do; if the project is approved and the chosen direction is satisfactory, it would be great to create high-quality components. Looking forward to your feedback!
UX is an amazing component - it just needs "that little extra something" to truly make a difference in the daily lives of Symfony developers. I hope this kind of feature can help achieve that.
Takslist
symfony/ux-toolkit
boilerplatetales-from-a-dev/twig-tailwind-extra
if it wants to fully use our componentsux:toolkit:install
commandux:toolkit:install Button
)ux:toolkit:install github.com/MyRemote/UiKit:Button
)prefix
when installing components, e.g.:<twig:Badge>
must be replaced by<twig:Foobar:Badge>
if the user use the prefixFoobar
.json
containing the list of components, their name, type (component or example/variant), registry dependencies, source code, ... that will be used by theux:toolkit:install
command and the ux.symfony.com website:Registry
andRegistryItem
html_cva
, to provide a good development and customization experience for UX maintainers and usersclass
property, by using the following boilerplate:<div class="{{ style.apply({}, attributes.render('class'))|tailwind_merge }}" {{ attributes.defaults({}).without('class') }}>
tales-from-a-dev/twig-tailwind-extra
non hard-requirement, and what it can provides to userssymfony/ux-toolkit
in dev dependency, run./vendor/symfony/ux-toolkit/bin/generate-registry.php
, ...)