Design system
The five packages under design-system/ — tokens, ui, opal, opal-host, and the docs site that publishes them.
The design system is split into five workspace packages under design-system/.
| Package | Path | Role |
|---|---|---|
@todayai-labs/tdx-tokens | design-system/tokens | Design tokens (colors, spacing, typography) + theme CSS exports |
@todayai-labs/tdx-ui | design-system/ui | Core component library — Radix UI primitives + TDX styling |
@todayai-labs/opal | design-system/opal | Higher-level product flow primitives (onboarding shells, narrative mark) |
@todayai-labs/opal-host | design-system/opal-host | Host adapter contract (in-memory implementation, emitter) |
@todayai-labs/tdx-docs | design-system/docs | Fumadocs site that documents tokens, ui, and opal |
Layering
apps/* (product surfaces)
└─ consume @todayai-labs/opal
└─ consume @todayai-labs/tdx-ui
└─ consume @todayai-labs/tdx-tokens@todayai-labs/opal-host is the host-side contract: in-tree it ships an in-memory
implementation that lets Opal flow components run in Storybook, tests, and
the web app without a real native host attached. Real hosts (the native iOS /
macOS apps) implement the same contract on their side.
Storybook topology
There are five Storybook installations in the repo (one per app plus two under design-system):
| Storybook | What it shows |
|---|---|
apps/web | App-level integration stories (composed flows) |
apps/admin | Admin-specific components |
apps/onboarding | Onboarding-app components |
design-system/ui | TDX component primitives |
design-system/opal | Opal flow primitives + onboarding screens |
Visual regression (pnpm test:visual → web:test-visual Moon task) runs
against the web Storybook only. See
Toolchain → Testing → Storybook for the
full topology and the visual-regression CI gating.
Where component / token reference docs live
Component API tables, design-token swatches, and usage examples live in
design-system/docs
— not in this site. If you are looking for "what props does Button take"
or "what color is text-primary", that site is the canonical answer.
This site only covers how the design system fits into the workspace and how its build / publish pipeline works — see Toolchain → Storybook topology for runtime structure and Workflow → Deployment for how the docs site itself ships.
What @todayai-labs/opal-host exists for
@todayai-labs/opal defines flow primitives that an app composes (e.g.
OpalShaderShell, OpalNarrativeMark). At runtime these primitives sometimes
need to talk to a native host: "tell me the platform", "mint a session cookie",
"fire an analytics event". @todayai-labs/opal-host defines that contract as a
TypeScript interface plus an in-memory implementation used in tests, Storybook,
and the web app's preview routes.
When apps/web runs in a browser it uses the in-memory implementation. When
the same Opal flow runs inside an iOS / macOS WebView, the native side
implements the same contract over the WebView Bridge — see
apps/webview-bridge-docs
for the bridge details.