Substratal Hub — Application Specifications

Build specifications, UI design, themes and the logo standard for the six Substratal Hub apps — the dashboard client for the Substratal Apps Platform (API v1.4.0, 118 operations).

📖 Documentation site: https://compositecode.github.io/substratalapps-applications-specs/

The site is the primary documentation for this spec. It is generated from this repository and redeployed on every push to main.

Apps covered

App	Stack	Notifications	Spec page
Web (responsive PWA)	TypeScript, React, React Aria, TanStack, Workbox	Web Push (VAPID)	Web app UI
iOS / iPadOS	SwiftUI (min iOS 17)	APNs	iOS app UI
Android	Jetpack Compose + material3-adaptive	FCM	Android app UI
Windows	WinUI 3 / Windows App SDK, C#	Polling + local notifications	Windows app UI
Linux (GNOME)	GTK 4 + libadwaita, Flatpak	Polling + local notifications	Linux app UI
macOS	SwiftUI (min macOS 15)	APNs	macOS app UI

What's on the site

• Screens — every reference screen on every platform in light and dark, with live HTML mockups that follow the theme you pick.
• Themes — the 5 light and 5 dark palettes (defaults Moss Paper / Forest Floor), token roles, WCAG contrast and per-platform implementation. The site itself is styled with the Hub's web theme, so you can switch it to any theme.
• Brand — the logo standard: mark, wordmark, lockups, colours and platform icon kits.
• Flows — 16 end-to-end UX flows.
• Docs — every spec document rendered, with the API → screen map as a filterable table.

For AI tools (Claude, Codex, Cursor…)

• llms.txt — index of the site with absolute links.
• llms-full.txt — the whole shared spec in one file.
• platforms/<app>.md — one Markdown file per app (for example platforms/ios.md) with facts, document links, every reference screen and the full platform spec text.
• Every rendered document's Markdown source is served under /spec/, matching the paths in this repo.

Repository layout

.
├── substratal-application-specs/   the specification package (source of truth — edit here)
│   ├── 00-shared/                  shared spec for every team: product, screens, flows, themes, brand, data
│   └── web/ ios/ android/ windows/ linux/ macos/
│                                   per-platform handoff, platform spec, screens, theme code,
│                                   brand assets, reference renders and HTML mockups
├── site/
│   ├── build.mjs                   static site generator → _site/
│   ├── serve.mjs                   local preview server
│   └── assets/                     site CSS and JS
├── .github/workflows/pages.yml     builds and deploys the site on push to main
└── package.json

See substratal-application-specs/README.md for the package's own layout and reading order.

Working on the docs

Requires Node.js 20.11 or later.

npm install
npm run dev        # build, then serve at http://localhost:4000/substratalapps-applications-specs/

npm run build writes the site to _site/ (git-ignored). The generator:

• copies substratal-application-specs/ to _site/spec/ so mockups, images and downloads keep their relative paths;
• renders every Markdown and CSV file to HTML next to its source, with GitHub-compatible heading anchors and links between documents;
• builds the overview, screens, themes, brand, flows and per-platform pages from the spec's own data (themes.json, brand-tokens.json, SCREEN-SPECS.md, screens/, mockups/);
• writes WebP thumbnails for the screen galleries, plus llms.txt, llms-full.txt, per-app Markdown bundles and sitemap.xml.

New screens, documents, themes and platforms files are picked up automatically. To add a document to the sidebar, add it to DOC_GROUPS in site/build.mjs.

Publishing

.github/workflows/pages.yml builds the site on every push and pull request, and deploys it to GitHub Pages on push to main. In the repository's Settings → Pages, the source must be GitHub Actions.

License

MIT © 2026 Adron Hall / Composite Code