Skip to content

Commit ecba3a3

Browse files
deleoniodeleonio
committed
Refactor documentation and improve formatting across multiple files
- Updated tables in arc42_de/05-building-block-view.md for better readability - Enhanced structure and clarity in arc42_de/07-deployment-view.md - Improved accessibility and implementation strategy details in arc42_de/08-cross-cutting-concepts.md - Clarified quality requirements and metrics in arc42_de/10-quality-requirements.md - Revised risks and technical debt section in arc42_de/11-risks-and-technical-debt.md - Standardized glossary terms and definitions in arc42_de/12-glossary.md - Adjusted package.json formatting scripts for consistency and functionality
1 parent 6afc58c commit ecba3a3

24 files changed

+933
-929
lines changed

‎.claude/commands/migrate-to-skeleton.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -52,11 +52,11 @@ The [`ARC42.md`](packages/components/src/components/_skeleton/ARC42.md) is the *
5252
- `packages/components/src/internal/functional-components/skeleton/component.tsx`
5353
3. Create a **gap analysis** and output it as a Markdown table:
5454

55-
| Aspect | Legacy (Current) | Skeleton (Target) | Action Required |
56-
|--------|-----------------|-------------------|-----------------|
57-
| Inheritance | None / custom | `BaseWebComponent<Api>` | Migrate |
58-
| Controller | None / inline | `BaseController<Api>` | Create |
59-
| ... | ... | ... | ... |
55+
| Aspect | Legacy (Current) | Skeleton (Target) | Action Required |
56+
| ----------- | ---------------- | ----------------------- | --------------- |
57+
| Inheritance | None / custom | `BaseWebComponent<Api>` | Migrate |
58+
| Controller | None / inline | `BaseController<Api>` | Create |
59+
| ... | ... | ... | ... |
6060

6161
### Phase 2: Props-First — Establish Structure (CRITICAL — DO THIS FIRST!)
6262

