OSS adoption UX
Frontend adopts OSS only when it removes generic maintenance without leaking provider-shaped data into user-facing screens.
Current adoption points
Section titled “Current adoption points”| Area | OSS | Why adopted | Frontend boundary |
|---|---|---|---|
| Documentation | Astro Starlight | Navigation, search-ready content collections, and docs layout stay maintained by Starlight. | Do not build a custom docs shell in assembly-repo/apps/docs. |
| Styling | DaisyUI | Common buttons, badges, cards, stats, tables, and forms stay consistent without bespoke CSS. | Use Astro atomic layers; do not create a second component system. |
| Document output | print-js | Browser print fallback works without handmade iframe/print-window code. | Backend still owns render policy, artifacts, and signed download handoff. |
| CMS authoring | Strapi | Board, notice, health education, campaign, FAQ, document definition, and rule editing use an OSS admin surface. | App screens consume Sanmopia contracts and show Korean labels, not Strapi collection names or imported category numbers. |
| Date calculation | date-fns | Month/day arithmetic for child vaccination preview avoids handwritten date helpers. | Official schedule policy remains backend/contract-owned; frontend preview links to KDCA. |
| Admin navigation and data collections | MUI Material 9.2.0, TanStack React Table 8.21.3 | AppBar/Drawer/Table/Card primitives and one headless row model replace a custom navigation or table engine. | MUI has no native Navigation Rail, so use a M3-informed Drawer rail. Select table versus a distinct vertical card collection by container width, never squeeze the table. See the versioned trap sheet. |
| Report tables | TanStack Table | Sorting, column visibility, pagination, and row selection should not be rebuilt per report. | Use BusinessReportSnapshot contracts and Korean labels; keep the same row model when a narrow layout renders cards instead of a table. |
| Report exports | SheetJS, or backend-generated artifacts | XLSX/CSV/JSON export should read captured report snapshots instead of live mutable calculations. | Prefer Supabase Storage artifacts; use browser-side SheetJS only when offline/operator-side export removes backend work. |
| Reservation collaboration | Supabase Realtime, Nanostores | Broadcast, Presence, and local draft state replace manual reload/history hacks. | Use contract realtimeTopic, expectedRevision, draftSession, and coordinationPolicy; do not handwrite channel names or save payloads. |
| Reservation card flow | Assistant UI concepts, DaisyUI cards, Nanostores | Family reservation intake should feel like structured assistant cards, not a free chat composer or legacy PHP form maze. | Keep card state in Nanostores, keep UI under atomic layers, and render backend-owned service-day, price, receipt, and settlement labels only from projections. |
| Operator audit observability | OpenTelemetry Collector, later Prometheus/Grafana/Tempo/Loki exporters | Runtime logs, traces, metrics, and compliance correlation should not be rebuilt as bespoke admin tables. | Operator-facing history still comes from ReservationChangeJournalEntry; OTel-backed tools are operations surfaces. |
Adoption rule
Section titled “Adoption rule”Adopt a frontend OSS package only when all are true:
- It replaces repeated platform code or date/print/browser edge-case handling.
- It has a narrow API surface and does not require a new runtime framework.
- It reduces local LOC or test burden in the feature slice that uses it.
- It can be installed with
pnpmand checked through existing Astro gates. - It does not expose package names, collection names, ids, or camelCase contract fields as user-facing copy.
Reject an OSS package when a native browser API or existing DaisyUI/Starlight primitive is enough. App-open routing stays native browser code because adding a device-detection package would not remove meaningful maintenance.
Reservation UX evidence loop
Section titled “Reservation UX evidence loop”Customer reservation UX must be verified with real browser screenshots before claiming migration progress. The card flow is structured: actor/family, coverage/address, service plan duration, holiday or suspension preference, caregiver matching hints, pricing/support/payment review, care-history access, booking details, and backend submit. It must not introduce a free-form chat composer.
Current Playwright evidence paths:
frontend-repo/output/playwright/sfc-062-reservation-card-ux-20260708-before/frontend-repo/output/playwright/sfc-062-reservation-card-ux-20260708-after/frontend-repo/output/playwright/reservation-ux-current-20260708/
The after run covers desktop and mobile screenshots for each reachable card
step and records empty console-error lists in desktop-console.json and
mobile-console.json. Backend operational context was intentionally absent in
the run, so the final booking-details card stayed locked and displayed the
contract gap instead of fabricating service type, payment method, price, or
settlement state.
The current run covers /mother and /mother/booking on desktop and mobile
with fixture operational context. The user can visually complete the structured
card flow through ready_to_submit; #paymentMethod remains family_bank from
paymentMethodOptions[0].value, there is no horizontal overflow, and console
error arrays stay empty. The final backend submit remains outside this UX
evidence loop while backend reservation/payment preflight work is active.
Current frontend checklist status:
- Assistant-card flow remains structured cards, not free-form chat.
- Flow state remains in Nanostores.
- Backend-owned price, coupon, support, service-day, payment, receipt, and settlement decisions remain projection/display data, not frontend arithmetic.
- The long backend-authority audit board is collapsed by default so mobile booking can reach the submit card without legacy-form scroll fatigue.
When Assistant UI components are adopted directly, use them only as the interaction shell for structured cards. Keep composer input disabled or absent, keep every step as typed card state in Nanostores, and keep backend-owned money/status/date decisions out of the frontend.
UX copy rule
Section titled “UX copy rule”Screens must translate contract and provider details into natural Korean:
- Show “작성 도구”, not
authoringProvider. - Show “계약 조회”, not
ContentPublication. - Show “다운로드 링크 준비됨”, not
renderRequestCode. - Show “게시 종료” and “조회”, not
activeUntilorviews. - Keep migration source keys in docs or audit logs, not visible app panels.
Child vaccination source handling
Section titled “Child vaccination source handling”The vaccination schedule screen is a convenience preview, not medical advice. It must link to KDCA Prevention Helper pages for the current official schedule and child schedule lookup. Any backend policy update should cite the KDCA source date and keep delayed-dose rules out of frontend-only fixtures.