Skip to content

docs(design-system): add tailwind migration docs #1221

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.

Sign up for GitHub

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

Merged
JammingBen merged 3 commits into from
Sep 22, 2025
Merged

docs(design-system): add tailwind migration docs #1221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4e83cac
docs(design-system): add tailwind migration docs
JammingBen Sep 18, 2025
ab3f795
docs(design-system): add docs for OcCard
JammingBen Sep 19, 2025
d67e165
Update packages/design-system/docs/components/OcCard/OcCard.md
JammingBen Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 2 additions & 122 deletions packages/design-system/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'

<oc-button>
Click me!
</oc-button>
```

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:

```
/// <reference types="@opencloud-eu/design-system/types" />
```

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.
21 changes: 21 additions & 0 deletions packages/design-system/docs/.vitepress/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: [
Expand Down Expand Up @@ -123,6 +140,10 @@ export default defineConfig({
text: 'OcButton',
link: '/OcButton'
},
{
text: 'OcCard',
link: '/OcCard'
},
{
text: 'OcCheckbox',
link: '/OcCheckbox'
Expand Down
29 changes: 29 additions & 0 deletions packages/design-system/docs/.vitepress/theme/custom.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,37 @@
--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);
}

.vp-doc .live-code-block {
h1,
h2,
h3,
h4,
h5,
h6 {
// reset vitepress styling inside live code blocks
margin: revert-layer;
border: revert-layer;
padding: revert-layer;
font-size: revert-layer;
line-height: revert-layer;
letter-spacing: revert-layer;
}
}

// 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;
Expand All @@ -20,6 +46,9 @@
html * {
text-rendering: optimizeLegibility;
-webkit-font-smoothing: antialiased;
}

body {
overflow: auto;
}

Expand Down
59 changes: 59 additions & 0 deletions packages/design-system/docs/components/OcCard/OcCard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: OcCard component
next: false
prev: false
---

# OcCard component

## Description

The `OcCard` component represents a simple card element consisting of a body and an optional header and footer. It is used to group related information in a visually distinct container.

## Examples

### Default

::: livecode

```html
<oc-card title="Card title"> Some content inside a card. </oc-card>
```

:::

### Styling

Visually, the default card mainly handles spacing and alignment. The card can then be customized via the provided properties `headerClass`, `bodyClass` and `footerClass` or simply by using utility classes on the card.

::: livecode

```html
<oc-card title="Card title" class="border" header-class="bg-gray-100 pb-4">
Some content inside a card.
</oc-card>
```

:::

### Slots

The card can display custom content using the default slot.

::: livecode

```html
<oc-card title="Card title">
<template #header>
<p>Custom header</p>
</template>
<p>Some content inside a card.</p>
<template #footer>
<p>Custom footer</p>
</template>
</oc-card>
```

:::

::: component-api
6 changes: 0 additions & 6 deletions packages/design-system/docs/designTokens/colorPalette.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,12 +45,6 @@ const fields = [
</template>
</oc-table>

<style lang="scss">
.oc-tbody-tr {
background-color: var(--oc-role-surface) !important;
}
</style>

## Usage

You can use these variables in your SCSS files or style blocks:
Expand Down
14 changes: 8 additions & 6 deletions packages/design-system/docs/designTokens/colorRoles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,12 +45,6 @@ const fields = [
</template>
</oc-table>

<style lang="scss">
.oc-tbody-tr {
background-color: var(--oc-role-surface) !important;
}
</style>

## Usage

You can use these variables in your SCSS files or style blocks:
Expand All @@ -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
<div class="bg-role-secondary">
<span class="text-role-on-secondary">Some text.</span>
</div>
```
Loading