README.md

@@ -2,7 +2,7 @@
 
 LUNA Charts is a reusable, developer-friendly charting library designed to make accessible, WCAG-oriented data visualization the default rather than an afterthought.
 
-> **Project status:** Groundwork phase. Core architecture and tooling are in place; production-ready chart components (starting with `BarChart`) are still in development. See the [Roadmap](./docs/src/content/docs/getting-started/roadmap.mdx) for details.
+> **Project status:** Foundation phase. This milestone focuses on setting up the technical core of the component library. The goal is to build an automated, testable, and documented environment for efficient StencilJS component development. (starting with `BarChart`) are still in development. See the [Roadmap](./docs/src/content/docs/getting-started/roadmap.mdx) for details.
 
 ## Preface & Repository Mirror Notice
 
@@ -17,7 +17,7 @@ Please be aware of our repository structure:
 Most charting libraries treat accessibility as an add-on. LUNA Charts builds it in from the start:
 
 * **Accessible by default** — components are designed and tested against WCAG guidance from day one, not patched in afterward
-* **Framework-agnostic** — built as standard Web Components (Stencil), usable in React, Vue, Angular, Svelte, or plain HTML
+* **Framework-agnostic** — built as standard Web Components (Stencil), usable in React, Vue or Angular.
 * **SVG-based rendering** — inspectable, stylable, and screen-reader-friendly output instead of an opaque canvas
 
 ## Tech Stack
@@ -104,4 +104,4 @@ Component and browser tests run inside Docker (`docker-compose.test.yaml`), base
 
 ## License
 
-LUNA Charts is licensed under the [GNU Lesser General Public License v3.0 (LGPL-3.0)](./LICENSE).
+LUNA Charts is licensed under the [GNU Lesser General Public License v3.0 (LGPL-3.0)](./LICENSE).

docs/src/content/docs/architecture/adr/000600-declarative-component-api.mdx

@@ -0,0 +1,111 @@
+---
+title: Declarative Component API
+description: "LUNA Charts exposes chart functionality through a strongly typed, component-based declarative API."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-08-31
+* **Decision Makers:** LUNA Charts Maintainers
+
+---
+
+## Context
+
+LUNA Charts must provide a developer-facing API that is easy to understand, strongly typed, framework-agnostic, and capable of enforcing accessibility and validation rules consistently.
+
+Several API models were considered, including a pure domain-specific language (DSL), JSON-based configuration, and a component-based API. The architecture also requires a controlled system boundary so that developers provide chart data and configuration without directly interfering with internal processing.
+
+The Information Systems Architecture defines chart-specific components such as `<BarChart />`, `<LineChart />`, and `<PieChart />`, each with its own strongly typed data model. A single controlled entry point is used for developer interaction, while validation, configuration resolution, accessibility enforcement, and rendering remain under the ownership of the library.
+
+---
+
+## Decision Drivers
+
+* Developer Experience
+* Type Safety
+* Framework Agnosticism
+* Accessibility
+* Maintainability
+* Predictable Behavior
+* Clear System Boundaries
+* Simplicity
+
+---
+
+## Considered Alternatives
+
+| Alternative | Description |
+| ----------- | ----------- |
+| Component-based declarative API | Developers configure charts through strongly typed chart components and their properties. |
+| JSON-based API | Developers provide chart definitions as JSON objects that are interpreted by the library. |
+| Pure DSL | A dedicated textual or configuration language is used to describe charts. |
+| Imperative API | Developers directly invoke rendering and processing operations. |
+
+The component-based declarative API was selected because it provides a natural developer experience, strong TypeScript integration, and a clear boundary between public inputs and internal processing. JSON and pure DSL approaches would require an additional abstraction layer and provide less natural integration with component-based frontend ecosystems. An imperative API would expose more implementation details and weaken the controlled processing model.
+
+---
+
+## Decision
+
+LUNA Charts uses a **component-based declarative API** as its primary developer interaction model.
+
+Developers interact with chart-specific components such as:
+
+* `<BarChart />`
+* `<LineChart />`
+* `<PieChart />`
+
+Each chart component exposes a strongly typed data and configuration model.
+
+The public API is the controlled entry point into the library. Developers provide structured data and configuration, while the internal processing pipeline remains under the control of LUNA Charts.
+
+---
+
+## Rationale
+
+A component-based declarative API aligns the developer experience with modern web component and framework ecosystems while allowing TypeScript to express valid data and configuration structures.
+
+The model also supports LUNA Charts' architectural goals:
+
+* Developers describe the desired chart rather than controlling rendering steps.
+* Type-safe contracts make invalid inputs more explicit.
+* Internal validation and accessibility enforcement remain centrally controlled.
+* The same conceptual API can be consumed through framework-specific integrations.
+* The API remains predictable and maintainable as additional chart types are introduced.
+
+---
+
+## Consequences
+
+### Positive
+
+* Clear and approachable developer API.
+* Strong TypeScript integration and type safety.
+* Declarative usage reduces exposure to internal implementation details.
+* Consistent integration model across supported frontend ecosystems.
+* Internal accessibility and validation rules remain centrally enforceable.
+* New chart types can follow the same API pattern.
+
+### Negative
+
+* Developers have less low-level control over internal processing.
+* Custom behavior outside the defined API requires changes by the LUNA Charts maintainers.
+* Strong API constraints can make unusual use cases harder to support.
+* Each chart type requires a dedicated typed model.
+
+---
+
+## Related TOGAF Phases
+
+* Architecture Vision (Phase A)
+* Business Architecture (Phase B)
+* Information Systems Architecture (Phase C)
+* Technology Architecture (Phase D)
+
+---
+
+## References
+
+* [Information Systems Architecture](../adm/information-systems-architecture/)
+* [Technology Architecture](../adm/technology-architecture/)
+* [ADR-000300 – Web Components as Public API](./000300-web-components-as-public-api/)

