@bompus/house-rules 0.0.0-stage → 0.11.0

package/skills/hr-better-colors/token-naming.md

@@ -0,0 +1,97 @@
+# Token naming
+
+Naming is what makes a palette usable by anyone who did not build it. For which ramps exist and what each step does, see [palette-structure.md](palette-structure.md).
+
+## Two tiers
+
+**Primitives** name a value. They are the ramp, named by hue and step: `--blue-500`, `--neutral-200`. A primitive describes what the color _is_, so it never changes meaning between themes and is never applied directly in a component.
+
+**Semantics** name a job. They point at a primitive and take the name of the role they fill: `--color-text-secondary`, `--color-border-subtle`. Components only ever reference this tier.
+
+```css
+:root {
+  /* Tier 1: primitives, named by appearance. Never used directly. */
+  --blue-500: #3b82f6;
+  --neutral-200: #e5e7eb;
+  --neutral-700: #374151;
+
+  /* Tier 2: semantics, named by role. This is what components use. */
+  --color-accent-solid: var(--blue-500);
+  --color-border: var(--neutral-200);
+  --color-text-secondary: var(--neutral-700);
+}
+```
+
+The tiering is what makes theming possible. Dark mode, a white-label theme and an increased-contrast variant all repoint the semantic tier, leaving the primitives and every component untouched. A codebase applying `--blue-500` directly in components has no theming seam. Adding one later means auditing every usage to work out which meant "the accent" and which just wanted blue.
+
+Add a third, component-level tier (`--color-button-danger-bg`) only where a component genuinely and intentionally diverges from the system. One component token is a documented exception; twenty mean the semantic tier is missing roles.
+
+## The role inventory
+
+A system is complete when every role below has a token. Build against this list rather than adding tokens as components demand them, or the palette ends up shaped like whichever screen came first.
+
+| Group    | Roles                                                                                     |
+| -------- | ----------------------------------------------------------------------------------------- |
+| Surfaces | page background, surface, raised (menus, popovers), sunken (inputs, wells), overlay scrim |
+| Text     | primary, secondary, disabled, inverse, on-accent                                          |
+| Borders  | subtle, default, strong, focus ring, separator                                            |
+| Accent   | subtle background, border, solid, solid hover, text                                       |
+| Status   | per status shipped: subtle background, border, solid, text                                |
+
+Separator and border are separate roles even when they share a value today. A separator divides content; a border encloses a control. They diverge the first time someone restyles inputs, and a system that conflated them gets untangled at that moment.
+
+## Naming grammar
+
+Use one shape and never deviate: `--color-{role}-{variant}-{state}`.
+
+```css
+--color-bg-surface
+--color-text-secondary
+--color-border-strong
+--color-accent-solid-hover
+```
+
+Pick one word per concept and use only that word. Consistency matters more than the vocabulary. A reader who has seen `--color-text-primary` must be able to guess `--color-text-disabled` without looking:
+
+| Concept     | Pick one | Never mix in                                     |
+| ----------- | -------- | ------------------------------------------------ |
+| Foreground  | `text`   | `fg`, `foreground`, `content`, `ink`             |
+| Background  | `bg`     | `background`, `surface` as a synonym, `fill`     |
+| Edge        | `border` | `stroke`, `outline`, `line`                      |
+| Brand color | `accent` | `primary`, `brand`, `theme` used interchangeably |
+
+Reserve `primary` for exactly one meaning. `--color-text-primary` for body text beside `--color-primary` for the brand is the most common naming collision there is, and it makes every `primary` token ambiguous until you open its definition. Use `accent` for the brand and let `primary` mean "the most prominent of its group".
+
+## Anti-patterns
+
+| Name                             | Problem                                                                 | Instead                        |
+| -------------------------------- | ----------------------------------------------------------------------- | ------------------------------ |
+| `--color-blue-button`            | Appearance at the semantic tier; lies the moment the brand changes      | `--color-accent-solid`         |
+| `--color-sidebar-gray`           | Named for where it was used first; the second usage makes it nonsense   | `--color-bg-surface`           |
+| `--color-light-gray`             | Lies in dark mode, where it is the dark one                             | `--neutral-200` as a primitive |
+| `--color-text-2`                 | Numbered semantics carry no meaning; nobody can guess what `3` would be | `--color-text-secondary`       |
+| `--color-gray-hover`             | Mixes a hue with a state and belongs to no tier                         | `--color-bg-surface-hover`     |
+| `--blue-500` used in a component | Skips the semantic tier and removes the theming seam                    | Point a semantic token at it   |
+
+Every one of them is a case of **Use a token only in its role**. See [color-usage.md](color-usage.md).
+
+## In Tailwind projects
+
+Tailwind v4 generates utilities from `@theme`, so names declared there become the API. Declare primitives and semantics in the same block; the `--color-*` namespace is what produces `bg-*`, `text-*` and `border-*`:
+
+```css
+@theme {
+  /* Primitives */
+  --color-brand-50: #eff6ff;
+  --color-brand-500: #3b82f6;
+  --color-brand-900: #1e3a8a;
+
+  /* Semantics: what templates should use */
+  --color-accent-solid: var(--color-brand-500);
+  --color-text-secondary: var(--color-neutral-700);
+}
+```
+
+That yields `bg-accent-solid` and `text-text-secondary` alongside `bg-brand-500`, because Tailwind v4 appends everything after `--color-` to the utility prefix. Both are reachable, so the discipline is a convention rather than a constraint. Templates use the semantic utilities, and a raw `bg-brand-500` in a component is the thing to flag.
+
+Opacity modifiers work on either tier, as in `bg-accent-solid/50`. But a color carrying alpha cannot be contrast-checked against a static background, because what it renders depends on what sits behind it. Use solid tokens for anything with text on it.

