fix: correct theming variable docs and modernize project docs

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,7 +1,7 @@
 ---
 name: Bug Report
 about: Create a report to help us improve calendar-simple
-title: ""
+title: "[Bug]: "
 labels: bug
 assignees: ""
 ---
@@ -17,16 +17,28 @@ Steps to reproduce the behavior:
 3. Scroll down to '....'
 4. See error
 
+**Minimal reproduction**
+If possible, link a minimal reproduction (StackBlitz, CodeSandbox, or a small repo). This is the fastest way to get a fix.
+
 **Expected behavior**
 A clear and concise description of what you expected to happen.
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+**Screenshots / recordings**
+If applicable, add screenshots or a short recording to help explain your problem.
+
+**Affected view(s)**
+Which calendar view(s) does this affect? (Month, Week, Day, Custom Days, Schedule, or all)
 
 **Environment (please complete the following information):**
 
-- Browser: [e.g. chrome, safari]
-- Component Version: [e.g. 1.0.0]
+- `calendar-simple` version: [e.g. 1.2.0]
+- React version: [e.g. 19.2.0]
+- Browser: [e.g. Chrome 124, Safari 17]
+- OS: [e.g. Windows 11, macOS 14]
+- Is RTL / dark mode / a custom locale enabled? [yes/no — which]
+
+**Did this work in a previous version?**
+If this is a regression, which version last worked?
 
 **Additional context**
-Add any other context about the problem here.
+Add any other context about the problem here (relevant props, event data, console errors).

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,7 +1,7 @@
 ---
 name: Feature Request
-about: Suggest an idea for this project
-title: ""
+about: Suggest an idea or improvement for calendar-simple
+title: "[Feature]: "
 labels: enhancement
 assignees: ""
 ---
@@ -12,8 +12,21 @@ A clear and concise description of what the problem is. Ex. I'm always frustrate
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.
 
+**Which area does this affect?**
+e.g. a specific view (Month/Week/Day/Custom Days/Schedule), theming, accessibility, localization/RTL, events/layout, or the public API.
+
+**Proposed API (if applicable)**
+If your idea introduces or changes props, callbacks, or types, sketch what the API might look like.
+
+```tsx
+// Example usage of the proposed feature
+```
+
 **Describe alternatives you've considered**
 A clear and concise description of any alternative solutions or features you've considered.
 
+**Are you willing to contribute this?**
+Would you be open to opening a PR for this feature? (We're happy to help — see [CONTRIBUTING.md](../../CONTRIBUTING.md).)
+
 **Additional context**
-Add any other context or screenshots about the feature request here.
+Add any other context, mockups, or screenshots about the feature request here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,12 +1,11 @@
-## Pull Request Checklist
-
-- [ ] My code follows the code guidelines of this project
-- [ ] I have updated the documentation accordingly (if applicable)
-- [ ] Tests and builds pass locally
+<!--
+Thanks for contributing to Calendar Simple!
+Please target your PR at the `dev` branch (not `main`) and fill out the sections below.
+-->
 
 ## Description
 
-Please include a summary of the change and which issue is fixed.
+Please include a summary of the change and the motivation behind it.
 
 Fixes # (issue)
 
@@ -16,12 +15,27 @@ Fixes # (issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
 - [ ] Documentation update
-- [ ] This change requires a documentation update
+- [ ] Refactor / chore (no functional change)
+
+## Pull Request Checklist
+
+- [ ] My PR targets the `dev` branch
+- [ ] My code follows the project's coding guidelines (TypeScript, CSS Modules, Luxon for dates)
+- [ ] My commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) spec
+- [ ] I have added or updated tests that cover my change
+- [ ] I have added or updated a Storybook story (if applicable)
+- [ ] I have updated the documentation (`README.md`, `FEATURES.md`) where relevant
+- [ ] All local checks pass: `npm run format:check`, `npm run lint`, `npm test`, `npm run build`
 
 ## How Has This Been Tested?
 
-Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce.
+Please describe the tests you ran to verify your changes and provide instructions to reproduce.
+
+- [ ] Added/updated automated tests (`npm test`)
+- [ ] Verified via Storybook (`npm run storybook`)
+- [ ] Verified via the local playground (`cd playground && npm run dev`)
+- [ ] Verified the build bundle (`npm run build`)
+
+## Screenshots / Recordings
 
