@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-better-accessibility/motion-and-zoom.md

@@ -0,0 +1,81 @@
+# Motion and zoom
+
+`prefers-reduced-motion`, zoom and reflow, and unit choices that respect user settings.
+
+## prefers-reduced-motion
+
+Make motion opt-in. Wrap animations in `@media (prefers-reduced-motion: no-preference)` so users who asked for reduced motion get the static version by default, rather than you chasing every animation with an override.
+
+```css
+/* Good: motion is opt-in */
+.card {
+  /* static styles */
+}
+@media (prefers-reduced-motion: no-preference) {
+  .card {
+    transition: transform 200ms ease-out;
+  }
+}
+```
+
+```tsx
+// Tailwind: motion-safe / motion-reduce variants
+<div className="motion-safe:transition-transform motion-safe:hover:-translate-y-1" />
+```
+
+For an existing codebase where opt-in isn't feasible, a global reset is the fallback. Exclude loading spinners and progress indicators, including animated descendants and pseudo-elements. This example uses `.progress-indicator`; replace it with the project's existing indicator classes:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *:not(.progress-indicator, .progress-indicator *),
+  *:not(.progress-indicator, .progress-indicator *)::before,
+  *:not(.progress-indicator, .progress-indicator *)::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+`0.01ms` rather than `none`, so `animationend` and `transitionend` still fire and JS waiting on them doesn't hang.
+
+### What to disable vs reduce
+
+Reduced motion means reduced, not eliminated. It targets vestibular triggers, not feedback.
+
+| Disable entirely                                 | Replace                                          | Keep                                            |
+| ------------------------------------------------ | ------------------------------------------------ | ----------------------------------------------- |
+| Parallax scrolling                               | Slide/scale/zoom transitions → opacity crossfade | Loading spinners and progress                   |
+| Autoplaying video, GIFs, looping decoration      | Smooth scrolling → instant jump                  | Instant state changes (hover color, focus ring) |
+| Spinning, large-scale movement across the screen | Auto-rotating carousels → start paused           | Brief functional feedback (button press)        |
+
+Animations are interruptible and driven by user input. Nothing autoplays or refuses to stop, and under reduced motion carousels start paused.
+
+## Autoplay and timed UI
+
+Motion the user didn't ask for and UI acting on its own schedule:
+
+- **No autoplaying media without visible controls** (WCAG 2.2.2). Anything moving, blinking, or updating on its own for more than 5 seconds needs a visible pause or stop control, muted looping hero videos included.
+- **Prefer explicit dismissal over timers.** Auto-dismissal suits low-stakes confirmations and nothing else. A toast carrying an action, an error, or information the user may need stays until dismissed. Where one must time out, 5 seconds is the floor, and hovering or focusing it pauses the timer.
+- **Never put critical information only in a timed element.** A vanished toast with the only link to an undo action is data loss on a schedule.
+
+## Zoom and reflow
+
+- **200% zoom** (WCAG 1.4.4). All content and functionality survives text scaled to 200%, and the viewport leaves the reader able to zoom.
+- **Reflow at 320px** (WCAG 1.4.10). At 400% zoom on a 1280px viewport, equivalent to a 320px one, the page must work with vertical scrolling alone. Genuinely 2D content is the exception: tables, maps and code blocks scroll inside their own container.
+
+Fixed heights are what break under zoom. Use `min-height` on anything containing text and let containers grow.
+
+### rem vs px
+
+Respect how the codebase is set up. Where the project sizes in `px`, or on an established Tailwind scale, stay consistent and never introduce mixed units into someone else's system. Where you do have the choice, in new code or a codebase already on `rem`, `rem` respects the user's base font size and `px` ignores it:
+
+| Use `rem`                                             | Use `px`                       |
+| ----------------------------------------------------- | ------------------------------ |
+| `font-size`                                           | Borders and hairlines          |
+| `max-width` of text containers                        | Focus outline width and offset |
+| Media-query breakpoints (`@media (min-width: 48rem)`) | `box-shadow` details           |
+| Spacing that should scale with text                   | Fixed-size decorations         |
+
+Breakpoints are where the choice matters most. At a larger base font size an `em` or `rem` query switches to the mobile layout when the text needs it, and a `px` query does not.