package/skills/hr-better-layout/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jakub Krehel
+Copyright (c) 2026 Emil Kowalski
+
+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-layout/NOTICE.md

@@ -0,0 +1,48 @@
+# Source notices
+
+This notice accompanies the hr-better-layout 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
+
+## emilkowalski/skills
+
+Source: https://github.com/emilkowalski/skills (compared at revision `e8a175de22ae1e49370fc144c1f3bb9aeedf988d`)
+
+- `skills/hr-better-accessibility/` and `skills/hr-better-layout/`: mobile behavior and
+  viewport guidance adapted from `skills/mobile-native/SKILL.md`.
+- `skills/hr-better-layout/`, `skills/hr-better-typography/` and `skills/hr-better-writing/`:
+  clipping, truncation and plural-form guidance adapted from `skills/break-ui/SKILL.md`.
+
+Copyright (c) 2026 Emil Kowalski
+
+## 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-layout/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: hr-better-layout
+description: "Layout rules for web UI: grouping, alignment, spacing, reading order, responsive breakpoints, logical properties and clipping at narrow widths. Use when building or reviewing page or component layout CSS."
+license: MIT
+metadata:
+  upstream: https://github.com/jakubkrehel/skills
+  upstream_ref: 267330e1adfc66a718fb65fa6918c1f06d0a689e
+  upstream_path: skills/better-layout/
+  local_patches: "Use-when description; peek-scroller arithmetic; better-ui handoff dropped (not vendored); dvh/svh, viewport-fit, theme-color and row-squeeze rules (from emilkowalski/skills)"
+  house_rules_patches: "Portable provenance and review verdict"
+  mobile_native_source: https://github.com/emilkowalski/skills/blob/e8a175de22ae1e49370fc144c1f3bb9aeedf988d/skills/mobile-native/SKILL.md
+  break_ui_source: https://github.com/emilkowalski/skills/blob/e8a175de22ae1e49370fc144c1f3bb9aeedf988d/skills/break-ui/SKILL.md
+---
+
+# Layout
+
+Position, spacing and alignment carry hierarchy before a word is read. This skill builds that structure and stress-tests it: resize it, translate it, mirror it for RTL.
+
+Write every fix in the project's styling system. The numbers below are starting points for interfaces with no established density system, and where one applies, use it as written rather than a familiar-looking substitute. Keep deliberate platform chrome, compact professional tools and project tokens where they still pass the stress tests.
+
+Hit areas and focus behavior belong to `hr-better-accessibility`. Radius, shadows and animation are outside this skill. Line length and text spacing belong to `hr-better-typography`.
+
+## Group with space, not lines
+
+Space groups first, background shapes second, separator lines last and only where space alone can't carry the structure. The gap between groups must be at least 2× the gap within one (`8px` intra-group to `16px`+ inter-group), or the grouping reads as noise. Alignment edges and importance ordering are in [grouping-and-alignment.md](grouping-and-alignment.md).
+
+## Keep controls distinct from content
+
+Give every interactive element a background shape, a border, or a consistent placement zone. A control styled like the static text beside it does not read as a control.
+
+## Align to shared edges
+
+Pick alignment edges and stick to them; every stray edge reads as noise. Use one project spacing step per level of subordination, where `16px` is a useful default.
+
+Use logical properties for direction-dependent layout: `padding-inline-start`, `margin-inline-end`. Reserve physical left and right for genuinely physical geometry.
+
+## Order by importance
+
+The most important content sits near the top and the leading edge. Reading order flows top-to-bottom, leading-to-trailing. Think in leading and trailing, not left and right.
+
+## Hint at hidden content
+
+Progressive disclosure needs a visible affordance. Use the project's established cue, or let the next item peek `16–32px` past the scroll edge, or show a disclosure control. Content hidden with zero cue may as well not exist.
+
+## Breathing room between targets
+
+Without an established density system, start with `12px` between adjacent bordered or filled controls and `24px` around borderless text- and icon-only ones. Compact layouts may use less, as long as `hr-better-accessibility` hit areas don't overlap and the controls stay distinct. Layout margins and breakpoint recipes are in [spacing-and-adaptivity.md](spacing-and-adaptivity.md).
+
+## Inset buttons from the edges
+
+In content layouts, keep full-width buttons inside the layout margins with a visible radius, starting near `16px` inline on mobile. Edge-to-edge actions work when they follow established platform chrome, account for safe areas and stay distinguishable from system UI.
+
+## Content bleeds, controls float
+
+Backgrounds and media extend to the viewport edges. Controls and text stay inside the layout margins and safe areas (`env(safe-area-inset-*)`). Sticky chrome floats above the content layer rather than blocking it.
+
+## Hold structure until it breaks
+
+Breakpoints come from the content, not device presets. Keep the expanded layout as long as it genuinely fits and collapse late. Prefer container queries for component-level adaptation, and test the smallest and largest sizes first.
+
+## Plan for growth and clipping
+
+Translated strings grow, and short ones grow proportionally more, so a one-word button label is the riskiest thing on the screen. Put no fixed width or height on a text container, and let rows wrap. Test with pseudo-localization and one representative locale rather than budgeting a percentage.
+
+Never park a critical action where resizing or scrolling clips it. Keep it in the normal flow, or in stable chrome suited to the product.
+
+## Before you finish
+
+| Mistake                                                                    | Fix                                                                              |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `margin-left` / `padding-right` in a localizable layout                    | `margin-inline-start` / `padding-inline-end`                                     |
+| Content-layout button touches the viewport edge                            | Inset within the project margins; keep intentional platform chrome               |
+| Breakpoints at 768/1024 because they're the defaults                       | Break where the content actually stops fitting                                   |
+| Fixed-width text container sized to one language                           | `max-width` and wrapping; test pseudo-localization                               |
+| Primary action at the clip-prone bottom of a pane                          | Sticky positioning or stable chrome with safe-area padding                       |
+| `100vh` app shell or hero on mobile                                        | `100dvh` for a shell that tracks the browser chrome, `100svh` for a first screen |
+| Long text pushes a row's trailing action off-screen or squashes its avatar | `min-width: 0` on the text column, `flex-shrink: 0` on fixed-size items          |
+
+## Reporting
+
+**Severity.** `HIGH` blocks content or an action at a supported viewport. `MEDIUM` harms hierarchy, reading order, or adaptability. `LOW` is isolated alignment or spacing polish.
+
+**Verification.** Without a browser: logical properties in place of physical ones, container and media queries against the supported viewport list and DOM order against the intended reading order. With one: every supported width, 200% zoom and the RTL mirror. 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 layout findings" and report verification.

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

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Better Layout"
+  short_description: "Structure, grouping, alignment and adaptive layout"