@@ -165,15 +165,15 @@ public componentWillLoad(): void {
165165

166166
```typescript
167167
export class MyController extends BaseController<MyApi> implements ControllerInterface<MyApi> {
168-
public constructor(setState: SetStateFn<MyApi>, getState: GetStateFn<MyApi>) {
169-
super(myPropsConfig, setState, getState);
170-
}
171-
172-
public watchName(value?: string): void {
173-
nameProp.apply(value, (v) => {
174-
this.setRenderProp('name', v);
175-
});
176-
}
168+
public constructor(setState: SetStateFn<MyApi>, getState: GetStateFn<MyApi>) {
169+
super(myPropsConfig, setState, getState);
170+
}
171+
172+
public watchName(value?: string): void {
173+
nameProp.apply(value, (v) => {
174+
this.setRenderProp('name', v);
175+
});
176+
}
177177
}
178178
```
179179

@@ -189,7 +189,7 @@ export class MyController extends BaseController<MyApi> implements ControllerInt
189189
- Underscored public props (`_name`, `_label`)
190190
- Tests co-located next to `component.tsx`
191191
- No `types.ts` files, no barrel files
192-
- **ARIA IDs via `nonce()`**: Any `id` referenced by `aria-controls`, `aria-labelledby`, `aria-describedby` or `aria-owns` must be unique per instance — declare as `private readonly myId = \`prefix-${nonce()}\`` using `nonce()` from `utils/dev.utils`
192+
- **ARIA IDs via `nonce()`**: Any `id` referenced by `aria-controls`, `aria-labelledby`, `aria-describedby` or `aria-owns` must be unique per instance — declare as `private readonly myId = \`prefix-${nonce()}\``using`nonce()`from`utils/dev.utils`
193193
- **Kein `data-testid`**: Tests verwenden BEM-Klassen als Selektoren (`page.locator('.kol-component__element')`), niemals `data-testid`-Attribute im Komponenten-Markup
194194

195195
---

‎KNOWN_ISSUES.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -194,11 +194,11 @@ Toasts are unsolicited interruptions. `role="alert"` literally interrupts the ru
194194
195195
Every measure that makes a toast genuinely accessible transforms it into a different component:
196196

197-
| Measure | Result |
198-
|---|---|
199-
| No auto-dismiss | → Persistent inline alert |
200-
| Focus moved into the toast | → Non-modal dialog |
201-
| Notification history | → Notification panel / landmark region |
197+
| Measure | Result |
198+
| ---------------------------------------- | --------------------------------------------- |
199+
| No auto-dismiss | → Persistent inline alert |
200+
| Focus moved into the toast | → Non-modal dialog |
201+
| Notification history | → Notification panel / landmark region |
202202
| Plain text only, no interactive elements | → ARIA live region (no longer a visual toast) |
203203

204204
> "If a notification contains an interactive element, it should not be a live region. And it should also not be a toast."
@@ -221,13 +221,13 @@ The structural accessibility problems remain unresolved:
221221

222222
#### How leading design systems decide
223223

224-
| Design system | Decision |
225-
|---|---|
226-
| **GOV.UK Design System** | No toast — Notification Banner (persistent) instead |
227-
| **U.S. Web Design System** | No toast — Alert + Site Alert instead |
228-
| **GitHub Primer** | Toast officially banned after moderated usability tests with disabled users: "The tests showed significant problems that cannot be addressed with a sprinkling of ARIA." |
229-
| **Adobe Spectrum** | Toast with strict constraints: min. 5 s timeout, pause on hover/focus, F6 landmark navigation |
230-
| **Carbon (IBM) v11** | Split into non-interactive (`role="status"`) and interactive (`role="alertdialog"` with full focus management) |
224+
| Design system | Decision |
225+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
226+
| **GOV.UK Design System** | No toast — Notification Banner (persistent) instead |
227+
| **U.S. Web Design System** | No toast — Alert + Site Alert instead |
228+
| **GitHub Primer** | Toast officially banned after moderated usability tests with disabled users: "The tests showed significant problems that cannot be addressed with a sprinkling of ARIA." |
229+
| **Adobe Spectrum** | Toast with strict constraints: min. 5 s timeout, pause on hover/focus, F6 landmark navigation |
230+
| **Carbon (IBM) v11** | Split into non-interactive (`role="status"`) and interactive (`role="alertdialog"` with full focus management) |
231231

232232
#### References
233233

‎docs/arc42/01-introduction-and-goals.md‎

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@ This section introduces Public UI - KoliBri (KoliBri), outlining its core missio
1717

1818
## 1.2 Quality Goals
1919

20-
| Priority | Quality Goal | Motivation |
21-
|----------|-------------|------------|
22-
| 1 | **Accessibility** | Core mission - every component must be accessible to all users regardless of disabilities |
23-
| 2 | **Standard Compliance** | Build on W3C standards ensures longevity and interoperability |
24-
| 3 | **Usability** | Components should be intuitive for developers and end-users |
25-
| 4 | **Maintainability** | Clean architecture enables long-term evolution and community contributions |
26-
| 5 | **Performance** | Fast loading and rendering for optimal user experience |
20+
| Priority | Quality Goal | Motivation |
21+
| -------- | ----------------------- | ----------------------------------------------------------------------------------------- |
22+
| 1 | **Accessibility** | Core mission - every component must be accessible to all users regardless of disabilities |
23+
| 2 | **Standard Compliance** | Build on W3C standards ensures longevity and interoperability |
24+
| 3 | **Usability** | Components should be intuitive for developers and end-users |
25+
| 4 | **Maintainability** | Clean architecture enables long-term evolution and community contributions |
26+
| 5 | **Performance** | Fast loading and rendering for optimal user experience |
2727

2828
### Quality Scenarios
2929

@@ -34,22 +34,24 @@ This section introduces Public UI - KoliBri (KoliBri), outlining its core missio
3434

3535
## 1.3 Stakeholders
3636

37-
| Role/Name | Expectations | Contact |
38-
|-----------|-------------|---------|
39-
| **End Users** | Accessible, usable web interfaces that work with assistive technologies | - |
40-
| **Developers** | Easy-to-use, well-documented components that integrate with their tech stack | - |
41-
| **Designers** | Flexible theming system that supports their design systems | - |
42-
| **ITZBund** | Sustainable open-source project that meets public sector requirements | kolibri@itzbund.de |
43-
| **Public Sector Organizations** | BITV-compliant components for government websites and applications | - |
44-
| **Open Source Community** | Transparent development, contribution opportunities, and reusable components | GitHub Issues/PRs |
45-
| **Accessibility Advocates** | Reference implementation of WCAG standards in web components | - |
37+
| Role/Name | Expectations | Contact |
38+
| ------------------------------- | ---------------------------------------------------------------------------- | ------------------ |
39+
| **End Users** | Accessible, usable web interfaces that work with assistive technologies | - |
40+
| **Developers** | Easy-to-use, well-documented components that integrate with their tech stack | - |
41+
| **Designers** | Flexible theming system that supports their design systems | - |
42+
| **ITZBund** | Sustainable open-source project that meets public sector requirements | kolibri@itzbund.de |
43+
| **Public Sector Organizations** | BITV-compliant components for government websites and applications | - |
44+
| **Open Source Community** | Transparent development, contribution opportunities, and reusable components | GitHub Issues/PRs |
45+
| **Accessibility Advocates** | Reference implementation of WCAG standards in web components | - |
4646

4747
## 1.4 Vision and Mission
4848

4949
### Vision
50+
5051
> Together we make **HTML** accessible using **reusable web components** to ensure **usability** and **accessibility**.
5152
5253
### Mission
54+
5355
The HTML web standard is openly specified to be long-lasting and robust, but this often results in compositions that are not easily accessible, semantic, or valid. KoliBri provides:
5456

5557
- **Framework-agnostic components** based on W3C web standards

0 commit comments

Comments
 (0)
⚡