# Frontier Atlas Design System

Frontier Atlas is VyDex's shared presentation contract for the Stage 1 public interface. It gives pages one set of colors, typography roles, layout rules, controls, evidence-state treatments, and responsive behavior. This page is for maintainers and coding agents building or reviewing Astro presentation code.

## Purpose and Ownership

Frontier Atlas prevents each page or component from creating a local visual system. It owns:

- The light-only color tokens and their intended roles.
- Inter variable typography across editorial and interface roles.
- The spacing scale, reading measure, page widths, responsive breakpoints, columns, gutters, and margins.
- Shared sheets, rules, buttons, links, status tabs, tables, and disclosure motion.
- Responsive behavior for heading rails, metadata bands, annotations, Frontier Delta records, registration cues, and essential tables.
- Focus, reduced-motion, grayscale, contrast, and horizontal-overflow requirements.
- Presentation safeguards that reject substitute colors, unapproved radii or shadows, gradients, glass effects, and inaccessible focus styling.

It does not own:

- Canonical Entry fields, status definitions, or evidence rules.
- The content, information architecture, or data selection for a particular public page.
- Route generation, release construction, or dataset output.
- A dark palette. Stage 1 has no automatic dark mode.
- Browser telemetry, analytics, or persistent client logging.

## Normal Flow

1. `FoundationLayout.astro` loads the pinned project-owned Inter variable font, then imports `src/styles/global.css`.
2. `global.css` imports the token, base, typography, layout, component, and site-shell stylesheets in a stable order.
3. Mobile tokens apply by default. Media queries change the grid and approved type roles at 768px, 1024px, and 1312px; viewports below 400px use the smaller mobile page margin.
4. Astro pages use the shared `atlas-*` classes and status data attributes instead of declaring local colors or substitute components. The [Stage 1 Site Shell](./stage-1-site-shell.md) composes those primitives for shared navigation, the [Entry Preview](./entry-preview.md) composes them for record summaries, the [Stage 1 About Page](./stage-1-about-page.md) composes them for project identity and limitations, the [Stage 1 Changelog Page](./stage-1-changelog-page.md) composes them for the ruled type key and revision index, the [Stage 1 Entry Page](./stage-1-entry-page.md) composes them for complete maintained records, the [Stage 1 Export JSON Page](./stage-1-export-json-page.md) composes them for the release sheet and responsive field index, the [Stage 1 Methodology Page](./stage-1-methodology-page.md) composes them for the public rulebook, and the [Stage 1 Topic Trail Page](./stage-1-topic-trail-page.md) composes them for trail metadata and Entry lists.
5. Vitest checks the token and source contract. Playwright checks representative computed styles, responsive layouts, interaction states, reduced motion, grayscale-readable states, accessibility, and horizontal overflow.

The current public interface includes the [Stage 1 Homepage](./stage-1-homepage.md), [Stage 1 About Page](./stage-1-about-page.md), [Stage 1 Changelog Page](./stage-1-changelog-page.md), statically generated [Stage 1 Entry pages](./stage-1-entry-page.md), the [Stage 1 Export JSON Page](./stage-1-export-json-page.md), current and immutable [Stage 1 Methodology pages](./stage-1-methodology-page.md), and generated [Stage 1 Topic Trail pages](./stage-1-topic-trail-page.md). Each feature owns its composition while reusing the same type roles, rules, sheets, links, status treatments, spacing, and focus behavior.

## Presentation Contracts

`atlas-page`, `atlas-page-boundary`, `atlas-grid`, and `atlas-prose` provide the contained page measure, shared outer alignment, responsive columns, and long-form reading measure. The Homepage may request the typed full-width Main mode and compose sections against the separate 1400px wide token. The site shell uses the same wide boundary for the Header and Footer. Rail, metadata, annotation, registration-cue, and Frontier Delta classes provide the approved responsive transformations without requiring page-specific breakpoint logic.

Typography classes assign the complete Inter size, line-height, weight, and tracking role. The type scale distinguishes editorial titles, claims, evidence prose, navigation, controls, headings, metadata, dates, tables, labels, errors, and compact annotations without introducing a competing font family.

Sheets, rules, buttons, links, status tabs, tables, and disclosures use shared component classes. Essential tables require a visible caption or heading and a `data-label` on each body cell so the mobile layout can become a stacked definition record without horizontal scrolling.

Claim-status tabs use visible text and borders as well as color. The base treatment is neutral; `reported_but_unverified`, `disputed`, and `failed_retracted` use the three approved exceptional treatments. Pages must supply the real public label in the markup because CSS must not generate or replace essential status information.

## Accessibility adjustments for compact color

Slate (`#64748B`) has a 4.55:1 contrast ratio against Atlas Canvas (`#F8FAFC`) and remains the neutral compact-metadata treatment. Compact blue text uses Accessible Blue (`#0369A1`), which has a 5.57:1 ratio against Pale Blue (`#F0F9FF`).