package/skills/hr-better-accessibility/screen-readers.md

@@ -0,0 +1,102 @@
+# Screen readers
+
+Visually hidden content, live regions, toasts, alt text and SVG.
+
+## Visually hidden content
+
+The canonical `.sr-only` pattern hides content visually while keeping it in the accessibility tree:
+
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+Use `1px` boxes, not `0`, because some screen readers skip zero-sized elements. `white-space: nowrap` stops words being read as one run-together string. Never `display: none` or `visibility: hidden`, which remove the content from assistive tech entirely.
+
+Tailwind ships this as `sr-only`. Skip links add a focus variant that un-hides it, `focus:not-sr-only` or an override on `:focus`.
+
+Use it for context sighted users get visually: `<span class="sr-only">Opens in new tab</span>`, table captions, or an icon-only control's label where `aria-label` isn't an option.
+
+## Choosing how to announce a change
+
+Work down this list and stop at the first match:
+
+1. **Focus moves to named content**, such as a modal with an accessible name and description. Focus exposes that associated content; no duplicate live announcement is needed. For custom field validation, use the next rule even when focus moves to the invalid field.
+2. **Tied to a specific control**, such as a field error or character count: `aria-describedby` on the control, announced with the field.
+3. **Non-urgent, not tied to a control**, such as a toast, "Saved", a result count, or a loading state: a polite live region, `role="status"`.
+4. **Urgent and not tied to a control**, such as a form-level failure or session expiry: `role="alert"`.
+
+## Live regions
+
+Live regions announce content that changes without a page load: toasts, validation, search-result counts, loading states.
+
+| Mechanism                                                         | Politeness             | Use for                                         |
+| ----------------------------------------------------------------- | ---------------------- | ----------------------------------------------- |
+| `role="status"` (= `aria-live="polite"` + `aria-atomic="true"`)   | Waits for a pause      | Toasts, "Saved", result counts, loading updates |
+| `role="alert"` (= `aria-live="assertive"` + `aria-atomic="true"`) | Interrupts immediately | Errors and urgent problems only                 |
+
+Rules for reliable announcements:
+
+- For repeated polite updates, keep a stable empty region in the DOM before changing its text. Inserting a new polite region with its content is announced inconsistently.
+- Dynamically inserted `role="alert"` content is usually announced, but behavior varies. Use it only for urgent errors not tied to a control, and test the target browser and screen-reader combinations.
+- Default to polite. Overusing `assertive` is the most common live-region mistake, because it interrupts whatever the user was reading.
+- Keep messages short and self-contained. `aria-atomic="true"` re-reads the whole region on change.
+- Never move focus to a toast. Announce it and leave focus where the user is working. Give toasts a generous timeout or a dismiss button, and never put the only path to an action inside an auto-dismissing one.
+
+```tsx
+// Region rendered from the start, message injected later
+<div role="status" className="sr-only">
+  {statusMessage}
+</div>
+```
+
+For loading states: set `aria-busy="true"` on the updating region, announce "Loading…" politely, then announce the outcome ("Loaded, 12 results").
+
+## aria-hidden
+
+`aria-hidden="true"` removes an element and its whole subtree from assistive tech. Use it for decorative icons and content duplicated for visual effect. Never put it on or above a focusable element, which creates stops you can Tab to that do not exist for a screen reader. Hiding something interactive means removing it from the tab order too.
+
+## Alt text
+
+Choose by purpose, not by what the image looks like:
+
+| Purpose                                     | Alt                                                         | Example                                                    |
+| ------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------- |
+| Decorative, or redundant with adjacent text | `alt=""` (empty, but present)                               | Logo next to the company name in text                      |
+| Informative                                 | Describe the meaning it adds                                | `alt="Ticket QR code"`                                     |
+| Functional (image is the link/button)       | Describe the action or destination                          | Search icon → `alt="Search"`, not `alt="magnifying glass"` |
+| Image of text                               | The exact text (better: use real text)                      | `alt="50% off everything"`                                 |
+| Complex (chart, diagram)                    | Short summary in `alt`, full data as a table or text nearby | `alt="Revenue by quarter, described below"`                |
+
+A missing `alt` is worse than an empty one, because screen readers fall back to reading the file name.
+
+## SVG
+
+- Decorative SVG: `aria-hidden="true"` and `focusable="false"`, the latter for legacy Edge and IE tabbing. No title needed.
+- Meaningful inline SVG: `role="img"` plus `aria-label="…"`, or a `<title>` as the first child referenced by `aria-labelledby`.
+- Give each `<title>` and `<desc>` an `id` that is unique on the page, such as `chart-revenue-title`. Two inline SVGs that share a bare `id="title"` both resolve to the first one. Keep `<title>` to a short name and make `<desc>` one sentence about what the figure shows, not how it is drawn.
+- Simple cases: `<img src="icon.svg" alt="…">` is the most reliable delivery.
+
+```tsx
+// Decorative icon inside a labeled button
+<button aria-label="Close">
+  <svg aria-hidden="true" focusable="false">…</svg>
+</button>
+
+// Standalone meaningful icon
+<svg role="img" aria-label="Verified account">…</svg>
+```
+
+## Video and audio
+
+Prerecorded video needs captions; provide transcripts for audio. Never autoplay with sound, and always render controls.

