This is a collection of mostly internal notes.
The shared UI library code is built from Vue, Javascript, and Sass. It requires the dependencies specified under the dependencies
and peerDependencies
attributes of /package.json
. An external application will import and functionality from kolibri-design-system/lib
as described in the documentation, and then generate build artifacts as necessary for the application's specific deployment or distribution requirements.
The documentation site is built using NuxtJS and Vue. It requires the dependencies specified in the devDependencies
attribute of /package.json
to build and run. The documentation site can either be run locally using the Node.js development server, or exported as a static site and uploaded to a CDN.
There is one top-level package.json
file, and:
- Dependencies used by the shared component library (
/lib
) are independencies
- Some other dependencies used by the shared component library (
/lib
) are expected/assumed to be provided by the library user - All other design system dependencies should be specified in
devDependencies
. This includes both build and run-time Nuxt-related dependencies
See issue #20 for more information about how this situation could be improved.
The documentation site is currently deployed to Netlifty automatically when changes are pushed to one of the primary branches. This is configured in the Netlify web UI to run yarn generate
and point at the created dist
directory.
Netlify is authenticated with the Netlify GitHub app.
Note that we currently use the deprecated Nuxt.js mode: universal
flag, and should switch to the newer target: static
flag.
The documentation site itself intentionally does not conform to the design system it describes, for two reasons:
- The user-interface of the site (links, buttons, headers, etc) is intentionally built without depending on the Kolibri shared UI library. This helps ensure as we update the UI library, we only need to update content and examples in the documentation, not the implementation of the documentation.
- From a design perspective, it's important that the documentation site looks and feels sufficiently distinct from the design patterns it describes, so that users do not mistakenly immitate it. Instead, users should focus on the patterns that are explicitly documented.
From a coding perspective this means that references to ~~/lib
code should in general only appear in ~/pages/
as illustrations of the shared UI library. However, we might decide on a case-by-case basis to have occasional exceptions to this rule. For example, we currently use ~~/lib/KResponsiveElementMixin
inside ~/common/Header
because it would be excessive to duplicate that functionality.
We do not use client-side routing. The reason is that we make extensive use of #anchor
links, and there are many issues in both NuxtJS and Vue Router with mixing anchors and client-side routing. In practice, this means that there should be no instances of <router-link>
or <nuxt-link>
in documentation code.
Several years ago, we vendored Keen UI. Since then, some of the components were updated occasionally to match Keen UI updates, but overall we use fairly old versions. We agreed not to follow Keen UI updates and consider forked components as "our own". Therefore, Keen UI components can be modified directly as needed.