Reference Blue (`#0284C7`) remains available for decoration and larger accents, but its 4.10:1 ratio against white does not meet WCAG AA for normal-sized text. Page and component CSS must use the owned accessible blue token for compact text instead of substituting the decorative reference blue.

## User-Facing Behavior

Frontier Atlas remains understandable when color is removed. Status names stay visible, evidence states do not resemble rewards or scores, and no essential information appears only in a margin annotation. Prose links are underlined, keyboard focus uses a visible three-pixel outline, and controls keep their approved mobile dimensions rather than shrinking to preserve a desktop composition.

The operating system's dark-mode preference does not change Frontier Atlas colors. A dark mode requires a separate approved palette and complete component-state specification.

Under `prefers-reduced-motion: reduce`, non-essential transitions and disclosure movement are removed. The same open and closed states remain available without animation.

## Internal Edge Cases

- Viewports below 400px reduce page margins from 20px to 16px; typography does not shrink below the approved mobile scale.
- Contained pages retain the 1248px content maximum and existing page margins. The Homepage and shared shell may use the approved 1400px wide boundary with section-owned responsive padding.
- The shared `atlas-prose` primitive stays near 68 characters. The Entry Page's maintained-record sections deliberately use the full sheet width; its feature tests protect wrapping and horizontal overflow at each responsive layout.
- Pure White is reserved for text on dark controls or another case where Atlas Sheet lacks sufficient contrast. It is not a substitute page or card surface.
- The mobile table layout depends on author-provided `data-label` values. Missing labels remove the definition term and break the essential mobile record.
- Disclosure and Homepage content remain readable without browser JavaScript because core presentation uses static HTML and CSS.

## Cross-System Edge Cases

- [Canonical Records](../evidence-ledger/canonical-records.md) owns claim-status machine values and public labels. Frontier Atlas only maps those machine values to presentation treatments.
- The [Entry Preview](./entry-preview.md) owns its field sequence, typed projection, and feature layout. Frontier Atlas supplies the sheet, rules, typography, status treatments, focus behavior, spacing, and responsive breakpoint used by that component.
- The [Stage 1 Site Shell](./stage-1-site-shell.md) owns shared navigation behavior and page structure. Frontier Atlas supplies its tokens, focus treatment, responsive breakpoint, and page alignment primitive.
- The [Stage 1 Homepage](./stage-1-homepage.md) owns its 1400px Hero composition, regular four-card Entry grid, full-width Premise band, and populated Domain overview while reusing Frontier Atlas tokens and primitives.
- The [Stage 1 About Page](./stage-1-about-page.md) owns its open editorial composition, reading-width prose, responsive actions, ruled Scope Limit rows, carefulness band, and Related Links list while reusing Frontier Atlas tokens and primitives.
- The [Stage 1 Changelog Page](./stage-1-changelog-page.md) owns its continuous ruled Change Type Key, neutral material-event tabs, responsive date grouping, and wide date rail while reusing Frontier Atlas status, rule, type, grid, focus, and color contracts.
- The [Stage 1 Entry Page](./stage-1-entry-page.md) owns its continuous 1080px sheet, exact record hierarchy, full-width section composition, responsive Frontier Delta, and feature-specific source records while reusing Frontier Atlas tokens and primitives.
- The [Stage 1 Export JSON Page](./stage-1-export-json-page.md) owns its prominent release sheet, exact summary rows, ruled field index, Stage 1 limits, and direct download action while reusing Frontier Atlas sheet, table, button, focus, rule, and responsive contracts.
- The [Stage 1 Topic Trail Page](./stage-1-topic-trail-page.md) owns its Trail Header, Metadata Strip, route cue, quiet note, and Entry list composition. Frontier Atlas supplies the approved compact type, Route Blue, rules, spacing, focus, and responsive primitives.
- The [Stage 1 Methodology Page](./stage-1-methodology-page.md) owns its open reading sections, ruled Jump To index, Methodology plates, and feature-specific table composition while reusing Frontier Atlas table, focus, typography, spacing, and color contracts.
- [Static Application Foundation](../static-application-foundation.md) owns the Astro shell, local font loading, static build, and validation commands. Frontier Atlas owns the presentation contract loaded by that shell.
- Later page modules may choose which real record information to show, but annotations may only repeat or emphasize that information. A page cannot move an essential value exclusively into an annotation.
- Page-specific CSS may arrange content within an approved primitive, but it must not introduce substitute colors, radii, shadows, gradients, or a competing responsive scale. Cards use the approved 16px radius and subtle shadow; controls use the approved 12px radius; pills use the approved pill radius.

## Failure Behavior

