T-XIFP-design-language-ui-subpath-exports
Status: open/ready · Impact: medium · Complexity: small
Consumers outside the auto-import boundary reach the layer’s runtime
modules by deep source path (@determined/ui/app/utils/dSemantics in
pumice’s semantics barrel). It works, but a future internal file move
breaks consumers silently. A real exports map makes the public surface
explicit. Danger to design around: an exports map RESTRICTS subpaths — a
naive one breaks today’s deep imports and possibly Nuxt’s layer
resolution of nuxt.config.ts, so every consumer must be verified in the
same change.
| Location | Role today |
|---|---|
packages/ts/ui/package.json | No exports map; any internal path is importable. |
apps/pumice/src-nuxt/app/utils/uiSemantics.ts | Deep-imports @determined/ui/app/utils/dSemantics (commented as fragile). |
packages/ts/ui/app/utils/dSemantics.ts | The module consumers actually want. |
Proposed
Section titled “Proposed”package.json gains an exports map exposing a stable public surface
(e.g. ./semantics → ./app/utils/dSemantics.ts, plus whatever Nuxt
layer resolution needs — ./nuxt.config.ts, config/css paths; verify
what jiti/Nuxt actually requests). Pumice’s deep import moves to the
stable subpath. Every extends consumer still builds and boots.
Approach
Section titled “Approach”- Trace what paths Nuxt/jiti resolve through the package during layer
extension (build one consumer with tracing) — the exports map must not
block them; a permissive
"./*"passthrough plus named stable subpaths is an acceptable landing point. - Add the map; move pumice (and any other deep importer — grep repo-wide
for
@determined/ui/) onto the named subpath. - Build/boot every consumer: shell, sdf desktop, suspenders, zoo, agentpants, pumice, learn_web, vimit_prototype, augmented_web.
- Document the public surface in
design-system.md§5/§6.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
packages/ts/ui/package.json | modify | exports map |
apps/pumice/src-nuxt/app/utils/uiSemantics.ts | modify | stable subpath import |
packages/ts/ui/docs/design-system.md | modify | public-surface note |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: A named stable subpath serves dSemantics; no repo consumer deep-imports an internal path.
- AC-2: All nine consumers build and boot unchanged.
- AC-3: The spec names the public import surface.
Out of scope
Section titled “Out of scope”- Publishing the package outside the repo; API changes to dSemantics.
Dependencies
Section titled “Dependencies”- Land after the Phase 3 adoption PRs merge (they introduce the consumers this must verify).
Discovery context
Section titled “Discovery context”- Flagged by the pumice adoption review (2026-08-28, #1513): the deep import is fragile by construction.