Skip to content

AGENTS.md

Latest commit

 

History

History
154 lines (121 loc) · 8.46 KB

AGENTS.md

File metadata and controls

154 lines (121 loc) · 8.46 KB
Raw

AGENTS.md

Instructions for AI coding agents working on droidspaces.org. Humans can read it too, but it is written for the agent, so it is short and it repeats itself where repetition has proven necessary.

What this is

The public website for Droidspaces, a Linux container runtime for Android. A static site on GitHub Pages, plain HTML and CSS, two small scripts (site.js everywhere, docs.js on docs pages). No framework, no build step for the pages.

  • index.html, downloads.html, 404.html are hand-written pages.
  • docs/*.html are generated. Never edit them. They are built by .github/scripts/build-docs.py from the Markdown in the main repository's Documentation/ folder, on a repository_dispatch from that repo. Fix docs content upstream at https://github.com/ravindu644/Droidspaces-OSS, fix docs styling in assets/css/.
  • _nav.html and _footer.html are the shared partials. template.html is the docs page shell. Change navigation in the partial, then re-run the build so every page picks it up.
  • assets/css/tokens.css is generated by scripts/tokens.mjs. Never edit it by hand.
  • The ?v= on every CSS, JS and font URL is a content hash stamped by the build, because GitHub Pages lets browsers cache those files for four hours. Do not edit or remove it.
  • CNAME says www.droidspaces.org. Do not touch it.

Commands

node scripts/tokens.mjs > assets/css/tokens.css     # regenerate colour and motion tokens
pip install markdown-it-py mdit-py-plugins pygments  # the build's renderer and highlighter
python3 .github/scripts/build-docs.py               # rebuild docs/ from docs/content/
npx @google/design.md lint DESIGN.md                # validate the design file
python3 -m http.server 8000                         # preview at http://localhost:8000

There is no test suite. "Done" means all four of these hold:

  1. npx @google/design.md lint DESIGN.md reports no errors.
  2. Every changed page renders complete with JavaScript disabled.
  3. Every changed page renders correctly with prefers-reduced-motion: reduce and in both prefers-color-scheme values.
  4. grep -rn "—" --include=*.html --include=*.css --include=*.md . returns nothing.

The design file is the law

Anything visual follows DESIGN.md. Always read it before generating or changing any HTML or CSS, and read it again before you say you are finished. It is not a mood board. It is a list of the only colours, sizes, radii, fonts and motions that exist on this site, and each value has a source in Google's Material 3 token files or the Droidspaces Android app.

The closed-world rule: use only values defined in DESIGN.md. No hex literal outside tokens.css. No radius that is not on the shape scale. No gap that is not on the spacing scale. No font that is not IBM Plex Sans or JetBrains Mono. No easing that is not one of the five spring tokens. No breakpoint that is not 600, 840, 1200 or 1600. If the value you want is not in the file, the file is telling you not to want it.

The Do's and Don'ts and the Decided exceptions sections are the parts agents get wrong most often. The Don'ts are not style preferences; each one describes a pattern that makes a page look generated, and reviewers reject them on sight. The Decided exceptions are decisions, not bugs. Do not "fix" them.

If a rule genuinely does not fit, deviate, leave a comment at the site saying what the deviation buys, and say it in the PR. An undocumented deviation is drift and the next contributor will "fix" it. A documented one is a decision, and it survives.

Style

Four rules. They apply to markup, CSS, comments, commit messages, copy on the page and this file.

No em dashes. Use a comma, a full stop, or rewrite the sentence. This applies to the copy visitors read, not only to code. Check with the grep in the Commands section.

No ASCII banner comments. No rows of ----- or ===== in CSS or HTML. A one-line /* section */ is enough.

Comments say why. Say what breaks if the line is removed, or which rule in DESIGN.md it implements. Skip comments that restate the selector below them.

Ten lines that work beat a hundred. Delete before you add. The current style.css is 21 KB and about a third of it is dead. A smaller diff in the right place is the goal.

Copy

The copy is part of the design. It is written by the person who built the runtime, to someone who will check the claims, and it sounds that way.

  • Plain sentences. Say what the thing does, in the words a kernel developer would use.
  • Specific over impressive: "boots systemd as PID 1 in 150 to 750 milliseconds" beats "lightning fast".
  • Sentence case everywhere. Buttons are "Download the APK", not "DOWNLOAD NOW".
  • No "Unlock", "Supercharge", "Seamless", "Blazing", "Next-generation", "Reimagine", "Effortless", "Empower". If a headline could sit on any SaaS site, rewrite it until it could only sit on this one.
  • Numbers are current and sourced. Stars, contributors and downloads come from the GitHub API at build time or are left out. Never type a number from memory.
  • The comparison against PRoot, chroot and QEMU describes what each one costs. It does not say they failed. Their users read this page.

Before you write it at all

Work down this list and stop at the first answer that holds.

  1. Does this need to exist? A section nobody asked for, a fourth button variant, a second decorative shape on a page that has one: skip it and say so in one line.
  2. Does it already exist here? Grep assets/css/ for the class before writing a new one. The phone mockup, the chip, the card, the code block and the button are the only components, and they are defined once.
  3. Does CSS already do it? Scroll-driven animations, @starting-style, linear() easings, light-dark(), mask-image, View Transitions. The site targets current Chrome, Safari and Firefox. Reach for JavaScript only for the theme toggle, the copy button, the mobile drawer, the arrival trigger (it adds a class; the animation is CSS), and on docs pages the search dialog and the device filter. Both docs controls ship hidden and only the script reveals them, so a docs page without JavaScript is complete.
  4. Does an existing asset cover it? Screenshots come from the main repository's Documentation/resources/. Shapes come from assets/shapes/. Do not generate new imagery, do not draw a new shape, do not add an illustration.
  5. Can it be one line? Then it is one line.
  6. Only then write the smallest thing that works.

Hard constraints

  • No third-party request at runtime. Fonts, icons and shapes are self-hosted under assets/. The Font Awesome and Google Fonts links in the current pages are being removed, do not add them back and do not add a CDN script.
  • No JavaScript animation library. Motion is CSS. If it cannot be done in CSS, it is not done.
  • No web component library and no CSS framework. Google's @material/web Lit components are in maintenance mode and predate Expressive; only their token CSS is used, vendored into assets/css/.
  • No new page without a matching entry in sitemap.xml and _nav.html.
  • Never edit docs/*.html, assets/css/tokens.css, or CNAME.
  • Never generate, invent or restyle a screenshot. The phones show the real app.
  • Never remove the prefers-reduced-motion branch or make content depend on an animation having run.
  • Never store anything in localStorage except the theme preference, which is the one key the site already uses.
  • Never add analytics, a cookie banner, a newsletter form or a chat widget.

Commits

  • Sign off every commit: git commit -s.
  • Never add a Co-Authored-By: trailer for an AI agent. Human co-authors are fine.
  • Prefixes, matching the main repository: site: for pages and styles, docs: for the docs build or template, tokens: for a regenerated tokens.css, ci: for workflows.
  • One concern per commit. A token regeneration is its own commit.

Reviewing your own work

Before you report a page as done, open it and look at it, at 390px wide and at 1440px wide, in both themes. Then ask, in this order:

  1. Is there more than one primary element in any section?
  2. Is anything moving that is not a phone, a shape, a button being pressed, or a surface being hovered?
  3. Does any headline contain a word from the banned list, an em dash, or a single accented word?
  4. Would this page look the same with the logo swapped for another project's? If yes, it is a template, and it goes back.

If you cannot render the page, say so and stop. Do not report it as reviewed.