Design System Documentation

[kulmann]

Initial Checklist

• I understand this is a feature request and questions should be posted in the Community Discussions
• I searched issues and couldn’t find anything (or linked relevant results below)

Motivation / context

For the documentation of the design system we're currently using vue-styleguidist. This is mostly unmaintained and also fills up our Security issue tracker. Since the documentation is not published anywhere we want to get rid of it (edit: of vue-styleguidist, not of the documentation).

Requirements

We have a very limited set of requirements at the moment. There are two main use cases for the documentation:

1. Component development within rendered examples (dev server)
2. Documentation for developers within the extension eco-system with the following main points of interest:
   a. Component features and how to use them
   b. CSS utility classes and how to use them
   c. Look up available icons
   d. (later on: how to use material color roles... if we ever switch to Material)

Alternatives

There are several alternatives for our small set of requirements. The following is a non-exhaustive list of alternatives including some pros and cons respectively.

Storybook

Pros

• actively maintained
• MIT licensed

Cons

• might be too bloated (e.g. visual tests are far beyond what we need)
• open core? what's the enterprise-featureset?

VitePress

Pros

• actively maintained and officially supported by Vue
• seems easy to use as you can write simple markdown and use components within (https://vitepress.dev/guide/using-vue#using-components)

Cons

• needs some digging into to check if it fulfills all our needs and how to make it work

Custom-built with our design system :-)

Pros

• dog-fooding our own design system
• quick start (-> no need to gain expert-knowledge in a documentation tool)

Cons

• nothing auto-generated

[JammingBen]

So we decided to go with VitePress.

To-Dos:

Content

• Add component docs
• Add emit, prop and slot docs
• What content do we need besides "Design Tokens" and "Components"?
• Add logo
• Add favicon
• Make "Design Tokens" markdown files look nice

Technical

• Remove doc blocks and inline docs from Vue components
• Remove @opencloud-eu/vite-plugin-docs from all vite configs once the doc blocks have been removed
• Remove webpack build scripts
• Migrate design-system scripts to modules
• Remove unused dependencies
• Disable dark theme for now
• Can we extract the props of components and document them automatically via the doc blocks?
• How does the built bundle look like? Do we need to include build tokens etc. manually?
• Build and deploy design system somewhere (see Publish design system docs #217)
• Add global types for things like variation, appearance, sizes etc. so they can be used in component props (Add reusable types in design system #250)