From 4e83caca3480ab74f22e88a8e58b5592e36557cb Mon Sep 17 00:00:00 2001 From: Jannik Stehle Date: Thu, 18 Sep 2025 19:46:00 +0200 Subject: [PATCH 1/3] docs(design-system): add tailwind migration docs --- packages/design-system/README.md | 124 +------- .../design-system/docs/.vitepress/config.ts | 17 ++ .../docs/.vitepress/theme/custom.scss | 12 + .../docs/designTokens/colorPalette.md | 6 - .../docs/designTokens/colorRoles.md | 14 +- .../docs/gettingStarted/installation.md | 129 ++++++++ .../docs/gettingStarted/tailwindMigration.md | 285 ++++++++++++++++++ .../docs/gettingStarted/usage.md | 24 ++ 8 files changed, 477 insertions(+), 134 deletions(-) create mode 100644 packages/design-system/docs/gettingStarted/installation.md create mode 100644 packages/design-system/docs/gettingStarted/tailwindMigration.md create mode 100644 packages/design-system/docs/gettingStarted/usage.md diff --git a/packages/design-system/README.md b/packages/design-system/README.md index 6bbd667864..425102655c 100644 --- a/packages/design-system/README.md +++ b/packages/design-system/README.md @@ -22,126 +22,6 @@ Start docs in dev mode: pnpm docs:dev ``` -## Usage as a package +## Using the design-system as a developer -### Installation - -To use the design-system in your application, you first need to install the package. Depending on your package manager, run one of the following commands: - -``` -$ npm install @opencloud-eu/design-system - -$ pnpm add @opencloud-eu/design-system - -$ yarn add @opencloud-eu/design-system -``` - -Note that if you're using the design-system in an OpenCloud Web app, it's recommended to install it as dev dependency. This is because the Web runtime already ships the design-system and you only need it for development purposes in your IDE. - -### Styles - -In order to use the provided CSS classes and to ensure the components are styled correctly, you need to import the styles like so: - -``` -import '@opencloud-eu/design-system/dist/design-system.css' -``` - -Again, this is not needed if you're using the design-system in an OpenCloud Web app because the styles are already available via the Web runtime. - -### Components - -To use a component, you need to import it. For example, to use the `OcButton` component: - -``` -import { OcButton } from '@opencloud-eu/design-system/components' - - - Click me! - -``` - -You can also register the components globally in your standalone Vue app. This way you don't need to import them any time you want to use them. - -``` -import { createApp } from 'vue' -import DesignSystem from '@opencloud-eu/design-system' - -const app = createApp({ ... }) -app.use(DesignSystem) -``` - -In order for your IDE to pick up the correct component types, you need to add the following to your `types.d.ts` file: - -``` -/// -``` - -Optionally, you can pass custom design tokens to the design-system. Check the [example theme](https://github.com/opencloud-eu/opencloud/blob/v2.2.0/services/web/assets/themes/opencloud/theme.json) for a list of available tokens. - -``` -const tokens = { - spacing: { - small: '4px', - medium: '8px', - large: '16px', - } -} - -app.use(DesignSystem, { tokens }) -``` - -### Icons - -To make sure all icons are loaded properly, you need to make sure they are served by your application. They are located under `node_modules/@opencloud-eu/design-system/dist/icons`. It's recommended to copy them to your public folder. You might need to set `iconUrlPrefix: '/'` when installing the design-system to ensure they are always loaded from the correct path. - -### Fonts - -There is no need to serve the fonts yourself since they are embedded in the CSS. - -### Translations - -The design-system uses [vue3-gettext](https://jshmrtn.github.io/vue3-gettext/) for translations. If your application doesn't use `vue3-gettext`, you need to tell the design-system to initialize it. This is done by passing the `initGettext` option: - -``` -app.use(DesignSystem, { - language: { - initGettext: true, - defaultLanguage: 'en' - } -}) -``` - -The provided `setLanguage` method must then be called when switching languages in your application: - -``` -import { setLanguage } from '@opencloud-eu/design-system' - -setLanguage('de') -``` - -You can also provide custom translations: - -``` -app.use(DesignSystem, { - language: { - initGettext: true, - defaultLanguage: 'en', - translations: { - 'en': { - 'hello': 'Hello', - 'world': 'World' - }, - 'de': { - 'hello': 'Hallo', - 'world': 'Welt' - } - } - } -}) -``` - -If your application already uses `vue3-gettext`, there is no need for all of this. However, you might want to include the provided translations in your `vue3-gettext` instance. They can be imported like so: - -``` -import translations from '@opencloud-eu/design-system/dist/translations.json' -``` +Please refer to the [docs](https://docs.opencloud.eu/design-system/gettingStarted/installation.html) for information about how to install and use the design-system as a developer. diff --git a/packages/design-system/docs/.vitepress/config.ts b/packages/design-system/docs/.vitepress/config.ts index af529fc69d..11cba1fe81 100644 --- a/packages/design-system/docs/.vitepress/config.ts +++ b/packages/design-system/docs/.vitepress/config.ts @@ -74,6 +74,23 @@ export default defineConfig({ }, sidebar: { '/': [ + { + text: 'Getting Started', + items: [ + { + text: 'Installation', + link: '/gettingStarted/installation' + }, + { + text: 'Usage', + link: '/gettingStarted/usage' + }, + { + text: 'Tailwind migration (v4)', + link: '/gettingStarted/tailwindMigration' + } + ] + }, { text: 'Design Tokens', items: [ diff --git a/packages/design-system/docs/.vitepress/theme/custom.scss b/packages/design-system/docs/.vitepress/theme/custom.scss index ff6520111f..d750313088 100644 --- a/packages/design-system/docs/.vitepress/theme/custom.scss +++ b/packages/design-system/docs/.vitepress/theme/custom.scss @@ -3,11 +3,20 @@ --vp-c-brand-1: var(--oc-role-secondary); } +.vp-doc tr:nth-child(2n) { + // disable the color change on table rows + background-color: var(--vp-c-bg); +} + // re-apply some basic styling we removed during the build to avoid conflicts with tailwind .title span { font-size: 14px; } +li::marker { + color: var(--oc-role-on-surface); +} + #VPSidebarNav .VPLink p { padding: 0; margin: 4px 0; @@ -20,6 +29,9 @@ html * { text-rendering: optimizeLegibility; -webkit-font-smoothing: antialiased; +} + +body { overflow: auto; } diff --git a/packages/design-system/docs/designTokens/colorPalette.md b/packages/design-system/docs/designTokens/colorPalette.md index 5e8b42783a..c065109361 100644 --- a/packages/design-system/docs/designTokens/colorPalette.md +++ b/packages/design-system/docs/designTokens/colorPalette.md @@ -45,12 +45,6 @@ const fields = [ - - ## Usage You can use these variables in your SCSS files or style blocks: diff --git a/packages/design-system/docs/designTokens/colorRoles.md b/packages/design-system/docs/designTokens/colorRoles.md index 064fcf6bff..e1c04a6a56 100644 --- a/packages/design-system/docs/designTokens/colorRoles.md +++ b/packages/design-system/docs/designTokens/colorRoles.md @@ -45,12 +45,6 @@ const fields = [ - - ## Usage You can use these variables in your SCSS files or style blocks: @@ -61,3 +55,11 @@ You can use these variables in your SCSS files or style blocks: background-color: var(--oc-role-primary); } ``` + +They can also be used via Tailwind's utility classes: + +```html +
+ Some text. +
+``` diff --git a/packages/design-system/docs/gettingStarted/installation.md b/packages/design-system/docs/gettingStarted/installation.md new file mode 100644 index 0000000000..4ff9c6a62c --- /dev/null +++ b/packages/design-system/docs/gettingStarted/installation.md @@ -0,0 +1,129 @@ +--- +title: Installation +next: false +--- + +# Installation + +## Within an OpenCloud Web app + +You don't necessarily need to install the design-system when developing an application or extension for OpenCloud Web, since it's already included in the Web runtime. However, if you want to have proper type support and access to the components in your IDE, or need to use the provided helper functions, you can install the design-system as a dev dependency. + +```shell +$ npm install @opencloud-eu/design-system --save-dev + +$ pnpm add @opencloud-eu/design-system -D + +$ yarn add @opencloud-eu/design-system -D +``` + +This is all you need to do, the Web runtime already takes care of the initialization. + +## As a package + +If you want to use the design-system in your own standalone Vue application, you first need to install the package. Depending on your package manager, run one of the following commands: + +```shell +$ npm install @opencloud-eu/design-system + +$ pnpm add @opencloud-eu/design-system + +$ yarn add @opencloud-eu/design-system +``` + +### Add styles + +The design-system uses [Tailwind](https://tailwindcss.com/) for styling. However, it does not ship Tailwind, meaning it must be provided by your application. Additionally, you need to import the design-system's styles at the very beginning of your main CSS file. It's important that this file is imported before any other styles to ensure the styles and Tailwind are working correctly. + +```ts +import '@opencloud-eu/design-system/tailwind' +``` + +Again, this is not needed if you're using the design-system in an OpenCloud Web app because the styles are already available via the Web runtime. + +### Register components + +To register the components globally in your standalone Vue app, you need to do the following: + +```ts +import { createApp } from 'vue' +import DesignSystem from '@opencloud-eu/design-system' + +const app = createApp({ ... }) +app.use(DesignSystem) +``` + +In order for your IDE to pick up the correct component types, you need to add the following to your `types.d.ts` file: + +```ts +/// +``` + +Optionally, you can pass custom design tokens to the design-system. Check the [example theme](https://github.com/opencloud-eu/opencloud/blob/v3.5.0/services/web/assets/themes/opencloud/theme.json) for a list of available tokens. + +```ts +const tokens = { + roles: { + primary: '#ffffff', + onPrimary: '#000000' + } +} + +app.use(DesignSystem, { tokens }) +``` + +### Icons + +To make sure all icons are loaded properly, you need to make sure they are served by your application. They are located under `node_modules/@opencloud-eu/design-system/dist/icons`. It's recommended to copy them to your public folder. You might need to set `iconUrlPrefix: '/'` when installing the design-system to ensure they are always loaded from the correct path. + +### Fonts + +There is no need to serve the fonts yourself since they are embedded in the CSS. + +### Translations + +The design-system uses [vue3-gettext](https://jshmrtn.github.io/vue3-gettext/) for translations. If your application doesn't use `vue3-gettext`, you need to tell the design-system to initialize it. This is done by passing the `initGettext` option: + +```ts +app.use(DesignSystem, { + language: { + initGettext: true, + defaultLanguage: 'en' + } +}) +``` + +The provided `setLanguage` method must then be called when switching languages in your application: + +```ts +import { setLanguage } from '@opencloud-eu/design-system' + +setLanguage('de') +``` + +You can also provide custom translations: + +```ts +app.use(DesignSystem, { + language: { + initGettext: true, + defaultLanguage: 'en', + translations: { + en: { + hello: 'Hello', + world: 'World' + }, + de: { + hello: 'Hallo', + world: 'Welt' + } + } + } +}) +``` + +If your application already uses `vue3-gettext`, there is no need for all of this. However, you might want to include the provided translations in your `vue3-gettext` instance. They can be imported like so: + +```ts +import translations from '@opencloud-eu/design-system/dist/translations.json' +``` diff --git a/packages/design-system/docs/gettingStarted/tailwindMigration.md b/packages/design-system/docs/gettingStarted/tailwindMigration.md new file mode 100644 index 0000000000..1eba76c42c --- /dev/null +++ b/packages/design-system/docs/gettingStarted/tailwindMigration.md @@ -0,0 +1,285 @@ +--- +title: Tailwind migration +next: false +--- + +# Tailwind migration + +Starting with `v4` of OpenCloud Web and the design-system, the custom utility classes and variables have been removed in favor of [Tailwind](https://tailwindcss.com/). We made this decision because great CSS frameworks like Tailwind are already out there and we feel like there is no need to reinvent the wheel. We want as little custom code as possible to be able to develop fast and with high quality while providing a well documented developer experience. The latter is given via [Tailwind's extensive documentation](https://tailwindcss.com/docs). + +The following guide shows how to migrate your application or extension to `v4` of OpenCloud Web and its design-system. + +## Utility classes + +### Spacing + +| OC utility class | Tailwind utility class | +| ---------------- | ---------------------- | +| `oc-m-xs` | `m-1` | +| `oc-m-s` | `m-2` | +| `oc-m-m` | `m-4` | +| `oc-m-l` | `m-6` | +| `oc-m-xl` | `m-12` | +| `oc-m-xxl` | `m-24` | +| `oc-m` | `m-4` | +| `oc-m-rm` | `m-0` | + +The same goes for the `padding` utility classes (replace `m` with `p`). + +### Text size + +| OC utility class | Tailwind utility class | +| ---------------- | ---------------------- | +| `oc-text-xsmall` | `text-xs` | +| `oc-text-small` | `text-sm` | +| `oc-text-medium` | `text-base` | +| `oc-text-large` | `text-lg` | +| `oc-text-xlarge` | `text-xl` | + +### Font weight + +| OC utility class | Tailwind utility class | +| ------------------ | ---------------------- | +| `oc-font-semibold` | `font-semibold` | +| `oc-text-bold` | `font-semibold` | + +### Text alignment + +| OC utility class | Tailwind utility class | +| ---------------- | ---------------------- | +| `oc-text-center` | `text-center` | +| `oc-text-left` | `text-left` | +| `oc-text-right` | `text-right` | + +### Word breaks and truncation + +| OC utility class | Tailwind utility class | +| ------------------ | ---------------------- | +| `oc-text-truncate` | `truncate` | +| `oc-text-nowrap` | `whitespace-nowrap` | + +### Line height + +The `line-height` gets determined by the given `text-` class. However, it can also be adjusted separately via the `leading-` classes (see https://tailwindcss.com/docs/line-height#setting-independently). + +### Text decoration + +For `text-decoration` we didn't have a utility class. When a decoration is needed on hover, just use `hover:underline`. Disabling the underline is usually not needed since this is already done via the Tailwind preflight. + +### Colors + +The theme color roles now exist as Tailwind variables and can be used like so: `bg-role-primary`, `text-role-on-primary`. This also supports variations, e.g. `hover:text-role-on-primary` or `bg-role-primary/50`. + +These oc-helper classes are now redundant: + +| OC utility class | Tailwind utility class | +| ---------------- | ------------------------------ | +| `oc-text-muted` | `text-role-on-surface-variant` | +| `oc-text-error` | `text-role-on-error` | + +### Borders + +| OC utility class | Tailwind utility class | +| ---------------- | ---------------------- | +| `oc-border` | `border` | +| `oc-rounded` | `rounded-sm` | + +For more variants, please refer to https://tailwindcss.com/docs/border-width. + +### Width + +| OC utility class | Tailwind utility class | +| ----------------- | ---------------------- | +| `oc-width-1-1` | `w-full` | +| `oc-width-1` | `w-full` | +| `oc-width-large` | `w-lg` | +| `oc-width-medium` | `w-sm` | +| `oc-width-small` | `w-xs` | +| `oc-width-expand` | `flex-1` | +| `oc-width-auto` | `w-auto` | + +### Height + +| OC utility class | Tailwind utility class | +| -------------------- | ---------------------- | +| `oc-height-1-1` | `h-full` | +| `oc-height-viewport` | `h-screen` | +| `oc-height-small` | `h-[150px]` | +| `oc-height-medium` | `h-[300px]` | +| `oc-height-large` | `h-[450px]` | + +### Display + +| OC utility class | Tailwind utility class | +| ------------------------- | ---------------------- | +| `oc-display-block` | `block` | +| `oc-display-inline-block` | `inline-block` | + +### Flex + +| OC utility class | Tailwind utility class | +| ------------------------ | ---------------------- | +| `oc-flex` | `flex` | +| `oc-flex-inline` | `inline-flex` | +| `oc-flex-left` | `justify-start` | +| `oc-flex-center` | `justify-center` | +| `oc-flex-right` | `justify-end` | +| `oc-flex-between` | `justify-between` | +| `oc-flex-around` | `justify-around` | +| `oc-flex-top` | `items-start` | +| `oc-flex-middle` | `items-center` | +| `oc-flex-bottom` | `items-end` | +| `oc-flex-stretch` | `items-stretch` | +| `oc-flex-row` | `flex-row` | +| `oc-flex-row-reverse` | `flex-row-reverse` | +| `oc-flex-column` | `flex-col` | +| `oc-flex-column-reverse` | `flex-col-reverse` | +| `oc-flex-nowrap` | `flex-nowrap` | +| `oc-flex-wrap` | `flex-wrap` | +| `oc-flex-wrap-reverse` | `flex-wrap-reverse` | +| `oc-flex-1` | `flex-1` | + +### Overflow + +| OC utility class | Tailwind utility class | +| -------------------- | ------------------------------------- | +| `oc-overflow-hidden` | `overflow-hidden` | +| `oc-overflow-auto` | `overflow-auto` | +| `oc-text-overflow` | `max-w-full` and/or `overflow-hidden` | + +### Position + +| OC utility class | Tailwind utility class | +| --------------------------- | ----------------------------------------------------------------- | +| `oc-position-relative` | `relative` | +| `oc-position-fixed` | `fixed` | +| `oc-position-absolute` | `absolute` | +| `oc-position-center` | `absolute top-[50%] left-[50%] transform-[translate(-50%, -50%)]` | +| `oc-position-center-right` | `absolute top-[50%] right-0 transform-[translateY(-50%)]` | +| `oc-position-bottom-center` | `absolute left-[50%] bottom-0 transform-[translateX(-50%)]` | +| `oc-position-cover` | `absolute inset-0` | + +### Visibility + +| OC utility class | Tailwind utility class | +| ----------------- | ---------------------- | +| `oc-invisible-sr` | `sr-only` | +| `oc-invisible` | `invisible` | +| `oc-hidden` | `hidden` | + +### Cursor + +| OC utility class | Tailwind utility class | +| ------------------- | ---------------------- | +| `oc-cursor-pointer` | `cursor-pointer` | + +### Box-shadow + +| OC utility class | Tailwind utility class | +| ---------------------- | ---------------------- | +| `oc-box-shadow-medium` | `shadow-md/20` | + +## Custom CSS + +The philosophy of Tailwind is to use utility classes as much as possible. However, in rare occasions where you need to write custom CSS, it's recommended to put your styles into Tailwind's layer system. + +### Example + +```html + +``` + +The `reference` is needed so Tailwind classes like `text-small` are recognized when working with `@apply`. Still, you can also use layers without that: + +```html + +``` + +Please refer to https://tailwindcss.com/docs/adding-custom-styles#using-custom-css for more information on layers and how to write custom CSS with Tailwind. + +## OcCard + +`OcCard` is now a dedicated component instead of a class. + +```ts +
// [!code --] + // [!code ++] +
// [!code --] + // [!code ++] +
// [!code --] +

Some body content

+
// [!code --] +
// [!code --] + // [!code ++] +
// [!code --] + // [!code ++] +``` + +Please refer to the [OcCard docs](../components/OcCard/OcCard.md) for more details on how to use this component. + +## OcGrid + +The `OcGrid` component has been removed. Please use the [Tailwind grid layout](https://tailwindcss.com/docs/grid-template-columns) instead. + +## Mixins + +The following mixins have been removed: + +- `oc-form-check-size` +- `oc-icon-size` +- `oc-spinner-size` + +## Media queries (breakpoints) + +The custom breakpoint variables have been removed: + +- `$oc-breakpoint-xsmall-max` +- `$oc-breakpoint-small-default` +- `$oc-breakpoint-small-max` +- `$oc-breakpoint-medium-default` +- `$oc-breakpoint-medium-max` +- `$oc-breakpoint-large-default` +- `$oc-breakpoint-large-max` +- `$oc-breakpoint-xlarge` + +Please use the corresponding [Tailwind utilities](https://tailwindcss.com/docs/responsive-design) instead. The old breakpoints have been mapped to those. + +```ts +
// [!code --] +