package/skills/hr-better-accessibility/semantics-and-aria.md

@@ -0,0 +1,84 @@
+# Semantics and ARIA
+
+Native elements first, landmarks, accessible names and the ARIA rules that keep custom widgets honest.
+
+## The rules of ARIA
+
+1. If a native HTML element with the semantics and behavior you need exists, use it instead of repurposing another element with ARIA.
+2. Don't change native semantics unless you really have to.
+3. Every interactive ARIA control must be keyboard-operable; a role is a promise of the full keyboard model, states and behavior.
+4. Never put `role="presentation"` or `aria-hidden="true"` on a focusable element.
+5. All interactive elements must have an accessible name.
+
+No ARIA is better than bad ARIA. A screen reader trusts your roles, so a wrong one is worse than none.
+
+## Button vs link vs div
+
+| Element         | Use for                                                     | Why                                                                   |
+| --------------- | ----------------------------------------------------------- | --------------------------------------------------------------------- |
+| `<a href>`      | Navigation: anything that goes somewhere or changes the URL | Free Cmd/Ctrl/middle-click, right-click → copy link, Enter activation |
+| `<button>`      | Actions: submit, toggle, open, delete                       | Free focus, Enter _and_ Space activation, form semantics              |
+| `<div onClick>` | Nothing                                                     | No role, no focus, no keyboard; screen readers see plain text         |
+
+```tsx
+// Bad: invisible to keyboard and screen readers
+<div onClick={openSettings}>Settings</div>
+
+// Good: focus, Enter/Space activation and semantics for free
+<button onClick={openSettings}>Settings</button>
+```
+
+If it looks clickable it must be clickable, and if it's clickable it must be a real interactive element. Rebuilding a link as a button, or the reverse, breaks user expectations. A "button" that navigates is a styled `<a>`.
+
+Where a native element is truly impossible, the full polyfill is `role="button"` plus `tabindex="0"` plus Enter and Space handlers, which is why the native element is always less code.
+
+## Landmarks and headings
+
+- Expose one visible primary `<main>` landmark. `<header>`, `<nav>`, `<aside>`, `<footer>` map to landmarks screen-reader users jump between.
+- Multiple landmarks of the same type need distinguishing labels: `<nav aria-label="Primary">`, `<nav aria-label="Breadcrumbs">`.
+- Do not report the one-`<h1>` or the no-skipped-levels convention as a standalone WCAG failure without a concrete navigation or comprehension impact. Headings are structure, not styling; style a heading level with CSS instead of picking the tag by size.
+- `<title>` matches the current context, most specific first: `Billing · Settings · Acme`.
+
+## Accessible names
+
+Name precedence: `aria-labelledby` > `aria-label` > native label (`<label>`, text content, `alt`) > `title` attribute.
+
+- Prefer visible text or `aria-labelledby` over `aria-label`, which is invisible, drifts out of sync with the UI and is handled inconsistently by translation tools.
+- Icon-only buttons always need a name: `<button aria-label="Close">` with the icon `aria-hidden="true"`.
+- WCAG 2.5.3 Label in Name: a button showing "Send" with `aria-label="Submit message"` breaks voice control users who say "click Send".
+- Accessible names must exist even when the design omits visible labels.
+
+```tsx
+// Good: name from visible text, icon hidden
+<button>
+  <TrashIcon aria-hidden="true" /> Delete
+</button>
+
+// Good: icon-only, explicit name
+<button aria-label="Delete">
+  <TrashIcon aria-hidden="true" />
+</button>
+```
+
+Add `translate="no"` to brand names, code tokens and identifiers so auto-translation doesn't garble them.
+
+## Common ARIA mistakes
+
+| Mistake                                                       | Why it fails                                                                         |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `aria-label` on a plain `<div>` or `<span>`                   | Most screen readers ignore names on non-interactive, role-less elements              |
+| `<button role="button">`                                      | Redundant role; adds noise, no benefit                                               |
+| `aria-hidden="true"` on or above a focusable element          | Creates elements you can Tab to but that don't exist for screen readers              |
+| `aria-labelledby`/`aria-describedby` pointing at a missing ID | Silently produces no name or description                                             |
+| `role="menu"` on a nav list                                   | `menu` promises app-style arrow-key behavior; site navigation is `<nav>` with a list |
+
+## Disabled states
+
+Native `disabled` supplies the platform's complete disabled behavior. It removes the control from the tab order, suppresses activation, applies `:disabled` and excludes form controls from submission. Use it when a native control is genuinely unavailable. `aria-disabled="true"` only announces the state, changing neither focusability, nor behavior, nor styling.
+
+- Never disable submit buttons. Keep them enabled, validate on submit and focus the first error ([forms.md](forms.md)).
+- A natively `disabled` control suppresses pointer events and leaves the tab order, so a tooltip on it never opens for keyboard or touch users and is unreliable for mouse users. Put the reason in visible text beside the control, or switch to `aria-disabled="true"`, which keeps it focusable and hoverable and can carry a tooltip.
+- Use `aria-disabled="true"` where keeping a control discoverable in the tab order is intentional, or where a custom control cannot use native `disabled`.
+- With `aria-disabled="true"`, block pointer and keyboard activation in the handler, prevent form submission where applicable, add explicit styling including forced-colors support and explain nearby why the action is unavailable.
+- Never set both `disabled` and `aria-disabled` on the same element.
+- Disabled controls are exempt from contrast minimums. Keep them legible anyway.

