diff --git a/front/ui-docs/.vitepress/config.ts b/front/ui-docs/.vitepress/config.ts
index 2e9a50cd8..87ec8559a 100644
--- a/front/ui-docs/.vitepress/config.ts
+++ b/front/ui-docs/.vitepress/config.ts
@@ -1,7 +1,7 @@
import { defineConfig } from 'vitepress'
export default defineConfig({
- title: 'Funkwhale Vue Components',
+ title: 'Funkwhale Ui',
cleanUrls: true,
cacheDir: './.vitepress/.vite',
themeConfig: {
@@ -10,8 +10,14 @@ export default defineConfig({
{ text: 'Gitlab', link: 'https://dev.funkwhale.audio/funkwhale/ui' },
],
sidebar: [
+ {text:'Contributing', link:'/contributing'},
+ {
+ text: 'Using Color', link: '/using-color'
+ },
+ {
+ text: 'Using Components', link: '/using-components'
+ },
{
- text: 'Components',
items: [
{ text: 'Activity', link: '/components/ui/activity' },
{ text: 'Alert', link: '/components/ui/alert' },
diff --git a/front/ui-docs/contributing.md b/front/ui-docs/contributing.md
new file mode 100644
index 000000000..7449190f0
--- /dev/null
+++ b/front/ui-docs/contributing.md
@@ -0,0 +1,31 @@
+# Contributing
+
+[[toc]]
+
+## Setting up your IDE
+
+If you are using vscode, [enable `Vue` code hints in the `.md`
+docs](https://vitepress.dev/guide/using-vue#vs-code-intellisense-support):
+
+```json
+// .vscode/settings.json
+"vue.server.includeLanguages": ["vue", "markdown"]
+```
+
+## Adding new Ui components
+
+::: tip Prerequisites
+
+✔ I am using the same pattern in many different places in the app
+
+✔ The pattern is not coupled with any funkwhale types
+
+✔ It's a conventional Ui pattern
+
+:::
+
+1. Create a file `Xyz.vue` at `src/components/ui` and code the component
+2. Add a file `xyz.md` at `ui-docs/components` with exhaustive examples
+3. In `ui-docs/.vitepress/config.ts`, add the component to the sidebar links
+
+Make sure to follow the [anatomy of a Component](./using-components#anatomy-of-a-component-file)!
diff --git a/front/ui-docs/image.png b/front/ui-docs/image.png
new file mode 100644
index 000000000..a038018b0
Binary files /dev/null and b/front/ui-docs/image.png differ
diff --git a/front/ui-docs/index.md b/front/ui-docs/index.md
index 5e597dc69..6cfa01f98 100644
--- a/front/ui-docs/index.md
+++ b/front/ui-docs/index.md
@@ -3,6 +3,10 @@ import Layout from '../src/components/ui/Layout.vue'
import Card from '../src/components/ui/Card.vue'
import Spacer from '../src/components/ui/layout/Spacer.vue'
+import {useRouter} from 'vitepress'
+
+const docsRouter = useRouter()
+
// import { RouterLink, RouterView } from "vue-router";
// import { createWebHistory, createRouter } from 'vue-router'
@@ -27,19 +31,31 @@ import Spacer from '../src/components/ui/layout/Spacer.vue'
# Funkwhale design component library
-Welcome to the Funkwhale design component library. This repository contains a collection of reusable components written
-in [Vue.js](https://vuejs.org) and [Sass](https://sass-lang.com).
+## Contribute
-## Develop Ui components and Views
+- [Improve the component library!](./contributing)
+- [Found a bug? Report it here](https://dev.funkwhale.audio/funkwhale/funkwhale/-/issues/?sort=created_date&state=opened&label_name%5B%5D=Type%3A%3AUX%2FUI&first_page_size=20)
-**Prerequisites:** If you are using vscode, [enable `Vue` code hints in the `.md`
-docs](https://vitepress.dev/guide/using-vue#vs-code-intellisense-support):
+## Use
-> **.vscode/settings.json**
->
-> ```json
-> "vue.server.includeLanguages": ["vue", "markdown"]
-> ```
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Check out the design system on our Penpot.
+
+
+
+
+
+
---
-
-
-
-
- Check out the design system on our Penpot.
-
-
+
::: warning Deprecation of Activity, AlbumCard
diff --git a/front/ui-docs/using-color.md b/front/ui-docs/using-color.md
new file mode 100644
index 000000000..82416999a
--- /dev/null
+++ b/front/ui-docs/using-color.md
@@ -0,0 +1 @@
+# Using Color
diff --git a/front/ui-docs/using-components.md b/front/ui-docs/using-components.md
new file mode 100644
index 000000000..9dceede6c
--- /dev/null
+++ b/front/ui-docs/using-components.md
@@ -0,0 +1,77 @@
+# Using Components
+
+We distinguish between components that are coupled with funkwhale-specific datatypes and "pure" user interface components:
+
+- Funkwhale-specific components such as `Activity` or `AlbumCard` import from `types.ts`.
+- Pure Ui components (found in `src/components/ui`) are independent from Funkwhale. Think of `Button`, `Tabs` or `Layout`
+
+---
+
+[[toc]]
+
+## Anatomy of a component file
+
+### Imports
+
+First, import vue features and external libraries. Add the sub-components you want to use last. Order each block of imports by alphabet to prevent commit diff noise.
+
+### Script
+
+Add a blank line between Imports and script. Use modern typescript-friendly features such as `defineModel` and `defineProps` [as documented in the Vue Docs](https://vuejs.org/api/sfc-script-setup.html#definemodel) instead of Macros.
+
+### Template
+
+If you are new to Vue, read the docs, especially [the chapter about Single-File Components](https://vuejs.org/guide/scaling-up/sfc), to get familiar.
+
+### Style
+
+Don't pollute the global namespace. Funkwhale compiles a single stylesheet (used in the app, the blog and the website). If you need specific styles in your component, use vue's [SFC features](https://vuejs.org/api/sfc-css-features.html#sfc-css-features) such as `module`. Vue will give you a `$style` object containing all locally defined classes.
+
+```vue
+
+
+
+
+
+
+
+```
+
+::: details Tip: Debugging styles
+
+We have enabled [the vite feature `css.devSourcemap: true`](https://v2.vitejs.dev/config/#css-devsourcemap) so that in your browser devtools, you can trace the code responsible for module styles:
+
+
+
+:::
+
+::: info What about the global style?
+
+As of now, class and variable names from the global styles are not available as typescript objects. We should definitely add this feature at some point.
+
+:::
+
+## Using Ui components in your views
+
+```vue
+
+
+
+
+
+
+
+
+```
diff --git a/front/ui-docs/vite.config.ts b/front/ui-docs/vite.config.ts
index 3e66956f8..63673f9b2 100644
--- a/front/ui-docs/vite.config.ts
+++ b/front/ui-docs/vite.config.ts
@@ -15,6 +15,7 @@ export default defineConfig({
},
css: {
+ devSourcemap: true,
preprocessorOptions: {
scss: {
additionalData: `
+
+:::
+
+::: info What about the global style?
+
+As of now, class and variable names from the global styles are not available as typescript objects. We should definitely add this feature at some point.
+
+:::
+
+## Using Ui components in your views
+
+```vue
+
+
+
+
+
+