docs/src/content/docs/architecture/adr/000700-no-plugin-or-extension-system.mdx

@@ -0,0 +1,102 @@
+---
+title: No Plugin or Extension System
+description: "LUNA Charts does not provide a consumer-facing plugin or extension mechanism."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-08-31
+* **Decision Makers:** LUNA Charts Maintainers
+
+---
+
+## Context
+
+LUNA Charts is designed as an opinionated charting library with a controlled internal processing pipeline. Accessibility, validation, configuration resolution, and rendering are library-owned responsibilities.
+
+An extension mechanism could allow consumers to modify internal behavior or add functionality without changing the core library. However, unrestricted extensibility could also introduce inconsistent behavior, weaken accessibility guarantees, and increase architectural and maintenance complexity.
+
+The Information Systems Architecture therefore defines LUNA Charts as a closed system with a strict input boundary and no external plugin or extension mechanism.
+
+---
+
+## Decision Drivers
+
+* Accessibility
+* Maintainability
+* Predictable Behavior
+* Simplicity
+* Quality Control
+* Security
+* Developer Experience
+
+---
+
+## Considered Alternatives
+
+| Alternative | Description |
+| ----------- | ----------- |
+| No plugin or extension system | Consumers use only the public API provided by LUNA Charts. |
+| Consumer plugin system | Consumers can register plugins that modify or extend library behavior. |
+| Extension hooks | Consumers can inject custom logic into selected processing stages. |
+| Fully extensible architecture | Internal layers and chart types can be extended directly by consumers. |
+
+The no-plugin approach was selected because the library's accessibility and rendering behavior must remain centrally controlled. Plugin systems and extension hooks would increase the number of execution paths that must be validated and supported.
+
+---
+
+## Decision
+
+LUNA Charts **does not provide a consumer-facing plugin or extension system**.
+
+Consumers interact with the library exclusively through its defined public API. Internal processing stages cannot be replaced, intercepted, or extended by consumers.
+
+New chart types, accessibility behavior, rendering capabilities, and other architectural functionality are implemented and maintained within the LUNA Charts project itself.
+
+---
+
+## Rationale
+
+LUNA Charts is intentionally opinionated. Its value depends not only on providing chart visualizations but also on providing predictable and accessible implementations.
+
+Allowing consumers to modify internal behavior would make it harder to guarantee consistent accessibility and quality. A closed architecture keeps the processing pipeline deterministic and allows maintainers to evolve the implementation under a single quality and accessibility model.
+
+This decision also avoids the additional API surface, compatibility requirements, documentation burden, and support obligations associated with a plugin ecosystem.
+
+---
+
+## Consequences
+
+### Positive
+
+* Centralized control over accessibility behavior.
+* Predictable and deterministic processing.
+* Smaller public API surface.
+* Lower maintenance and compatibility burden.
+* Easier quality assurance and testing.
+* No plugin ecosystem needs to be designed or maintained.
+* Reduced risk that consumer extensions bypass architectural safeguards.
+
+### Negative
+
+* Consumers cannot add custom processing stages.
+* Consumers cannot introduce custom chart types through plugins.
+* Unusual use cases may require changes to LUNA Charts itself.
+* The architecture places more responsibility on the maintainers to evolve the library.
+
+---
+
+## Related TOGAF Phases
+
+* Architecture Vision (Phase A)
+* Business Architecture (Phase B)
+* Information Systems Architecture (Phase C)
+* Technology Architecture (Phase D)
+
+---
+
+## References
+
+* [Business Architecture](../adm/business-architecture/)
+* [Information Systems Architecture](../adm/information-systems-architecture/)
+* [Technology Architecture](../adm/technology-architecture/)
+* [ADR-000500 – Accessibility as a Cross-Cutting Concern](./000500-accessibility-as-a-cross-cutting-concern/)