package/skills/hr-better-layout/grouping-and-alignment.md

@@ -0,0 +1,144 @@
+# Grouping and alignment
+
+How spacing, shapes, shared edges and ordering communicate what belongs together and what matters most.
+
+## Group with space, not lines
+
+Three tools create grouping, in order of preference:
+
+1. **Negative space**, the default. Related items sit close, unrelated ones far apart.
+2. **Background shapes**, a card or filled container, where a group must read as one unit such as a selectable row or a draggable card.
+3. **Separator lines**, a last resort for dense data where space costs too much, such as tables and long settings lists.
+
+The structural rule is that the gap between groups is at least 2× the gap within one. At `8px` inside a group, groups need `16px`+ between them, or the eye can't tell where one ends.
+
+```css
+/* Good: spacing alone communicates the grouping */
+.field-group {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+}
+
+/* Bad: uniform spacing plus lines to compensate */
+.form > * {
+  margin-bottom: 12px;
+  border-bottom: 1px solid var(--separator);
+}
+```
+
+```html
+<!-- Good: Tailwind -->
+<div class="space-y-6">
+  <div class="space-y-2">…field group…</div>
+  <div class="space-y-2">…field group…</div>
+</div>
+```
+
+Where a separator is genuinely needed, keep it quiet: hairline width, low contrast, never combined with a large gap that already did the job.
+
+## Keep controls distinct from content
+
+Interactive elements need a visual signal: a background, a border, an underline, or placement in a consistent control zone such as a toolbar or footer row. A control styled identically to static text is invisible.
+
+```html
+<!-- Bad: action looks exactly like the description text next to it -->
+<p class="text-zinc-600">Your trial ends soon. Upgrade now</p>
+
+<!-- Good: the action reads as an action -->
+<p class="text-zinc-600">Your trial ends soon.</p>
+<button class="font-medium text-blue-600">Upgrade now</button>
+```
+
+The inverse holds too. A non-clickable badge shaped exactly like the buttons beside it collects dead clicks.
+
+## Align to shared edges
+
+Pick a small set of alignment edges and put everything on them, because the eye tracks straight edges to scan content.
+
+- Every stray edge reads as noise even when nobody can name it: an icon 2px off the text edge, a card padded unlike its neighbor.
+- Use one project spacing step to express hierarchy. `16px` is a useful default where no scale exists, and deeper nesting repeats the same step.
+- Numbers in tables align to the trailing edge, text to the leading edge. Tabular figures are `hr-better-typography`'s.
+
+```css
+/* Good: one shared leading edge, one indent step */
+.section {
+  padding-inline: 24px;
+}
+.section .child {
+  margin-inline-start: 16px;
+}
+
+/* Bad: three unrelated leading edges in one column */
+.header {
+  padding-inline-start: 20px;
+}
+.list-item {
+  padding-inline-start: 14px;
+}
+.footer {
+  padding-inline-start: 24px;
+}
+```
+
+## Logical properties, not physical
+
+Express direction-dependent horizontal position as leading/trailing so the layout mirrors automatically under `dir="rtl"`:
+
+| Physical (avoid)   | Logical (use)           |
+| ------------------ | ----------------------- |
+| `margin-left`      | `margin-inline-start`   |
+| `padding-right`    | `padding-inline-end`    |
+| `left: 0`          | `inset-inline-start: 0` |
+| `text-align: left` | `text-align: start`     |
+| `border-right`     | `border-inline-end`     |
+
+```html
+<!-- Good: Tailwind logical utilities -->
+<div class="ms-4 pe-6 text-start">…</div>
+
+<!-- Bad: breaks in RTL -->
+<div class="ml-4 pr-6 text-left">…</div>
+```
+
+Reserve physical properties for things that refer to physical screen sides whatever the language, such as positioning against a device notch or matching a gesture direction.
+
+Where arrangement encodes progression, as in star ratings, step indicators and progress bars, the sequence mirrors in RTL and stars fill from the trailing side. Flexbox and grid with logical properties mirror automatically; hand-positioned elements do not. Digit order inside numbers never reverses, which with other bidi rules belongs to `hr-better-typography`.
+
+## Order by importance
+
+Readers scan top-to-bottom and leading-to-trailing. Place content accordingly:
+
+- The most important information sits near the top and the leading edge. The further down and trailing something sits, the less attention it gets.
+- Give essential information room. Never bury the one number the user came for under rows of secondary detail. Push that into collapsed sections, tabs, or detail views.
+- Within a row, identifying content leads and metadata and actions trail.
+
+```html
+<!-- Good: primary fact first, detail demoted -->
+<div>
+  <p class="text-2xl font-semibold">$4,320.00</p>
+  <p class="text-sm text-zinc-500">Available balance</p>
+</div>
+
+<!-- Bad: the key fact is buried below the fold of the card -->
+<div>
+  <p class="text-sm">Account 4402 · Opened 2019 · Standard tier</p>
+  <p class="text-sm">Last statement: June 30</p>
+  <p class="text-sm">Balance: $4,320.00</p>
+</div>
+```
+
+With logical properties, the same hierarchy mirrors correctly in RTL locales.
+
+## Don't overload the entry point
+
+The first screenful is a table of contents, not the whole book. If everything is prominent, nothing is:
+
+- One primary action per view. `hr-better-colors` owns how color enforces it.
+- Group secondary actions behind a menu once they exceed two or three.
+- Prefer a short view that links deeper over a long view that shows everything at level one.

