DESIGN.md for Google Antigravity

Google Antigravity is built around a desktop command center, Projects, and asynchronous subagents. That model lets multiple pieces of work move at once, but parallel work increases the chance of visual drift. DESIGN.md is the shared reference every subagent can use before it touches a route.

Antigravity supports workspace rules in the .agents directory. Use those rules to point the agent toward DESIGN.md and to preserve the existing component system. Keep detailed visual guidance in DESIGN.md so it remains portable to other agents.

Read DESIGN.md before UI work.
Reuse existing primitives.
Report the routes and visual states verified before marking the task complete.

Split work by surface, not by arbitrary file count: one agent can handle the page shell, another the table states, and another the responsive pass. Each task should name the same tokens, patterns, and acceptance checks from DESIGN.md. This reduces conflicting local interpretations.

Use DESIGN.md as the visual source of truth.
Do not add new tokens.
Verify desktop, narrow mobile, empty, error, and focus-visible states.

When parallel work lands, review the combined surface rather than approving each piece in isolation. Check the seams: spacing between sections, duplicated controls, inconsistent terminology, and different interpretations of hierarchy. Promote a repeated correction into DESIGN.md.

Antigravity’s project model is useful when work continues beyond one interactive chat: a subagent can take a bounded task, and scheduled or background work can prepare a later review. UI work needs stronger guardrails in that setting because nobody may be watching every generated component. DESIGN.md should therefore describe not only the desired appearance but also the stopping conditions: reuse existing primitives, do not invent tokens, list changed routes, and leave a concise verification report.

A good background task has a small surface area. Ask one agent to add a table state, update one route, or prepare a responsive pass rather than asking it to redesign the whole product. The task can reference the same design file that local work uses. When the result returns, the human review is faster because the agent has already named the states it checked. If a scheduled task is allowed to touch UI without a browser review, keep it limited to safe, deterministic changes such as token migration or content updates and require a diff for anything structural.

For asynchronous UI work:
- Read DESIGN.md and inspect the nearest existing component.
- Do not add tokens or primitives.
- Report changed routes and verified states.
- Stop and ask for review if the design contract is ambiguous.

The safest Antigravity UI tasks are bounded by route, surface, and state. “Improve the dashboard” is too broad for asynchronous work because it hides a chain of design decisions. “Add the empty state to the projects table, reuse the existing table and button primitives, and verify the narrow layout” is specific enough for a subagent to complete and easy enough for a person to review later. DESIGN.md supplies the global rules; the task supplies the local acceptance criteria.

When several subagents work in one Project, avoid assigning overlapping ownership. One can prepare the page shell, one can implement a table state, and one can check responsive behavior. Each task should report the files and routes it touched. The final reviewer then checks the combined result for seams rather than trusting that individually valid tasks will automatically form a coherent screen.

Scheduled work deserves an even stricter boundary. Safe recurring jobs can update documentation, migrate a known token, or prepare a content change for review. A job that invents a new component or changes hierarchy should produce a proposal instead of silently shipping. This is not a limitation of the agent; it is a useful product control. The more unattended the workflow, the more valuable it is to make design decisions explicit and reversible.

1. Define one surface and one user outcome.
2. Point the task to the relevant DESIGN.md section.
3. Name the existing component and token family to reuse.
4. Require a verification report and stop on ambiguity.

A human should be able to open the resulting diff and understand why each visual choice exists. That is the practical quality bar for asynchronous UI work: not zero automation, but automation that leaves behind a clear, reviewable trail.

When a subagent discovers that the shared rule is incomplete, it should propose the smallest documentation change that resolves the ambiguity. A project can then improve its visual contract deliberately instead of letting every future task interpret the missing rule differently.

That proposal should include the affected component, the user state that exposed the gap, and one concrete example. It keeps an asynchronous workflow easy to audit and prevents a scheduled task from quietly becoming a new design system.