-- [ ] Tested via Storybook
-- [ ] Tested via local playground application
-- [ ] Verified build bundle (`npm run build`)
+If your change affects the UI, please add before/after screenshots or a short recording.

CLAUDE.md

@@ -16,8 +16,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Code Quality
 
-- `npm run lint` — Check for ESLint violations
-- `npm run lint:fix` — Fix ESLint violations automatically
+- `npm run lint` — Type-check (`tsc --noEmit`) **and** check for ESLint violations (there is no standalone typecheck script — `lint` covers it)
+- `npm run lint:fix` — Type-check, then fix ESLint violations automatically
 - `npm run format` — Format all code with Prettier
 - `npm run format:check` — Check if code is formatted correctly
 
@@ -64,6 +64,11 @@ Each view is a separate component receiving props via `useCalendarProps()`:
 - **ScheduleView** — Continuous scrollable list of events grouped by date
 - **View** — Wrapper component that renders the appropriate view based on context state
 
+### Loading & Error Handling
+
+- **Loading states**: The `isLoading` prop has two behaviours. With **no events**, it replaces the body with a view-specific skeleton (`src/components/ui/skeleton/` — `MonthSkeleton`, `TimeGridSkeleton`, `ScheduleSkeleton`) or `renderLoading()` if provided. With **events present**, it keeps the calendar visible behind a non-interactive overlay so stale data stays on screen during a refresh.
+- **Error boundary**: `CalendarErrorBoundary` (`src/components/ui/`) wraps the calendar; on a render error it shows an empty `data-testid="calendar-error-boundary"` element and stays silent (the host app's error reporting is expected to handle logging).
+
 ### Prop Distribution Pattern
 
 **`useCalendarProps<T>(localProps: T)`** merges context config with local overrides:
@@ -77,10 +82,11 @@ This enables prop composition: global calendar props + view-specific overrides.
 ### Layout & Styling
 
 - **CSS Modules**: All styles co-located in `Component.module.css` files
-- **Theme system**: `CalendarTheme` type provides color overrides (`default`, `selected`, `today`)
+- **Theme system**: `CalendarTheme` provides `default`/`selected`/`today` color overrides. It is **scheme-aware**: flat keys apply to both schemes, while `dark` / `light` sub-objects take precedence when the resolved scheme matches. `width` / `height` props accept a number (px) or any CSS length string.
 - **Custom classes**: `CalendarClassNames` type allows targeting specific elements
-- **CSS Variables**: Layout dimensions (`--calendar-width`, `--calendar-height`) set at root level
-- **No Tailwind/SCSS**: Vanilla CSS modules only
+- **Color scheme / dark mode**: The `colorScheme` prop (`'light'`/`'dark'`/`'auto'`, default `auto`) is resolved by `useColorScheme` (listens to `prefers-color-scheme`). The resolved value is written as `data-color-scheme="light"|"dark"` on the calendar root, which swaps the CSS custom-property palette defined in `src/styles/variables.css` (`:root` = light, `[data-color-scheme="dark"]` = dark). The `theme` prop still wins over the palette.
+- **RTL**: The `direction` prop (`'ltr'`/`'rtl'`) defaults to `rtl` when `locale` is an RTL locale (ar, he, fa, ur, ps, sd, ckb, yi), else `ltr`. An explicit `direction` overrides auto-detection.
+- **No Tailwind/SCSS**: Vanilla CSS modules + the global `variables.css` palette only
 
 ### Core Hooks (Event & Layout Logic)
 
@@ -90,6 +96,7 @@ This enables prop composition: global calendar props + view-specific overrides.
 - **`useMonthGrid`** — Builds month calendar grid with week rows; handles adjacent month visibility
 - **`useScheduleView`** — Groups events by date for schedule layout; handles sorting
 - **`useResizeObserver`** — Observes container resize; provides width/height for responsive layout
+- **`useColorScheme`** — Resolves the `colorScheme` prop to a concrete `'light'`/`'dark'` value, subscribing to the OS `prefers-color-scheme` media query when `auto`
 
 ### Event Types & Interfaces
 
@@ -167,8 +174,8 @@ Multi-day events use `startDate` and `endDate` without time components; timed ev
 ### CSS Patterns
 
 - **Selectors**: Use CSS classes defined in module; avoid element selectors for encapsulation
-- **Responsive**: Container query style — width/height props + ResizeObserver
-- **Theme colors**: Applied via inline `style` prop or `classNames` override, not CSS variables
+- **Responsive**: Container query style — width/height props + ResizeObserver; built-in breakpoints at 768px (tablet) and 480px (phone)
+- **Color palette**: Light/dark colors live as CSS custom properties in `src/styles/variables.css`, swapped via the `[data-color-scheme="dark"]` attribute selector. Per-event/per-state `theme` prop colors are applied via inline `style`, overriding the palette.
 - **Layout**: Flexbox/Grid; no absolute positioning except for current-time line
 
 ### Git & Commits
@@ -180,20 +187,23 @@ Multi-day events use `startDate` and `endDate` without time components; timed ev
 
 ## Key Files & Directory Structure
 
-| Path                              | Purpose                                                              |
-| --------------------------------- | -------------------------------------------------------------------- |
-| `src/Calendar.tsx`                | Root component; wraps in provider and dispatches to View             |
-| `src/context/CalendarContext.tsx` | State management, reducer, provider, and `useCalendar()` hook        |
-| `src/components/views/`           | View implementations (Month, Week, Day, Schedule, CustomDays)        |
-| `src/components/core/`            | Reusable core components (AllDayBanner, DayColumn, EventItems, etc.) |
-| `src/hooks/`                      | Custom hooks (useEvents, useCalendarProps, layout hooks, etc.)       |
-| `src/utils/date.ts`               | Luxon wrappers and date calculations                                 |
-| `src/utils/common.ts`             | General utilities (event filtering, sorting, etc.)                   |
-| `src/types/`                      | TypeScript interfaces and type definitions                           |
-| `src/constants/`                  | Theme defaults, action types, layout constants                       |
-| `src/styles/`                     | Global CSS variables                                                 |
-| `src/stories/`                    | Storybook stories for all features and QA scenarios                  |
-| `dist/`                           | Build output (auto-generated)                                        |
+| Path                              | Purpose                                                                    |
+| --------------------------------- | -------------------------------------------------------------------------- |
+| `src/Calendar.tsx`                | Root component; wraps in provider and dispatches to View                   |
+| `src/context/CalendarContext.tsx` | State management, reducer, provider, and `useCalendar()` hook              |
+| `src/components/views/`           | View implementations (Month, Week, Day, Schedule, CustomDays)              |
+| `src/components/core/`            | Reusable core components (AllDayBanner, DayColumn, EventItems, etc.)       |
+| `src/components/ui/`              | Popover, `CalendarErrorBoundary`, and loading skeletons (`skeleton/`)      |
+| `src/hooks/`                      | Custom hooks (useEvents, useCalendarProps, useColorScheme, layout hooks)   |
+| `src/utils/date.ts`               | Luxon wrappers and date calculations                                       |
+| `src/utils/common.ts`             | General utilities (event filtering, sorting, etc.)                         |
+| `src/utils/formatting.ts`         | UI string formatting (tooltip text, GMT offset, localized day/month names) |
+| `src/utils/contrast.ts`           | WCAG contrast helpers for accessible theme colors                          |
+| `src/types/`                      | TypeScript interfaces and type definitions                                 |
+| `src/constants/`                  | Theme defaults, action types, layout constants                             |
+| `src/styles/variables.css`        | Global CSS custom properties + light/dark palette (`data-color-scheme`)    |
+| `src/stories/`                    | Storybook stories for all features and QA scenarios                        |
+| `dist/`                           | Build output (auto-generated)                                              |
 
 ## Important Context from Memory
 

CODE_OF_CONDUCT.md

@@ -59,7 +59,10 @@ representative at an online or offline event.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement.
+reported to the community leaders responsible for enforcement by contacting the
+project maintainer privately — open a confidential report via GitHub's
+[private vulnerability reporting](https://github.com/Jaganath-MSJ/CalendarSimple/security/advisories/new)
+or reach out to [@Jaganath-MSJ](https://github.com/Jaganath-MSJ).
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the