# Homepage Contract

> For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt).

## Route Contract

*   The Docusaurus root route `/` is the canonical homepage for the TraderX reference architecture portal.
*   `new_website/traderx.html` is a prototype source and is not the canonical portal route.
*   `website/src/pages/index.js` should remain a thin page entrypoint that delegates to `website/src/components/homepage/TraderXHomepage.jsx`.

## Data Source Contract

The homepage has three classes of data:

| Homepage Content | Source | Rule |
| --- | --- | --- |
| Generated state list | `catalog/state-catalog.json` | Required source of truth |
| State artifact links | `catalog/state-catalog.json` fields plus feature-pack paths | Derived, not duplicated |
| Live demo cards | `catalog/live-environments.json` joined to `catalog/state-catalog.json` | Required source of truth |
| Knowledge Graph route | `docs/learning-paths/index.md` | Linked from hero |
| Marketing/audience copy | Homepage component copy | May be curated manually |
| SDD examples | Homepage component copy | Must illustrate specs, overlays, and generated states |

Catalog-backed content must not be retyped into component constants except for presentation labels that are independent of state identity.

## State Link Contract

For each state in `catalog/state-catalog.json`, the homepage must derive:

*   Spec link: `/specs/<feature-pack-slug>`
*   Architecture link: `/specs/<feature-pack-slug>/system/architecture`
*   Runtime link:
    *   `/specs/<feature-pack-slug>/system/end-to-end-flows` for `001-baseline-uncontainerized-parity`
    *   `/specs/<feature-pack-slug>/system/runtime-topology` for later generated states
*   Learning guide link: `/docs/learning/state-<state-id>`
*   Generated code link: `https://github.com/finos/traderX/tree/<publish.branch>`
*   ADR link when `decisionRecord` is present in the state catalog

If a new state needs a different runtime-doc target, add explicit metadata to the catalog rather than hard-coding another exception in rendering logic.

## Live Environment Contract

Live environment cards must render from `catalog/live-environments.json.environments`.

Each live environment card must show:

*   environment name
*   environment status
*   joined state title and state id
*   environment notes when present
*   exact environment URL from the registry
*   generated branch from the registry or joined state publish metadata

The homepage must not invent demo hostnames. The current advanced demo URL is `https://demo-advanced.traderx.finos.org`.

## Brand Asset Contract

*   Top navigation icon: `/img/favicon/favicon-traderX.ico`
*   Top navigation FINOS association logo: `/img/finos/finos-white.png`
*   Hero primary logo: `/img/traderX/TraderX_Horizontal_BLK.svg`
*   Footer FINOS logo: `/img/finos/finos-blue.png`
*   Top navigation brand text: `FINOS TraderX`

If these assets move, update this contract and the homepage implementation together.

## Accessibility Contract

State-card action controls may be icon-only, but each action must provide:

*   `aria-label`
*   `title`
*   keyboard focus styling
*   tooltip text for pointer users
*   a readable fallback label for assistive technology

## Footer Claim Contract

The footer may claim that homepage state data is catalog-backed because it is derived from `catalog/state-catalog.json`. The footer source note must link to the repository copy of that catalog file while displaying `catalog/state-catalog.json`.

The footer must not claim that curated homepage copy is generated by SpecKit unless that copy is moved into a generated or metadata-backed source.

The footer copyright text must use `Fintech Open Source Foundation`.

## SDD Messaging Contract

The homepage must position TraderX as a reinvention of the FINOS hackathon model: a repeatable way to create sophisticated financial-services demos in hours, not days.

The SDD section must explain:

*   core requirements remain canonical in upstream specs
*   internal overlays customize the learning journey for company-specific platforms, controls, and audiences
*   generated state branches produce runnable demos while preserving traceability to the reviewed requirements

Code snippets in this section should show specification, overlay, catalog, or generation workflow examples. They should not be generic application implementation snippets unless the snippet directly demonstrates a requirement-to-code trace.

## Spec Kit Link Contract

The `What is Spec Kit?` homepage section must link to:

*   Official docs: `https://github.github.com/spec-kit/index.html`
*   Official quickstart: `https://github.github.com/spec-kit/quickstart.html`
*   GitHub repository: `https://github.com/github/spec-kit`

## Verification Contract

Before publishing homepage changes, run:

```bash
tools/validate-frontmatter.shbash pipeline/speckit/validate-root-spec-kit-gates.shbash pipeline/speckit/validate-speckit-readiness.shbash pipeline/verify-spec-coverage.shcd website && npm run build
```

At minimum, browser smoke testing must confirm:

*   `/` renders the portal homepage
*   tab switching works
*   Knowledge Graph link reaches `/docs/learning-paths`
*   generated state action links are present
*   live demo links match `catalog/live-environments.json`