docs/src/content/docs/architecture/adr/000800-single-package-distribution-model.mdx

@@ -0,0 +1,101 @@
+---
+title: Single-Package Distribution Model
+description: "LUNA Charts is distributed as one unified package rather than separate packages per chart type or internal module."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-08-31
+* **Decision Makers:** LUNA Charts Maintainers
+
+---
+
+## Context
+
+LUNA Charts is developed as a monorepo and contains multiple internal modules and chart types. The repository structure must remain flexible for implementation while the public distribution model should remain simple for consumers.
+
+The architecture distinguishes between internal implementation boundaries and the public package boundary. Chart types such as BarChart, LineChart, and PieChart are not intended to become independent npm packages.
+
+LUNA Charts is intended to be consumed as one coherent, accessibility-focused library.
+
+---
+
+## Decision Drivers
+
+* Developer Experience
+* Simplicity
+* Accessibility
+* Maintainability
+* Consistent API Behavior
+* Framework Agnosticism
+* Release Management
+* Reduced Package Fragmentation
+
+---
+
+## Considered Alternatives
+
+| Alternative | Description |
+| ----------- | ----------- |
+| Single package | All public chart functionality is distributed through one LUNA Charts package. |
+| Package per chart type | Each chart type is published as an independent npm package. |
+| Package per internal module | Internal modules such as core and charts are independently published. |
+| Monorepo with multiple public packages | The repository remains a monorepo while several independently versioned packages are published. |
+
+The single-package model was selected because the library is intended to provide one coherent developer experience and one consistent accessibility model. Publishing chart types or internal modules separately would increase package, versioning, dependency, and compatibility complexity.
+
+---
+
+## Decision
+
+LUNA Charts is distributed as **one unified public npm package**.
+
+Chart types, core functionality, accessibility mechanisms, and other implementation modules remain internal parts of the distribution and are not published as separate public packages.
+
+Framework-specific integrations generated from the Stencil-based implementation are considered part of the overall LUNA Charts distribution model rather than independent chart packages.
+
+---
+
+## Rationale
+
+A single package gives consumers one installation target and one coherent version of the library.
+
+It also supports the project's accessibility-first architecture. Accessibility enforcement, validation, rendering, and chart functionality can evolve together without requiring consumers to coordinate compatible versions of several packages.
+
+The monorepo therefore provides internal organizational and architectural separation without exposing unnecessary package fragmentation to consumers.
+
+---
+
+## Consequences
+
+### Positive
+
+* Simple installation and onboarding.
+* One public version and release lifecycle.
+* Consistent accessibility and API behavior across chart types.
+* No dependency coordination between separate chart packages.
+* Easier documentation and support.
+* Internal modules can evolve without becoming public package contracts.
+
+### Negative
+
+* Consumers cannot install only an individual chart package.
+* The public package may contain functionality that a particular consumer does not use.
+* A change in one part of the library may require a release of the unified package.
+* Package-level boundaries cannot be used to independently version individual chart types.
+
+---
+
+## Related TOGAF Phases
+
+* Architecture Vision (Phase A)
+* Business Architecture (Phase B)
+* Information Systems Architecture (Phase C)
+* Technology Architecture (Phase D)
+
+---
+
+## References
+
+* [Repository Structure](./000100-repository-structure/)
+* [Technology Architecture](../adm/technology-architecture/)
+* [Information Systems Architecture](../adm/information-systems-architecture/)

