Added the first 5 ADRs, which are important for first Work package "Groundwork"
This commit is contained in:
@@ -0,0 +1,142 @@
|
||||
# ADR-0001: Repository Structure
|
||||
|
||||
* **Status:** Accepted
|
||||
* **Date:** 2026-07-12
|
||||
* **Decision Makers:** LUNA Charts Maintainers
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
LUNA Charts is designed as an open-source charting library with a strong focus on accessibility, maintainability, and long-term evolution.
|
||||
|
||||
The project consists of multiple concerns, including source code, documentation, examples, testing infrastructure, and continuous integration.
|
||||
|
||||
A repository structure was required that supports collaborative development while keeping the project easy to understand for contributors and maintainers.
|
||||
|
||||
The repository should also support future growth without requiring structural changes.
|
||||
|
||||
---
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
The following factors influenced this decision:
|
||||
|
||||
* Maintainability
|
||||
* Developer Experience
|
||||
* Open Source Collaboration
|
||||
* Modular Architecture
|
||||
* Shared Tooling
|
||||
* Consistent Build Process
|
||||
* Long-Term Evolution
|
||||
|
||||
---
|
||||
|
||||
## Considered Alternatives
|
||||
|
||||
| Alternative | Description |
|
||||
| ------------------------------------ | ---------------------------------------------------------------------------------- |
|
||||
| Multiple repositories | Separate repositories for documentation, examples, and library packages. |
|
||||
| Single repository without workspaces | One repository containing all files without workspace separation. |
|
||||
| **Monorepo using pnpm Workspaces** | One repository containing all project artifacts with logical workspace separation. |
|
||||
|
||||
Multiple repositories were rejected because they increase maintenance effort, duplicate tooling, and complicate contribution workflows.
|
||||
|
||||
A single repository without workspaces was rejected because the project is expected to grow over time and benefits from a clear modular organization.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
LUNA Charts is implemented as a **pnpm-based monorepo**.
|
||||
|
||||
The repository contains all project artifacts, including:
|
||||
|
||||
* Source code
|
||||
* Documentation
|
||||
* Storybook
|
||||
* Examples
|
||||
* Architecture documentation
|
||||
* Architecture Decision Records (ADRs)
|
||||
* CI/CD configuration
|
||||
|
||||
The repository is organized into logical workspaces.
|
||||
|
||||
```text
|
||||
luna-charts/
|
||||
│
|
||||
├── packages/
|
||||
│ └── luna-charts/
|
||||
│
|
||||
├── apps/
|
||||
│ ├── storybook/
|
||||
│ └── docs/
|
||||
│
|
||||
├── docs/
|
||||
│ ├── architecture/
|
||||
│ └── adr/
|
||||
│
|
||||
├── examples/
|
||||
│
|
||||
└── .github/
|
||||
```
|
||||
|
||||
Internally, the library is organized into architectural modules such as:
|
||||
|
||||
* Core
|
||||
* Charts
|
||||
* Themes
|
||||
* Utilities
|
||||
|
||||
These modules are implementation details and are **not** exposed as individual npm packages.
|
||||
|
||||
---
|
||||
|
||||
## Rationale
|
||||
|
||||
A monorepo provides a single source of truth for the entire project.
|
||||
|
||||
All contributors work within the same repository using a shared toolchain, coding standards, testing infrastructure, and documentation.
|
||||
|
||||
Using **pnpm Workspaces** enables clear separation of responsibilities while avoiding duplicated dependencies and configuration.
|
||||
|
||||
This structure supports the project's architecture-first approach and simplifies future expansion.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
* Single source of truth
|
||||
* Simplified onboarding for contributors
|
||||
* Shared tooling and configuration
|
||||
* Consistent CI/CD pipeline
|
||||
* Easier dependency management
|
||||
* Centralized documentation
|
||||
* Scalable project organization
|
||||
|
||||
### Negative
|
||||
|
||||
* Larger repository size
|
||||
* Contributors clone the complete repository
|
||||
* Workspace configuration introduces a small amount of additional complexity
|
||||
|
||||
---
|
||||
|
||||
## Related TOGAF Phases
|
||||
|
||||
* Architecture Vision (Phase A)
|
||||
* Technology Architecture (Phase D)
|
||||
* Opportunities & Solutions (Phase E)
|
||||
* Migration Planning (Phase F)
|
||||
* Implementation Governance (Phase G)
|
||||
* Architecture Change Management (Phase H)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
* LUNA Charts Architecture Wiki
|
||||
* ADR-0002: Technology Stack
|
||||
* pnpm Workspaces Documentation
|
||||
@@ -0,0 +1,211 @@
|
||||
# ADR-0002: Technology Stack
|
||||
|
||||
* **Status:** Accepted
|
||||
* **Date:** 2026-07-12
|
||||
* **Decision Makers:** LUNA Charts Maintainers
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
LUNA Charts is an open-source charting library designed to provide accessible, framework-agnostic, and strongly typed chart components.
|
||||
|
||||
The selected technology stack must support the architectural principles defined during the TOGAF Architecture Development Method (ADM), including:
|
||||
|
||||
* Accessibility by Design
|
||||
* Framework Agnosticism
|
||||
* Strong Type Safety
|
||||
* Component-Based Architecture
|
||||
* High Developer Experience
|
||||
* Open Source Collaboration
|
||||
* Long-Term Maintainability
|
||||
|
||||
Rather than selecting technologies based on popularity, each technology is evaluated according to its ability to support these architectural goals.
|
||||
|
||||
---
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
The following factors influenced the decision:
|
||||
|
||||
* Accessibility
|
||||
* Framework Agnosticism
|
||||
* Type Safety
|
||||
* Developer Experience
|
||||
* Maintainability
|
||||
* Testability
|
||||
* Documentation
|
||||
* Open Source Collaboration
|
||||
* Long-Term Evolution
|
||||
|
||||
---
|
||||
|
||||
## Considered Alternatives
|
||||
|
||||
| Technology Area | Considered Alternatives | Selected |
|
||||
| ----------------------- | ----------------------------------------------- | ------------------ |
|
||||
| Component Framework | React, Vue, Angular, Lit, StencilJS | **StencilJS** |
|
||||
| Component Documentation | Storybook, Styleguidist | **Storybook** |
|
||||
| Project Documentation | Docusaurus, VitePress, Starlight | **Starlight** |
|
||||
| Package Manager | npm, Yarn, pnpm | **pnpm** |
|
||||
| Unit Testing | Vitest, Jest | **Jest** |
|
||||
| Browser Testing | Cypress, Playwright | **Playwright** |
|
||||
| Accessibility Testing | Manual Testing Only, axe-core | **axe-core** |
|
||||
| Code Formatting | Manual Formatting, Prettier | **Prettier** |
|
||||
| Static Analysis | TSLint, ESLint | **ESLint** |
|
||||
| Versioning | Manual Versioning, Semantic Release, Changesets | **Changesets** |
|
||||
| Continuous Integration | GitLab CI, Azure Pipelines, GitHub Actions | **GitHub Actions** |
|
||||
|
||||
The selected technologies best support the project's architectural goals while remaining broadly adopted and well documented.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
The following technology stack is adopted for the implementation of LUNA Charts.
|
||||
|
||||
| Technology | Purpose |
|
||||
| ------------------ | --------------------------------------------------- |
|
||||
| **StencilJS** | Web Component development |
|
||||
| **Storybook** | Interactive component documentation and development |
|
||||
| **Starlight** | Project and architecture documentation |
|
||||
| **TypeScript** | Strong typing and developer tooling |
|
||||
| **pnpm** | Package management and workspace support |
|
||||
| **Jest** | Unit testing |
|
||||
| **Playwright** | Browser and interaction testing |
|
||||
| **axe-core** | Accessibility validation |
|
||||
| **ESLint** | Static code analysis |
|
||||
| **Prettier** | Consistent code formatting |
|
||||
| **Changesets** | Versioning and release management |
|
||||
| **GitHub Actions** | Continuous Integration |
|
||||
|
||||
The technology stack is considered part of the project's architecture and may only be changed through a new Architecture Decision Record.
|
||||
|
||||
---
|
||||
|
||||
## Rationale
|
||||
|
||||
Each technology has been selected because it directly supports one or more architectural principles.
|
||||
|
||||
### StencilJS
|
||||
|
||||
StencilJS enables the development of standards-based Web Components.
|
||||
|
||||
This aligns with the project's goal of remaining framework agnostic while allowing framework-specific wrappers to be generated automatically during the build process.
|
||||
|
||||
---
|
||||
|
||||
### Storybook
|
||||
|
||||
Storybook provides an isolated environment for component development.
|
||||
|
||||
It supports rapid development, interactive examples, accessibility validation, and visual review of chart components.
|
||||
|
||||
---
|
||||
|
||||
### Starlight
|
||||
|
||||
Starlight serves as the central documentation platform.
|
||||
|
||||
It separates architectural documentation from component documentation and supports long-term maintainability of the project's knowledge base.
|
||||
|
||||
---
|
||||
|
||||
### TypeScript
|
||||
|
||||
TypeScript enables strong compile-time validation.
|
||||
|
||||
It improves the developer experience by detecting integration errors early and providing comprehensive IDE support.
|
||||
|
||||
---
|
||||
|
||||
### pnpm
|
||||
|
||||
pnpm Workspaces enable a modular repository structure while maintaining a single source of truth for dependencies and tooling.
|
||||
|
||||
---
|
||||
|
||||
### Jest
|
||||
|
||||
Jest provides fast unit testing for business logic, utility functions, configuration handling, validation, and other non-browser-specific functionality.
|
||||
|
||||
---
|
||||
|
||||
### Playwright
|
||||
|
||||
Playwright validates component behavior inside real browsers.
|
||||
|
||||
It is used to verify keyboard interaction, focus management, SVG rendering, and other browser-dependent accessibility features.
|
||||
|
||||
---
|
||||
|
||||
### axe-core
|
||||
|
||||
axe-core automatically validates accessibility requirements and complements manual accessibility reviews.
|
||||
|
||||
---
|
||||
|
||||
### ESLint and Prettier
|
||||
|
||||
Both tools ensure consistent coding standards across the project and reduce friction during code reviews.
|
||||
|
||||
---
|
||||
|
||||
### Changesets
|
||||
|
||||
Changesets manages package versioning and release notes while keeping release decisions under maintainer control.
|
||||
|
||||
---
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
GitHub Actions automates testing, validation, and release workflows to ensure consistent software quality.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
* Technology stack directly supports architectural principles.
|
||||
* Strong accessibility support throughout development.
|
||||
* Framework-independent component model.
|
||||
* Excellent developer experience.
|
||||
* Consistent documentation workflow.
|
||||
* High maintainability.
|
||||
* Modern testing strategy.
|
||||
* Simplified contributor onboarding.
|
||||
* Automated quality assurance.
|
||||
* Scalable project foundation.
|
||||
|
||||
### Negative
|
||||
|
||||
* Initial project setup is more complex.
|
||||
* Contributors must become familiar with multiple development tools.
|
||||
* Toolchain maintenance requires periodic updates.
|
||||
* CI configuration is more comprehensive than for smaller projects.
|
||||
|
||||
---
|
||||
|
||||
## Related TOGAF Phases
|
||||
|
||||
* Architecture Vision (Phase A)
|
||||
* Information Systems Architecture (Phase C)
|
||||
* Technology Architecture (Phase D)
|
||||
* Opportunities & Solutions (Phase E)
|
||||
* Migration Planning (Phase F)
|
||||
* Implementation Governance (Phase G)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
* LUNA Charts Architecture Wiki
|
||||
* ADR-0001: Repository Structure
|
||||
* ADR-0003: Web Components as Public API
|
||||
* StencilJS Documentation
|
||||
* Storybook Documentation
|
||||
* Starlight Documentation
|
||||
* Playwright Documentation
|
||||
* Jest Documentation
|
||||
* pnpm Documentation
|
||||
@@ -0,0 +1,110 @@
|
||||
# ADR-0003: Web Components as Public API
|
||||
|
||||
* **Status:** Accepted
|
||||
* **Date:** 2026-07-12
|
||||
* **Decision Makers:** LUNA Charts Maintainers
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
LUNA Charts is intended to be an open-source charting library that can be integrated into applications regardless of the frontend framework used.
|
||||
|
||||
A primary architectural objective defined during the Architecture Vision and Technology Architecture phases is **framework agnosticism**. Consumers should be able to use LUNA Charts in React, Angular, Vue, Svelte, or plain HTML applications without requiring framework-specific implementations of the chart components.
|
||||
|
||||
The public API therefore had to be based on a stable and widely adopted web standard rather than a framework-specific component model.
|
||||
|
||||
---
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
The following factors influenced this decision:
|
||||
|
||||
* Framework Agnosticism
|
||||
* Standards Compliance
|
||||
* Long-Term Maintainability
|
||||
* Accessibility
|
||||
* Developer Experience
|
||||
* Component Reusability
|
||||
* Open Web Platform
|
||||
* Future Compatibility
|
||||
|
||||
---
|
||||
|
||||
## Considered Alternatives
|
||||
|
||||
| Alternative | Description |
|
||||
| -------------------------------------- | ----------------------------------------------------------------- |
|
||||
| React Components | Components implemented exclusively for React. |
|
||||
| Vue Components | Components implemented exclusively for Vue. |
|
||||
| Angular Components | Components implemented exclusively for Angular. |
|
||||
| Separate implementations per framework | Independent implementations for each supported framework. |
|
||||
| **Web Components** | Standards-based custom elements implemented using Web Components. |
|
||||
|
||||
Framework-specific implementations were rejected because they increase maintenance effort, duplicate functionality, and couple the architecture to individual frontend ecosystems.
|
||||
|
||||
Maintaining multiple implementations would also increase the likelihood of inconsistent behavior across frameworks.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
LUNA Charts exposes its public API exclusively through **Web Components**.
|
||||
|
||||
The project uses **StencilJS** to implement these components according to the Web Components standard.
|
||||
|
||||
Framework integrations (e.g., React, Angular, Vue) are generated automatically during the build process and are considered **integration adapters**, not independent implementations.
|
||||
|
||||
The architecture therefore consists of a single component model with multiple consumption options.
|
||||
|
||||
---
|
||||
|
||||
## Rationale
|
||||
|
||||
Web Components are an open web standard supported by all modern browsers.
|
||||
|
||||
By building directly upon this standard, LUNA Charts remains independent of any frontend framework while still supporting popular ecosystems through automatically generated wrappers.
|
||||
|
||||
This approach minimizes duplicated implementation effort and guarantees consistent functionality across all supported platforms.
|
||||
|
||||
Using a single implementation also simplifies testing, documentation, maintenance, and accessibility validation.
|
||||
|
||||
Framework wrappers remain lightweight integration layers and do not introduce architectural differences.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
* Framework-independent public API.
|
||||
* Single implementation for all supported platforms.
|
||||
* Reduced maintenance effort.
|
||||
* Consistent behavior across frameworks.
|
||||
* Simplified testing and documentation.
|
||||
* Better long-term stability.
|
||||
* Supports future frontend frameworks without redesigning the library.
|
||||
|
||||
### Negative
|
||||
|
||||
* Developers unfamiliar with Web Components may require additional documentation.
|
||||
* Framework wrappers depend on the capabilities provided by StencilJS.
|
||||
* Some framework-specific features cannot be exposed without breaking framework independence.
|
||||
|
||||
---
|
||||
|
||||
## Related TOGAF Phases
|
||||
|
||||
* Architecture Vision (Phase A)
|
||||
* Information Systems Architecture (Phase C)
|
||||
* Technology Architecture (Phase D)
|
||||
* Opportunities & Solutions (Phase E)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
* LUNA Charts Architecture Wiki
|
||||
* ADR-0002: Technology Stack
|
||||
* StencilJS Documentation
|
||||
* Web Components Specification
|
||||
@@ -0,0 +1,129 @@
|
||||
# ADR-0004: SVG as Rendering Technology
|
||||
|
||||
* **Status:** Accepted
|
||||
* **Date:** 2026-07-12
|
||||
* **Decision Makers:** LUNA Charts Maintainers
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
One of the primary goals of LUNA Charts is to provide accessible chart components that support modern accessibility standards and assist developers in creating WCAG-compliant data visualizations.
|
||||
|
||||
Charts are graphical user interfaces that contain meaningful information. Depending on the chart type, individual graphical elements such as bars, points, labels, legends, and axes may need to be discoverable by assistive technologies, focusable using the keyboard, or interactable by users.
|
||||
|
||||
The rendering technology therefore has a direct impact on accessibility, developer experience, testing capabilities, maintainability, and future extensibility.
|
||||
|
||||
A rendering technology had to be selected that supports these architectural goals while remaining compatible with modern browsers and Web Components.
|
||||
|
||||
---
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
The following factors influenced this decision:
|
||||
|
||||
* Accessibility
|
||||
* WCAG Compliance
|
||||
* Semantic Structure
|
||||
* Keyboard Navigation
|
||||
* Focus Management
|
||||
* Screen Reader Support
|
||||
* Developer Experience
|
||||
* Maintainability
|
||||
* Browser Compatibility
|
||||
* Long-Term Evolution
|
||||
|
||||
---
|
||||
|
||||
## Considered Alternatives
|
||||
|
||||
| Alternative | Description |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| HTML Elements | Represent charts using standard HTML elements. |
|
||||
| Canvas | Render graphics using the HTML Canvas API. |
|
||||
| Hybrid Rendering | Combine Canvas and SVG depending on the chart type. |
|
||||
| **SVG** | Render all chart graphics using Scalable Vector Graphics. |
|
||||
|
||||
HTML was rejected because it is not designed to represent complex graphical visualizations.
|
||||
|
||||
Canvas was rejected because graphical objects are rendered as pixels rather than DOM elements. This makes individual chart elements difficult to expose to assistive technologies and increases implementation complexity for keyboard interaction and accessibility.
|
||||
|
||||
Hybrid rendering was rejected because it would introduce two rendering models, increasing architectural complexity, testing effort, and maintenance costs.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
All chart visualizations within LUNA Charts are rendered using **Scalable Vector Graphics (SVG)**.
|
||||
|
||||
Each visual element (e.g., bars, lines, points, labels, legends, and axes) is represented as an individual SVG element within the DOM.
|
||||
|
||||
Accessibility information, keyboard navigation, focus management, and interaction are implemented directly on these SVG elements.
|
||||
|
||||
Canvas is not used as a rendering technology for chart components.
|
||||
|
||||
---
|
||||
|
||||
## Rationale
|
||||
|
||||
SVG integrates directly into the browser's Document Object Model (DOM), allowing every graphical element to be individually identified, styled, focused, and enriched with accessibility information.
|
||||
|
||||
This capability aligns with the project's goal of supporting accessible chart implementations by design.
|
||||
|
||||
Using SVG enables the library to:
|
||||
|
||||
* associate semantic information with graphical elements,
|
||||
* support keyboard navigation,
|
||||
* expose meaningful structures to assistive technologies,
|
||||
* apply standard web accessibility techniques,
|
||||
* simplify automated accessibility testing,
|
||||
* integrate naturally with Web Components.
|
||||
|
||||
SVG also provides excellent scalability across different display resolutions without requiring additional rendering logic.
|
||||
|
||||
Although Canvas may provide better rendering performance for extremely large datasets, accessibility and maintainability are considered higher architectural priorities for LUNA Charts.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
* Native DOM representation of graphical elements.
|
||||
* Improved accessibility support.
|
||||
* Better compatibility with assistive technologies.
|
||||
* Simplified keyboard navigation.
|
||||
* Simplified focus management.
|
||||
* Easier automated accessibility testing.
|
||||
* Resolution-independent rendering.
|
||||
* Consistent styling using CSS.
|
||||
* Better integration with Web Components.
|
||||
* Simplified debugging using browser developer tools.
|
||||
|
||||
### Negative
|
||||
|
||||
* Rendering performance may decrease for extremely large datasets.
|
||||
* SVG documents become larger as chart complexity increases.
|
||||
* Very large visualizations may require optimization techniques such as virtualization or data aggregation.
|
||||
|
||||
These trade-offs are considered acceptable because accessibility and maintainability have higher architectural priority than maximum rendering performance.
|
||||
|
||||
---
|
||||
|
||||
## Related TOGAF Phases
|
||||
|
||||
* Architecture Vision (Phase A)
|
||||
* Business Architecture (Phase B)
|
||||
* Information Systems Architecture (Phase C)
|
||||
* Technology Architecture (Phase D)
|
||||
* Opportunities & Solutions (Phase E)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
* LUNA Charts Architecture Wiki
|
||||
* ADR-0002: Technology Stack
|
||||
* ADR-0003: Web Components as Public API
|
||||
* Scalable Vector Graphics (SVG) Specification
|
||||
* Web Content Accessibility Guidelines (WCAG)
|
||||
@@ -0,0 +1,139 @@
|
||||
# ADR-000500: Accessibility as a Cross-Cutting Concern
|
||||
|
||||
* **Status:** Accepted
|
||||
* **Date:** 2026-07-12
|
||||
* **Decision Makers:** LUNA Charts Maintainers
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Accessibility is the primary quality attribute of LUNA Charts.
|
||||
|
||||
The project's objective is not only to render charts but also to support developers in creating accessible data visualizations that align with the Web Content Accessibility Guidelines (WCAG).
|
||||
|
||||
During the architectural design process, accessibility was initially considered as a separate subsystem responsible for validating and enforcing accessibility requirements.
|
||||
|
||||
Further analysis revealed that accessibility affects nearly every architectural layer of the system.
|
||||
|
||||
Rendering, component APIs, configuration, validation, interaction, keyboard navigation, documentation, and testing all contribute to the accessibility of the final chart.
|
||||
|
||||
As a result, accessibility cannot be implemented as an isolated engine without introducing architectural inconsistencies.
|
||||
|
||||
---
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
The following factors influenced this decision:
|
||||
|
||||
* Accessibility by Design
|
||||
* WCAG Compliance
|
||||
* Separation of Concerns
|
||||
* Maintainability
|
||||
* Consistency
|
||||
* Developer Experience
|
||||
* Long-Term Evolution
|
||||
* Testability
|
||||
|
||||
---
|
||||
|
||||
## Considered Alternatives
|
||||
|
||||
| Alternative | Description |
|
||||
| ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
|
||||
| Dedicated Accessibility Engine | A centralized subsystem responsible for accessibility validation and enforcement. |
|
||||
| Accessibility Utilities | A collection of reusable accessibility helper functions. |
|
||||
| **Cross-Cutting Concern** | Accessibility is integrated into every architectural layer where accessibility-related decisions are made. |
|
||||
|
||||
A dedicated accessibility engine was rejected because accessibility cannot be guaranteed after a chart has already been designed or rendered.
|
||||
|
||||
Accessibility decisions must be made continuously throughout the rendering process and component lifecycle.
|
||||
|
||||
Accessibility utilities remain part of the implementation but do not represent the architectural model.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
Accessibility is treated as a **cross-cutting concern** throughout the entire architecture of LUNA Charts.
|
||||
|
||||
Accessibility responsibilities are distributed across multiple architectural modules rather than centralized in a single subsystem.
|
||||
|
||||
Examples include:
|
||||
|
||||
* Public component APIs
|
||||
* TypeScript type definitions
|
||||
* Validation
|
||||
* Rendering
|
||||
* SVG generation
|
||||
* Keyboard interaction
|
||||
* Focus management
|
||||
* Documentation
|
||||
* Automated testing
|
||||
|
||||
Each architectural component is responsible for implementing the accessibility requirements relevant to its own responsibility.
|
||||
|
||||
---
|
||||
|
||||
## Rationale
|
||||
|
||||
Accessibility is not a feature that can be added after rendering has completed.
|
||||
|
||||
Instead, accessibility emerges from many architectural decisions working together.
|
||||
|
||||
Examples include:
|
||||
|
||||
* selecting SVG instead of Canvas,
|
||||
* designing semantic component APIs,
|
||||
* exposing accessible keyboard interaction,
|
||||
* generating meaningful DOM structures,
|
||||
* providing strongly typed configuration,
|
||||
* validating accessibility-related configuration,
|
||||
* documenting accessibility behavior,
|
||||
* verifying accessibility through automated testing.
|
||||
|
||||
Treating accessibility as a cross-cutting concern ensures that accessibility remains an architectural responsibility rather than an isolated implementation detail.
|
||||
|
||||
This approach also aligns with established software architecture principles, where quality attributes such as security, logging, and observability are commonly treated as cross-cutting concerns.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
* Accessibility is considered throughout the entire development process.
|
||||
* Architectural responsibilities remain clearly separated.
|
||||
* Accessibility becomes part of every feature rather than an optional extension.
|
||||
* Better support for WCAG-compliant chart implementations.
|
||||
* Simplified long-term maintenance.
|
||||
* Consistent accessibility behavior across all chart types.
|
||||
* Accessibility can be validated at multiple architectural levels.
|
||||
|
||||
### Negative
|
||||
|
||||
* Accessibility responsibilities are distributed across multiple modules.
|
||||
* Contributors must understand accessibility requirements beyond their immediate implementation.
|
||||
* Architectural reviews must continuously consider accessibility implications.
|
||||
|
||||
These trade-offs are acceptable because accessibility represents the primary quality objective of LUNA Charts.
|
||||
|
||||
---
|
||||
|
||||
## Related TOGAF Phases
|
||||
|
||||
* Architecture Vision (Phase A)
|
||||
* Business Architecture (Phase B)
|
||||
* Information Systems Architecture (Phase C)
|
||||
* Technology Architecture (Phase D)
|
||||
* Implementation Governance (Phase G)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
* LUNA Charts Architecture Wiki
|
||||
* ADR-000300: Web Components as Public API
|
||||
* ADR-000400: SVG as Rendering Technology
|
||||
* Web Content Accessibility Guidelines (WCAG)
|
||||
* WAI-ARIA Authoring Practices Guide
|
||||
Reference in New Issue
Block a user