Design-system review fails when presentation code introduces a local color, unapproved radius or shadow, inaccessible focus state, automatic dark-mode override, essential color-only state, gradient, or horizontal page scrolling. The foundation contract tests catch source-level violations, while browser tests catch representative computed-style, responsive, motion, grayscale, contrast, and accessibility failures.

## Invariants

- Frontier Atlas is light-only for Stage 1, with `color-scheme: light`.
- `src/styles/global.css` is the application stylesheet entry point.
- Pages and components use project-owned tokens and primitives rather than local substitutes.
- Neutral compact metadata uses Slate, while compact blue text uses Accessible Blue rather than the decorative Reference Blue.
- The interface remains understandable in grayscale.
- Evidence states never use green escalation, scores, reward cues, or popularity styling.
- No essential information appears only in an annotation.
- Essential tables do not require horizontal scrolling.
- Focus remains visible, reduced-motion preferences are respected, and text never shrinks below the approved mobile roles.
- The design system adds no telemetry, analytics, production console logging, or persistent client logging.

## Implementation Landmarks

- `src/styles/tokens.css` — Color, Inter typography, spacing, grid, focus, radius, shadow, and motion tokens.
- `src/styles/global.css` — Ordered public stylesheet entry point.
- `src/styles/base.css` and `src/styles/typography.css` — Document defaults, interaction behavior, and type roles.
- `src/styles/layout.css` and `src/styles/components.css` — Responsive layouts and shared presentation primitives.
- `src/styles/site-shell.css` — Frontier Atlas presentation for the shared Stage 1 Header, Footer, mobile disclosure, and skip link.
- `src/components/entry-preview/` — Feature-owned composition of Atlas primitives for the Entry Preview.
- `src/features/homepage/homepage.css` — Homepage-owned composition of Frontier Atlas primitives.
- `src/features/about-page/about-page.css` — About-owned composition of reading-width prose, actions, and continuous ruled structures.
- `src/features/changelog-page/changelog-page.css` — Changelog-owned composition of the ruled legend, material-event records, and responsive date rail.
- `src/features/entry-page/` — Entry Page projection, Astro composition, and feature-owned responsive styles.
- `src/features/export-page/` — Export JSON release sheet, field index, limits, and responsive styles.
- `src/features/methodology-page/` — Methodology rulebook projection, Astro composition, and feature-owned responsive styles.
- `tests/foundation/frontier-atlas-contract.test.ts` — Source and token safeguards.
- `tests/browser/frontier-atlas.spec.ts` — Computed-style, responsive, motion, grayscale, and accessibility checks.
- `tests/browser/entry-preview.spec.ts` — Preview-specific responsive, focus, status, overflow, and accessibility checks.
- `tests/browser/entry-page.spec.ts` — Entry Page hierarchy, widths, connector, source, focus, overflow, static 404, and accessibility checks.
- `tests/browser/export-page.spec.ts` — Export hierarchy, immutable download, Schema agreement, responsive table, focus, no-JavaScript, and accessibility checks.
- `tests/browser/changelog-page.spec.ts` — Changelog hierarchy, type treatments, responsive legend and date rail, focus, overflow, no-JavaScript, and accessibility checks.
- `tests/browser/methodology-page.spec.ts` — Methodology route identity, anchors, responsive tables, focus, overflow, no-JavaScript, and accessibility checks.

## Before Changing Frontier Atlas

Check:

- Whether the change uses an existing token or primitive before adding a new public interface.
- Whether text and controls retain required contrast, focus, labeling, and grayscale meaning.
- Whether all five representative widths still have the approved columns, gutters, margins, type roles, and no horizontal overflow.
- Whether mobile tables retain visible definition labels and desktop table semantics.
- Whether reduced-motion and dark operating-system preferences preserve the approved static states and light palette.
- Whether a page ticket predates the compact-metadata accessibility adjustment. If it conflicts, preserve the Secondary Ink rule unless the project owner explicitly approves a tested accessible replacement.
- Whether the change belongs to Frontier Atlas, the [Stage 1 Site Shell](./stage-1-site-shell.md), the [Entry Preview](./entry-preview.md), the [Stage 1 Homepage](./stage-1-homepage.md), the [Stage 1 About Page](./stage-1-about-page.md), the [Stage 1 Changelog Page](./stage-1-changelog-page.md), the [Stage 1 Entry Page](./stage-1-entry-page.md), the [Stage 1 Export JSON Page](./stage-1-export-json-page.md), the [Stage 1 Methodology Page](./stage-1-methodology-page.md), or the [Stage 1 Topic Trail Page](./stage-1-topic-trail-page.md).

Read [Stage 1 Site Shell](./stage-1-site-shell.md) before changing shared navigation or page structure, and read [Static Application Foundation](../static-application-foundation.md) before changing global imports, font loading, test commands, or the Astro presentation boundary.