Skip to content

AGENTS.md

Latest commit

 

History

History
105 lines (71 loc) · 4.4 KB

AGENTS.md

File metadata and controls

105 lines (71 loc) · 4.4 KB
Raw

Prototype: QR Code generator

Scope

You may ONLY create or edit files within this directory. Do NOT modify anything outside this folder.

Rules

  • Export a default React component from page.tsx
  • Use mock data only (in mockData.ts) — no real APIs, no auth, no databases
  • Use Tailwind CSS with design system tokens only — no arbitrary values
  • Document design decisions in notes.md
  • Follow the SF.gov writing style guide (see .kiro/docs/writing-style-guide.md)
  • Follow the SF.gov design system guide (see .kiro/docs/sfgov-design-system-guide.md)
  • Import components directly from their file path: import { SiteHeader } from "@/components/SiteHeader"
  • Do NOT import from the barrel "@/components" (it pulls in heavy deps)
  • Do NOT recreate components that already exist in the codebase

File Structure

File Purpose
page.tsx Default-exported React component
mockData.ts All mock/sample data
notes.md Design decisions and rationale
prototype.json Metadata (do not edit manually)
package.json Workspace marker (add deps here if needed)
.kiro/docs/ Symlinked design guides (always up to date)

Reference Docs

Read these before building — they contain the full component catalog, design tokens, content type patterns, and coding rules:

  • .kiro/docs/playground-import-rules.md — READ FIRST. Playground-specific import path rules
  • .kiro/docs/sfgov-design-system-guide.md — Complete component catalog, props, patterns, content types, and AI rules
  • .kiro/docs/writing-style-guide.md — SF.gov writing conventions for all user-facing text

Workflow

Before building

When the user describes what they want to build:

  1. Ask follow-up questions — clarify scope, content types, interactions, and edge cases before writing code
  2. Make a plan — outline the approach (which components, data shape, page structure) and confirm with the user before executing

After building

After completing a piece of work:

  1. Give review instructions — tell the user specifically what to check (e.g. "Open the prototype at tablet width and verify the heading sizes look correct", "Check that the accordion opens/closes", "Verify the tile links are styled correctly")
  2. Call out assumptions — if you made choices the user didn't specify, list them so they can confirm or correct

Getting Started

  1. Read .kiro/docs/sfgov-design-system-guide.md to understand available components and patterns
  2. Read the existing files in this directory
  3. Help the user build their prototype using existing components
  4. When done, update notes.md with design decisions made
  5. Generate metadata (description + preview image) — see "After Building — Generate Metadata" section below

After Building — Generate Metadata

Once the user has built something meaningful (not just the starter template), do the following:

1. Write a description

Update prototype.json and set the "description" field to a concise 1–2 sentence summary of what the prototype demonstrates. Write it from a third-person perspective, e.g.:

"Explores a multi-step permit application flow with progress tracking and inline validation."

2. Generate a preview image

Create a file called preview.png in this directory. This should be a representative screenshot or mockup of the prototype's main view. Options:

  • If you have access to a screenshot tool, capture the rendered prototype
  • Otherwise, create a simple SVG-based placeholder that represents the layout (save as preview.png)
  • The image should be roughly 1200×800px and clearly show the prototype's primary UI

Then update prototype.json to add "preview": "preview.png".

The gallery app will pick up both the description and preview automatically on the next manifest regeneration.

Design System Discrepancies

While building, watch for differences between what the Figma designs specify and what the code produces. If you notice a discrepancy (wrong spacing, incorrect font size, color mismatch, etc.), log it in:

docs/design-system/discrepancies.md (at the repo root)

Format:

## [Short title]
- **Component**: Which component
- **Issue**: What's wrong
- **Figma spec**: What it should be
- **Code reality**: What it actually does
- **Suggested fix**: How to fix upstream
- **Workaround**: Any temp fix applied
- **Found by**: [your name], [date]

This helps the team clean up the production design system codebase.