📚 Add buttons documentation for the design system

frontend/src/app/main/ui/ds/buttons/buttons.mdx

@@ -0,0 +1,69 @@
+import { Canvas, Meta } from '@storybook/blocks';
+import * as ButtonStories from "./button.stories";
+import * as IconButtonStories from "./icon_button.stories";
+
+<Meta title="Buttons/Buttons" />
+
+# Buttons
+
+Buttons trigger an action such as submitting a form or showing/hiding an interface component.
+
+## Variants
+
+**Primary** (`"primary"`), used to initiate the main / primary action of a view or flow. Avoid to have more than one primary buttons in the same view or flow.
+
+<Canvas of={ButtonStories.Primary} />
+
+**Secondary** (`"secondary"`), the default and most common buttons in the interface. Use them for non primary actions.
+
+<Canvas of={ButtonStories.Secondary} />
+
+**Ghosts** (`"ghost"`), used for less prominent, and sometimes independent, actions (examples: add pages, add properties, etc.)
+
+<Canvas of={ButtonStories.Ghost} />
+
+**Destructive** (`"destructive"`), used for any action that destroys any object or data. Don't use them for actions like dettach, unlink, etc.
+
+<Canvas of={ButtonStories.Destructive} />
+
+## Technical notes
+
+### Icons
+
+Both `button*` and `icon-button*` accept an `icon` prop, which must contain an [icon ID](../foundations/assets/icon.mdx).
+These are available in the `app.main.ds.foundations.assets.icon` namespace.
+
+```clj
+(ns app.main.ui.foo
+  (:require
+   [app.main.ui.ds.foundations.assets.icon :as i]))
+```
+
+```clj
+[:> button* {:icon i/effects} "Lorem ipsum"]
+```
+
+<Canvas of={ButtonStories.WithIcon} />
+
+### Accessibility
+
+Icon buttons require an `aria-label`. This is also shown in a tooltip on hovering the button.
+
+```clj
+[:> icon-button* {:icon i/effects :aria-label "Lorem ipsum"}]
+```
+
+<Canvas of={IconButtonStories.Default} />
+
+## Usage guidelines (design)
+
+### Where to use
+
+Penpot app has a high-density interface, so use buttons thoughtfully to establish
+a clear and logical visual hierarchy, and avoid overwhelming the user.
+
+### When to use
+
+Buttons can be used in forms, navigation links or anywhere that needs simple,
+standard button functionality. Used also to grab users' attention (i.e. navigate
+to main user flows like register, etc.)