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.6 KiB

Raw Blame History

Rule: theming

Binding for every colour, font size, spacing value, and breakpoint.

Read ../context/design-system.md first. The current CSS has three drifting palettes and a broken @font-face. This rule describes the target; that file describes what you are migrating from.

One token layer

Every value comes from src/styles/tokens.css. If a component needs a value that is not a token, either it is a genuine one-off (justify it in a comment) or the token layer is missing something (add it there, not inline).

/* forbidden */
color: #172f42;
color: rgba(23,47,66,.6);

/* required */
color: var(--ink);
color: var(--muted);

No raw hex outside tokens.css. .agents/scripts/check-tokens.mjs enforces it; wire it into npm run verify.

Semantic names, not literal ones

--ink, --paper, --muted, --line, --accent, --gold, --blue, --deep are the existing vocabulary. Keep it — it is already semantic and the team reads it fluently. Do not rename to --color-neutral-900.

If a genuine second surface is needed, extend semantically (--surface-lab, --ink-inverse), never numerically.

Type scale

Replace the 14 ad-hoc clamp() triples with named steps:

--step-display: clamp(56px, 9vw, 126px);   /* h1 */
--step-6: clamp(36px, 5vw, 65px);          /* section h2 */
--step-5: clamp(24px, 3vw, 38px);          /* sub-head */
--step-4: clamp(22px, 3vw, 36px);          /* pull-quote */
--step-1: 15px;                            /* body */
--step-0: 11px;                            /* eyebrow / label */

The eyebrow treatment (10–11px monospace, letter-spacing:.08–.1em, uppercase) is a signature of this design. Make it one class, not fifteen repetitions.

Breakpoints

Five named widths replace the current sixteen:

--bp-sm: 560px;  --bp-md: 800px;  --bp-lg: 1100px;
--bp-xl: 1600px; --bp-2xl: 2200px;

When collapsing a component's old breakpoint onto a named one, screenshot at the old value. That is where the regression will be.

Preserve the house style

Flat colour blocks, hairline 1px rules, near-zero border-radius.
Tight negative tracking on display type (-.06em … -.08em).
Grid separators built as gap:1px over a coloured parent background. This is deliberate. Do not "fix" it into border.
Georgia, serif for emphasis spans (h1 em). It renders today; keep it.

Fonts

Do not add a webfont without an explicit decision recorded in the task. The intended Manrope/DM Mono has never rendered; introducing it is a visual redesign, not a refactor. Default: match what renders today.

2.6 KiB Raw Blame History Unescape Escape