Agents

Ask in plain words

Describe pages the way you would to a designer. The agent knows which component fits each request, and how each one is built:

A list of past projects I can filter by type

Numbered list rows, with filter chips folded in an accordion

Let visitors save the ones they like

A favorite star on each row, and a Favorites filter

A contact form

Underlined fields, a select, a switch and one filled Send button

A home page with our artwork

A hero, with the image beside the title or under it, by its shape

A list of what changed and when

A dated list, newest first

Show our install steps

A code block, with commands in bold

To see each one before you ask, open Components.

The agents file

Coding agents such as Claude Code, Codex and Cursor look for a file called AGENTS.md in the folder they work in, and read it before they start. Claude Code reads the same notes as CLAUDE.md. The kit's repository has both, with the same text.

It covers the three jobs people bring: changing the kit, starting a new site with it, and restyling a site that already exists. For each, it lists the steps in order and the files to read first: DESIGN.md for the rules and its "Do not" list, COMPONENTS.md for each component's markup, and tokens.json for every color and size.

Read it yourself first: AGENTS.md on GitHub.

Start a new site

One request is enough. Name the pages and the accent, and point the agent at the kit:

Start a new Astro site with the Swiss Minimal design kit.
Follow "Starting a new site with the kit" in
https://github.com/danny-englander/swiss-minimal/blob/main/AGENTS.md
Pages: Home, Work, About and Contact. Accent: teal.
Add an AGENTS.md for the site that points at the kit's docs.

The agent sets up an Astro site with Tailwind, copies the kit into it, builds each page from the components and adds the accessibility tests. It leaves the kit's own files untouched, so a newer kit can be dropped in later.

Give your site its own file

The kit's AGENTS.md stays in the kit's repository. Your site needs its own, so the next agent that opens the project, next week or next year, knows the rules without being told. This is enough to start, and it grows with your own notes:

# Notes for AI agents

This site uses the Swiss Minimal design kit: src/design/kit,
with its fonts in src/design/fonts. Before changing a page, read
the kit's rules and component guide:

- https://github.com/danny-englander/swiss-minimal/blob/main/DESIGN.md
- https://github.com/danny-englander/swiss-minimal/blob/main/COMPONENTS.md

- Build pages on BaseLayout, and open each with a Hero or a PageTitle.
- Page layout is Tailwind utilities; components are kit classes.
- Colors only through the token utilities (text-muted, bg-bar,
  text-accent-text), never Tailwind's palette.
- Check each change against the "Do not" list in DESIGN.md.
- Don't edit src/design/. A fix there belongs in the kit's repository.
- Run the axe tests before calling a change done.

Save it as AGENTS.md at the top of the project. If you use Claude Code, save a copy as CLAUDE.md too, or a CLAUDE.md that only says @AGENTS.md.

Restyle an existing site

Restyling is mostly removing: the kit only works when it is the site's only visual system. So the agent starts by looking, not changing. It notes how the site loads its CSS, how dark mode works and which pieces each page uses, then maps each piece to a kit component and lists the ones with no match.

Restyle this site with the Swiss Minimal design kit.
Follow "Restyling an existing site with the kit" in
https://github.com/danny-englander/swiss-minimal/blob/main/AGENTS.md
Start with the survey, and show me the map of our pages to kit
components before you change anything.

Once you agree the map, it moves one kind of page at a time and commits after each, so any problem traces back to one step. It leaves your copy, URLs and features as they are, and asks you where content and a rule disagree. The site doesn't have to be built with Astro or Tailwind; the agent works out how to load the kit either way.

For agents on the web

An agent that reads this site instead of the repository can start at /llms.txt. It is a short plain-text index, in the llms.txt format, that says what the kit is and links to the same docs as plain Markdown, plus the pages of this demo.