Skip to content

Commit eac1872

Browse files
deleoniodeleonio
committed
update kolibri
1 parent 8fd6065 commit eac1872

File tree

12,896 files changed

+562409
-1093697
lines changed

Some content is hidden

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

12,896 files changed

+562409
-1093697
lines changed

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

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

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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
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 means of clearly defined component APIs and
15+
restrictive access to the interior of the components. The usability of the components is largely driven by the test steps of the WCAG and BITV, which
16+
standardizes the behavior of the individual interactive elements. Building on this basis, the aesthetics of the components can be freely designed by means
17+
of the decoupled KoliBri Designer.
18+
</p>
19+
<h2>§ 2 Compatibility</h2>
20+
<p>
21+
All components are implemented framework-agnostic as Web Components and can thus be easily reused universally in all web-based projects. Additionally,
22+
we offer numerous adapters for the most popular frameworks to provide an even better Developer Experience (DX).
23+
</p>
24+
<h2>§ 3 Portability</h2>
25+
<p>
26+
The focus is on small components (e.g. buttons) that can be easily reused. The special thing about this is that an HTML button or input is not accessible
27+
without further ado. However, a KoliBri button or input takes into account the numerous use cases and the semantic construction of the components that must
28+
be considered.
29+
</p>
30+
<h2>§ 4 Maintainability</h2>
31+
<p>
32+
The most modern and popular tools from web development are used for the realization. In addition to the TypeScript programming language, aspects of
33+
reusability for other design systems and component libraries have also been incorporated. The architecture is subject to a decoupled modularity and high
34+
degree of automation (DevOps).
35+
</p>
36+
<h2>§ 5 Functional Suitability</h2>
37+
<p>
38+
There is no perfect solution. However, the claim is to functionally enable everything that is overarching and compatible with the strict view of the W3C web
39+
standards. Functionalities can thus either flow into the components of KoliBri itself or be added by means of the swizzling concept.
40+
</p>
41+
<h2>§ 6 Security</h2>
42+
<p>
43+
All components serve solely to achieve a consistent and accessible representation of web-based user interfaces in the sense of a corporate design or design
44+
system. We provide a universally applicable and subject-neutral library without any data transfer functionalities and storage.
45+
</p>
46+
</div>

‎dev/i18n/en/docusaurus-plugin-content-docs/version-2.1/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 _href="/docs/license" _label="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 _href="https://github.com/public-ui/kolibri/blob/45726c50d7f28c9c595442b2241582816eca5670/packages /create-kolibri/templates/kolibri-library/packages/components/src/global/script.ts#L8" _label="TS file" _target="github"/>. Our <KolLink _href="/designer/" _label=" Theme Designer" _target="designer"/> 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 _href="/docs/concepts/architecture" _label="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 _href="/docs/concepts/expert-slot" _label="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 _href="/docs/concepts/properties" _label="Properties" /> for more information.
57+
58+
## Any questions?
59+
60+
If you still have questions, please send us an email to <KolLink _href="mailto:kolibri@itzbund.de" _label="kolibri@itzbund.de" _target="email" _icons="codicon codicon-mail " />.

0 commit comments

Comments
 (0)