Homepage Contract

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:

tools/validate-frontmatter.sh
bash pipeline/speckit/validate-root-spec-kit-gates.sh
bash pipeline/speckit/validate-speckit-readiness.sh
bash pipeline/verify-spec-coverage.sh
cd 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