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>
This commit is contained in:
Marcos Paulo
@@ -0,0 +1,39 @@
|
||||
---
|
||||
// Grid-group template — for a set of sibling cards separated by hairlines.
|
||||
//
|
||||
// Note the separator technique: `gap: 1px` over a coloured parent background.
|
||||
// That is DELIBERATE house style throughout this site, not a workaround.
|
||||
// Do not "fix" it into `border`.
|
||||
|
||||
interface Props {
|
||||
label: string;
|
||||
/** Number of columns at the widest breakpoint. */
|
||||
columns?: number;
|
||||
}
|
||||
|
||||
const { label, columns = 3 } = Astro.props;
|
||||
---
|
||||
|
||||
<section class="group" aria-label={label}>
|
||||
<div class="grid" style={`--columns: ${columns}`}>
|
||||
<slot />
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<style>
|
||||
.grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(var(--columns), 1fr);
|
||||
gap: 1px; /* hairline separators, drawn by the parent background */
|
||||
background: var(--line);
|
||||
}
|
||||
|
||||
/* Children paint their own background, which is what makes the 1px show. */
|
||||
.grid > :global(*) {
|
||||
background: var(--paper);
|
||||
}
|
||||
|
||||
@media (max-width: 800px) {
|
||||
.grid { grid-template-columns: 1fr; }
|
||||
}
|
||||
</style>
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
// Interactive island template. Use ONLY when the component genuinely needs
|
||||
// client-side behaviour, and write the justification in your PR description.
|
||||
//
|
||||
// Islands are LEAVES. Do not wrap static children that could have been
|
||||
// server-rendered — hydrate the tab panel, not the page.
|
||||
//
|
||||
// Hydration preference, in order:
|
||||
// (none) → client:visible → client:idle → client:load
|
||||
//
|
||||
// Usage: <Island client:visible items={items} />
|
||||
|
||||
interface Props {
|
||||
items: { id: string; label: string; body: string }[];
|
||||
initialId?: string;
|
||||
}
|
||||
|
||||
const { items, initialId = items[0]?.id } = Astro.props;
|
||||
---
|
||||
|
||||
<div class="island" data-initial={initialId}>
|
||||
<div class="tabs" role="tablist" aria-label="Sections">
|
||||
{items.map((item) => (
|
||||
<button
|
||||
role="tab"
|
||||
id={`tab-${item.id}`}
|
||||
aria-controls={`panel-${item.id}`}
|
||||
aria-selected={item.id === initialId}
|
||||
data-tab={item.id}
|
||||
>{item.label}</button>
|
||||
))}
|
||||
</div>
|
||||
{items.map((item) => (
|
||||
<div
|
||||
role="tabpanel"
|
||||
id={`panel-${item.id}`}
|
||||
aria-labelledby={`tab-${item.id}`}
|
||||
data-panel={item.id}
|
||||
hidden={item.id !== initialId}
|
||||
>{item.body}</div>
|
||||
))}
|
||||
</div>
|
||||
|
||||
<script>
|
||||
// Scoped to this island's own root so multiple instances never collide.
|
||||
document.querySelectorAll<HTMLElement>('.island').forEach((root) => {
|
||||
const tabs = root.querySelectorAll<HTMLButtonElement>('[data-tab]');
|
||||
const select = (id: string) => {
|
||||
tabs.forEach((tab) => tab.setAttribute('aria-selected', String(tab.dataset.tab === id)));
|
||||
root.querySelectorAll<HTMLElement>('[data-panel]').forEach((panel) => {
|
||||
panel.hidden = panel.dataset.panel !== id;
|
||||
});
|
||||
};
|
||||
tabs.forEach((tab) => tab.addEventListener('click', () => select(tab.dataset.tab!)));
|
||||
|
||||
// Arrow-key navigation is required for role="tablist" — see
|
||||
// .agents/rules/accessibility.md
|
||||
root.querySelector('[role="tablist"]')?.addEventListener('keydown', (event) => {
|
||||
const key = (event as KeyboardEvent).key;
|
||||
if (key !== 'ArrowRight' && key !== 'ArrowLeft') return;
|
||||
const list = [...tabs];
|
||||
const current = list.findIndex((tab) => tab.getAttribute('aria-selected') === 'true');
|
||||
const next = list[(current + (key === 'ArrowRight' ? 1 : -1) + list.length) % list.length];
|
||||
select(next.dataset.tab!);
|
||||
next.focus();
|
||||
});
|
||||
});
|
||||
</script>
|
||||
|
||||
<style>
|
||||
.tabs { display: grid; gap: 8px; }
|
||||
|
||||
button {
|
||||
padding: 12px;
|
||||
color: var(--ink);
|
||||
background: transparent;
|
||||
border: 1px solid var(--line);
|
||||
text-align: left;
|
||||
cursor: pointer;
|
||||
/* transform/opacity only — never animate layout properties */
|
||||
transition: background 180ms cubic-bezier(.2, 0, 0, 1);
|
||||
}
|
||||
|
||||
button[aria-selected='true'] {
|
||||
color: var(--paper);
|
||||
background: var(--ink);
|
||||
}
|
||||
|
||||
button:focus-visible {
|
||||
outline: 3px solid var(--red);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
button { transition-duration: .01ms; }
|
||||
}
|
||||
</style>
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
// Static block template — the default. Ships zero JavaScript.
|
||||
// Copy to src/components/blocks/<Name>.astro and replace everything marked TODO.
|
||||
//
|
||||
// Before using this, confirm the block earns extraction: it appears three times,
|
||||
// or it has a name a person says out loud. See .agents/rules/componentization.md
|
||||
|
||||
interface Props {
|
||||
/** TODO: describe each prop. Required by default; optional needs a reason. */
|
||||
eyebrow: string;
|
||||
title: string;
|
||||
body: string;
|
||||
href?: string;
|
||||
}
|
||||
|
||||
const { eyebrow, title, body, href } = Astro.props;
|
||||
---
|
||||
|
||||
<article class="block">
|
||||
<span class="eyebrow">{eyebrow}</span>
|
||||
<h2>{title}</h2>
|
||||
<p>{body}</p>
|
||||
{href && <a href={href}>Open →</a>}
|
||||
<slot />
|
||||
</article>
|
||||
|
||||
<style>
|
||||
/* Tokens only. No raw hex, no px font sizes, no ad-hoc breakpoints.
|
||||
.agents/scripts/check-tokens.mjs enforces this. */
|
||||
.block {
|
||||
display: grid;
|
||||
gap: 10px;
|
||||
padding: 22px;
|
||||
background: var(--paper);
|
||||
color: var(--ink);
|
||||
}
|
||||
|
||||
/* The house eyebrow: uppercase monospace, wide tracking. One class, not
|
||||
fifteen repetitions. */
|
||||
.eyebrow {
|
||||
color: var(--accent);
|
||||
font: var(--font-eyebrow);
|
||||
letter-spacing: .1em;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
h2 {
|
||||
margin: 0;
|
||||
font-size: var(--step-5);
|
||||
line-height: 1.05;
|
||||
letter-spacing: -.06em; /* tight display tracking is a signature of this design */
|
||||
}
|
||||
|
||||
p {
|
||||
margin: 0;
|
||||
color: var(--muted);
|
||||
line-height: 1.65;
|
||||
}
|
||||
|
||||
a {
|
||||
color: var(--blue);
|
||||
font-weight: 700;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
a:focus-visible {
|
||||
outline: 3px solid var(--red);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
@media (max-width: 800px) {
|
||||
.block { padding: 18px; }
|
||||
}
|
||||
</style>
|
||||
Reference in New Issue
Block a user