Files

T

Marcos Paulo aae4d42229 docs: add .agents workspace and the Astro refactor plan

Adds the agent-facing workspace and a 20-task plan for migrating the site
to Astro. Nothing here implements the refactor; these are briefs, rules and
templates that the task agents read.

- .agents/ holds context, rules, checklists, skills, specialist agents,
  component/page/config templates and gate scripts. It is vendor-neutral so
  MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at
  AGENTS.md.
- .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on
  the shared git-common-dir so parallel worktrees serialise, and guards the
  assertion count in scripts/verify.mjs against a coverage drop.
- plans/astro-refactor/ carries the phase graph, per-task briefs and the
  model-routing recommendation.

These files must be tracked before fanning out: a worktree only checks out
tracked files, so an untracked plan is invisible to every agent working in one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-05 01:18:27 +00:00

2.4 KiB

Raw Blame History

Rule: animation

This is an editorial-print design. Motion is punctuation, not decoration.

Budget

Purpose or nothing. Motion may signal a state change, direct attention to what just changed, or smooth a layout shift. Nothing else.
Duration: 150–250ms for UI feedback, up to 400ms for a page transition. Longer reads as sluggish; shorter reads as a glitch.
Easing: cubic-bezier(.2,0,0,1) for entrances, ease-out for exits. Never linear for anything a person watches. Never bounce/elastic — wrong register for this design.
One thing moves at a time. Staggered cascades of cards are a template default; this site has a point of view and does not do them.

`prefers-reduced-motion` is mandatory

Several current stylesheets already honour it. Every new animation must:

@media (prefers-reduced-motion: reduce) {
  * { animation-duration: .01ms !important; animation-iteration-count: 1 !important;
      transition-duration: .01ms !important; scroll-behavior: auto !important; }
}

Reduced motion means reduced, not broken: the end state must still be correct and the interface still usable. Test it — in DevTools, Rendering → Emulate prefers-reduced-motion.

Performance

Animate transform and opacity only. They composite on the GPU. Animating width, height, top, left, or margin forces layout on every frame and will show up as a failed INP.
will-change only on an element about to animate, removed after. Leaving it on permanently costs memory and can hurt performance.
Prefer CSS transitions. Reach for the Web Animations API only for sequencing that CSS cannot express. Do not add an animation library — it is a runtime dependency on a site whose thesis is having none.
INP budget is 200ms. An animation that delays interaction response fails.

Astro view transitions

If page transitions are wanted, use Astro's <ClientRouter />. It is the only sanctioned motion dependency, and it must:

degrade cleanly with JS disabled (it does — full navigation)
respect prefers-reduced-motion
not break the review desk's query-param deep links or browser back/forward

Accessibility

Never animate anything that conveys information on its own. Motion is redundant reinforcement.
Nothing flashes more than three times per second.
Focus must stay visible throughout a transition, and focus order must not change because of one.

2.4 KiB Raw Blame History Unescape Escape