# Fractal Evidence Contract

This file defines how Axon must interpret every file routed from this design system. It is universal evidence: read it once before loading capability-specific evidence.

## Purpose

Fractal constrains design decisions without turning every output into the same template. It separates decisions into four kinds:

- **Required invariant** — always obey when its capability is active.
- **Allowed choice** — a bounded option that may vary between valid outputs.
- **Selection criterion** — evidence for choosing among allowed options.
- **Forbidden outcome** — a result that must never be produced.

Consistency applies to rules, tokens, component behavior, accessibility, and semantic meaning. Variety should come from composition, information hierarchy, an approved colourmap, chart form when several are truthful, density within an allowed range, annotation strategy, and—outside Mirror product UI—brand expression.

Recreating the same component with the same variant, state, and props should be visually consistent. Recreating a page, report, chart, or presentation should not automatically reproduce the same composition.

## Loading protocol

1. Classify the request into one or more capabilities before semantic retrieval.
2. Read this contract and the `requiredEvidence` for every active capability in [`capabilities.json`](./capabilities.json).
3. Select a subtype only after the required evidence is present—for example, select `line-chart` after recognizing a time-series visualization.
4. Retrieve only situational evidence whose `activatesWhen` condition is true.
5. Use tools to inspect exact package APIs, available assets, source data, and the target environment. Do not use broad retrieval as a substitute for those exact checks.
6. Validate the result against every active required invariant and forbidden outcome.

RAG may add relevant situational evidence. It may not omit or override required evidence.

## Authority and conflict resolution

Use this precedence order:

1. The user's explicit requirement for the current task.
2. Accessibility, scientific fidelity, factual fidelity, and safety requirements.
3. Required evidence for an active capability.
4. Situational evidence selected by a matching trigger.
5. Existing implementation details.
6. Examples and historical material.

An explicit user request may select an allowed exception. It does not silently waive accessibility, scientific meaning, or factual accuracy. When two active evidence files appear to conflict, follow the more specific file only within its stated scope. If both have the same scope and authority, stop and surface the conflict instead of choosing arbitrarily.

## Universal invariants

- Do not fabricate content, data, links, resources, component APIs, or evidence.
- Preserve semantic meaning. Visual styling must not distort the source data or domain conventions.
- Meet applicable accessibility requirements, including keyboard access, focus visibility, non-color cues, and contrast.
- In generated UI, use semantic design tokens. Primitive tokens are allowed only in token definitions, approved colourmap data, and evidence that explicitly reasons about a scale stop.
- In generated UI, use the 4px spacing grid. An off-grid value is allowed only when the user explicitly requests it; treat it as temporary and leave a `TODO` identifying the value and the intended token-based repair.
- A 1px stroke rule applies to UI borders and dividers, including chart frames, axes, and gridlines when they serve as interface structure. Data-bearing lines, icon artwork, and scientific marks follow their own capability evidence.
- Use named motion duration and easing tokens. Raw timing values and easing curves belong only in the token definitions.
- Prefer the current `@mirror-physics/fractal-ui` and `@mirror-physics/fractal-icons` packages for Mirror product interfaces. Inspect the installed version before assuming an export or prop.

Presentation geometry and typography follow the active presentation evidence rather than product-UI defaults. In the opt-in Mirror Physics Blueprint profile, 2 px rules and 14 px custom markers are slide artwork, not UI borders or spacing tokens. Keep these measurements scoped to that profile.

## Controlled variation

When several options satisfy the evidence, choose according to the content and task rather than a fixed default shell. Record the reason internally in one sentence. Valid reasons include the shape of the data, reading order, comparison structure, interaction cost, available space, and the user's desired tone.

Do not create variation by:

- inventing tokens, component variants, or package APIs;
- changing established component anatomy without a use-case reason;
- assigning arbitrary colors to data;
- changing scientific conventions;
- using random spacing, radii, typography, or motion;
- applying decorative differences that imply nonexistent semantics.

## Evidence boundary

Only Markdown and JSON paths listed in [`capabilities.json`](./capabilities.json) are Axon-facing evidence. CSS, JavaScript, Python, Storybook stories, generated images, eval output, and scripts are implementation or validation artifacts unless a task explicitly asks to modify those artifacts.

Implementation artifacts may confirm what currently exists. They do not override canonical evidence except for exact third-party or package API facts that the evidence explicitly delegates to the installed implementation.