@tzslot/theme 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plinthworks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# tzslot
+
+Date and time pickers that know what daylight saving does.
+
+Most pickers — flatpickr, Air Datepicker, nearly every Angular wrapper — are
+built on `Date`, which has no notion of an IANA time zone. They will let
+someone book 02:30 on a morning when 02:30 does not happen, or on one when it
+happens twice, and store whichever reading the browser guessed. They call a
+night shift from 23:00 to 05:00 six hours on the night it lasts seven.
+
+tzslot is built on [Temporal](https://tc39.es/proposal-temporal/docs/). It
+shows the hour that does not exist, offers both readings of the one that
+happens twice, and says in words when an interval lasts something other than
+what the clock faces suggest.
+
+## Packages
+
+| | |
+|---|---|
+| `@tzslot/core` | The arithmetic. No DOM, no framework — usable on a server too. |
+| `@tzslot/dom` | Every widget, in plain DOM. Works in any framework, or none. |
+| `@tzslot/angular` | Angular components over `@tzslot/dom`: signals, forms, zoneless or not. Angular 18 to 21. |
+| `@tzslot/theme` | Optional. CSS (or Sass) setting the widgets' colours; light, dark, high contrast, a Tailwind v4 bridge. |
+
+The widgets live in `@tzslot/dom`; a framework package only translates its own
+idioms into calls on them. A behaviour fixed there is fixed everywhere.
+
+## The widgets
+
+| Angular | Plain DOM | What it chooses |
+|---|---|---|
+| `<tz-calendar>` | `createCalendar` | a day — month and year views, keyboard, Today / Clear |
+| `<tz-multi-date>` | `createMultiDate` | several days, not necessarily adjacent |
+| `<tz-date-field>` | `createDateField` | a day, from a field that opens a panel, anchored or centred |
+| `<tz-date-range>` | `createDateRange` | two days, refusing a range across a closed one |
+| `<tz-time-slots>` | `createTimeSlots` | a moment on one day: the skipped hour struck through, the repeated one offered twice |
+| `<tz-datetime-range>` | `createDateTimeRange` | an interval with a time at both ends, and the hour it hides |
+| `<tz-daily-range>` | `createDailyRange` | a range of days with the same hours on each, overnight allowed |
+
+`renderCell` puts a price, places left or your own class on any day.
+
+## Angular
+
+```bash
+npm install @tzslot/angular @tzslot/theme
+```
+
+```jsonc
+// angular.json → build.options
+"styles": ["@tzslot/theme/tzslot.css", "src/styles.css"]
+```
+
+```ts
+import { Component, signal } from '@angular/core';
+import { Calendar, TimeSlotPicker, provideTzslotMessages, FR } from '@tzslot/angular';
+import type { Instant, PlainDate } from '@tzslot/core';
+
+@Component({
+  imports: [Calendar, TimeSlotPicker],
+  template: `
+    <tz-calendar [(value)]="day" [buttons]="['today', 'clear']" />
+    @if (day(); as d) {
+      <tz-time-slots [date]="d" timeZone="Europe/Paris" [(value)]="moment" />
+    }
+  `,
+})
+export class Booking {
+  readonly day = signal<PlainDate | null>(null);
+  readonly moment = signal<Instant | null>(null);
+}
+
+// French everywhere: bootstrapApplication(App, { providers: [provideTzslotMessages(FR)] })
+```
+
+Every component is a `ControlValueAccessor` — `formControlName`, `ngModel` and
+`[(value)]` all work — and takes `valueAs="date"` to keep an existing
+`FormControl<Date>` untouched. See `docs/migrating-from-flatpickr.md`.
+
+## Without a framework
+
+```bash
+npm install @tzslot/dom @tzslot/theme
+```
+
+```js
+import { createCalendar } from '@tzslot/dom';
+import { Temporal } from '@tzslot/core';
+import '@tzslot/theme';
+
+const calendar = createCalendar(document.querySelector('#day'), {
+  onChange: (day) => console.log(day?.toString()),
+});
+calendar.update({ min: Temporal.Now.plainDateISO() });
+```
+
+Each `create…` returns an instance with `update`, `clear` and `destroy`.
+Layout CSS is injected once; pass `injectStyles: false` under a strict
+Content-Security-Policy and include the exported `*_CSS` strings yourself.
+
+## The arithmetic
+
+```ts
+import { getDaySlots, getDailyWindows } from '@tzslot/core';
+
+getDaySlots('2026-10-25', 'Europe/Paris').filter((s) => s.time.hour === 2);
+// 02:00 is ambiguous: offsets ['+02:00', '+01:00'], two instants an hour apart
+
+getDailyWindows('2026-10-23', '2026-10-26', '22:00', '06:00', 'Europe/Paris').minutes / 60;
+// 33 — four night shifts, one of them nine hours long
+```
+
+Store an instant, never a wall time: it is unambiguous everywhere and
+survives a change of zone, of the rules, and being read back next year.
+
+## Theming
+
+Nine palette colours, each `light-dark(light, dark)`. `data-theme="dark"` on
+any element themes everything inside it; `--tz-accent` on any element
+recolours the selection, the range tint and the focus ring beneath it.
+`@tzslot/theme/contrast.css` follows `prefers-contrast: more`, and
+`@tzslot/theme/tailwind.css` maps the palette to a Tailwind v4 theme. From
+Sass, `@use '@tzslot/theme/tzslot' with ($accent: …)`. All of it in
+`docs/customising.md`.
+
+## Browsers
+
+Temporal is used natively where it exists and polyfilled where it does not.
+The polyfill is a static import, so a bundle carries it for every visitor —
+about 19 kB gzipped. There is deliberately no fallback to `Date`: it would
+bring back the exact bug this library exists to fix.
+
+The theme uses `light-dark()` and `color-mix()`: Chrome 123, Safari 17.5,
+Firefox 120 and later.
+
+## Development
+
+```bash
+npm install
+npm start            # playground: http://localhost:4500/playground/index.html
+npm test             # 263 tests, against real time zone rules
+npm run typecheck
+npm run build        # every package into its own dist/, ready to publish
+```
+
+The playground has a page per way of using it: Angular, Tailwind, and plain
+DOM.
+
+## Licence
+
+[MIT](LICENSE). Free to use, in personal and commercial projects alike, free
+to copy, modify and redistribute; keep the copyright notice. It comes with no
+warranty.

package/contrast.css

@@ -0,0 +1,61 @@
+/**
+ * @tzslot/theme/contrast.css — more contrast, for people who need it.
+ *
+ *   import '@tzslot/theme';
+ *   import '@tzslot/theme/contrast.css';
+ *
+ * Applies on its own when the system asks for more contrast
+ * (prefers-contrast: more), and on request with data-contrast="more" on any
+ * element. data-contrast="normal" on the root opts the page out of the
+ * automatic version.
+ *
+ * A separate axis from light and dark, not a third theme: someone who needs
+ * more contrast still has a preference between the two.
+ *
+ * Contrast: text and the selection meet WCAG AAA (7:1); faded states that
+ * carry meaning (outside the month, unavailable) stay above 4.5:1.
+ */
+
+@media (prefers-contrast: more) {
+  :root:not([data-contrast='normal']) {
+    --tz-bg: light-dark(#ffffff, #000000);
+    --tz-bg-raised: light-dark(#e4e4e7, #27272a);
+    --tz-fg: light-dark(#000000, #ffffff);
+    --tz-fg-muted: light-dark(#27272a, #e4e4e7);
+    --tz-border: light-dark(#000000, #ffffff);
+    --tz-accent: light-dark(#1d3fb8, #ffd400);
+    --tz-accent-fg: light-dark(#ffffff, #000000);
+    --tz-danger: light-dark(#8b0000, #ff8a8a);
+    --tz-warning: light-dark(#6b3a00, #ffd27a);
+    --tz-cal-outside-opacity: 0.7;
+    --tz-slot-missing-opacity: 0.75;
+    --tz-slot-unavailable-opacity: 0.75;
+    --tz-focus-ring: 3px solid var(--tz-fg);
+  }
+}
+
+[data-contrast='more'] {
+  --tz-bg: light-dark(#ffffff, #000000);
+  --tz-bg-raised: light-dark(#e4e4e7, #27272a);
+  --tz-fg: light-dark(#000000, #ffffff);
+  --tz-fg-muted: light-dark(#27272a, #e4e4e7);
+  --tz-border: light-dark(#000000, #ffffff);
+  --tz-accent: light-dark(#1d3fb8, #ffd400);
+  --tz-accent-fg: light-dark(#ffffff, #000000);
+  --tz-danger: light-dark(#8b0000, #ff8a8a);
+  --tz-warning: light-dark(#6b3a00, #ffd27a);
+  --tz-cal-outside-opacity: 0.7;
+  --tz-slot-missing-opacity: 0.75;
+  --tz-slot-unavailable-opacity: 0.75;
+  --tz-focus-ring: 3px solid var(--tz-fg);
+}
+
+/* Borders on every cell, so the grid reads without relying on colour. */
+:is([data-contrast='more']) :is(.tz-cal__day, .tz-range__day):not(:disabled) {
+  box-shadow: inset 0 0 0 1px var(--tz-border);
+}
+@media (prefers-contrast: more) {
+  :root:not([data-contrast='normal']) :is(.tz-cal__day, .tz-range__day):not(:disabled) {
+    box-shadow: inset 0 0 0 1px var(--tz-border);
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@tzslot/theme",
+  "version": "0.1.0-beta.0",
+  "description": "An optional stylesheet for the tzslot components. Plain CSS, no framework.",
+  "license": "MIT",
+  "main": "./tzslot.css",
+  "exports": {
+    ".": "./tzslot.css",
+    "./tzslot.css": "./tzslot.css",
+    "./contrast.css": "./contrast.css",
+    "./tzslot.scss": "./tzslot.scss",
+    "./tzslot": {
+      "sass": "./tzslot.scss",
+      "default": "./tzslot.css"
+    },
+    "./tailwind.css": "./tailwind.css"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "sass": "./tzslot.scss",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plinthworks/tzslot.git",
+    "directory": "packages/theme"
+  },
+  "homepage": "https://github.com/plinthworks/tzslot#readme",
+  "bugs": {
+    "url": "https://github.com/plinthworks/tzslot/issues"
+  },
+  "keywords": [
+    "date",
+    "time",
+    "datepicker",
+    "timezone",
+    "dst",
+    "temporal",
+    "calendar",
+    "time-slots"
+  ]
+}

package/tailwind.css

@@ -0,0 +1,55 @@
+/**
+ * @tzslot/theme/tailwind.css — the widgets in your Tailwind v4 theme.
+ *
+ * In the CSS file that imports Tailwind, after it:
+ *
+ *   @import "tailwindcss";
+ *   @import "@tzslot/theme";
+ *   @import "@tzslot/theme/tailwind.css";
+ *
+ * It has to go through Tailwind, not beside it: Tailwind v4 only emits the
+ * theme variables something references, and this file is what references
+ * them. Imported on its own, it would point at variables that do not exist.
+ *
+ * ── What it maps ────────────────────────────────────────────────────────────
+ *
+ *   surfaces and text  → the zinc scale
+ *   accent             → your --color-primary-600 / -400 if your @theme has
+ *                        them, Tailwind's blue otherwise
+ *   danger / warning   → red / amber
+ *   font, radius       → --font-sans, --radius-md
+ *
+ * Another grey (slate, neutral, stone…) is a matter of overriding the five
+ * surface lines below with your own scale.
+ *
+ * ── Dark mode ───────────────────────────────────────────────────────────────
+ *
+ * Tailwind's default dark mode follows the system, and so do the widgets:
+ * nothing to do. With the class strategy (a .dark class toggled by your
+ * app), the .dark rule below reaches them; add
+ *
+ *   :root { --tz-color-scheme: light; }
+ *
+ * so that no .dark means light even when the system is dark.
+ */
+
+:root {
+  --tz-bg: light-dark(var(--color-white), var(--color-zinc-900));
+  --tz-bg-raised: light-dark(var(--color-zinc-100), var(--color-zinc-800));
+  --tz-fg: light-dark(var(--color-zinc-900), var(--color-zinc-100));
+  --tz-fg-muted: light-dark(var(--color-zinc-600), var(--color-zinc-400));
+  --tz-border: light-dark(var(--color-zinc-300), var(--color-zinc-700));
+  --tz-accent: light-dark(
+    var(--color-primary-600, var(--color-blue-600)),
+    var(--color-primary-400, var(--color-blue-400))
+  );
+  --tz-accent-fg: light-dark(var(--color-white), var(--color-zinc-950));
+  --tz-danger: light-dark(var(--color-red-700), var(--color-red-400));
+  --tz-warning: light-dark(var(--color-amber-700), var(--color-amber-400));
+  --tz-font: var(--font-sans);
+  --tz-radius: var(--radius-md);
+}
+
+.dark {
+  --tz-color-scheme: dark;
+}

package/tzslot.css

@@ -0,0 +1,182 @@
+@charset "UTF-8";
+/**
+ * @tzslot/theme — one import and the widgets are presentable.
+ *
+ *   import '@tzslot/theme';                     // plain CSS
+ *   @use '@tzslot/theme/tzslot' with ($accent: #e11d48, $accent-fg: #fff);
+ *
+ * Generated from tzslot.scss — edit that file, then `npm run build:theme`.
+ *
+ * Optional by design. The widgets carry structural class names and read their
+ * colours from custom properties; this file only sets those properties and a
+ * handful of interaction rules. Replacing it means writing your own values for
+ * the same names, not fighting selectors.
+ *
+ * ── How it is built ──────────────────────────────────────────────────────────
+ *
+ * One palette, nine colours, each written light-dark(light, dark). Which half
+ * applies is decided by `color-scheme` at the element that uses the colour, so:
+ *
+ *   - by default the widgets follow the system;
+ *   - data-theme="dark" or "light" on ANY element forces it for everything
+ *     inside — a dark card on a light page is one attribute;
+ *   - there is no second copy of the dark values to keep in step.
+ *
+ * Nothing derived is declared here. A variable like "the selected day's
+ * background" defaults to the accent at the place it is drawn, not on :root —
+ * a custom property that refers to another is frozen where it is declared, and
+ * declaring it on :root would stop a card's own --tz-accent from reaching it.
+ * Every such default lives in the widgets' base CSS as a var() fallback.
+ *
+ * Contrast: every text/background pair meets WCAG AA at the sizes used.
+ * light-dark() needs Chrome 123, Safari 17.5 or Firefox 120 (all of 2024).
+ */
+:root {
+  --tz-bg: light-dark(#ffffff, #18181b);
+  --tz-bg-raised: light-dark(#f4f4f5, #27272a);
+  --tz-fg: light-dark(#18181b, #f4f4f5);
+  --tz-fg-muted: light-dark(#52525b, #a1a1aa);
+  --tz-border: light-dark(#d4d4d8, #3f3f46);
+  --tz-accent: light-dark(#2563eb, #60a5fa);
+  --tz-accent-fg: light-dark(#ffffff, #0b1220);
+  --tz-danger: light-dark(#b91c1c, #f87171);
+  --tz-warning: light-dark(#b45309, #fbbf24);
+  /**
+   * The widgets inherit the page's font by default, which is almost always
+   * right. Set this only to make them differ from their surroundings.
+   */
+  --tz-font: inherit;
+  --tz-radius: 0.375rem;
+  --tz-gap: 0.25rem;
+  --tz-cal-cell-size: 2.25rem;
+  --tz-cal-weekday-size: 0.6875rem;
+  --tz-cal-outside-opacity: 0.32;
+  --tz-slot-gap: 0.375rem;
+  --tz-slot-padding: 0.4375rem 0.25rem;
+  --tz-slot-note-size: 0.6875rem;
+  --tz-field-width: 13rem;
+  --tz-dtr-gap: 1.25rem;
+  --tz-dtr-leg-min: 15rem;
+  --tz-dtr-legend-size: 0.6875rem;
+  --tz-dtr-summary-size: 1.375rem;
+}
+
+/**
+ * Which half of every light-dark() applies. Declared on the widgets rather than
+ * the page, so importing the theme never changes the page's own form controls
+ * and scrollbars. --tz-color-scheme is inherited, which is how data-theme on
+ * any ancestor reaches them.
+ */
+.tz-cal,
+.tz-range,
+.tz-slots,
+.tz-field,
+.tz-field__panel,
+.tz-field__backdrop,
+.tz-dtr,
+.tz-daily {
+  color-scheme: var(--tz-color-scheme, light dark);
+  color: var(--tz-fg);
+  font: var(--tz-font);
+}
+
+[data-theme=light] {
+  --tz-color-scheme: light;
+}
+
+[data-theme=dark] {
+  --tz-color-scheme: dark;
+}
+
+/**
+ * The rules the variables cannot express: hover, focus, the panel surface.
+ * Kept short — every rule here is one a consumer may have to override.
+ */
+.tz-cal__day:hover:not(:disabled),
+.tz-cal__coarse-cell:hover:not(:disabled),
+.tz-range__day:hover:not(:disabled),
+.tz-cal__nav:hover:not(:disabled),
+.tz-cal__title:hover:not(:disabled),
+.tz-cal__action:hover:not(:disabled),
+.tz-range__nav:hover:not(:disabled) {
+  background: var(--tz-bg-raised);
+}
+
+/* Hovering the selection must not hide it. */
+.tz-cal__day--selected:hover:not(:disabled),
+.tz-cal__coarse-cell--selected:hover:not(:disabled),
+.tz-range__day--start:hover:not(:disabled),
+.tz-range__day--end:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--tz-accent) 85%, var(--tz-fg));
+}
+
+.tz-slots__slot:hover:not(:disabled),
+.tz-field__trigger:hover:not(:disabled) {
+  border-color: var(--tz-accent);
+}
+
+/* Focus must be visible on every control, including those inside the panel —
+   a keyboard user who cannot see where they are is stuck. */
+.tz-cal__day:focus-visible,
+.tz-cal__coarse-cell:focus-visible,
+.tz-cal__title:focus-visible,
+.tz-range__day:focus-visible,
+.tz-cal__nav:focus-visible,
+.tz-cal__action:focus-visible,
+.tz-range__nav:focus-visible,
+.tz-slots__slot:focus-visible,
+.tz-field__trigger:focus-visible {
+  outline: var(--tz-focus-ring, 2px solid var(--tz-accent));
+  outline-offset: 2px;
+}
+
+.tz-field__panel {
+  border: 1px solid var(--tz-border);
+  border-radius: calc(var(--tz-radius) * 1.5);
+  background: var(--tz-bg);
+  box-shadow: 0 10px 30px -12px rgba(0, 0, 0, 0.35);
+}
+
+.tz-field__panel--dialog {
+  box-shadow: 0 25px 60px -15px rgba(0, 0, 0, 0.5);
+}
+
+.tz-field__backdrop {
+  background: rgba(0, 0, 0, 0.45);
+}
+
+.tz-cal__weekday,
+.tz-range__weekday,
+.tz-dtr__legend,
+.tz-daily__legend {
+  color: var(--tz-fg-muted);
+}
+
+/**
+ * Windows high contrast and other forced-colour modes replace every colour
+ * with the system's, backgrounds included — so a selection shown only by its
+ * background would vanish. System colours keep it visible.
+ */
+@media (forced-colors: active) {
+  .tz-cal__day--selected,
+  .tz-cal__coarse-cell--selected,
+  .tz-range__day--start,
+  .tz-range__day--end,
+  .tz-slots__slot--selected {
+    forced-color-adjust: none;
+    background: Highlight;
+    color: HighlightText;
+  }
+  .tz-cal__day--today {
+    outline-color: CanvasText;
+  }
+}
+@media (prefers-reduced-motion: no-preference) {
+  .tz-cal__day,
+  .tz-cal__coarse-cell,
+  .tz-range__day,
+  .tz-slots__slot,
+  .tz-field__trigger {
+    transition: background-color 120ms ease, border-color 120ms ease;
+  }
+}

package/tzslot.scss

@@ -0,0 +1,247 @@
+@use 'sass:list';
+@use 'sass:meta';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The source of @tzslot/theme. tzslot.css is compiled from this file and a
+// test fails when the two drift apart, so there is one theme, not two.
+//
+// Sass is optional for consumers. What it adds over the CSS:
+//
+//   // configure the palette at compile time
+//   @use '@tzslot/theme/tzslot' with ($accent: (#be123c, #fb7185));
+//
+//   // or scope one to a selector, from your own palette variables
+//   @use '@tzslot/theme/tzslot' as tz;
+//   .brand-card { @include tz.palette((accent: $brand, accent-fg: #fff)); }
+//
+// A colour is either one value, used in both schemes, or a pair
+// (light, dark) that becomes light-dark(light, dark).
+//
+// Everything still ends up as --tz-* custom properties: that is what lets a
+// theme change at runtime, per element, which Sass variables alone cannot do.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ── palette ──────────────────────────────────────────────────────────────────
+$bg: (#ffffff, #18181b) !default;
+$bg-raised: (#f4f4f5, #27272a) !default;
+$fg: (#18181b, #f4f4f5) !default;
+$fg-muted: (#52525b, #a1a1aa) !default;
+$border: (#d4d4d8, #3f3f46) !default;
+$accent: (#2563eb, #60a5fa) !default;
+$accent-fg: (#ffffff, #0b1220) !default;
+$danger: (#b91c1c, #f87171) !default;
+$warning: (#b45309, #fbbf24) !default;
+
+$font: inherit !default;
+
+// ── shape and size ───────────────────────────────────────────────────────────
+$sizes: (
+  radius: 0.375rem,
+  gap: 0.25rem,
+  cal-cell-size: 2.25rem,
+  cal-weekday-size: 0.6875rem,
+  cal-outside-opacity: 0.32,
+  slot-gap: 0.375rem,
+  slot-padding: 0.4375rem 0.25rem,
+  slot-note-size: 0.6875rem,
+  field-width: 13rem,
+  dtr-gap: 1.25rem,
+  dtr-leg-min: 15rem,
+  dtr-legend-size: 0.6875rem,
+  dtr-summary-size: 1.375rem,
+) !default;
+
+/// False to load only the functions and mixins, with no CSS emitted.
+$emit: true !default;
+
+/// A single colour, or a (light, dark) pair turned into light-dark().
+@function value($colour) {
+  @if meta.type-of($colour) == 'list' and list.length($colour) == 2 {
+    @return light-dark(list.nth($colour, 1), list.nth($colour, 2));
+  }
+  @return $colour;
+}
+
+/// Sets palette variables on the current selector. Keys are the names without
+/// the prefix: (accent: #e11d48) sets --tz-accent.
+@mixin palette($colours) {
+  @each $name, $colour in $colours {
+    --tz-#{$name}: #{value($colour)};
+  }
+}
+
+@if $emit {
+  /**
+   * @tzslot/theme — one import and the widgets are presentable.
+   *
+   *   import '@tzslot/theme';                     // plain CSS
+   *   @use '@tzslot/theme/tzslot' with ($accent: #e11d48, $accent-fg: #fff);
+   *
+   * Generated from tzslot.scss — edit that file, then `npm run build:theme`.
+   *
+   * Optional by design. The widgets carry structural class names and read their
+   * colours from custom properties; this file only sets those properties and a
+   * handful of interaction rules. Replacing it means writing your own values for
+   * the same names, not fighting selectors.
+   *
+   * ── How it is built ──────────────────────────────────────────────────────────
+   *
+   * One palette, nine colours, each written light-dark(light, dark). Which half
+   * applies is decided by `color-scheme` at the element that uses the colour, so:
+   *
+   *   - by default the widgets follow the system;
+   *   - data-theme="dark" or "light" on ANY element forces it for everything
+   *     inside — a dark card on a light page is one attribute;
+   *   - there is no second copy of the dark values to keep in step.
+   *
+   * Nothing derived is declared here. A variable like "the selected day's
+   * background" defaults to the accent at the place it is drawn, not on :root —
+   * a custom property that refers to another is frozen where it is declared, and
+   * declaring it on :root would stop a card's own --tz-accent from reaching it.
+   * Every such default lives in the widgets' base CSS as a var() fallback.
+   *
+   * Contrast: every text/background pair meets WCAG AA at the sizes used.
+   * light-dark() needs Chrome 123, Safari 17.5 or Firefox 120 (all of 2024).
+   */
+  :root {
+    @include palette(
+      (
+        bg: $bg,
+        bg-raised: $bg-raised,
+        fg: $fg,
+        fg-muted: $fg-muted,
+        border: $border,
+        accent: $accent,
+        accent-fg: $accent-fg,
+        danger: $danger,
+        warning: $warning,
+      )
+    );
+
+    /**
+     * The widgets inherit the page's font by default, which is almost always
+     * right. Set this only to make them differ from their surroundings.
+     */
+    --tz-font: #{$font};
+
+    @each $name, $size in $sizes {
+      --tz-#{$name}: #{$size};
+    }
+  }
+
+  /**
+   * Which half of every light-dark() applies. Declared on the widgets rather than
+   * the page, so importing the theme never changes the page's own form controls
+   * and scrollbars. --tz-color-scheme is inherited, which is how data-theme on
+   * any ancestor reaches them.
+   */
+  .tz-cal,
+  .tz-range,
+  .tz-slots,
+  .tz-field,
+  .tz-field__panel,
+  .tz-field__backdrop,
+  .tz-dtr,
+  .tz-daily {
+    color-scheme: var(--tz-color-scheme, light dark);
+    color: var(--tz-fg);
+    font: var(--tz-font);
+  }
+
+  [data-theme='light'] { --tz-color-scheme: light; }
+  [data-theme='dark'] { --tz-color-scheme: dark; }
+
+  /**
+   * The rules the variables cannot express: hover, focus, the panel surface.
+   * Kept short — every rule here is one a consumer may have to override.
+   */
+  .tz-cal__day:hover:not(:disabled),
+  .tz-cal__coarse-cell:hover:not(:disabled),
+  .tz-range__day:hover:not(:disabled),
+  .tz-cal__nav:hover:not(:disabled),
+  .tz-cal__title:hover:not(:disabled),
+  .tz-cal__action:hover:not(:disabled),
+  .tz-range__nav:hover:not(:disabled) {
+    background: var(--tz-bg-raised);
+  }
+
+  /* Hovering the selection must not hide it. */
+  .tz-cal__day--selected:hover:not(:disabled),
+  .tz-cal__coarse-cell--selected:hover:not(:disabled),
+  .tz-range__day--start:hover:not(:disabled),
+  .tz-range__day--end:hover:not(:disabled) {
+    background: color-mix(in srgb, var(--tz-accent) 85%, var(--tz-fg));
+  }
+
+  .tz-slots__slot:hover:not(:disabled),
+  .tz-field__trigger:hover:not(:disabled) {
+    border-color: var(--tz-accent);
+  }
+
+  /* Focus must be visible on every control, including those inside the panel —
+     a keyboard user who cannot see where they are is stuck. */
+  .tz-cal__day:focus-visible,
+  .tz-cal__coarse-cell:focus-visible,
+  .tz-cal__title:focus-visible,
+  .tz-range__day:focus-visible,
+  .tz-cal__nav:focus-visible,
+  .tz-cal__action:focus-visible,
+  .tz-range__nav:focus-visible,
+  .tz-slots__slot:focus-visible,
+  .tz-field__trigger:focus-visible {
+    outline: var(--tz-focus-ring, 2px solid var(--tz-accent));
+    outline-offset: 2px;
+  }
+
+  .tz-field__panel {
+    border: 1px solid var(--tz-border);
+    border-radius: calc(var(--tz-radius) * 1.5);
+    background: var(--tz-bg);
+    box-shadow: 0 10px 30px -12px rgb(0 0 0 / 0.35);
+  }
+
+  .tz-field__panel--dialog {
+    box-shadow: 0 25px 60px -15px rgb(0 0 0 / 0.5);
+  }
+
+  .tz-field__backdrop {
+    background: rgb(0 0 0 / 0.45);
+  }
+
+  .tz-cal__weekday,
+  .tz-range__weekday,
+  .tz-dtr__legend,
+  .tz-daily__legend {
+    color: var(--tz-fg-muted);
+  }
+
+  /**
+   * Windows high contrast and other forced-colour modes replace every colour
+   * with the system's, backgrounds included — so a selection shown only by its
+   * background would vanish. System colours keep it visible.
+   */
+  @media (forced-colors: active) {
+    .tz-cal__day--selected,
+    .tz-cal__coarse-cell--selected,
+    .tz-range__day--start,
+    .tz-range__day--end,
+    .tz-slots__slot--selected {
+      forced-color-adjust: none;
+      background: Highlight;
+      color: HighlightText;
+    }
+    .tz-cal__day--today { outline-color: CanvasText; }
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .tz-cal__day,
+    .tz-cal__coarse-cell,
+    .tz-range__day,
+    .tz-slots__slot,
+    .tz-field__trigger {
+      transition:
+        background-color 120ms ease,
+        border-color 120ms ease;
+    }
+  }
+}