diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8513f61 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,342 @@ +# CLAUDE.md — Native Form Elements + +## Project Purpose + +A static reference page for testing and consulting native HTML form element behaviour. Every element is shown in all possible states so developers can experience native behaviour using assistive technology and keyboard testing. No frameworks, no build tools — intentionally minimal. + +**Live site:** nativeformelements.com +**Stack:** HTML5, CSS (custom properties), Cash JS (jQuery-like micro-library), GitHub Actions CI + +--- + +## Open GitHub Issues + +| # | Title | Status | +|---|-------|--------| +| [#1](https://github.com/formspiel/native-form-elements/issues/1) | Add `accent-color` CSS | Open since 2023 | +| [#2](https://github.com/formspiel/native-form-elements/issues/2) | Add modern theme switch (CSS style queries) | Open since 2024 | +| [#3](https://github.com/formspiel/native-form-elements/issues/3) | Add ARIA `role="group"` example | Open since 2025 — partially in `index.html:734` | + +--- + +## Layout + +### Column structure +The grid always has exactly **5 columns**, one per state: + +| Column | State | HTML mechanism | +|--------|-------|----------------| +| 1 | Default | — | +| 2 | Default (pre-filled) | `value=""` / `checked` | +| 3 | Required | `required` | +| 4 | Read-only | `readonly` | +| 5 | Disabled | `disabled` | + +If a state is not available per the HTML standard, a visible "Not available" placeholder must fill the cell so the grid alignment is preserved. + +Some element types have **variants** below the main 5-column row (e.g. placeholder, hint, pattern for text inputs). This must remain possible. + +### Responsive behaviour +- Mobile: single column, minimal horizontal page padding +- Tablet: two or three columns +- Desktop (≥ 900 px): full 5-column grid + +Currently `.grid-wrapper` has no `gap` — items sit flush. A small gap is needed. + +--- + +## Design Tiers + +Three tiers are switched by checkboxes in the header. The checkboxes apply CSS classes to ``. + +### Tier 0 — Default (no class) +- `font-family: system-ui, sans-serif` +- Dynamic type for WebKit via `font: -apple-system-body` guarded by `@supports`: + ```css + @supports (font: -apple-system-body) { + body { font: -apple-system-body; font-family: system-ui, sans-serif; } + } + ``` +- **No CSS applied to form elements** — they must render exactly as the browser/OS renders them natively. +- Minimal horizontal page padding only (`padding-inline`). + +### Tier 1 — "Streamline typography" (`body.design-01`) +- Font family and font size are applied uniformly to `input`, `textarea`, `select`, `button`. +- `font-size: 100%; font-family: inherit` is the minimal correct fix. +- Currently `body.design-01 {}` and `body.design-01 label {}` are empty rule blocks — these are dead CSS and should be removed. + +### Tier 2 — "Minimal Design" (`body.design-02`, formerly "Basic borders and padding") +- Minimalistic design with **Allianz Blue (`#003781`)** as accent colour. +- Custom focus style: a clearly visible `outline` using the accent colour. +- Padding, border-radius, and border on form elements. +- This replaces both the old "Basic borders and padding" (design-02) and "Basic design" (design-03) checkboxes — consolidate into one. +- `design-basic.css` is currently broken (see Bugs). It should be repaired and renamed `design-minimal.css`, or its contents merged into `style.css` under `.design-02`. + +--- + +## Colour & Accessibility + +### Contrast requirement — WCAG AAA (7:1) +Current colour values **do not meet 7:1** in either mode: + +| Mode | Text | Background | Approx. ratio | Status | +|------|------|------------|----------------|--------| +| Light | `hsl(0,0%,20%)` = `#333` | `hsl(0,0%,90%)` = `#e6e6e6` | ~5.3:1 | ❌ Fails AAA | +| Dark | `hsl(0,0%,90%)` = `#e6e6e6` | `hsl(0,0%,20%)` = `#333` | ~5.3:1 | ❌ Fails AAA | + +**Fix — light mode:** `#111111` on `#f5f5f5` → ~16:1 ✓ +**Fix — dark mode:** `#f0f0f0` on `#1a1a1a` → ~14:1 ✓ + +Update the `:root` custom properties accordingly. The `--color-link` value must also reach 7:1 against the page background on its own (without underline as the only distinguisher). + +### Focus visibility +- Dark mode uses `:focus { outline-color: … }` — this overrides focus for all interactive elements globally, including when navigating with a mouse. Use `:focus-visible` instead so only keyboard focus shows the ring. +- High-contrast mode (`forced-colors`) is already present — keep it. + +### `accent-color` (Issue #1) +Add one line to `:root`: +```css +:root { accent-color: #003781; } +``` +This visually styles checkboxes, radios, range sliders, and progress bars in supporting browsers. It is also a natural companion to the Minimal Design tier. + +--- + +## Navigation + +### Current state +Skip links are generated dynamically by `behaviour.js` for `legend`, `h1`, and `h2` elements. They are injected into `