CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to LUNA Charts
+
+Thank you for considering a contribution to LUNA Charts! This document explains how the project is governed, what's expected of a contribution, and how to get your change through review.
+
+Before contributing, please also read our [Code of Conduct](./.github/CODE_OF_CONDUCT.md).
+
+## Project Status
+
+LUNA Charts is currently in its **groundwork phase** — foundational architecture, tooling, and testing infrastructure are being established before chart components are built out. Check the [Roadmap](./docs/src/content/docs/getting-started/roadmap.mdx) to see what's currently in scope.
+
+## How the Project Is Governed
+
+LUNA Charts balances open community contribution with a documented architecture. In short:
+
+- **The architecture is the authoritative source for implementation decisions** — it's documented under [`docs/.../architecture/adm`](./docs/src/content/docs/architecture/adm) (Architecture Development Method) and [`docs/.../architecture/adr`](./docs/src/content/docs/architecture/adr) (Architecture Decision Records)
+- **Contributions are reviewed on three levels**: automated checks (types, linting, tests, accessibility), architectural compliance (does it fit the documented architecture?), and general project quality (readability, maintainability, documentation)
+- **A Pull Request can be rejected even if all automated checks pass** — for example, if it introduces an unnecessary public API change, bypasses accessibility mechanisms, or conflicts with a documented architectural decision
+- Community members can propose architectural changes, but such changes only become official once the relevant ADR/ADM documentation has been updated to reflect them (see [Architecture Change Management](./docs/src/content/docs/architecture/adm/architecture-change-management.mdx))
+
+If you're planning a larger change, especially one that touches the public API, rendering approach, or accessibility behavior, please open an issue or discussion first so it can be reviewed against the architecture before you invest time in an implementation.
+
+## Getting Started
+
+1. Fork the repository and clone your fork
+2. Install dependencies:
+
+   ```bash
+   pnpm install
+   ```
+
+3. Requirements: Node.js `>= 22.0.0`, pnpm `11.11.0` (via Corepack), and Docker (for component/browser tests)
+
+## Making a Change
+
+1. Create a branch from `main` with a descriptive name (e.g. `fix/axis-label-overflow`, `docs/update-technology-architecture`)
+2. Make your change
+3. Run the checks locally before opening a PR:
+
+   ```bash
+   pnpm lint
+   pnpm test:unit
+   pnpm test:component   # runs inside a Docker/Playwright container
+   pnpm test             # runs both of the above
+   ```
+  
+4. If your change affects published package behavior (bug fix, feature, breaking change), add a changeset:
+
+   ```bash
+   pnpm changeset
+   ```
+
+   Documentation-only or internal tooling changes generally don't need a changeset — if you're unsure, mention it in your PR description and a maintainer will advise.
+
+## Pull Request Guidelines
+
+- Keep PRs focused on a single concern where possible — smaller PRs are easier to review against the architecture
+- Describe **what** changed and **why**, not just what the diff shows
+- If your change affects accessibility behavior, explain how it was verified (e.g. which axe-core checks or manual screen-reader testing was done)
+- If your change touches an area covered by an existing ADR, reference it and note whether the ADR needs a corresponding update
+- Automated testing (unit, accessibility, linting) must pass before a PR can be merged
+
+## Documentation Changes
+
+Documentation lives in `docs/` (Starlight) and is a first-class contribution — fixing unclear wording, expanding examples, or correcting an outdated ADR/ADM page is just as valuable as a code change.
+
+If your code change makes a documented architectural statement incorrect (for example, changing a technology choice or the repository structure), please update the relevant ADR/ADM page in the same PR, including a short **Change Log** entry at the end of that document explaining what changed and why. Keeping documentation in sync with implementation is part of the review criteria described above.
+
+## Reporting Bugs and Suggesting Features
+
+Please open an issue with:
+
+- A clear description of the problem or suggestion
+- Steps to reproduce (for bugs), including browser/OS if relevant to rendering or accessibility
+- What you expected to happen vs. what actually happened
+
+## Questions
+
+If anything here is unclear, feel free to open a discussion or issue — improving this guide based on real contributor questions is welcome too.

README.md

@@ -1,3 +1,85 @@
-# LUNA-Charts
+# LUNA Charts
 
-LUNA Charts is a reusable, developer-friendly charting library designed to make accessible, WCAG-oriented data visualization the default rather than an afterthought.
+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.
+
+## Why LUNA Charts
+
+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
+- **SVG-based rendering** — inspectable, stylable, and screen-reader-friendly output instead of an opaque canvas
+
+## Tech Stack
+
+| Area | Technology |
+|---|---|
+| Component framework | [Stencil](https://stenciljs.com) (compiles to standard Web Components) |
+| Language | TypeScript |
+| Package manager | pnpm (monorepo workspaces) |
+| Unit & component testing | [Vitest](https://vitest.dev), with [Playwright](https://playwright.dev) as the browser provider |
+| Accessibility testing | axe-core |
+| Documentation | [Starlight](https://starlight.astro.build) |
+| Component explorer | Storybook |
+| Linting & formatting | ESLint, Prettier |
+| Release management | [Changesets](https://github.com/changesets/changesets) |
+
+The full set of architecture decisions behind these choices is documented in [`docs/.../architecture/adr`](./docs/src/content/docs/architecture/adr) and the broader [Architecture Development Method (ADM) documentation](./docs/src/content/docs/architecture/adm).
+
+## Project Structure
+
+```text
+luna-charts/
+│
+├── packages/
+│   └── luna-charts/        # The library itself (Stencil components, Storybook)
+│
+├── docs/                    # Architecture docs, ADRs, guides (Starlight)
+│
+├── examples/                # Usage examples (framework integrations)
+│
+├── .changeset/               # Release/versioning configuration
+│
+└── .github/                  # Community health files (Code of Conduct, etc.)
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js `>= 22.0.0`
+- pnpm `11.11.0` (see `devEngines` in `package.json`; pnpm will be downloaded automatically via Corepack if missing)
+- Docker (required for running component/browser tests locally, see below)
+
+### Installation
+
+```bash
+git clone <this-repository>
+cd luna-charts
+pnpm install
+```
+
+### Common commands
+
+| Command | Description |
+|---|---|
+| `pnpm lint` | Run ESLint across the repository |
+| `pnpm format` | Format all files with Prettier |
+| `pnpm test:unit` | Run unit tests for the `luna-charts` package |
+| `pnpm test:component` | Run component/browser tests inside the containerized Playwright environment |
+| `pnpm test` | Run the full test suite (unit + component) |
+| `pnpm changeset` | Record a changeset for your change (required for any user-facing change) |
+
+Component and browser tests run inside Docker (`docker-compose.test.yaml`) to guarantee a reproducible browser environment across all contributors and CI — you don't need Playwright browsers installed locally.
+
+## Documentation
+
+- **Architecture documentation**: see `docs/` — includes the full Architecture Development Method (ADM) documentation (vision, business architecture, technology architecture, governance, migration planning) and all Architecture Decision Records (ADRs)
+- **Contributing**: see [CONTRIBUTING.md](./CONTRIBUTING.md)
+- **Code of Conduct**: see [.github/CODE_OF_CONDUCT.md](./.github/CODE_OF_CONDUCT.md)
+
+## License
+
+LUNA Charts is licensed under the [GNU Lesser General Public License v3.0 (LGPL-3.0)](./LICENSE).