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

FoundationLayout.astro loads the pinned project-owned Inter variable font, then imports src/styles/global.css.
global.css imports the token, base, typography, layout, component, and site-shell stylesheets in a stable order.
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.
Astro pages use the shared atlas-* classes and status data attributes instead of declaring local colors or substitute components. The Stage 1 Site Shell composes those primitives for shared navigation, the Entry Preview composes them for record summaries, the Stage 1 About Page composes them for project identity and limitations, the Stage 1 Changelog Page composes them for the ruled type key and revision index, the Stage 1 Entry Page composes them for complete maintained records, the Stage 1 Export JSON Page composes them for the release sheet and responsive field index, the Stage 1 Methodology Page composes them for the public rulebook, and the Stage 1 Topic Trail Page composes them for trail metadata and Entry lists.
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 About Page, Stage 1 Changelog Page, statically generated Stage 1 Entry pages, the Stage 1 Export JSON Page, current and immutable Stage 1 Methodology pages, and generated Stage 1 Topic Trail pages. 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 owns claim-status machine values and public labels. Frontier Atlas only maps those machine values to presentation treatments.
The Entry Preview 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 owns shared navigation behavior and page structure. Frontier Atlas supplies its tokens, focus treatment, responsive breakpoint, and page alignment primitive.
The Stage 1 Homepage 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 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 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 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 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 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 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 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, the Entry Preview, the Stage 1 Homepage, the Stage 1 About Page, the Stage 1 Changelog Page, the Stage 1 Entry Page, the Stage 1 Export JSON Page, the Stage 1 Methodology Page, or the Stage 1 Topic Trail Page.

Read Stage 1 Site Shell before changing shared navigation or page structure, and read Static Application Foundation before changing global imports, font loading, test commands, or the Astro presentation boundary.