Imported from happygeneralist/happygeneralist-web-system (AGENTS.md). Install upstream with npx skills add happygeneralist/happygeneralist-web-system. Copyright stays with the author.

Agent instructions

This repository is the reusable Happygeneralist web system.

It provides visual, semantic and publishing foundations for Astro-based Happygeneralist projects.

Purpose

Build reusable foundations for clear, accessible, GOV.UK-adjacent web projects with room for richer Lab-style visual explanation.

A wider 2026–2028 practice goal is to keep reducing the friction between having an idea and turning it into something tangible that can be used, tested, challenged, or published.

This repository contributes directly to that goal.

Its value should be judged partly by whether it makes it easier to turn mature knowledge work into clear visual, interactive, and public artefacts.

Do not let development of the web system become a substitute for publishing or testing the work it is meant to support.

Important distinction

This is not only a visual design system.

It includes:

• visual patterns
• semantic models
• content structures
• publishing conventions
• accessibility defaults
• Lab display patterns
• knowledge relationship conventions

Wider practice direction

Happygeneralist is developing a broader outcome-oriented practice in which complex knowledge should become increasingly legible and usable through real artefacts.

Possible outputs include:

• essays and notes
• diagrams and visual models
• interactive explanations
• tools and prototypes
• public experiments
• software interfaces
• richer Lab-style investigations

The web system should make those forms easier to express without forcing every piece into the same page type or visual grammar.

Prefer the smallest reusable pattern that unlocks a real output.

Do not pre-build speculative components for work that does not yet exist.

Technical posture

Use simple Astro patterns.

Use Markdown or MDX where useful.

Use TypeScript and Zod for content modelling.

Keep dependencies light.

Do not add a CMS, search, analytics, comments or heavy visualisation library without a documented reason.

Design posture

Standard patterns should be clear, accessible, content-led and GOV.UK/x-gov adjacent.

Lab patterns may be more expressive and spatial, especially on large screens, but must remain accessible and semantically clear.

Visual explanation is part of the intellectual work, not decoration added after the thinking is finished.

Boundaries

Do not add private thinking, client material, work-support notes or website-specific content to this repo.

Use examples only when they demonstrate the reusable system.

Do not turn this repository into the home for Outcome Intelligence Infrastructure, Civic Design Intelligence, Unignorable, MT Genome, or other bodies of knowledge. It is an enabling publishing layer for them when appropriate.

Change safety

Make small, reviewable changes.

Preserve British English.

Prefer semantic HTML.

Preserve accessibility.

Document conventions when adding new patterns.

Prefer infrastructure changes that reduce demonstrated publishing or interaction friction.