@damiangilgonzalez/harness 1.3.7

package/skills/mejor-colores/palette-structure.md

@@ -0,0 +1,76 @@
+# Palette structure
+
+What a color system is made of, before any values exist. For computing the values see [palette-generation.md](palette-generation.md); for what to call them see [token-naming.md](token-naming.md).
+
+## What a system needs
+
+Most products need three kinds of ramp and nothing else:
+
+| Ramp | How many | Notes |
+| --- | --- | --- |
+| Neutral | 1 | Carries 80–90% of the interface: backgrounds, borders, body text |
+| Accent | 1 | The brand hue. Interactive and selected states |
+| Status | 0–4 | `danger`, `warning`, `success`, `info`. Add one only when the product shows that state |
+
+A second accent hue must also never sit adjacent to the first. Where it would, the accent ramp's own steps provide the range.
+
+## Every step has a job
+
+Each step maps to a role. Generate the steps the roles below call for and skip the rest.
+
+| Role | Tailwind | Radix |
+| --- | --- | --- |
+| Page background | `50` | `1` |
+| Subtle background | `50` | `2` |
+| Component background | `100` | `3` |
+| Component hover | `200` | `4` |
+| Component active / selected | `200` | `5` |
+| Subtle border | `200` | `6` |
+| Border, separator | `300` | `7` |
+| Strong border, focus ring | `400` | `8` |
+| Solid fill | `500` | `9` |
+| Solid fill hover | `600` | `10` |
+| Low-contrast text | `700` | `11` |
+| High-contrast text | `900` | `12` |
+
+The two conventions differ in kind, not only in numbering:
+
+- **Radix defines its 12 steps by role.** Step 9 is "the solid fill" in every ramp and appearance. The dark scale is a separate ramp reusing the same numbers, so `--accent-9` is the fill in both and component CSS never changes.
+- **Tailwind defines its 11 steps by lightness.** `50` is light, `950` is dark. The mapping above therefore holds in light mode and inverts in dark, with the page background at `950` and high-contrast text at `50`. Components either swap step numbers per appearance or read a semantic token that swaps once.
+
+Match whichever the project uses. For a new system prefer Radix's model, because a role-defined step survives a theme change that a lightness-defined step does not. On Tailwind, keep `50`–`950` and put the role mapping in the semantic tier.
+
+Tailwind's 11 steps cover 12 roles, so some do double duty. Where the table repeats a step, the two roles are adjacent in practice and the collision is real. A design needing a subtle border and a component hover to be distinguishable needs a 12-step ramp.
+
+## Neutrals
+
+A pure gray ramp is a perfectly good default. It sits under any accent hue without competing and never needs revisiting when the brand color changes.
+
+Tinting the neutral toward the accent hue is a stylistic option, not a correction. A trace of the accent, a few percent of its vividness, puts the greys in the same family as the accent rather than merely coexisting with it. Enough to measure, not enough to name. Neither choice reads as a mistake.
+
+Warm neutrals, hue toward orange, read approachable and editorial; cool ones, toward blue, read technical and precise. Whichever you pick, including none, hold it across the whole ramp. A warm gray border on a cool gray background is visible even when neither color is nameable alone.
+
+Neutrals carry the most roles, so they need the most steps. Never generate fewer neutral steps than accent steps.
+
+## Status colors
+
+Convention constrains status hues before taste does. Red reads as danger, amber as warning, green as success. See the cultural exceptions in [color-usage.md](color-usage.md).
+
+Two rules govern them:
+
+- **Keep every status hue distinct from the accent.** If the brand is red, the danger ramp cannot also be red. Move danger toward a deeper crimson and check the two side by side, or the destructive and primary actions are the same button.
+- **Status ramps need fewer steps than the accent.** Most render four roles: a background, a border, a solid fill and text. Generate the full ramp only where the product styles status components across the whole range.
+
+Status color is never the only signal of a state change; pair it with an icon or text. `better-accessibility` owns that requirement.
+
+## Auditing an existing palette
+
+Before restructuring a system, inventory it. Most codebases hold several times more colors than the design has decisions.
+
+1. **Collect every literal.** Grep for hex, `rgb(`, `hsl(`, `oklch(` and the project's utility-class prefixes. Include SVG `fill`/`stroke`, chart configs and email templates. Colors hide outside stylesheets.
+2. **Sort by perceived lightness within each hue family.** Duplicates surface immediately as near-identical neighbors.
+3. **Collapse near-duplicates.** Two colors closer than about one ramp step are one color that drifted. Keep the one used most and retire the others. Never average them.
+4. **Assign each survivor a role** from the table above. A color matching no role is a missing token or a mistake. Decide which, and say so in the finding.
+5. **Count what is left.** More than one ramp per role above means the palette outgrew its structure, not that the product needs more color.
+
+Report the inventory before changing anything. Consolidating a palette changes rendered output on screens nobody asked you to touch, so it stays a proposal until the user accepts it.

