Skip to content

Commit dfe83cd

Browse files
deleoniodeleonio
authored
update kolibri to 2.2 (#255)
The A11y and PO reviews will only take place after all other DoD steps have been completed by the Developer: - [x] Maturation completed and documented - [x] Meaningful pull request title for the release notes - [ ] Pull request is linked to an issue - [x] All changes relate to the issue - [x] No TODOs or commented out code in the final commit - [x] Tests to protect this code implemented (if applicable) - [ ] Manual test performed successfully (if applicable) - [x] Documentation or migration has been updated (if applicable)
2 parents 84a6f7d + a476717 commit dfe83cd

File tree

172 files changed

+13720
-1481
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

172 files changed

+13720
-1481
lines changed

‎i18n/en/docusaurus-plugin-content-docs/version-2.2/00-welcome.mdx

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
---
2+
slug: /
3+
title: Welcome
4+
description: We want to jointly provide accessible basic components.
5+
tags:
6+
- Demo
7+
- Getting started
8+
---
9+
10+
11+
import {KolAlert, KolKolibri, KolLink, KolLogo,} from '@public-ui/react';
12+
import {KoliBri} from '@site/src/components/KoliBri';
13+
import {KoliBriAbbr} from '@site/src/components/KoliBriAbbr';
14+
import {WelcomeQualityTable, WelcomeSupportTable} from '@site/src/components/docs/Welcome';
15+
16+
<div className="flex gap-4">
17+
<KolLogo
18+
_org="ITZBund"
19+
style={{
20+
display: 'block',
21+
width: '175px',
22+
marginTop: '1em',
23+
}}
24+
/>
25+
<KolKolibri
26+
style={{
27+
display: 'block',
28+
width: '100px',
29+
marginBottom: '1em',
30+
}}
31+
/>
32+
</div>
33+
34+
<KolAlert _type="info" _variant="card">
35+
<KolLink _label="Learn here why KoliBri is so helpful." _href="/en/docs/concepts/styling/theming" />
36+
</KolAlert>
37+
38+
<br />
39+
40+
<p className="col-12">
41+
<KoliBriAbbr />
42+
</p>
43+
44+
## Vision
45+
46+
<p className="col-12">
47+
Together, we make <strong>HTML semantically accessible using reusable Web Components</strong> to ensure{' '}
48+
<strong>usability</strong> and <strong>accessibility</strong>.
49+
</p>
50+
51+
## Mission
52+
53+
<p className="col-12">
54+
The <KolLink _label="HTML web standard" _href="https://html.spec.whatwg.org" _target="_blank" /> is specified to be very "open" in order to be as durable and robust as possible. It therefore often happens that HTML compositions are not readily accessible, semantic and valid.
55+
<KoliBri /> builds directly on the <KolLink _label="W3C" _href="https://www.w3.org" _target="_blank"/>
56+
<KolLink _label="web standards" _href="https://www.w3.org/standards/webdesign/" _target="_blank" /> (framework-agnostic), is thereby a generic reference implementation of the
57+
<KolLink _label="WCAG standard" _href="https://www.w3.org/WAI/standards-guidelines/wcag/" _target="_blank" /> and
58+
<KolLink _label="BITV" _href="https://www.bitvtest.de/bitv_test.html" _target="_blank" /> for accessibility, and is implemented as a multi-theme-enabled presentation layer. There is no technical reference and
59+
no data transfer functionalities. This makes <KoliBri /> equally reusable for the realization of static websites as
60+
well as dynamic web applications of different corporate designs and style guides and thus very interesting for open
61+
source.
62+
</p>
63+
64+
## Collaboration and cooperation
65+
66+
<p>
67+
The <strong>focus</strong> of <KoliBri /> is on <strong>small</strong> (atomic), very <strong>flexible</strong> and
68+
well <strong>reusable</strong> HTML compositions (e.g. button). We provide an accessible, semantic and valid standard
69+
implementation of such components that can be reused for any higher-level HTML structure or component (molecule,
70+
organism or template).
71+
</p>
72+
<p>
73+
We should <strong>collaborate</strong> and <strong>cooperate</strong> on these atomic components in order to bundle
74+
our skills and knowledge. Through the synergy effects at the basic components, our own focus can be placed more on
75+
subject-specific content.
76+
</p>
77+
<p>
78+
Let <strong>us</strong> make <KoliBri /> <strong>better</strong> and more <strong>colorful</strong>{' '}
79+
<strong>together</strong>!
80+
</p>
81+
82+
## License
83+
84+
<p className="col-12">
85+
<KoliBri /> is released under the <strong>EUROPEAN UNION PUBLIC LICENCE v1.2</strong> open source. The following
86+
aspects are in particular thereby considered:
87+
<ul>
88+
<li>
89+
<strong>Making accessible</strong>: The artifacts and source code can be reused freely and without charge by
90+
anyone. In this way, the ITZBund makes a contribution in the sense of <KolLink _label="“Public Money – Public Code”" _href="https://publiccode.eu/" _target="_blank" />.
91+
</li>
92+
<li>
93+
<strong>Warranty and liability disclaimer</strong>: No warranty or liability claims are associated with the reuse.
94+
</li>
95+
<li>
96+
<strong>“Copyleft” clause</strong>: Copyleft states that any copy of <KoliBri /> (fork) must be re-released under
97+
the same or a compatible open-source license.
98+
</li>
99+
</ul>
100+
</p>
101+
102+
## Delimitation
103+
104+
<p className="col-12">
105+
To use <KoliBri /> correctly, it is important to know where it unleashes its potential. <KoliBri /> is reusable in
106+
many ways because the styling has been completely decoupled and rendering is possible client-side but also
107+
server-side.
108+
</p>
109+
110+
### Styling
111+
112+
<p className="col-12">
113+
<KoliBri /> is neither a CSS framework nor a design system, but a library of frequently used components that have
114+
accessibility and usability requirements. To avoid having to look at these requirements over and over again,{' '}
115+
<KoliBri /> uses Web Components to create an overarching uniform standard for all style guides here.
116+
</p>
117+
<p className="col-12">
118+
The more relevant components are found and implemented, the more value is added to all web-based projects. However,{' '}
119+
<KoliBri /> does not aim to implement components without accessibility and usability requirements. Standard HTML and
120+
CSS or alternative CSS frameworks can be used for this purpose.
121+
</p>
122+
<p className="col-12">
123+
<KolAlert _type="success" _variant="card">
124+
<KoliBri /> components can be seamlessly integrated into existing websites or web applications and provide their
125+
style (guide) themselves, encapsulating it almost completely from the outside.
126+
</KolAlert>
127+
</p>
128+
129+
### Rendering
130+
131+
<p className="col-12">
132+
Web components can be rendered on the client side (CSR), prerendered (SSG), or on the server side (SSR). The rendering
133+
depends on the respective technical framework conditions (<KolLink _label="https://web.dev" _href="https://web.dev/rendering-on-the-web/" _target="_blank" />, <KolLink _label="https://medium.com" _href="https://medium.com/nerd-for-tech/compare-and-contrast-csr-ssr-and-ssg-in-nextjs-58e3caf2e15e" _target="_blank" />).
134+
</p>
135+
<p>
136+
<KolAlert _type="info" _variant="card">
137+
<small>
138+
💡 It should be noted that Web Components is a JavaScript-based web standard. Server-side rendering allows the Web
139+
Component to be rendered for optimal display speed on the client. If client-side JavaScript is allowed, the full
140+
dynamics of the Web Component are also available client-side. However, if you want to avoid using JavaScript on
141+
the client side, the Web Component is rendered, but the dynamics are lost.
142+
</small>
143+
</KolAlert>
144+
<br />
145+
<KolAlert _type="info" _variant="card">
146+
<small>
147+
🧪 Server-side rendering of Web Components is an exciting new functionality where adjustments to the prerenderer
148+
will still be necessary and is therefore classified as experimental on our part (<KolLink _label="https://web.dev" _href="https://web.dev/declarative-shadow-dom/" _target="_blank" />).
149+
</small>
150+
</KolAlert>
151+
</p>
152+
153+
## Versioning
154+
155+
<p className="col-12">
156+
<KoliBri /> follows the principles of semantic versioning.
157+
</p>
158+
<p className="col-12">
159+
<strong>Structure</strong> of a version:
160+
<ul>
161+
<li>
162+
It usually consists of 3 parts (e.g. 1.0.2)
163+
<ul>
164+
<li>
165+
Major, here the <i>1</i>
166+
</li>
167+
<li>
168+
Minor, here the <i>0</i>
169+
</li>
170+
<li>
171+
Patch, here the <i>2</i>
172+
</li>
173+
</ul>
174+
</li>
175+
<li>
176+
For the release phase of a version, you can use additional labels (e.g. 1.0.3-rc.2)
177+
<ul>
178+
<li>
179+
Label, here the <i>rc.2</i>
180+
</li>
181+
</ul>
182+
</li>
183+
</ul>
184+
</p>
185+
<p className="col-12">
186+
The following <strong>main principles</strong> are applied:
187+
<ul>
188+
<li>
189+
<b>Patch</b>: Includes changes that improve the current functionality and do not change its use.
190+
</li>
191+
<li>
192+
<b>Minor</b>: Includes changes that extend the functional scope and do not change the existing functional scope in
193+
its use.
194+
</li>
195+
<li>
196+
<b>Major</b>: Includes changes that enable architectural realignment and are allowed to change the use of the
197+
existing feature set.
198+
</li>
199+
</ul>
200+
You can find the complete description of the SemVer here: <KolLink _href="https://semver.org" _target="_blank" />
201+
</p>
202+
203+
## Quality objectives
204+
205+
<p className="col-12">
206+
The following table lists the prioritized qualities of <KoliBri />:
207+
</p>
208+
<WelcomeQualityTable lang="en" />
209+
210+
## Device, operating system, browser and screen reader requirements
211+
212+
<p className="col-12">
213+
<KoliBri /> is intended for the implementation of any web-based user interfaces and should be able to be used on all
214+
modern devices (PC, tablet, mobile), operating systems (Windows, Linux, macOS, Android, iOS) and standards-compliant
215+
browsers.
216+
<br />
217+
Microsoft Internet Explorer is explicitly not supported in order not to weaken the project and the development by
218+
legacy. Instead, <KoliBri /> consistently invests in the future.
219+
</p>
220+
<WelcomeSupportTable lang="en" />

‎i18n/en/docusaurus-plugin-content-docs/version-2.2/01-manifest.mdx

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: Manifest
3+
description: The manifest sets the frame of reference in our decisions.
4+
tags:
5+
- architecture
6+
- arc42
7+
- manifest
8+
---
9+
10+
<div class="manifest">
11+
<blockquote>We make the HTML accessible and themeable for reuse.</blockquote>
12+
<h2>§ 1 Usability</h2>
13+
<p>
14+
The ultimate goal is to provide standardized, semantically accessible components for the web. We ensure this by
15+
means of clearly defined component APIs and restrictive access to the interior of the components. The usability of
16+
the components is largely driven by the test steps of the WCAG and BITV, which standardizes the behavior of the
17+
individual interactive elements. Building on this basis, the aesthetics of the components can be freely designed by
18+
means of the decoupled KoliBri Designer.
19+
</p>
20+
<h2>§ 2 Compatibility</h2>
21+
<p>
22+
All components are implemented framework-agnostic as Web Components and can thus be easily reused universally in all
23+
web-based projects. Additionally, we offer numerous adapters for the most popular frameworks to provide an even
24+
better Developer Experience (DX).
25+
</p>
26+
<h2>§ 3 Portability</h2>
27+
<p>
28+
The focus is on small components (e.g. buttons) that can be easily reused. The special thing about this is that an
29+
HTML button or input is not accessible without further ado. However, a KoliBri button or input takes into account
30+
the numerous use cases and the semantic construction of the components that must be considered.
31+
</p>
32+
<h2>§ 4 Maintainability</h2>
33+
<p>
34+
The most modern and popular tools from web development are used for the realization. In addition to the TypeScript
35+
programming language, aspects of reusability for other design systems and component libraries have also been
36+
incorporated. The architecture is subject to a decoupled modularity and high degree of automation (DevOps).
37+
</p>
38+
<h2>§ 5 Functional Suitability</h2>
39+
<p>
40+
There is no perfect solution. However, the claim is to functionally enable everything that is overarching and
41+
compatible with the strict view of the W3C web standards. Functionalities can thus either flow into the components
42+
of KoliBri itself or be added by means of the swizzling concept.
43+
</p>
44+
<h2>§ 6 Responsibility</h2>
45+
<p>
46+
KoliBri relies on modern web standards to implement accessible web solutions across devices and browsers. However,
47+
device- and browser-specific issues should ideally be resolved by the respective manufacturers. Our own solutions
48+
could result in unstable and unsustainable workarounds that might create new accessibility problems. Therefore, it
49+
is advisable to address and resolve these issues directly at their source.
50+
</p>
51+
<h2>§ 7 Security</h2>
52+
<p>
53+
All components serve solely to achieve a consistent and accessible representation of web-based user interfaces in
54+
the sense of a corporate design or design system. We provide a universally applicable and subject-neutral library
55+
without any data transfer functionalities and storage.
56+
</p>
57+
</div>

‎i18n/en/docusaurus-plugin-content-docs/version-2.2/03-faq.mdx

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: FAQ
3+
description: Frequently asked questions about KoliBri
4+
tags:
5+
- Architecture
6+
- arc42
7+
- Faq
8+
- Concept
9+
- License
10+
- Legal
11+
---
12+
13+
import { KolLink } from '@public-ui/react';
14+
15+
# Frequently Asked Questions (FAQ)
16+
17+
## General
18+
19+
- **What is so special about KoliBri?**<br/>
20+
KoliBri offers granular, easily reusable HTML compositions that are semantically accessible and decoupled from the design. Using the basic styling, which is limited exclusively to the layout, the components can be easily adapted to your own corporate design.
21+
- **How do you save with KoliBri?**<br/>
22+
Websites/applications are implemented with different HTML elements and variants of elements. Each of these HTML structures must be semantically accessible and marked. KoliBri focuses on exactly such HTML structures and their variants and summarizes them in clearly defined components. The development teams that later reuse KoliBri can now use these components and adjust parameters to display different variants without having to think about the correctness of the HTML structure within the component. You are relieved and can focus more on the implementation of the actual technicality.<br/>
23+
- **How can you not explain KoliBri technically?**<br/>
24+
KoliBri is for accessibility like a Thermomix® is for cooking. It makes cooking easier because you can simply choose a suitable dish (component) without having to know how to cook it exactly. The Thermomix® (KoliBri) guides you through the cooking process (parameters for different variants) and ensures that the right dish (accessible user interface) comes out at the end.
25+
- **How dependent will I be if I use KoliBri?**<br/>
26+
If you compare KoliBri with a LEGO® set, you can simply mix the building blocks it contains with other building blocks to depict the overall application. You enter into a partial dependency (logical) in order to receive advantages in ensuring accessibility in return.
27+
- **How can I influence a component if necessary?**<br/>
28+
KoliBri components are very restrictive to ensure accessibility and are reused through composition. Adjustments from the outside can only be made through wrapping or the Expert slot. The styling is possible via the theme concept through configuration.
29+
- **What do I do if a component or feature is missing?**<br/>
30+
New technically neutral components or functions are to be implemented within KoliBri. Participation in this is expressly desired and will speed up implementation.
31+
- **What does the licensing say?**<br/>
32+
The EUPL allows unrestricted use of the artifacts, which can be customized in a configurative way to suit one's needs.
33+
On the other hand, it forces the disclosure of changes made when copying source code from KoliBri (Copy-Left).
34+
See the <KolLink _label="License" _href="/en/docs/project/license" /> for more information.
35+
36+
## Theming and styling
37+
38+
- **Who creates a theme if it doesn't already exist?**<br/>
39+
The current situation is that the ITZBund has implemented and maintains numerous themes of its customer authorities and example themes. However, the theme concept provides that themes can be created and maintained independently. We are happy to answer any questions and can provide selective support. As soon as your own theme has been created, an independent accessibility test is necessary to ensure, for example, the contrast ratios of the color values. Themes that have been created and tested can now be used again in other projects.
40+
- **How does theming work?**<br/>
41+
Typically, web components are created with fixed styling. KoliBri separates the semantically accessible components from the styling and provides a register method for combining them. Since the web components must always be registered (defined) in the browser, there is the option here of loading the components with a defined theme.
42+
- **How to create your own theme?**<br/>
43+
We are always working to further simplify the creation and maintenance of themes. For example, the basic styling (pure layout) of the components from version 1.5 is used for this. You can set it up simply by creating a theme definition, e.g. with your own theme project (NPM package) using the <KolLink _label="TS file" _href="https://github.com/public-ui/kolibri/blob/45726c50d7f28c9c595442b2241582816eca5670/packages/create-kolibri/templates/kolibri-library/packages/components/src/global/script.ts#L8" _target="_blank" />. Our <KolLink _label="Theme Designer" _href="/designer/" _target="_blank" /> is also helpful for creating and maintaining themes.
44+
- **Why does CSS need to be managed in JavaScript?**<br/>
45+
KoliBri components are not styled solely using embedded CSS or the use of CSS frameworks (such as Bootstrap, Material-UI, Tailwind CSS, etc.), but
46+
about the technical setting of CSS on the component. This has the advantage that the components are independent of the external CSS. Robustness is an architectural quality objective. It is reflected in the fact that only the component itself decides on its styling.
47+
- **Why do you need the scheme?**<br/>
48+
KoliBri is based on a sophisticated <KolLink _label="Architecture" _href="/en/docs/concepts/architecture" />. For example, the small schema package (@public-ui/schema) is used to define the tag names and language keys of the KoliBri components independently of the concrete implementation. This enables completely detached work with auto-completion when creating the theme, but without needing the components and their dependencies. This has advantages in some integration scenarios, such as static pages or content management systems (CMS).
49+
50+
## Technical
51+
52+
- **Why can KoliBri components really be accessible?**<br/>
53+
The KoliBri components are designed in terms of software architecture in such a way that they can only be instrumented via properties and not via their own HTML that can be entered. This means that the components can only be controlled via the API (properties). This is a quality feature because the components cannot be manipulated from the outside. The components are very restrictive and can therefore always be accessible.<br/>
54+
In order to be able to break out of this restriction, there is the <KolLink _label="Expert-Slot" _href="/en/docs/concepts/expert-slot" />, which makes it possible to embed your own HTML in the component. Accessibility via the expert slot is in the hands of the expert (developer) and should only be used in exceptional cases.
55+
- **Why are component properties sometimes named differently from HTML naming?**<br/>
56+
In order to keep KoliBri easy to learn, the HTML naming is usually used. But even the HTML standard is not uniform in its naming across several elements (components). And that is why we have chosen uniform names for similar properties in KoliBri. See concept <KolLink _label="Properties" _href="/en/docs/concepts/properties" /> for more information.
57+
58+
## Any questions?
59+
60+
If you still have questions, please send us an email to <KolLink _label="kolibri@itzbund.de" _href="mailto:kolibri@itzbund.de" _icons="codicon codicon-mail" />.

0 commit comments

Comments
 (0)