[Toolkit] Fine-tune the documentation

Author: Kocal

src/Toolkit/doc/index.rst

@@ -4,25 +4,76 @@ Symfony UX Toolkit
 **EXPERIMENTAL** This component is currently experimental and is likely
 to change, or even change drastically.
 
-Symfony UX Toolkit provides a set of ready-to-use UI components for Symfony applications.
+Symfony UX Toolkit provides a set of ready-to-use Tailwind CSS based UI components for Symfony applications.
 It is part of `the Symfony UX initiative`_.
 
+Please note that the **UX Toolkit is not a library of UI components**,
+but **a tool to help you build your own UI components**.
+It uses the same approach than the popular `Shadcn UI`_,
+and a similar approach than `Tailwind Plus`_.
+
+After installing the UX Toolkit, you can start pulling the components you need
+from the `UX Components page`_, and use them in your project.
+They become your own components, and you can customize them as you want.
+
+These UI components are based on `Twig Component`_ UX package, so we are sure
+to provide the best experience as possible to Symfony developers.
+
+Additionally, the UI components come with `html_cva` and `tailwind_merge`,
+you can either remove them from your project or install `twig/html-extra`
+and `tales-from-a-dev/twig-tailwind-extra` to use them.
+
+Also, we do not force you to use Tailwind CSS at all. If you want to use
+another CSS framework, you can, but you will need to adapt the UI components to it.
+
 Installation
 ------------
 
-TODO
+Install the UX Toolkit using Composer and Symfony Flex:
+
+.. code-block:: terminal
+
+    # The UX Toolkit is a development dependency:
+    $ composer require symfony/ux-toolkit --dev
+
+    # If you want to to keep `html_cva` and `tailwind_merge` in your UI components:
+    $ composer require twig/extra-bundle twig/html-extra:^3.12.0 tales-from-a-dev/twig-tailwind-extra
 
 Configuration
 -------------
 
 TODO
 
+Usage
+-----
+
+You may find a list of components in the `UX Components page`_, with the installation instructions for each of them.
+
+For example, if you want to install the `Button` component, you will find the following instruction:
+
+.. code-block:: terminal
+
+    $ bin/console ux:toolkit:install Button
+
+It will create the ``templates/components/Button.html.twig`` file, and you will be able to use the `Button` component like this:
+
+.. code-block:: html+twig
+
+    <twig:Button>Click me</twig:Button>
+
 Backward Compatibility promise
 ------------------------------
 
 This bundle aims at following the same Backward Compatibility promise as
 the Symfony framework:
 https://symfony.com/doc/current/contributing/code/bc.html
 
+However, the UI components and other files provided by the Toolkit **are not** covered by the Backward Compatibility
+promise.
+We may break them in patch or minor release, but you won't get impacted unless you re-install the same UI component.
+
 .. _`the Symfony UX initiative`: https://ux.symfony.com/
-#.. _`Twig Component`: https://symfony.com/bundles/ux-twig-component/current/index.html
+.. _`Twig Component`: https://symfony.com/bundles/ux-twig-component/current/index.html
+.. _`UX Components page`: https://ux.symfony.com/components
+.. _`Shadcn UI`: https://ui.shadcn.com/
+.. _`Tailwind Plus`: https://tailwindcss.com/plus

ux.symfony.com/templates/ux_packages/toolkit.html.twig

@@ -101,14 +101,14 @@
             Official components require tailwindcss to be installed in your project. Visit the <a class="text-underline" target="_blank" href="https://tailwindcss.com/docs/installation" target="_blank">Tailwind CSS documentation</a> for more information.
             Components are based on <a class="text-underline" target="_blank" href="https://ui.shadcn.com/" >shadcdn/ui</a> design system.
         </p>
-        
+
         <p class="mt-4">
             If you use component library using <code>html_cva()</code> or <code>tailwind_merge()</code> functions, remember to install them with:
         </p>
 
         {% component Terminal with {bottomPadding: 20} %}
             {% block content %}
-                composer require --dev tales-from-a-dev/twig-tailwind-extra twig/extra-bundle
+                composer require twig/extra-bundle twig/html-extra:^3.12.0 tales-from-a-dev/twig-tailwind-extra
             {% endblock %}
         {% endcomponent %}
 
@@ -122,13 +122,13 @@
                     Toolkit provides ready-to-use components, but freely customizable.
                 </p>
                 <p>
-                    Official components are copied into your project in the <code>templates/components</code> folder, like classic TwigComponent. 
+                    Official components are copied into your project in the <code>templates/components</code> folder, like classic TwigComponent.
                     Feel free to modify the code to suit your needs.
                 </p>
             </div>
             <div class="col-12 mt-4">
                 <p>
-                    It is quite possible to install other component libraries, or even redistribute your own components 
+                    It is quite possible to install other component libraries, or even redistribute your own components
                     (for example, if you want to provide your internal Design System).
                 </p>
                 <p>
@@ -182,4 +182,4 @@
         border-radius: var(--radius-md);
     }
 </style>
-{% endblock %}
+{% endblock %}