# Feature Specification: Docs Portal Homepage > For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt). **Feature Branch**: `015-docs-portal-homepage` **Created**: 2026-06-12 **Status**: Draft **Input**: Replace the default Docusaurus homepage with the TraderX reference architecture portal homepage, derived from SpecKit metadata. ## User Stories * As a learner, I want the homepage to explain TraderX as a spec-driven financial-services reference architecture portal so I can orient quickly. * As a developer, I want every generated state card to link to its spec, architecture, runtime documentation, learning guide, and generated code branch. * As a maintainer, I want homepage state and demo data sourced from repository catalogs so the homepage does not drift from generated states. * As a demo operator, I want live demo links to come from the live-environment registry so public demo URLs remain accurate. * As an architect, I want the homepage to connect the state catalog to the learning graph so I can navigate from portal overview to deeper dependency/learning material. * As an accessibility user, I want compact homepage actions to remain keyboard accessible and understandable by screen readers. ## Functional Requirements * FR-01501: The Docusaurus root route `/` SHALL render the TraderX docs portal homepage instead of the previous default homepage. * FR-01502: The homepage SHALL be implemented as React components under `website/src/components/homepage/**`, with `website/src/pages/index.js` acting only as the page entrypoint. * FR-01503: The homepage SHALL derive the generated-state list from `catalog/state-catalog.json` and SHALL NOT duplicate state IDs, titles, status, tracks, publish branches, or feature-pack paths in static component data. * FR-01504: Each generated state displayed on the homepage SHALL expose links to its feature spec, generated architecture documentation, runtime or end-to-end flow documentation, learning guide, and generated code branch. * FR-01505: If a state catalog entry declares a decision record, the corresponding homepage state actions SHALL include a link to that ADR. * FR-01506: The homepage SHALL group generated states by catalog track so new states can appear in the appropriate portal section without editing rendered card content. * FR-01507: Live demo cards SHALL be derived from `catalog/live-environments.json` and joined to `catalog/state-catalog.json` by `stateId`. * FR-01508: Live demo links SHALL use the exact URL values from `catalog/live-environments.json`; for the advanced demo this currently means `https://demo-advanced.traderx.finos.org`. * FR-01509: The hero SHALL describe TraderX as a spec-driven reference architecture portal, not as a one-time transformation status. * FR-01510: The Knowledge Graph reference in the hero SHALL link to `/docs/learning-paths`. * FR-01511: The top navigation logo SHALL use the TraderX icon asset from `static/img`, and the hero brand mark SHALL use the primary TraderX horizontal logo asset from `static/img`. * FR-01512: The footer SHALL make only source claims that are true for the current implementation and SHALL identify the catalog-backed source for homepage state data. * FR-01513: Homepage state-card actions SHALL use compact gray icon buttons with hover/focus tooltips rather than verbose repeated text labels. * FR-01514: The homepage SHALL include audience-oriented copy for developers, platform teams, architects, and sponsors learning financial-services architecture through runnable reference states and SDD-enabled demos. * FR-01515: The homepage SHALL describe the FINOS hackathon reinvention value proposition: sophisticated financial-services demos assembled in hours, not days, through SDD. * FR-01516: The Spec-Driven Development homepage section SHALL use examples that explain specs, generated states, and internal overlays rather than unrelated application implementation snippets. * FR-01517: The homepage SHALL explain that companies can customize internal learning journeys through overlays while preserving traceability to core TraderX requirements. * FR-01518: The homepage SHALL use the actual FINOS logo asset in the footer instead of plain FINOS text and SHALL expose FINOS association in the top navigation. * FR-01519: The top navigation brand label SHALL read `FINOS TraderX`. * FR-01520: The homepage footer copyright SHALL name `Fintech Open Source Foundation`. * FR-01521: The `What is Spec Kit?` homepage section SHALL link to the official Spec Kit docs, quickstart, and GitHub repository. ## Non-Functional Requirements * NFR-01501: Homepage state and demo rendering must remain deterministic at build time so `cd website && npm run build` catches broken imports and route references. * NFR-01502: Internal links must use Docusaurus routing primitives where applicable so base-url handling remains correct. * NFR-01503: External generated-code and live-demo links must open safely with `target="_blank"` and `rel="noreferrer"`. * NFR-01504: Icon-only actions must include accessible names through `aria-label`, native `title`, and visible focus treatment. * NFR-01505: Homepage copy and data-source claims must avoid implying that static marketing content is generated from SpecKit unless that content is actually catalog or metadata driven. * NFR-01506: The implementation must preserve Docusaurus build compatibility without adding a separate homepage runtime service. * NFR-01507: Homepage styling must be responsive across desktop and mobile and must avoid overlapping text, clipped action buttons, or layout shifts caused by dynamic state data. ## Acceptance Scenarios ### Scenario 1: Visitor Opens Portal Root Given the Docusaurus website is running When a visitor opens `/` Then the TraderX portal homepage renders with the TraderX logo, reference-portal pill, hero navigation, overview sections, catalog state sections, live demo cards, and footer. ### Scenario 2: State Catalog Changes Given a new generated state is added to `catalog/state-catalog.json` with a feature pack and publish branch When the website is rebuilt Then the homepage state sections include that state without duplicating its metadata in component data. ### Scenario 3: Demo Registry Changes Given a live demo URL changes in `catalog/live-environments.json` When the website is rebuilt Then the corresponding homepage demo card uses the updated URL. ### Scenario 4: State Card Navigation Given a generated state card is visible When a user activates its spec, architecture, runtime, learning, ADR, or code icon action Then the user reaches the corresponding canonical repository artifact or generated branch URL. ### Scenario 5: Accessibility of Compact Actions Given a keyboard or screen-reader user reaches a state-card action When the action receives focus Then the control exposes an accessible label and visible focus state that identifies the destination. ## Success Criteria * SC-01501: `cd website && npm run build` succeeds with the new homepage and spec pack included. * SC-01502: The rendered homepage state count matches `catalog/state-catalog.json.states.length`. * SC-01503: The rendered live demo count matches `catalog/live-environments.json.environments.length`. * SC-01504: State action URLs are computed from catalog fields and feature-pack paths rather than duplicated literal state metadata. * SC-01505: The homepage footer accurately names `catalog/state-catalog.json` as the source for the state list. * SC-01506: The visual learning graph route is reachable from the hero Knowledge Graph link. * SC-01507: The SDD section includes a core requirements example, an internal overlay example, and copy that connects generated demos back to reviewed specs.