package/skills/hr-better-layout/spacing-and-adaptivity.md

@@ -0,0 +1,215 @@
+# Spacing and adaptivity
+
+Space between controls, margins against the viewport, hints at off-screen content and layouts that survive resizing and translation.
+
+## Breathing room between targets
+
+Controls placed too close get mis-tapped and read as one unit. Where the project has no density scale, start here:
+
+| Between                                                 | Starting point                   |
+| ------------------------------------------------------- | -------------------------------- |
+| Adjacent bordered/filled controls (buttons, inputs)     | `12px`                           |
+| Around borderless controls (text buttons, icon buttons) | `24px`                           |
+| Unrelated control groups                                | `24px`+ (2× the intra-group gap) |
+
+Borderless controls need more clearance, because nothing marks where one target ends and the next begins. The space is the boundary. Compact professional tools may use less where hit areas stay distinct and never overlap. Preserve an established, usable density rather than expanding controls to match these values.
+
+```html
+<!-- Good: bordered buttons at 12px, icon buttons given room -->
+<div class="flex gap-3">
+  <button class="rounded-lg border px-4 py-2">Cancel</button>
+  <button class="rounded-lg bg-blue-600 px-4 py-2 text-white">Save</button>
+</div>
+
+<!-- Bad: three borderless icon buttons packed at 4px -->
+<div class="flex gap-1">
+  <button><TrashIcon /></button>
+  <button><ArchiveIcon /></button>
+  <button><ShareIcon /></button>
+</div>
+```
+
+WCAG target-size requirements, larger usability targets and pseudo-element expansion belong to `hr-better-accessibility`; these clearances are in addition, so expanded hit areas never overlap.
+
+## Inset buttons from the edges
+
+In content layouts, buttons pressed against the viewport look like system chrome and clip against curved corners or gesture zones. Keep them inside the layout margins. Edge-to-edge actions stay valid where they are deliberately platform chrome and account for safe areas:
+
+```css
+/* Good: inset action bar */
+.action-bar {
+  padding-inline: 16px;
+  padding-bottom: calc(16px + env(safe-area-inset-bottom));
+}
+.action-bar button {
+  width: 100%;
+  border-radius: 12px;
+}
+
+/* Bad: button glued to all three edges */
+.action-bar button {
+  width: 100vw;
+  border-radius: 0;
+  position: fixed;
+  bottom: 0;
+}
+```
+
+Start near `16px` inline margin on mobile where the project has no layout token. The button can still span the full content width inside them.
+
+## Progressive disclosure needs an affordance
+
+Hiding complexity is good; hiding it without a cue is a trap. Every piece of off-screen or collapsed content needs a visible hint that it exists. Keep the product's established scroll indicator or disclosure pattern, and use the recipes below only where no cue exists:
+
+- **Peeking items.** In a horizontal scroller or carousel, size items so the next one peeks `16–32px` past the container edge. A row of cards that ends exactly at the edge looks complete, and nobody scrolls it.
+- **Disclosure controls.** Collapsed sections get a chevron or "Show more", labelled with what is hidden: "Show 12 more results", not "More".
+- **Truncation cues.** Clamped text shows an ellipsis and a way to expand. Truncation mechanics are `hr-better-typography`'s.
+
+In the peeking-scroller recipe, the container's padding creates the peek and snap points stay on the content edge. A percentage basis resolves against the content box, which already excludes that padding, so each item subtracts only the gap and the next item shows through the `24px` inline padding.
+
+```css
+.scroller {
+  display: flex;
+  gap: 12px;
+  overflow-x: auto;
+  padding-inline: 24px;
+  scroll-padding-inline: 24px;
+  scroll-snap-type: x mandatory;
+}
+.scroller > * {
+  flex: 0 0 calc(100% - 12px); /* content box minus the gap; the peek is the 24px padding */
+  scroll-snap-align: start;
+}
+```
+
+```html
+<!-- Tailwind: the content box minus the gap leaves the next card's leading 24px visible -->
+<div class="flex gap-3 overflow-x-auto px-6 [scroll-padding-inline:1.5rem] snap-x snap-mandatory">
+  <div class="w-[calc(100%-0.75rem)] shrink-0 snap-start">…</div>
+  <div class="w-[calc(100%-0.75rem)] shrink-0 snap-start">…</div>
+</div>
+```
+
+## Content bleeds, controls float
+
+The two layers behave differently at the edges:
+
+- **Content layer**: backgrounds, hero media and scrollable lists extend to the viewport edges.
+- **Control layer**: text and controls stay inside the layout margins and safe areas, floating above the content.
+
+```css
+/* Good: full-bleed media inside a constrained article */
+.article {
+  display: grid;
+  grid-template-columns: 1fr min(65ch, calc(100% - 48px)) 1fr;
+}
+.article > * {
+  grid-column: 2;
+}
+.article > .full-bleed {
+  grid-column: 1 / -1;
+}
+```
+
+Sticky headers and floating action buttons account for safe areas:
+
+```css
+.fab {
+  position: fixed;
+  inset-inline-end: calc(16px + env(safe-area-inset-right));
+  bottom: calc(16px + env(safe-area-inset-bottom));
+}
+.fab:dir(rtl) {
+  inset-inline-end: calc(16px + env(safe-area-inset-left));
+}
+```
+
+`env(safe-area-inset-*)` reads `0px` unless the viewport meta includes `viewport-fit=cover`.
+
+Full-height layouts pick their viewport unit by job. On mobile `100vh` is the largest viewport, measured with the URL bar collapsed, so on load it overflows and hides a bottom-pinned action under the browser chrome.
+
+```css
+/* App shell, sheet or drawer: tracks the visible area as the chrome shows and hides */
+.app {
+  height: 100dvh;
+}
+
+/* First screen or hero: the smallest viewport, so nothing is cut off and nothing shifts mid-scroll */
+.hero {
+  min-height: 100svh;
+}
+```
+
+Match `theme-color` to the color at the top of the page, once per color scheme.
+It suggests browser chrome colors in supporting browsers; verify the effect on supported platforms:
+
+```html
+<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
+<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a" />
+```
+
+A theme switched by class rather than the OS setting updates the tag from script on toggle.
+
+## Hold structure until it breaks
+
+Breakpoints belong to the content, not the device catalog:
+
+- Break where the layout actually stops fitting, not at `768px` because a preset says so. That is where the sidebar squeezes content below its minimum measure, or the card grid drops below a usable column width.
+- Collapse late. A layout keeping its expanded structure as long as it genuinely fits stays stable and familiar. Premature collapsing throws away space users paid for.
+- Prefer **container queries** for components. A card adapts to the column it is in, not to the viewport.
+
+```css
+/* Good: component adapts to its container */
+.card-list {
+  container-type: inline-size;
+}
+@container (max-width: 400px) {
+  .card {
+    grid-template-columns: 1fr;
+  }
+}
+
+/* Bad: viewport media query breaks the card inside a narrow sidebar */
+@media (max-width: 768px) {
+  .card {
+    grid-template-columns: 1fr;
+  }
+}
+```
+
+Test the smallest and largest supported sizes first, since those break first, then the sizes between.
+
+## Plan for growth and clipping
+
+Layouts fail in two directions. Content grows, and viewports shrink.
+
+**String expansion varies by language and by source-string length.** Never rely on one universal percentage.
+
+- No fixed widths sized to English labels. Use `max-width` plus wrapping.
+- No fixed heights on text containers. Use `min-height` where a floor is needed.
+- Buttons size themselves from their label (`padding-inline`), never a hardcoded width.
+- Test with pseudo-localization or a long-string locale before shipping.
+
+**Rows squeeze from the middle.** In a row of avatar, text and trailing action, long text pushes the action off the row unless the text column may shrink below its content width:
+
+- `min-width: 0` on the flex text column, or `minmax(0, 1fr)` for a grid track. The default `min-width: auto` refuses to shrink.
+- `flex-shrink: 0` on avatars, icons, badges and trailing actions, so they keep their size instead of squashing into ovals.
+- Top-align the row (`align-items: flex-start`) once the text can wrap to several lines.
+
+```css
+/* Good: label defines the size */
+.button {
+  padding-inline: 16px;
+  max-inline-size: 100%;
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+
+/* Bad: German will overflow or truncate */
+.button {
+  width: 96px;
+  overflow: hidden;
+}
+```
+
+**Clipping.** Never park a critical action where it can be cut off: the bottom edge of a resizable pane, below the fold of a fixed-height modal, behind an expanding keyboard. Keep primary actions in stable chrome, a sticky footer with safe-area padding or the top of the view. Where a modal's content scrolls, its action row does not.

package/skills/hr-better-typography/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jakub Krehel
+Copyright (c) 2026 Emil Kowalski
+
+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.