package/skills/mejor-colores/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-secondary` alongside `bg-brand-500`. 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/mejor-layout/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: mejor-layout
+description: "Use when building or reviewing a screen's layout — grouping, alignment, reading order, progressive disclosure, spacing, breakpoints, translated-text growth, and RTL."
+tags: ["layout", "responsive-design", "ui-design"]
+profiles: [ui, full]
+---
+
+# Layout
+
+La posicion, el espaciado y la alineacion transmiten jerarquia antes de que se lea una sola palabra. Esta skill construye esa estructura y la somete a esfuerzo: redimensionala, traducela, reflejala en RTL.
+
+Escribe cada arreglo en el sistema de estilos del proyecto. Los numeros de abajo son puntos de partida para interfaces sin sistema de densidad establecido; donde haya uno, usalo tal cual y no un sustituto que se le parezca. Conserva el chrome de plataforma deliberado, las herramientas profesionales compactas y los tokens del proyecto mientras sigan pasando las pruebas de esfuerzo.
+
+Las areas de pulsacion y el comportamiento del foco son de `mejor-accesibilidad`. Radios, sombras y animacion son de `mejor-ui`. La longitud de linea y el espaciado del texto son de `mejor-tipografia`.
+
+## Agrupa con espacio, no con lineas
+
+Primero espacio, luego formas de fondo, y lineas separadoras al final, solo donde el espacio por si solo no sostiene la estructura. El hueco ENTRE grupos debe ser al menos 2x el hueco DENTRO de uno (`8px` intragrupo frente a `16px`+ intergrupo), o la agrupacion se lee como ruido. Los bordes de alineacion y el orden de importancia estan en [grouping-and-alignment.md](grouping-and-alignment.md).
+
+## Manten los controles distintos del contenido
+
+Da a todo elemento interactivo una forma de fondo, un borde o una zona de colocacion consistente. Un control estilizado como el texto estatico de al lado no se lee como control.
+
+## Alinea a bordes compartidos
+
+Elige bordes de alineacion y respetalos; cada borde suelto se lee como ruido. Usa un paso de espaciado del proyecto por nivel de subordinacion, con `16px` como valor por defecto util.
+
+Usa propiedades logicas para el layout dependiente de direccion: `padding-inline-start`, `margin-inline-end`. Reserva left y right fisicos para geometria genuinamente fisica.
+
+## Ordena por importancia
+
+El contenido mas importante va arriba y en el borde de inicio. El orden de lectura fluye de arriba a abajo y de inicio a fin. Piensa en inicio y fin, no en izquierda y derecha.
+
+## Insinua el contenido oculto
+
+La divulgacion progresiva necesita una pista visible. Usa la senal establecida del proyecto, o deja que el siguiente elemento asome `16-32px` mas alla del borde de scroll, o muestra un control de despliegue. Contenido escondido sin ninguna pista es como si no existiera.
+
+## Aire entre objetivos
+
+Sin un sistema de densidad establecido, empieza con `12px` entre controles adyacentes con borde o relleno y `24px` alrededor de los que son solo texto o solo icono sin borde. Los layouts compactos pueden usar menos, siempre que las areas de pulsacion de `mejor-accesibilidad` no se solapen y los controles sigan distinguiendose. Los margenes de layout y las recetas de breakpoint estan en [spacing-and-adaptivity.md](spacing-and-adaptivity.md).
+
+## Separa los botones de los bordes
+
+En layouts de contenido, manten los botones a ancho completo dentro de los margenes del layout y con un radio visible, empezando cerca de `16px` en movil. Las acciones de borde a borde funcionan cuando siguen el chrome establecido de la plataforma, respetan las areas seguras y siguen siendo distinguibles de la UI del sistema.
+
+## El contenido sangra, los controles flotan
+
+Fondos y medios llegan hasta los bordes del viewport. Controles y texto se quedan dentro de los margenes del layout y las areas seguras (`env(safe-area-inset-*)`). El chrome pegajoso flota sobre la capa de contenido en lugar de bloquearla.
+
+## Sostiene la estructura hasta que rompa
+
+Los breakpoints salen del contenido, no de presets de dispositivo. Manten el layout expandido mientras quepa de verdad y colapsa tarde. Prefiere container queries para adaptacion a nivel de componente, y prueba primero los tamanos mas pequeno y mas grande.
+
+## Preve el crecimiento y el recorte
+
+Las cadenas traducidas crecen, y las cortas crecen proporcionalmente mas: la etiqueta de boton de una sola palabra es lo mas arriesgado de la pantalla. No pongas ancho ni alto fijo a un contenedor de texto, y deja que las filas hagan wrap. Prueba con pseudo-localizacion y un idioma representativo en vez de presupuestar un porcentaje.
+
+Nunca aparques una accion critica donde redimensionar o hacer scroll la recorte. Dejala en el flujo normal, o en chrome estable adecuado al producto.
+
+## Antes de terminar
+
+| Error | Arreglo |
+| --- | --- |
+| `margin-left` / `padding-right` en un layout localizable | `margin-inline-start` / `padding-inline-end` |
+| Boton de layout de contenido tocando el borde del viewport | Sangralo dentro de los margenes; conserva el chrome de plataforma intencionado |
+| Breakpoints en 768/1024 porque son los de por defecto | Rompe donde el contenido deja de caber de verdad |
+| Contenedor de texto de ancho fijo dimensionado para un idioma | `max-width` y wrap; prueba pseudo-localizacion |
+| Accion principal al fondo recortable de un panel | Posicion sticky o chrome estable con padding de area segura |
+
+## Como reportar
+
+**Severidad.** `ALTA` bloquea contenido o una accion en un viewport soportado. `MEDIA` dana la jerarquia, el orden de lectura o la adaptabilidad. `BAJA` es pulido aislado de alineacion o espaciado.
+
+**Verificacion.** Sin navegador: propiedades logicas en lugar de fisicas, container y media queries contra la lista de viewports soportados, y orden del DOM contra el orden de lectura pretendido. Con navegador: cada ancho soportado, zoom al 200% y el espejo RTL. Reporta como `No verificado` toda comprobacion que no pudieras ejecutar.
+
+**Formato.** Agrupa los hallazgos bajo el principio que incumplen, ordenados por severidad, una fila por causa raiz listando todas las ubicaciones donde aparece:
+
+| Severidad | Ubicacion | Antes | Despues | Por que |
+| --- | --- | --- | --- | --- |
+
+`Ubicacion` es `ruta/al/fichero:linea`. `Por que` nombra el principio y el impacto en el usuario.
+
+Termina con `Bloquear` si queda alguna `ALTA`, y con `Aprobar` en caso contrario, dejando el resto en la tabla como trabajo pendiente. Nunca `Aprobar` cobertura que no inspeccionaste. Si no hay nada que reportar, di "Sin hallazgos accionables de layout" y reporta la verificacion.

package/skills/mejor-layout/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: mejor-layout
+
+should_trigger:
+  - prompt: "Revisa la disposicion de esta pantalla, el agrupamiento y el orden de lectura."
+    why: "Disparador directo de mejor-layout."
+  - prompt: "Necesito definir los breakpoints de este layout responsive."
+    why: "Disparador directo de mejor-layout."
+  - prompt: "Ayudame con la divulgacion progresiva de esta pagina."
+    why: "Disparador directo de mejor-layout."
+  - prompt: "Review this screen's alignment, spacing and reading order."
+    why: "Disparador directo de mejor-layout."
+  - prompt: "Como deberia crecer este layout cuando el texto se traduce."
+    why: "Disparador directo de mejor-layout."
+
+should_not_trigger:
+  - prompt: "Elige la paleta de colores de esta pantalla."
+    route_to: "mejor-colores"
+    why: "Elegir la paleta de colores es el trabajo de mejor-colores, no de mejor-layout."
+  - prompt: "Escribe el texto del boton principal."
+    route_to: "mejor-redaccion"
+    why: "Escribir el texto de un boton es el trabajo de mejor-redaccion, no de mejor-layout."
+  - prompt: "Anade una animacion de entrada a esta tarjeta."
+    route_to: "animar"
+    why: "Anadir una animacion es el trabajo de animar, no de mejor-layout."
+  - prompt: "Revisa la accesibilidad del formulario."
+    route_to: "mejor-accesibilidad"
+    why: "Revisar la accesibilidad es el trabajo de mejor-accesibilidad, no de mejor-layout."
+
+capability:
+  - scenario: "El usuario construye o revisa la disposicion de una pantalla."
+    must_include:
+      - "layout"

package/skills/mejor-layout/grouping-and-alignment.md

@@ -0,0 +1,123 @@
+# 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 `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 `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. `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/mejor-layout/spacing-and-adaptivity.md

@@ -0,0 +1,159 @@
+# 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 `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 `better-typography`'s.
+
+In the peeking-scroller recipe, the container's padding creates the peek and snap points stay on the content edge.
+
+```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% - 48px - 24px); /* container minus margins minus peek */
+  scroll-snap-align: start;
+}
+```
+
+```html
+<!-- Tailwind: the 80% width keeps the next card's leading 16-32px visible -->
+<div class="flex gap-3 overflow-x-auto px-6 [scroll-padding-inline:1.5rem] snap-x snap-mandatory">
+  <div class="w-[80%] shrink-0 snap-start">…</div>
+  <div class="w-[80%] 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));
+}
+```
+
+## 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.
+
+```css
+/* Good: label defines the size */
+.button { padding-inline: 16px; white-space: nowrap; }
+
+/* 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.