# Design Assay Protocol v0.1

## Vocabulary

| Term | Meaning |
|---|---|
| **Target** | The thing being designed: a screen, flow, component set, or brand system. |
| **Genome** | The design system encoded as data: tokens, component recipes, composition rules. |
| **Gene** | One mutable parameter in the genome, with a bounded range. |
| **Variant** | One rendered candidate produced from a genome. |
| **Generation** | One batch of variants produced in a single round. |
| **Assay** | The full measurement pass over a generation using the fitness functions. |
| **Gate** | A hard pass/fail check. A variant failing any gate scores zero. |
| **Hit** | A variant that passes all gates and beats the baseline composite score by the hit threshold (default 10%). |
| **Hit rate** | Hits divided by variants assayed. |
| **Baseline** | The existing design, or the best human-made option, scored with the same functions. |
| **Run record** | The reproducible log of one assay run. |

## Stages

### Stage 0. Target profile
Define before generating anything.
- What the target is and who uses it.
- Fitness weights for this target (see `02-FITNESS-FUNCTIONS.md`).
- The baseline, rendered and scored.
- Budget: max generations, max variants, max compute cost.
- Stop condition: default is a plateau, meaning composite gain under 1% across 2 consecutive generations.

Output: `target.json`

### Stage 1. Genome
Encode the design system as data.
- Tokens: color, type scale, spacing, radius, elevation, motion.
- Component recipes: structure plus which tokens each slot accepts.
- Composition rules: layout grids, section order, density.
- Each gene gets a type, a range, and a lock flag. Locked genes never mutate. Brand-critical values such as the logo and primary hue are locked by default.

Output: `genome.json`, validated against `schema/genome.schema.json`

### Stage 2. Variation
Produce a generation.
- **Mutation:** change 1 to N genes within their ranges.
- **Crossover:** combine genes from two parent variants.
- **Exploration:** a fixed share of each generation (default 15%) is mutated with wider ranges, so the population does not collapse to one local optimum.
- Generation size: 200 to 2,000 for screens, 50 to 200 for full brand systems.
- Mutation is cheap work and runs on local inference by default.

Output: `gen-{n}/variants/*.json`

### Stage 3. Render
Every variant becomes real output, not a description.
- Rendered as production code (Next.js, Tailwind) in an isolated harness.
- Screenshots at 320, 768, 1280 and 1920 px widths, in light and dark.
- A variant that fails to render is logged and discarded.

Output: `gen-{n}/renders/{id}/`

### Stage 4. Assay
Run the fitness functions as a funnel, cheapest first.
1. **Gates** (seconds per variant): accessibility criticals, overflow, contrast floor.
2. **Measured functions** (seconds to minutes): token fidelity, rhythm, performance, responsiveness.
3. **Judged functions** (most expensive): rubric scoring by model judges, run only on the top 20% after step 2.

Output: `gen-{n}/scores.jsonl`

### Stage 5. Selection
- Keep the top 5% by composite score.
- Add a diversity bonus so near-duplicates do not fill the survivor set.
- Survivors become parents for the next generation.
- Repeat Stages 2 to 5 until the stop condition is met.

### Stage 6. Human review
The designer reviews the finalists (default: top 10).
- Every accept or reject is logged with a one-line reason.
- Repeated reasons become candidates for new fitness functions. This is how taste gets encoded over time.

Output: `review.jsonl`

### Stage 7. Field assay
Ship the top 2 or 3 finalists to real users when the target allows it.
- A/B or multivariate test, with the baseline as control.
- Pre-register the metric and sample size before launch.

Output: `field.json`

### Stage 8. Report
Publish using `04-CASE-STUDY-TEMPLATE.md`.

## Run record

Every run directory contains:

```
run-{date}-{slug}/
  target.json
  genome.json
  protocol-version.txt
  seed.txt
  gen-0/ ... gen-n/
    variants/
    renders/
    scores.jsonl
  review.jsonl
  field.json        (if Stage 7 ran)
  summary.json
```

`summary.json` holds the headline numbers: variants generated, hits, hit rate, best composite, baseline composite, gain, generations, wall-clock time, compute cost.

A run is **reproducible** when the seed, genome, protocol version and model versions regenerate the same variant set.

## Versioning

- Protocol versions follow semver. Breaking changes to stages or scoring bump the major version.
- Every published result states the protocol version it ran on.