AlexandrAI AGENTS.md
agents-md

html_report_design Agent Guide

Project-specific AGENTS.md guidance for maintaining the dense institutional report design system, format specs, schemas, samples, and bespoke SVG icon library.

AGENTS.md

Guidance for coding agents working on html_report_design. This repository is a design-system source of truth for dense, self-contained institutional HTML reports.

Project Overview

The core contract is: read DESIGN.md, read designs/_FOUNDATION.md, read designs/_DATA_DRIVEN.md, then modify the specific format spec, schema, sample, or icon category. The system is not one generic frame with different colors; each report format has a distinct document structure.

Important paths:

  • DESIGN.md: shared visual DNA, tokens, typography, density, rail behavior, themes, and icon rules.
  • designs/REPORT_POLICY.md: router from report intent to format, schema, required fields, theme, and icon categories.
  • designs/.md: the human spec for one report type.
  • designs/schemas/: JSON Schema contracts for data-driven samples.
  • sample/*_sample.html: self-contained exemplars.
  • icons/: bespoke currentColor SVG library and icon governance.

Setup Commands

This repo is documentation- and sample-heavy. Use file inspection and browser preview rather than inventing a package command that does not exist.

bashcd <project-root>
rg "data-theme|#report-data|rc-theme" DESIGN.md designs sample
rg "Required top-level fields" designs/REPORT_POLICY.md
rg "currentColor" icons

Open the relevant sample/*_sample.html in a browser when changing layout, tokens, interactivity, or print behavior.

Authoring Rules

  • Preserve self-contained output: inline CSS, inline SVG icons, system fonts, and no external requests.
  • Keep the dense institutional register: 13px body, compact panels, thin top bar, sticky rails where the format expects them.
  • Keep themes as token overrides. Do not scatter hard-coded accent colors inside individual samples.
  • Use only the bespoke icons under icons/; do not introduce emoji or generic assistant imagery.
  • Every format change must keep format distinction visible. A dashboard, data register, paper, and one-pager should not read as the same layout.

Schema And Sample Work

  • Update the format spec, schema, and sample together.
  • The sample's #report-data must validate against the schema conceptually and should demonstrate the required interactions.
  • If a required field changes, update designs/REPORT_POLICY.md so agents choose and fill the format correctly.
  • Keep placeholders such as {{ORG}} and {{PROJECT}} generic unless a concrete report intentionally replaces them.

Security And Privacy

  • Samples must not reference private hosts, local ports, credentials, or personal local paths.
  • Generated sample content should be plausible but not claim a real client's private facts.
  • Do not embed external analytics, fonts, iframes, or remote image fetches.

Done Criteria

  • The changed format still has a clear router entry, spec, schema, and sample.
  • The sample is visually usable at desktop width and has a printable fallback.
  • Icons render via inline SVG and currentColor.
  • Public-facing examples contain no local machine details.