# Forgeworks family interface contract

Contract version: 1.6.0 — 5 September 2026

This contract governs visible elements that recur across Forgeworks-family websites.
The executable reference is `app/forgeworks-interface.css`. Every consuming project
keeps that file byte-for-byte identical and imports it after its project stylesheet.

## Fixed shared primitives

| Primitive | Contract |
| --- | --- |
| Interface type | Locally bundled IBM Plex Sans, 400 and 700 |
| Content width | 1180px maximum |
| Desktop gutter | 40px total viewport subtraction |
| Mobile gutter | 28px total viewport subtraction below 650px |
| Header | Full viewport width; 72px inner row; 18px blur; 1px bottom border; sticky |
| Header opacity | 78% Light; 86% Dark Gray; 90% Pure Black |
| Brand | Wordmark at 1.22rem, 700, −0.035em tracking; Exocortex alone may place its approved 1em mark immediately before its wordmark without changing header height |
| Theme control | Three labelled 27px circular controls; 3px shell padding; 2px gap; sun, moon, black dot; Dark Gray is the first-visit default |
| Primary introduction | 62px top offset; 40px below 820px; 32px below 520px; 42–72px bold title; 17px description at a 620px measure; 14px description below 520px |
| Card | 1px border; 18px corners; shared surface and shadow geometry |
| Primary action | 46px minimum height; 10px corners; 14px bold text; project accent |
| Footer | One `Guide` link in a utility row; same 1180px alignment; right-aligned on desktop and left-aligned on mobile; 24px top and 30px bottom padding |
| Guide index | 210px sticky contents column beside project documentation; one column below 820px; two-column link list until 650px, then one column |
| Accent glow | Radial gradient at 75% 0%, fading to transparent at 28rem |

The Light, Dark Gray, and Pure Black neutral tokens, transparencies, shadows,
responsive breakpoints, focus treatment, and reduced-motion behavior are fixed in the
executable reference. They are not re-created approximately per project. The theme
control uses static, familiar symbols and no ambient animation. On the
`myforgeworks.net` domain family, a first-party `forgeworks-theme` cookie shares the
choice across the root site and project subdomains. The same-named local-storage value
provides immediate boot and fallback behavior on previews or legacy hostnames. The
preference contains only `light`, `gray`, or `black`; it is not an identifier.

## Project identity inputs

Each project supplies only these identity variables for each theme:

- `--family-accent`
- `--family-accent-strong`
- `--family-accent-soft`
- `--family-accent-glow`
- `--family-accent-shadow`
- `--family-accent-contrast`

BatchForge supplies green. Forgeworks supplies amber. Family headers use their
wordmarks. Exocortex is the single approved exception: its existing mark may appear at
exactly `1em` before the Exocortex wordmark. Other project logos remain favicons or
content assets unless this contract is deliberately revised.

## Repetition rule

If an element performs the same role in more than one family project, it uses the
same primitive, dimensions, opacity, typography, interaction behavior, and responsive
rule. Current shared elements are the header row, brand treatment, theme switch,
primary introduction type, container, card, primary action, footer, Guide index, focus
state, and page-background glow.

Repeated copy follows the same discipline: use literal labels, avoid promotional filler,
and do not embed a changing project count or version in overview prose when structured
records already carry that information. Every shared footer contains one link named
`Guide`; source, licence, architecture, and other documentation destinations are indexed
inside that Guide instead of competing in the footer.

Project-specific structures remain local: Forgeworks navigation and long-form reading
grammar, BatchForge conversion controls, each Guide's actual content, and future
domain-specific workflows. Optional
structures sit beside the shared chrome rather than silently changing it. Forgeworks
navigation therefore follows the common header instead of altering the header row.

## Extension and change

New family sites begin by copying the executable reference and theme-switch component
unchanged and defining their identity variables. They use the shared preference key,
the Dark Gray default, and a subdomain of `myforgeworks.net` when cross-site theme
continuity is required. A deliberate
change to a shared primitive requires a contract-version change, the same stylesheet and
component update in every consumer, contract tests, the Forgeworks Guide, the repository
design document, the changelog, and a decision record. A local approximation of a shared
primitive is a defect.
