# Quov artifacts: instructions for AI agents

Use this file when an agent generates a standalone HTML page for Quov: a report, a small tool, a summary to share, an internal page. Load `quov-brand.en.md` first (https://quov.io/design-system/quov-brand.en.md); this file applies the brand to self-contained pages and never overrides it.

Logo files are listed in the brand file and served from `https://quov.io/design-system/logo/`. In an artifact, prefer the inline SVG from the brand file with `fill="var(--mark)"` on the circle and `fill="var(--foreground)"` on the letters: it follows the theme. Never redraw the mark.

## Format

- One self-contained HTML file: inline CSS and JS, fonts from Google Fonts, images as `data:` URIs or files published beside the page.
- No build step. Libraries only when they do real work, loaded from a CDN pinned to an exact version.
- `<title>`: a short name of two to four words. The explanation goes in the page.
- Language: the reader's. Spanish with _tú_, English without contractions.
- Internal pages carry `<meta name="robots" content="noindex, nofollow">`.

## Tokens: both themes

An artifact opens dark, like everything Quov makes, and switches to paper when the host page sets `data-theme="light"` or the reader's system prefers light. Every color is a token; components only use the tokens. Copy this block as it is:

```css
:root {
  color-scheme: dark;
  --background: oklch(0.11 0.01 260);
  --card: oklch(0.15 0.01 260);
  --secondary: oklch(0.2 0.01 260);
  --muted: oklch(0.2 0.01 260);
  --foreground: oklch(0.93 0.01 260);
  --secondary-foreground: oklch(0.85 0.01 260);
  --muted-foreground: oklch(0.64 0.01 260);
  --primary: oklch(0.93 0 0);
  --primary-foreground: oklch(0.13 0 0);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 12%);
  --ring: oklch(0.55 0.01 260);
  --mark: oklch(0.06 0.005 260);
  --radius: 0.375rem;
  --font-heading: 'Aoboshi One', ui-serif, Georgia, serif;
  --font-sans: 'Geist', ui-sans-serif, system-ui, sans-serif;
  --font-mono: 'Geist Mono', ui-monospace, Menlo, monospace;
}
@media (prefers-color-scheme: light) {
  :root:not([data-theme='dark']) {
    color-scheme: light;
    --background: oklch(0.95 0.02 75);
    --card: oklch(0.98 0.015 75);
    --secondary: oklch(0.91 0.02 75);
    --muted: oklch(0.91 0.02 75);
    --foreground: oklch(0.18 0.01 75);
    --secondary-foreground: oklch(0.25 0.01 75);
    --muted-foreground: oklch(0.48 0.01 75);
    --primary: oklch(0.18 0 0);
    --primary-foreground: oklch(0.95 0.02 75);
    --border: oklch(0 0 0 / 10%);
    --input: oklch(0 0 0 / 8%);
    --ring: oklch(0.48 0.02 75);
    --mark: oklch(0.995 0.005 75);
  }
}
:root[data-theme='light'] {
  color-scheme: light;
  --background: oklch(0.95 0.02 75);
  --card: oklch(0.98 0.015 75);
  --secondary: oklch(0.91 0.02 75);
  --muted: oklch(0.91 0.02 75);
  --foreground: oklch(0.18 0.01 75);
  --secondary-foreground: oklch(0.25 0.01 75);
  --muted-foreground: oklch(0.48 0.01 75);
  --primary: oklch(0.18 0 0);
  --primary-foreground: oklch(0.95 0.02 75);
  --border: oklch(0 0 0 / 10%);
  --input: oklch(0 0 0 / 8%);
  --ring: oklch(0.48 0.02 75);
  --mark: oklch(0.995 0.005 75);
}
body {
  margin: 0;
  background: var(--background);
  color: var(--foreground);
  font: 400 16px/1.65 var(--font-sans);
}
h1,
h2 {
  font-family: var(--font-heading);
  font-weight: 400;
  text-wrap: balance;
}
:focus-visible {
  outline: 2px solid var(--ring);
  outline-offset: 3px;
}
```

- `body` always sets its own background.
- Never write a color literal in a component rule: a literal that works in one theme breaks the other.
- If the artifact shows signed figures or statuses (a gain, a loss, a warning), add the semantic tokens from `quov-app.en.md` and follow its rules. Nothing else carries color.

Fonts:

```html
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Aoboshi+One&family=Geist:wght@400..600&family=Geist+Mono:wght@400..500&display=swap"
/>
```

## Structure

- **Opening:** a mono line in `--muted-foreground` (the kind of page and its date, for example `report · 2026-10-25`), the `h1` in Aoboshi One, and one or two sentences saying what the page is for. Sized to its content, never to the full viewport.
- **Summary first:** key figures as a ruled row of label and value (label in Geist `--muted-foreground`, value in Geist Mono), then the detail. Never figure tiles with icons.
- **Sections:** an `h2` in Aoboshi One, with a mono index only when the sections are a real sequence.
- **Tables:** header cells in mono, small, `--muted-foreground`, over a hairline; hairlines between rows; figures right-aligned with `font-variant-numeric: tabular-nums`.
- **Controls:** the primary button in `--primary` with `--primary-foreground`, radius `var(--radius)`; secondary buttons with a `--border` outline. One primary action per view.
- **Footer:** "Quov" in mono, the date the page was generated and the source of its data.

## Layout

- Content up to about 1100 px wide, a side gutter of at least 16 px, a single column at phone width. Nothing scrolls sideways except a table or code block inside its own `overflow-x: auto` container.
- Borders at the `--border` alpha, radius `0.375rem`, no shadows. A card only where an item truly is a separate object, and never a card inside a card.
- Use `gap` in flex and grid layouts instead of per-element margins.

## Behavior

- Complete at rest: everything readable is visible on load, nothing waits for a scroll trigger.
- Tools open in a realistic working state, with example data marked as such, never as an empty shell.
- Motion only where it explains something; opacity and transform only; `prefers-reduced-motion` honored.
- Visible keyboard focus on every control; every form control has a label.

## Copy

- Plain, specific, active voice. A button says exactly what happens.
- No em dashes, no superlatives, no emoji as section markers, no invented figures, no people.
- Every number says where it comes from. Internal figures (costs, hours) never go in anything shared with a public link.

## Never

Gradients, glassmorphism, glows, an accent color, side-stripe borders, hero metrics, identical card grids, stock photos, illustrations.

## Before you finish

1. View the page in both themes (toggle `data-theme` on `<html>`) and at phone width.
2. Confirm the fonts loaded and that no color is written outside the token block.
3. Re-read the copy for em dashes, contractions, _usted_ and superlatives.