Tracking: gaps found migrating a production map-first app #385

Gaps found while porting a production map-first field-sales app (React/Tailwind/shadcn to SvelteKit + @codeatlasdev/ui@4.5.0, pinned there because later majors broke too much). Every gap that forced a local workaround is listed here. At the time of writing the app carries 35 TODO(lib#...) markers across 19 issues and 62 CSS selectors against internal .ca-* classes in 18 files. The goal is a library where this kind of product needs none of them.

Legend: additive = optional props/tokens/new components, defaults unchanged. breaking = changes default rendering or API for existing users.

Shell and map

• AppShellLayout: persistent background stage (map, canvas, video) that survives route changes, with pass-through content #343 Persistent background stage that survives navigation, pass-through content. Impact: map WebGL context kept (1-2 s saved per route), no manual z-index/pointer-events. additive
• Page frame primitive for map-first apps: floating panel / split / full page, non-modal bottom sheet on mobile, and covered-area reporting #344 Page frame (map / split / page, non-modal sheet) and covered-area reporting. Impact: replaces a ~290-line component and hand-computed fit padding. additive
• Map integration entry (@codeatlasdev/ui/map): Mapbox GL / MapLibre + deck.gl that follow the theme #345 Map entry (@codeatlasdev/ui/map) following the theme. Impact: removes the canvas color round-trip, glass controls, reduced-motion flyTo. additive
• Navigation: Rail labels and a search/⌘K trigger, plus a BottomNav overflow ("More") for more than 5 modules, with badges #346 Rail labels, search trigger, bottom-nav overflow and badges. Impact: 4 workaround markers, 7+ modules usable on mobile. additive
• AuthLayout: panel side, full-bleed custom panel (live map), header slot and form-first layout #347 AuthLayout panel side, full-bleed panel, header slot. Impact: live-map auth screens without a local shell. additive
• PageShell: mobile actions stretch StatusChip/Chip/Badge to full width #339 PageShell mobile actions stretch chips/badges. Impact: blocks inline status in headers. additive (bug fix)
• GlassCard: header padding stacks on card padding, so title is misaligned with content #341 GlassCard header padding stacks. Impact: misaligned titles. breaking (visual, small)
• PageShell/AppShellLayout: no aside column and panel always open, leaving dead space on wide screens #342 PageShell/AppShell aside column and closable panel. Impact: dead space on wide screens. additive
• Drawer: chromeless/full-bleed mode (no header, no body padding, full width) for side detail panels #362 Drawer chromeless / full-bleed. Impact: full-screen detail on phones without two close buttons. additive
• Dialog split: configurable size, columns and mobile full-screen; Dnd: container-target mode without insertion line #377 Dialog split size/columns, Dnd container-target mode. Impact: 4 .ca-dialog*/.ca-dnd-indicator rules. additive
• Theme island: full-page preset/scheme override with SSR parity (light landing inside a dark app) #352 Theme island with SSR parity. Impact: light landing inside a dark app, no flash. additive

Theme and tokens

• Theme presets: colors with alpha/OKLCH and extensible domain tokens (status, tier, channel) per preset and scheme #374 Preset colors with alpha/OKLCH and extensible domain tokens (status, tier, channel). Impact: removes 36 hand-flattened hex roles and 23 --z-* domain tokens (~30 usages). additive
• Theme presets: override primary-button fill/contrast and field font size per preset #354 Preset override of primary fill/contrast and field font size. Impact: 16 .ca-btn* rules, 2 markers. additive
• Theme: body text size is also the root font-size, so changing it rescales every rem token #351 Body size also sets the root rem (rescales everything 12.5%). Impact: every dense product hits it. breaking (visual)
• Editorial primitives: display scale, out-expo/quart easings, animated highlight/strike, paper grain #353 Editorial primitives (display scale, easings, highlight/strike, grain). Impact: local keyframes and clamps on landing. additive

Typography

• Typography: named type scale by role (title, heading, body, label, caption, mono-num) with tracking and line-height #375 Named type scale by role (title/heading/body/label/caption/num) with tracking and line-height. Impact: replaces 423 usages of a parallel token set. additive
• Typography: display font role for marketing/auth headlines (--ca-font-display) used by components #350 Display font role used by components. Impact: 2 markers, auth/empty/page titles. additive
• Button / IconButton / Kbd: weight, tracking, line-height, gap and padding as component tokens #373 Button/IconButton/Kbd weight, tracking, line-height, gap, padding tokens. Impact: ~25 rules in 6 files. additive

Forms

• TextField: password reveal toggle, and a field-level trailing link slot ("Forgot password?") #348 TextField password reveal, label-end slot, no required asterisk. Impact: local PasswordInput. additive
• ChipGroup: single-choice chips that wrap (radiogroup, roving tabindex, check icon) #355 ChipGroup (single choice, wraps). Impact: local ChoiceChips (158 lines). additive
• Locale switcher component (and a SiteHeader slot for it) #349 LocaleSwitcher and SiteHeader slot. Impact: local switcher with async persistence. additive
• Auth building blocks: Turnstile, PasswordStrength, decorative Avatar and SplashScreen #379 Auth building blocks: Turnstile, PasswordStrength, decorative Avatar, SplashScreen. Impact: 5 local components. additive
• Button: neutral/secondary tone for outlined and ghost (no brand-coloured label or border) #357 Neutral/secondary tone for Button outlined and ghost. Impact: ~11 rules plus a wrapper component, 3 markers. additive
• Density tokens for Avatar, TextArea, TextField, Card, SegmentedControl and EmptyState (no selectors against internal parts) #376 Density tokens for Avatar, TextArea, TextField, Card, SegmentedControl, EmptyState. Impact: ~12 rules in 7 files. additive

Feedback

• Toast: optional description and a single inline action (label + handler) #356 Toast description and inline action. Impact: 8 markers in 4 files. additive
• toast: mensagens idênticas empilham sem limite (sem dedupe nem teto) #363 Toast dedupe and cap. Impact: repeated failures stack identical toasts. additive
• Progress: configurable bar height (size prop or --ca-progress-height), currently fixed at 8px #358 Progress bar height token. Impact: 5 .ca-progress* rules in 4 files. additive
• NotificationBell: controllable open state and independent unread count (lazy list loading) #380 NotificationBell controllable open and independent count. Impact: always-on list query. additive
• Badge: subtle tone with dot for inline pills; Button: responsive trailing hint and label/trailing alignment #378 Badge subtle tone + dot; Button responsive trailing hint and alignment. Impact: pill and __trailing rules. additive

Data display

• Stat: card-less statistic primitive (label, value, hint, trend) sharing KpiCard typography #359 Stat (card-less statistic). Impact: local StatItem, 5 usages. additive
• Table: dense mode, pinned columns, group rows and interactive rows for CRM-style lists #360 Table: dense, pinned columns, group rows with external count, interactive rows. Impact: native table kept as fallback. additive
• Kanban/Board: columns with cross-column drag, board pan, per-column infinite scroll and mobile stage tabs #361 Kanban/Board (cross-column drag, pan, mobile stage tabs, keyboard move menu). Impact: ~190-line board plus helpers. additive

DX, docs and release

• DX: official list of stable .ca-* parts, variables and data attributes for overrides (API.md, manifest, MCP) #381 Official list of stable .ca-* parts, variables and data attributes (API.md, manifest, MCP). Impact: de-risks all 62 selectors across majors. additive
• Release: migration changelog per major, codemods for known breaking changes and deprecation warnings #382 Migration changelog per major, codemods, deprecation warnings. Impact: pinned at 4.5.0 because of unguided breaking changes. additive (process; it documents breaking changes)
• Migration tooling: help teams move an existing app (React/Tailwind/shadcn) onto @codeatlasdev/ui #383 Migration tooling: migrate, token importer, React-UI map, compare, doctor, lint/e2e templates, testing helpers. Impact: most of the non-component cost of the migration. additive

Notes

• Out of scope for the library: Biome not understanding template usage in .svelte (upstream).
• Unify the two marker conventions: consumers wrote TODO(lib#n) while codeatlas-ui workarounds only reads ca-ui-workaround(#n), so it reported 0 markers on an app with 35.
• Earlier docs and skill drift is already closed: skills: npx skills add codeatlasdev/ui installs only codeatlas-writing; codeatlas-ui and codeatlas-dx are not discovered #42, docs(skill): APPSHELL.md uses NavModule.path/sections, but the type is basePath/items #43, Installation docs/skill/init don't cover SvelteKit 3 (allowed by peer ^2.12.0 || ^3.0.0) #44, API.md/manifest: wrong JSDoc used as the component description (TextField shows "@deprecated Use description instead") #45, i18n: Locale is only "en" | "pt-BR" (no way to register es or another language) and setLocale is process-global during SSR #46.