package/skills/hr-better-colors/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Krehel
+
+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/skills/hr-better-colors/NOTICE.md

@@ -0,0 +1,37 @@
+# Source notices
+
+This notice accompanies the hr-better-colors bundle when copied on its own.
+
+## jakubkrehel/skills
+
+Source: https://github.com/jakubkrehel/skills (compared at revision `267330e1adfc66a718fb65fa6918c1f06d0a689e`)
+
+- `skills/hr-better-accessibility/`, `skills/hr-better-colors/`, `skills/hr-better-layout/`,
+  `skills/hr-better-typography/` and `skills/hr-better-writing/`: adapted skill bundles,
+  including their supporting references and discovery metadata.
+
+Copyright (c) 2026 Jakub Krehel
+
+## house-rules and MIT permission notice
+
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+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/skills/hr-better-colors/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: hr-better-colors
+description: "Color rules for web UI: palette ramps, semantic color tokens, color notation and gamut, and measured contrast of rendered pairs. Use when choosing, reviewing or fixing colors, color tokens, themes or text contrast in web UI."
+license: MIT
+metadata:
+  upstream: https://github.com/jakubkrehel/skills
+  upstream_ref: 267330e1adfc66a718fb65fa6918c1f06d0a689e
+  upstream_path: skills/better-colors/
+  local_patches: "Use-when description; 14pt bold = 18.67px; WCAG 2 text-color crossover; Tailwind v4 utility names; P3 fallback severity matches Reporting; better-ui handoff dropped (not vendored); enforce tokens with a lint or guard"
+  house_rules_patches: "Portable provenance and review verdict"
+---
+
+# Colors
+
+A color system is a small set of ramps, named by role and verified against the backgrounds they actually render on. Most color bugs are system bugs. A value picked in isolation, a token borrowed because it looked right, a pair nobody measured.
+
+Never report a contrast value you did not measure, and never estimate a color you could compute. Colors are one of the few interface concerns with an exact answer, so produce the exact answer.
+
+Contrast requirements belong to `hr-better-accessibility`. Surfaces, shadows and icon color are outside this skill.
+
+## Match the project's color system
+
+Reuse the project's tokens and notation. A second representation added to fix one value makes the palette harder to reason about. A consistent hex system beats hex with `oklch()` scattered through it.
+
+Once the tokens exist, enforce them with a lint rule or guard test that fails on a color literal outside the token files, with a short allowlist for places that need raw values by design. A written "use tokens" rule with no check behind it drifts.
+
+For a new system, `oklch()` is the best default, because its numbers behave the way the ramp rules below describe. Everywhere else, a color library produces the same ramp in the project's own notation ([color-formats.md](color-formats.md)).
+
+## A system is ramps, not colors
+
+One neutral ramp, one accent ramp and only the status ramps the product actually renders. A `warning` ramp nothing imports is maintenance for zero pixels. A second accent hue earns its place only when two things must be distinguishable at a glance.
+
+## Every step has a job
+
+A ramp is not a gradient to pick from by eye. Each step exists because a role needs it: page background, component hover, border, solid fill, body text. Do not generate a step no role consumes. Both the Tailwind `50`–`950` and Radix `1`–`12` conventions map to those roles ([palette-structure.md](palette-structure.md)).
+
+## Name primitives by hue, semantics by role
+
+Primitives name a value (`--blue-500`) and are never applied in a component. Semantic tokens name a job (`--color-text-secondary`), point at a primitive and are the only tier components reference.
+
+That seam is what makes theming possible. Without it, dark mode means auditing every usage to work out which meant "the accent" and which just wanted blue ([token-naming.md](token-naming.md)).
+
+## Use a token only in its role
+
+Never borrow a token because its value is right today. A separator used as a text color works until borders get lighter, and then the text goes with them. If a role has no token, add the token.
+
+## Hold the hue across the ramp
+
+Four properties define a well-formed ramp:
+
+- Steps follow a deliberate _perceived_ lightness progression ([palette-generation.md](palette-generation.md)).
+- Hue stays constant end to end.
+- Vividness peaks mid-ramp and falls off at both ends.
+- Steps sit denser at the light end than at the dark end.
+
+Both ends stop short of pure black and white, which cannot carry hue at all. Use a color library rather than eyeballing it ([palette-generation.md](palette-generation.md)).
+
+## One color, one meaning
+
+Use a color for one purpose across the whole interface, treating anything within `15°` of hue as the same color. If the accent means interactive, that hue on static text tells users to click something that is not clickable, and an interactive element rendered neutral misleads just as badly. Color is never the only carrier of meaning, which `hr-better-accessibility` owns.
+
+## Fill exactly one action per view
+
+When filled color encodes primary emphasis, one primary action gets it and peers stay neutral. Put the color on the background, not the label. A filled button reads as primary across the room; accent-colored text on a neutral button reads as a link.
+
+Several colored backgrounds are fine when they encode distinct states or categories rather than competing as peers.
+
+## Measure the rendered pair, then report
+
+Measure a foreground against the background it actually renders on, not the page background. When a pair fails, report the pair, its measured value and the threshold it misses, then leave the colors alone. They are a design decision. Change them only when asked, and remeasure after ([contrast.md](contrast.md)).
+
+## Pick a gradient's interpolation space
+
+The space is a look, not a correctness setting.
+
+- **`in oklab`** is the best default: even brightness, no hue surprises.
+- **`in oklch`** travels around the hue wheel rather than through the middle, staying vivid and sweeping every hue between the stops. Reach for it when a two-hue gradient goes gray in the middle.
+- **The sRGB default** darkens and mutes the midpoint. It is what most interfaces already have, because it is what you get without asking.
+
+See [color-usage.md](color-usage.md).
+
+## Before you finish
+
+| Mistake                                                                                      | Fix                                                                                           |
+| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| A raw value where the project has a token                                                    | Reuse or add the role token, in the project's notation                                        |
+| An isolated `oklch()` value dropped into a hex codebase                                      | Keep the established notation unless a migration is in scope                                  |
+| A primitive like `--blue-500` used directly in a component                                   | Point a semantic token at it                                                                  |
+| Token named for its appearance (`--color-blue-button`) or first use (`--color-sidebar-gray`) | Name it for its role: `--color-accent-solid`, `--color-bg-surface`                            |
+| `--color-primary` meaning the brand and `--color-text-primary` meaning body text             | Reserve `accent` for the brand; let `primary` mean "most prominent of its group"              |
+| Semantic token used outside its role (separator as text)                                     | Add a token for the missing role; never borrow by value                                       |
+| Ramp built by varying HSL lightness                                                          | Rebuild against perceived lightness with a constant hue                                       |
+| Ramp spaced evenly across the full range                                                     | Tighten the light end until `50` and `100` read as two surfaces                               |
+| Same saturation number reused across hues                                                    | Match the proportion of each hue's own maximum, not the raw value                             |
+| Status hue that collides with the accent hue                                                 | Move it until destructive and primary read apart side by side                                 |
+| Dark mode made by mechanically reversing the light palette                                   | Reverse as a starting point, then reduce vividness, widen the dark end and recheck every pair |
+| `prefers-color-scheme` setting some tokens and a `.dark` class setting others                | Pick one switching mechanism and use it throughout                                            |
+| Contrast fixed by changing hue                                                               | Change lightness, the channel contrast responds to                                            |
+| P3 color with no sRGB fallback                                                               | Declare the sRGB value first, then override inside `@media (color-gamut: p3)`                 |
+
+## Reporting
+
+**Severity.** `HIGH` makes content unreadable or assigns a misleading semantic color. `MEDIUM` is a noticeable theme, token, or gamut failure. `LOW` is isolated polish.
+
+**Verification.** Without a browser: token values, the gamut of every declared color, both theme blocks present and contrast computed from the declared token pair. With one: the background actually rendered behind the text, including opacity and any image beneath it, measured in both light and dark. A failing pair is reported, not repainted. Report every check you could not run as `Not verified`.
+
+**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
+
+| Severity | Location | Before | After | Why |
+| -------- | -------- | ------ | ----- | --- |
+
+`Location` is `path/to/file:line`. `Why` names the principle and the user impact.
+
+Report `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable color findings" and report verification.

package/skills/hr-better-colors/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Better Colors"
+  short_description: "Building, naming and applying color systems"

package/skills/hr-better-colors/color-formats.md

@@ -0,0 +1,90 @@
+# Color formats
+
+Which notation to write colors in, how to convert between them and what happens at the edges of a display's gamut. Every other rule in this skill is stated perceptually and holds whatever notation you write.
+
+## Choosing a notation
+
+| Notation  | Good for                                                      | Weakness                                                                                                                |
+| --------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Hex       | Universal support, compact, what design tools hand you        | Opaque. No channel is readable or editable by hand                                                                      |
+| `rgb()`   | Same reach as hex, readable alpha                             | Channels do not correspond to anything a designer thinks about                                                          |
+| `hsl()`   | Channels look like design controls                            | Its lightness is not perceptual and its hue drifts; a ramp built by varying lightness bunches at one end and shifts hue |
+| `oklch()` | Perceptually uniform lightness, stable hue, predictable ramps | Baseline 2023, so very old browser matrices need a fallback                                                             |
+
+**Match whatever the project already uses.** Notation is not a defect: a project on hex is not doing it wrong.
+
+**For a genuinely new color system, `oklch()` is the best default.** Even lightness steps stay even, and a fixed hue stays fixed. See [palette-generation.md](palette-generation.md).
+
+```css
+oklch(L C H)          /* lightness 0–1, chroma 0–~0.4, hue 0–360 */
+oklch(L C H / alpha)  /* alpha uses a slash, never a comma */
+```
+
+## Converting
+
+Convert when the user asks, when an agreed migration is in scope, or when the project is standardizing on a notation and this value is the straggler. Never convert an isolated value in a project that deliberately uses something else and never because this skill happened to load.
+
+When conversion is in scope, change the values and nothing else:
+
+- Leave CSS keywords alone: `currentColor`, `inherit`, `transparent`, `initial`, `unset`.
+- Leave gradient functions alone. Convert the color stops inside them; do not touch the interpolation method.
+- Leave colors in third-party configs that expect a specific format.
+- Preserve comments and formatting.
+
+```css
+/* Before */
+color: #3b82f6;
+border: 1px solid rgba(0, 0, 0, 0.1);
+
+/* After */
+color: oklch(0.623 0.188 259.815);
+border: 1px solid oklch(0 0 0 / 0.1);
+```
+
+Bulk conversion is a migration, not cleanup. It shifts every rendered color by a rounding margin and touches files nobody asked about, so it has to be the task rather than a side effect.
+
+## Gamut
+
+Every sRGB color exists in Display P3, but not the reverse. P3 covers roughly 50% more colors, which matters only for the most saturated values. A color at 60% of maximum vividness looks the same on both.
+
+Out-of-gamut colors are mapped into the display gamut. CSS gamut mapping reduces chroma while aiming to preserve lightness and hue; browser implementations can differ. Neighboring ramp steps may lose distinctions after mapping, so inspect the rendered palette on each target gamut. Maximum vividness varies by hue and lightness, so one chroma value can exceed the gamut at some steps and fit at others.
+
+The fix is to reduce vividness while holding hue and lightness. Generate ramps against sRGB unless the product is display-restricted, and add P3 as an enhancement:
+
+```css
+.accent {
+  background: #3b82f6;
+}
+
+@media (color-gamut: p3) {
+  .accent {
+    background: oklch(0.62 0.24 259);
+  }
+}
+```
+
+Order matters. The sRGB value comes first so every display gets something, and the P3 rule overrides only where it will render. A P3 color with no fallback is a `MEDIUM` gamut finding: browsers that cannot parse it drop the declaration.
+
+For browser matrices predating `oklch()` support, the same layering works with `@supports`:
+
+```css
+.accent {
+  background: #3b82f6;
+}
+
+@supports (color: oklch(0 0 0)) {
+  .accent {
+    background: oklch(0.62 0.19 259);
+  }
+}
+```
+
+Check the project's actual browser matrix before adding this. On a modern baseline it is dead weight.
+
+## Modern CSS worth knowing
+
+- **`color-mix()`** derives one color from another, as in `color-mix(in oklab, var(--color-accent-solid) 15%, white)` for a tinted background. Useful for states, but keep generated values out of the token layer, since a mixed color cannot be inspected in a design tool.
+- **Relative color syntax** adjusts one channel of an existing color. `oklch(from var(--color-accent-solid) calc(l - 0.1) c h)` darkens the accent by hand. Powerful and easy to overuse, since a token defined by three chained derivations is unreadable.
+- **`light-dark()`** puts both appearances in one declaration. See [palette-generation.md](palette-generation.md).
+
+All three compute at render time, so their output cannot be contrast-checked statically. Measure the rendered result.