docs/src/content/docs/architecture/adr/000900-multi-layer-testing-strategy.mdx

@@ -0,0 +1,116 @@
+---
+title: Multi-Layer Testing Strategy
+description: "LUNA Charts uses multiple complementary quality assurance layers with automated release gates."
+---
+
+* **Status:** Accepted
+* **Date:** 2026-08-31
+* **Decision Makers:** LUNA Charts Maintainers
+
+---
+
+## Context
+
+LUNA Charts is an accessibility-focused charting library whose output must be correct, stable, and usable across supported environments.
+
+No single testing technique can adequately validate the library. Functional correctness, accessibility constraints, DOM and SVG structure, visual stability, code quality, and real-world usability require different forms of verification.
+
+The Technology Architecture therefore defines a multi-layer quality assurance model covering functional tests, accessibility tests, linting, visual regression testing, and usability testing. Automated checks are combined with release gating so that defined quality requirements are evaluated before releases.
+
+---
+
+## Decision Drivers
+
+* Accessibility
+* Reliability
+* Visual Stability
+* Maintainability
+* Developer Experience
+* Reproducibility
+* Release Quality
+* Automation
+
+---
+
+## Considered Alternatives
+
+| Alternative | Description |
+| ----------- | ----------- |
+| Multi-layer testing strategy | Multiple complementary test and quality layers are combined into release gates. |
+| Unit tests only | Functional behavior is validated primarily through unit tests. |
+| End-to-end tests only | Browser-based tests are used as the primary validation mechanism. |
+| Manual testing only | Quality is validated through manual verification before releases. |
+
+The multi-layer approach was selected because each alternative alone leaves important quality risks uncovered. Unit tests do not sufficiently validate browser behavior or accessibility, while browser tests alone are less efficient for isolated logic. Manual testing remains valuable for usability but cannot provide sufficient automated regression coverage.
+
+---
+
+## Decision
+
+LUNA Charts uses a **multi-layer testing and quality assurance strategy**.
+
+The strategy includes:
+
+1. **Functional testing** for core logic and processing behavior.
+2. **Accessibility testing** for machine-verifiable accessibility requirements and ARIA structure.
+3. **Code quality checks** including linting and formatting-related quality controls.
+4. **Visual regression testing** to detect unintended visual and structural changes.
+5. **Usability testing** for relevant minor and major releases and significant user-facing changes.
+6. **Release gates** that prevent releases when required automated quality checks fail.
+
+Browser-based tests use a reproducible test execution environment so that local and CI execution can use a controlled environment.
+
+---
+
+## Rationale
+
+LUNA Charts has accessibility and visual output as central quality attributes. These cannot be reliably validated through unit tests alone.
+
+A layered strategy assigns each quality concern to an appropriate verification mechanism:
+
+* Unit tests provide fast feedback for logic.
+* Accessibility tests validate machine-verifiable accessibility constraints.
+* Linting protects code and architectural consistency.
+* Visual regression tests protect rendered output and relevant DOM structure.
+* Usability testing evaluates aspects that cannot be reliably automated.
+* Release gates ensure required automated checks are completed before distribution.
+
+The approach balances fast developer feedback with stronger release confidence.
+
+---
+
+## Consequences
+
+### Positive
+
+* Higher confidence in functional correctness.
+* Accessibility becomes part of the quality process rather than a final manual check.
+* Visual regressions can be detected automatically.
+* Release quality is enforced consistently.
+* Different test types can remain focused on the problems they are best suited to detect.
+* Reproducible browser test execution reduces environment-related differences between developers and CI.
+
+### Negative
+
+* More tooling and infrastructure must be maintained.
+* Test execution can require more time and resources than unit tests alone.
+* Visual regression tests require maintenance when intentional visual changes occur.
+* Usability testing introduces manual effort.
+* Release gates can delay releases when infrastructure or tests fail.
+
+---
+
+## Related TOGAF Phases
+
+* Architecture Vision (Phase A)
+* Technology Architecture (Phase D)
+* Opportunities and Solutions (Phase E)
+* Implementation Governance (Phase G)
+
+---
+
+## References
+
+* [Technology Architecture](../adm/technology-architecture/)
+* [Testing and Quality Strategy](../adm/technology-architecture/#6-testing--quality-strategy)
+* [ADR-000500 – Accessibility as a Cross-Cutting Concern](./000500-accessibility-as-a-cross-cutting-concern/)