Dev Notes: First Contact Manual — Style & Layout Contract

Internal reference for src/content/reader/first-contact-manual/*.mdx. The docs/ copy is the source of truth; this post mirrors the current contract for browsing.

Goal: every chapter should read as one designed book. All visual structure comes from imported CSS under src/styles/reader/; MDX should use the documented fcmi-* HTML patterns. Do not import Astro components for appearance, do not add per-chapter <style> blocks, and do not build new Tailwind class piles in chapter MDX.

CSS system#

Import the shared CSS at the top of each active manual MDX file:

import '../../../styles/reader/first-contact-manual.css'
import '../../../styles/reader/first-contact-manual-flow.css'

Use fcmi-window, fcmi-shell, fcmi-frame, fcmi-section-panel, fcmi-routing-*, fcmi-index-*, fcmi-imperative, and fcmi-next-link patterns from the source style guide. The base file owns the reusable technical-window system. The flow extension owns tone-legend visual flow: stronger legend swatches, chapter index rails, section-row dots, panel tone rails, and destination-colored next links. If a new base visual pattern is missing, add it to first-contact-manual.css and document the fcmi-* class contract first.

Tone palette (consistent meaning across the book)#

Pick the fcmi-tone-* class to match meaning, not just to vary color:

Class	Meaning in this manual
`fcmi-tone-red`	CRITICAL / hostile / survival imperative
`fcmi-tone-orange`	HIGH / species-level threat / elimination methodology
`fcmi-tone-yellow`	ELEVATED / caution / helpful-but-dangerous
`fcmi-tone-blue`	INFO / procedures / official protocol / neutral data
`fcmi-tone-purple`	SPECIAL / chapter hero / unique cosmic-scale cases
`fcmi-tone-green`	POSITIVE / rare survival success
`fcmi-tone-gray`	Corporate / bureaucratic / Bi-Smart material
`fcmi-tone-cyan`	Secondary/index accent

Set tone on the outer section whenever possible. Nested tone classes are only for semantic sub-items like legend rows, stat cards, data rows, protocol rows, and mini-cards.

Standard chapter skeleton#

Frontmatter (see checklist below)
Import ../../../styles/reader/first-contact-manual.css and ../../../styles/reader/first-contact-manual-flow.css
Hero block using <section className="not-prose fcmi-hero fcmi-window fcmi-tone-purple">
---
## Chapter Overview — 2–3 paragraphs, no components
---
Numbered ## N.M Section Title sections, with visual blocks built from fcmi-* HTML patterns
Use fcmi-section-panel, fcmi-metric-grid, fcmi-reference-spread, fcmi-notice, fcmi-protocol-stack, and related classes from the source style guide
---
## Conclusion (or chapter-specific closing heading)
Next chapter link using <a className="not-prose fcmi-next-link fcmi-window ...">
## Chapter References when the chapter uses research-backed scientific, theoretical, or historical material

Frontmatter checklist#

Copy forward.mdx’s frontmatter block and adjust per-chapter. Keep these consistent across all files:

authorName: "An Anonymous Interstellar Veteran (Redacted)" — use parentheses, not [Redacted] (forward currently has the bracket variant; fix when touched).
authorBio: exact shared sentence — see the world bible dev note.
image: a real chapter-specific image under /first-contact/ when one exists; fall back to /posts/timeline/chronos.png only if no custom art exists yet.
timelineYear: 7.652e3, timelineEra: "awakening-era", timelineLocation: "The Fringes of Known (and Mostly Hostile) Space", isKeyEvent: true, showImageOnPost: false, bannerType: "image", category: "MEGA MEAL", draft: true, series: "first-contact-manual", seriesTitle: "The Interstellar Traveler's First Contact Manual", contentFormat: "manual".
seriesPart: chapter number (1–5). Omit for forward/afterword.
tags: always include First Contact; add 2–4 chapter-specific tags, no more.

Things to avoid#

Don’t leave research sources only in chat notes. Research-backed additions need a grouped chapter reference entry, preferably using primary papers, review papers, DOI pages, standards bodies, or official scientific references.
Don’t import Astro components for styling or layout.
Don’t hand-write bg-{color}-900/NN border border-{color}-500/30 rounded-lg p-N combinations.
Don’t invent new gradient/border color combos for hero-style blocks.
Don’t nest raw <div className="grid grid-cols-1 lg:grid-cols-2 gap-6"> card grids.
Keep inline <span className="..."> styling only for small one-off emphasis, not structural layout.