@damiangilgonzalez/harness 1.3.7

package/skills/mejor-ui/enter-exit.md

@@ -0,0 +1,147 @@
+# Enter and exit animations
+
+Staged entrances and the exits that follow them. For interactive state feedback see [animations.md](animations.md); for icon swaps see [icon-transitions.md](icon-transitions.md).
+
+## Enter animations: split and stagger
+
+Use this for infrequent staged entrances where sequence communicates hierarchy: the first load of a page hero, a success state, an empty state. Break a large container into semantic chunks and animate each one. Never stagger routine interactions such as row hovers, keystrokes, or repeated tab changes.
+
+### Step by step
+
+1. **Split** into logical groups (title, description, buttons)
+2. **Stagger** with ~100ms delay between groups
+3. **For titles**, consider splitting into individual words with ~80ms stagger
+4. **Combine** `opacity`, `blur` and `translateY` for the enter effect
+
+### Code example
+
+```tsx
+// Motion (Framer Motion): staggered enter
+function PageHeader() {
+  return (
+    <motion.div
+      initial="hidden"
+      animate="visible"
+      variants={{
+        visible: { transition: { staggerChildren: 0.1 } },
+      }}
+    >
+      <motion.h1
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        Welcome
+      </motion.h1>
+
+      <motion.p
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        A description of the page.
+      </motion.p>
+
+      <motion.div
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        <Button>Get started</Button>
+      </motion.div>
+    </motion.div>
+  );
+}
+```
+
+### CSS-only stagger
+
+```css
+.stagger-item {
+  opacity: 0;
+  transform: translateY(12px);
+  filter: blur(4px);
+  animation: fadeInUp 400ms ease-out forwards;
+}
+
+.stagger-item:nth-child(1) { animation-delay: 0ms; }
+.stagger-item:nth-child(2) { animation-delay: 100ms; }
+.stagger-item:nth-child(3) { animation-delay: 200ms; }
+
+@keyframes fadeInUp {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+    filter: blur(0);
+  }
+}
+```
+
+## Exit animations
+
+Exits are softer and less attention-grabbing than enters. The user's focus is moving to the next thing, so do not fight for it.
+
+### Subtle exit (recommended)
+
+```tsx
+// Small fixed translateY: indicates direction without drama
+<motion.div
+  exit={{
+    opacity: 0,
+    y: -12,
+    filter: "blur(4px)",
+    transition: { duration: 0.15, ease: "easeOut" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Full exit (when context matters)
+
+```tsx
+// Slide fully out: use when spatial context is important
+// (e.g., a card returning to a list, a drawer closing)
+<motion.div
+  exit={{
+    opacity: 0,
+    x: "-100%",
+    transition: { duration: 0.2, ease: "easeOut" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Good vs. bad
+
+```css
+/* Good: subtle exit */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-12px);
+  transition: opacity 150ms ease-out, transform 150ms ease-out;
+}
+
+/* Bad: dramatic exit that steals focus */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-100%) scale(0.5);
+  transition: all 400ms ease-out;
+}
+
+/* Sometimes correct: remove immediately when motion adds no context */
+.item-exit {
+  display: none;
+}
+```
+
+**Key points:**
+- Use a small fixed `translateY`, say `-12px`, rather than the full container height
+- Keep some directional movement to indicate where the element went
+- Exit duration should be shorter than enter duration (150ms vs 300ms)
+- Use a subtle exit when it preserves spatial context. Remove immediately when motion adds no information, the interaction repeats frequently, or reduced motion is requested.
+

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

@@ -0,0 +1,32 @@
+skill: mejor-ui
+
+should_trigger:
+  - prompt: "Pule los radios de borde y las sombras de esta tarjeta."
+    why: "Disparador directo de mejor-ui."
+  - prompt: "Necesito animaciones interrumpibles en este boton."
+    why: "Disparador directo de mejor-ui."
+  - prompt: "Ajusta la escala al pulsar de estos elementos interactivos."
+    why: "Disparador directo de mejor-ui."
+  - prompt: "Polish this component's optical alignment and surface depth."
+    why: "Disparador directo de mejor-ui."
+  - prompt: "Suprime las transiciones raras al cambiar de tema."
+    why: "Disparador directo de mejor-ui."
+
+should_not_trigger:
+  - prompt: "Escribe el copy de este mensaje de error."
+    route_to: "mejor-redaccion"
+    why: "Escribir el copy de un mensaje de error es el trabajo de mejor-redaccion, no de mejor-ui."
+  - prompt: "Genera la paleta de colores del sistema."
+    route_to: "mejor-colores"
+    why: "Generar la paleta de colores es el trabajo de mejor-colores, no de mejor-ui."
+  - prompt: "Revisa el contraste de este texto."
+    route_to: "mejor-colores"
+    why: "Medir el contraste es el trabajo de mejor-colores, no de mejor-ui."
+  - prompt: "Documenta el modelo de dominio."
+    route_to: "domain-modeling"
+    why: "Documentar el modelo de dominio es el trabajo de domain-modeling, no de mejor-ui."
+
+capability:
+  - scenario: "El usuario quiere pulir y mejorar la UI de un proyecto."
+    must_include:
+      - "pule"

package/skills/mejor-ui/icon-transitions.md

@@ -0,0 +1,102 @@
+# Icon transitions
+
+Cross-fading an icon when it changes contextually or by state, with and without a motion library. Icon weight, color and direction live in [icons.md](icons.md).
+
+## Contextual icon animations
+
+When icons appear or disappear contextually, on hover or a state change, animate them with `opacity`, `scale` and `blur` rather than toggling visibility.
+
+### Motion example
+
+This uses the `motion` package. Where the project has `framer-motion`, import the same APIs from `"framer-motion"`. Never mix an installed package with the other's import path.
+
+```tsx
+import { AnimatePresence, motion } from "motion/react";
+
+function IconButton({ isActive, icon: Icon }) {
+  return (
+    <button>
+      <AnimatePresence mode="popLayout">
+        <motion.span
+          key={isActive ? "active" : "inactive"}
+          initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+          exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
+        >
+          <Icon />
+        </motion.span>
+      </AnimatePresence>
+    </button>
+  );
+}
+```
+
+### CSS transition approach (no Motion)
+
+Without Motion or Framer Motion, keep both icons in the DOM and cross-fade with CSS transitions. Neither unmounts, so enter and exit both animate smoothly.
+
+One icon is absolutely positioned on top of the other. Toggling state cross-fades them, the entering icon scaling up from `0.25` while the exiting one scales down to `0.25`, both with opacity and blur.
+
+```tsx
+function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
+  return (
+    <button>
+      <div className="relative">
+        <div
+          className={cn(
+            "absolute inset-0 flex items-center justify-center",
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-100 opacity-100 blur-0"
+              : "scale-[0.25] opacity-0 blur-[4px]"
+          )}
+        >
+          <ActiveIcon />
+        </div>
+        <div
+          className={cn(
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-[0.25] opacity-0 blur-[4px]"
+              : "scale-100 opacity-100 blur-0"
+          )}
+        >
+          <InactiveIcon />
+        </div>
+      </div>
+    </button>
+  );
+}
+```
+
+The non-absolute icon, `InactiveIcon`, defines the layout size. The absolute one, `ActiveIcon`, overlays it without affecting flow.
+
+### Choosing between Motion and CSS
+
+| | Motion (Framer Motion) | CSS transitions (both icons in DOM) |
+| --- | --- | --- |
+| **Enter animation** | Yes | Yes |
+| **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade, icon never unmounts) |
+| **Spring physics** | Yes | No, use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
+| **When to use** | Project already uses `motion` or `framer-motion` | No motion dependency, or keeping bundle small |
+
+Check the project's `package.json`. Import from `"motion/react"` when `motion` is installed, or `"framer-motion"` when that is. Where both exist, follow the imports the component or its nearest peers already use. Where neither is present, use the CSS cross-fade and never add a dependency just for icon transitions.
+
+### When to animate icons
+
+| Animate | Don't animate |
+| --- | --- |
+| Icons that appear on hover (action buttons) | Static navigation icons |
+| State change icons (play → pause, like → liked) | Decorative icons |
+| Icons in contextual toolbars | Icons that are always visible |
+| Loading/success state indicators | Icon labels (text next to icon) |
+
+Use exactly these values for contextual icon animations. Do not deviate:
+- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
+- `opacity`: `0` → `1`
+- `filter`: `"blur(4px)"` → `"blur(0px)"`
+- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }`; **bounce must always be `0`**, never `0.1` or any other value
+

package/skills/mejor-ui/icons.md

@@ -0,0 +1,110 @@
+# Icons
+
+Icon weight, states, sizing and direction, the details that make icons sit naturally in an interface.
+
+## Match icon stroke to text weight
+
+A hairline icon beside semibold text reads as broken; a heavy icon beside regular text shouts.
+
+| Adjacent text | Icon stroke width (24px grid) |
+| --- | --- |
+| Regular (400), 14–16px | `1.5px` |
+| Medium/Semibold (500–600) | `2px` |
+| Bold (700), or emphasized standalone | `2.5px` |
+
+```html
+<!-- Good: stroke tuned to the label weight -->
+<button class="flex items-center gap-2 font-semibold">
+  <PlusIcon stroke-width="2" class="size-4" />
+  New project
+</button>
+
+<!-- Bad: default 1.5px stroke against a bold label -->
+<button class="flex items-center gap-2 font-bold">
+  <PlusIcon stroke-width="1.5" class="size-4" />
+  New project
+</button>
+```
+
+Two related consistency rules:
+
+- **One optical strategy per surface.** Never mix icon libraries with incompatible stroke conventions on one toolbar. Where the library supports stroke variants, match them to adjacent text as above; otherwise keep the set's native stroke and use size or color for emphasis.
+- **Size icons relative to the text's cap height**, typically `1em`–`1.25em` when inline with text, so the pair scales together.
+
+## One SVG, recolored per state
+
+Never ship separate assets for default, hover, selected and disabled states. Use one SVG drawn with `currentColor` and let CSS state drive the color:
+
+```html
+<!-- Good: one asset, states are CSS -->
+<svg fill="none" stroke="currentColor" stroke-width="2">…</svg>
+```
+
+```css
+.icon-button { color: oklch(0.552 0.016 285.938); }
+.icon-button:hover { color: oklch(0.21 0.006 285.885); }
+.icon-button[aria-pressed="true"] { color: oklch(0.623 0.188 259.815); }
+.icon-button:disabled { opacity: 0.4; }
+```
+
+```html
+<!-- Tailwind -->
+<button class="text-zinc-500 hover:text-zinc-900 aria-pressed:text-blue-600 disabled:opacity-40">
+  <BookmarkIcon />
+</button>
+```
+
+Hardcoded fills inside the SVG, such as `fill="#666"`, break this. Strip them to `currentColor` when importing icons.
+
+## Outline default, fill active
+
+Where an icon set offers outline and filled variants, use them as a state pair, never interchangeably:
+
+| Variant | Use for |
+| --- | --- |
+| Outline | Default state: toolbars, list rows, inline with text |
+| Fill | Selected/active state: the active tab, a toggled bookmark, a liked heart |
+
+```tsx
+// Good: variant communicates state
+<TabIcon variant={isActive ? "solid" : "outline"} />
+
+// Bad: filled icons everywhere, so the active tab has no state signal
+<TabIcon variant="solid" />
+```
+
+The swap between variants is a contextual icon animation. Use the exact cross-fade values in [icon-transitions.md](icon-transitions.md).
+
+## Design at render size
+
+An icon that looks great at 48px collapses into mush at 16px. Thin interior lines, tight counters and fine texture all blur or alias when small.
+
+- Test every icon at the smallest size it will render, often `16px`. It must stay recognizable there.
+- Prefer simplified glyphs for small contexts over scaling down detailed artwork.
+- Keep icons on the pixel grid at their render size. A 16px icon drawn on a 24px grid with fractional scaling renders soft, so use the set's native grid sizes (`16`, `20`, `24`) rather than arbitrary scales.
+- Always SVG, never raster, so the same asset stays crisp at every density.
+
+## Icons in RTL
+
+Under `dir="rtl"`, flip icons whose meaning is tied to reading direction, and leave the rest alone:
+
+| Flip | Don't flip |
+| --- | --- |
+| Back/forward arrows, chevrons in navigation | Logos and brand marks |
+| Text-block glyphs (alignment, lists, indent) | Checkmarks |
+| Speaker/volume waves (emanate in reading direction) | Physical objects: clocks, cups, pencils |
+| "Send" style directional glyphs | Media playback (play/rewind refer to tape direction, convention keeps them LTR) |
+
+```css
+/* Good: mirror only direction-dependent icons */
+[dir="rtl"] .icon-directional {
+  scale: -1 1;
+}
+```
+
+```html
+<!-- Tailwind -->
+<ChevronRightIcon class="icon-directional rtl:-scale-x-100" />
+```
+
+Analyze composite icons part by part. A badge or slash overlay may keep its position even when the base glyph flips. Accessible names for icon-only buttons belong to `better-accessibility`.

package/skills/mejor-ui/performance.md

@@ -0,0 +1,88 @@
+# Performance
+
+Transition specificity and GPU compositing hints.
+
+## Transition only what changes
+
+Never use `transition: all` or Tailwind's `transition-all`. Always name the exact properties that change. Tailwind's bare `transition` maps to a curated list of colors, opacity, shadow and transforms rather than `all`, and naming what changes is still better.
+
+### Why
+
+- `transition: all` forces the browser to watch every property for changes
+- Causes unexpected transitions on properties you didn't intend to animate (colors, padding, shadows)
+- Prevents browser optimizations
+
+### CSS example
+
+```css
+/* Good: only transition what changes */
+.button {
+  transition-property: scale, background-color;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+/* Bad: transition everything */
+.button {
+  transition: all 150ms ease-out;
+}
+```
+
+### Tailwind
+
+```tsx
+// Good: explicit properties
+<button className="transition-[scale,background-color] duration-150 ease-out">
+
+// Bad: transition all
+<button className="transition-all duration-150 ease-out">
+```
+
+### Tailwind `transition-transform` note
+
+`transition-transform` in Tailwind maps to `transition-property: transform, translate, scale, rotate`, covering every transform-related property rather than only `transform`. Use it when animating transforms alone. For several non-transform properties, use the bracket syntax `transition-[scale,opacity,filter]`.
+
+## Use `will-change` sparingly
+
+`will-change` hints the browser to pre-promote an element to its own GPU compositing layer. Without it the browser promotes only when the animation starts, and that one-time promotion can cause a micro-stutter on the first frame.
+
+It helps most for `scale`, `rotation` and movement through `transform`. For other properties it does little, because the browser cannot composite them on the GPU anyway.
+
+### Rules
+
+```css
+/* Good: specific property that benefits from GPU compositing */
+.animated-card {
+  will-change: transform;
+}
+
+/* Good: multiple compositor-friendly properties */
+.animated-card {
+  will-change: transform, opacity;
+}
+
+/* Bad: never use will-change: all */
+.animated-card {
+  will-change: all;
+}
+
+/* Bad: properties that can't be GPU-composited anyway */
+.animated-card {
+  will-change: background-color, padding;
+}
+```
+
+### Useful properties
+
+| Property | GPU-compositable | Worth using `will-change` |
+| --- | --- | --- |
+| `transform` | Yes | Yes |
+| `opacity` | Yes | Yes |
+| `filter` (blur, brightness) | Yes | Yes |
+| `clip-path` | Newer Chromium only | Rarely; not reliable cross-browser |
+| `top`, `left`, `width`, `height` | No | No |
+| `background`, `border`, `color` | No | No |
+
+### When to skip
+
+Modern browsers optimize well on their own. Add `will-change` only when you see first-frame stutter, which Safari benefits from most. Never add it preemptively to every animated element, since each extra compositing layer costs memory.

package/skills/mejor-ui/surfaces.md

@@ -0,0 +1,219 @@
+# Surfaces
+
+Border radius, optical alignment, shadows and image outlines.
+
+## Concentric border radius
+
+When nesting rounded elements, the outer radius must equal the inner radius plus the padding between them:
+
+```
+outerRadius = innerRadius + padding
+```
+
+The rule matters most when nested surfaces sit close together. Past `24px` of padding, treat the layers as separate surfaces and choose each radius independently rather than forcing concentric math.
+
+### Example
+
+```css
+/* Good: concentric radii */
+.card {
+  border-radius: 20px; /* 12 + 8 */
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+
+/* Bad: same radius on both */
+.card {
+  border-radius: 12px;
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+```
+
+### Tailwind example
+
+```tsx
+// Good: outer radius accounts for padding
+<div className="rounded-2xl p-2">       {/* 16px radius, 8px padding */}
+  <div className="rounded-lg">          {/* 8px radius = 16 - 8 ✓ */}
+    ...
+  </div>
+</div>
+
+// Bad: same radius on both
+<div className="rounded-xl p-2">
+  <div className="rounded-xl">          {/* same radius, looks off */}
+    ...
+  </div>
+</div>
+```
+
+Mismatched radii on closely nested surfaces are a common source of visual tension. Calculate concentrically where the layers share a visible, even inset. Keep an established component token where they are independent or the padding is deliberately asymmetric.
+
+## Optical alignment
+
+When geometric centering looks off, align optically instead.
+
+### Buttons with text + icon
+
+Where an icon makes symmetric padding look unbalanced, use slightly less on the icon side. A starting point:
+`icon-side padding = text-side padding - 2px`.
+
+```css
+/* Good: less padding on icon side */
+.button-with-icon {
+  padding-inline-start: 16px;
+  padding-inline-end: 14px; /* trailing icon side = text side - 2px */
+}
+
+/* Bad: equal padding looks like icon is pushed too far right */
+.button-with-icon {
+  padding-inline: 16px;
+}
+```
+
+```tsx
+// Tailwind
+<button className="ps-4 pe-3.5 flex items-center gap-2">
+  <span>Continue</span>
+  <ArrowRightIcon />
+</button>
+```
+
+### Play button triangles
+
+Play icons are triangular and their geometric center is not their visual center. Shift slightly right:
+
+```css
+/* Good: optically centered */
+.play-button svg {
+  transform: translateX(2px); /* physical correction to the glyph itself */
+}
+
+/* Bad: geometrically centered but looks off */
+.play-button svg {
+  /* no adjustment */
+}
+```
+
+### Asymmetric icons (stars, arrows, carets)
+
+Some icons carry uneven visual weight. The best fix is adjusting the SVG directly, so the component needs no extra margin or padding.
+
+```tsx
+// Best: fix in the SVG itself
+// Adjust the viewBox or path to visually center the icon
+
+// Fallback: adjust with margin
+<span className="translate-x-px">
+  <StarIcon />
+</span>
+```
+
+## Shadows instead of borders
+
+Where **buttons, cards and containers** use a border for depth or elevation, replace it with a subtle `box-shadow`. Shadows use transparency, so they adapt to any background where solid borders do not. That matters most over images or multiple background colors, which a fixed border color was never designed for.
+
+**Never apply this to dividers**, meaning `border-b`, `border-t` and side borders, or any border whose purpose is layout separation rather than depth. Those stay borders.
+
+### Shadow as border (light mode)
+
+Three layers. The first acts as a 1px border ring, the second adds subtle lift, the third ambient depth:
+
+```css
+:root {
+  --shadow-border:
+    0px 0px 0px 1px oklch(0 0 0 / 0.06),
+    0px 1px 2px -1px oklch(0 0 0 / 0.06),
+    0px 2px 4px 0px oklch(0 0 0 / 0.04);
+  --shadow-border-hover:
+    0px 0px 0px 1px oklch(0 0 0 / 0.08),
+    0px 1px 2px -1px oklch(0 0 0 / 0.08),
+    0px 2px 4px 0px oklch(0 0 0 / 0.06);
+}
+```
+
+### Shadow as border (dark mode)
+
+In dark mode, simplify to one white ring, since layered depth shadows are invisible on dark backgrounds:
+
+```css
+/* Dark mode: adapt to whatever setup the project uses
+   (prefers-color-scheme, class, data attribute, etc.) */
+--shadow-border: 0 0 0 1px oklch(1 0 0 / 0.08);
+--shadow-border-hover: 0 0 0 1px oklch(1 0 0 / 0.13);
+```
+
+### Usage with hover transition
+
+Apply the variable and add `transition-[box-shadow]` for a smooth hover:
+
+```css
+.card {
+  box-shadow: var(--shadow-border);
+  transition-property: box-shadow;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.card:hover {
+  box-shadow: var(--shadow-border-hover);
+}
+```
+
+### When to use shadows vs. borders
+
+| Use shadows | Use borders |
+| --- | --- |
+| Cards, containers with depth | Dividers between list items |
+| Buttons with bordered styles | Table cell boundaries |
+| Elevated elements (dropdowns, modals) | Form input outlines (for accessibility) |
+| Elements on varied backgrounds | Hairline separators in dense UI |
+| Hover/focus states for lift effect | |
+
+## Image outlines
+
+Add a `1px` outline at low opacity to images for consistent depth, especially where other elements use borders or shadows.
+
+### Color rules (non-negotiable)
+
+- **Light mode**: pure black, `oklch(0 0 0 / 0.1)`.
+- **Dark mode**: pure white, `oklch(1 0 0 / 0.1)`.
+- Never a near-black or near-white from the project palette, such as slate-900, zinc-900, `#0a0a0a`, `#111827`, or `#f5f5f7`. Tinted outlines pick up the surrounding surface color and read as dirt on the image edge.
+- Never match the outline to the project's accent or ink color. The outline is a neutral separator, not a themed element.
+
+### Light mode
+
+```css
+img {
+  outline: 1px solid oklch(0 0 0 / 0.1);
+  outline-offset: -1px; /* draw the ring just inside the image edge */
+}
+```
+
+### Dark mode
+
+```css
+img {
+  outline: 1px solid oklch(1 0 0 / 0.1);
+  outline-offset: -1px;
+}
+```
+
+### Tailwind with dark mode
+
+```tsx
+<img
+  className="outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
+  src={src}
+  alt={alt}
+/>
+```
+
+Use `outline-black/10` and `outline-white/10` specifically, not `outline-slate-*`, `outline-zinc-*`, `outline-neutral-*`, or any tinted scale.
+
+**Why outline instead of border?** `outline` never affects layout, adding no width or height at any offset, and `outline-offset: -1px` draws the ring just inside the image edge so it hugs the corner radius.