Skip to content

Add CSS token migration plan for future UI framework swap#503

Draft
Copilot wants to merge 10 commits into
litfrom
copilot/migrate-mint-to-lit-components
Draft

Add CSS token migration plan for future UI framework swap#503
Copilot wants to merge 10 commits into
litfrom
copilot/migrate-mint-to-lit-components

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented May 25, 2026

Capture the plan for decoupling lit-components from Shoelace's --sl-* CSS custom properties so a future UI framework swap is a one-file mapping change rather than a sweep of every view.

Context

Views and stories reference Shoelace tokens directly (var(--sl-spacing-medium), var(--sl-color-neutral-200), etc.) — ~396 occurrences across ~90 files, drawing from 64 unique tokens. The markup side is already abstracted behind src/ui/registry.ts + UIComponents; the CSS side is not.

Plan summary (packages/lit-components/CSS_TOKEN_MIGRATION_PLAN.md)

  • Introduce --sq-* namespace owned by this package in src/ui/tokens/tokens.css — names express intent, not Shoelace internals.
  • Per-adapter mapping in src/ui/<framework>/tokens.css (e.g. --sq-spacing-md: var(--sl-spacing-medium);), imported from the adapter's bootstrap.ts.
  • Mechanical codemod of var(--sl-*)var(--sq-*) across src/components/** (views + stories). src/ui/shoelace/index.ts keeps --sl-* since it is the adapter.
  • Lock the boundary with a CI grep/lint rule, mirroring the existing "no <sl-*> markup in views" convention.
  • Future swap = write src/ui/<new>/{index.ts,tokens.css,bootstrap.ts} + change three lines in src/index.ts; zero edits under src/components/**.

Plan also includes a fresh-inventory command, full token breakdown by family, risk register, and rough effort sketch.

Copilot AI added 5 commits May 25, 2026 18:14
Components added:
- Text, BigStat, Image, Empty (display)
- Brand, TitledSection, Hero, HeroImage (layout)
- ShareLink, ShareButton, ShareCode, CouponCode, ReferralCodes (sharing)
- InputField, CheckboxField, DropdownField, PasswordField, NameFields, RadioCard (forms)
- NavigationSidebar, NavigationSidebarItem, Tabs, Tab, Router, Route, NavigationMenu (navigation)
…onents

Components added:
- DividedLayout, StatContainer, LinkButton, Pagination, PopupContainer, Scroll, CloseButton, FormMessage (utility)
- PortalContainer, PortalLogin, PortalRegister, PortalForgotPassword, PortalResetPassword, PortalChangePassword, PortalProfile, PortalFooter, PortalFrame (portal)
- Leaderboard, LeaderboardRank, TaskCard, Timeline, TimelineEntry, ProgramExplainer, ProgramExplainerStep (game/stats)
- UserName, QRCode, ReferralCard, ReferralIframe, RewardExchangeList, HeaderLogo, TextSpan, ProgramMenu, LogoutCurrentUser (misc)
- ReferralTable, RewardsTable, InvoiceTable, TableCell, TableRow, PayoutButtonScroll (tables)
- PortalEmailVerification, PortalVerifyEmail, PortalRegistrationForm, PortalChangeMarketing, PortalLogout, PortalProtectedRoute, PortalGoogleLogin, MarketingEmailsCheckbox, ContextRouter, GraphQLClientProvider (complex auth)
…for hooks

- Migrate verification/lead components (WidgetVerification, CodeVerification, EmailVerification, LeadForm, EditProfile, InstantAccessRegistration, ReferredRegistration)
- Migrate tax-and-cash components (TaxAndCash, TaxAndCashDashboard, BankingInfoForm, PayoutDetailsCard, PayoutStatusAlert, UserInfoForm, IndirectTaxForm, DocusignForm)
- Migrate remaining components (CardFeed, BaseRegistration, GoogleSignIn, PortalGoogleRegistrationForm)
- Add vitest unit tests for 11 component hooks
- All 94 components now migrated with stories and Chromatic readiness
- Added msw dependency and test script to package.json
- Added unit test project configuration to vite.config.ts
- Created 54 new test files covering all hooks (excluding demo hooks)
- Tests cover: initial state, form validation, event dispatch, GraphQL query handling, pagination, and interaction flows
- All 65 test files pass with 244 tests total
…ponents

Update the ShareLink GraphQL query to pass engagementMedium and
shareMedium parameters, matching the updated mint-components behavior
after the master merge.
@00salmon Sam Beveridge (00salmon) changed the title feat(lit-components): propagate ShareLink query changes from master merge Co-pilot mint -> lit migration May 25, 2026
…mponents

Add useDemo* hooks with static/mock data and isDemo() ternary branching
to 47 lit-components, mirroring the mint-components demo pattern for
sandbox environments. Components covered include:
- Copy-text: ShareLink, ShareCode, CouponCode, ReferralCode, ReferralCodes
- Data display: UserName, QRCode, ReferralIframe, ShareButton, TaskCard
- Tables: ReferralTable, RewardsTable, InvoiceTable, RewardExchangeList
- Portal/Auth: PortalLogin, PortalProfile, EditProfile, PortalRegister,
  PortalRegistrationForm, PortalGoogleRegistrationForm, PortalLogout,
  PortalProtectedRoute, PortalChangeMarketing, PortalChangePassword,
  PortalForgotPassword, PortalResetPassword, PortalEmailVerification,
  PortalVerifyEmail
- Tax/Payout: TaxAndCash, TaxAndCashDashboard, BankingInfoForm,
  DocusignForm, IndirectTaxForm, UserInfoForm, PayoutButtonScroll,
  PayoutDetailsCard, PayoutStatusAlert
- Navigation: NavigationMenu, NavigationSidebarItem, Pagination,
  ContextRouter, ProgramMenu
- Forms: CheckboxField, DropdownField, InputField, NameFields, PasswordField
- Other: GoogleSignIn, InstantAccessRegistration, LogoutCurrentUser,
  LeadForm, WidgetVerification
Copilot AI changed the title Co-pilot mint -> lit migration feat(lit-components): add demo hooks and isDemo() branching to all components May 26, 2026
Copilot AI changed the title feat(lit-components): add demo hooks and isDemo() branching to all components Introduce framework-agnostic UI adapter layer for lit-components May 26, 2026
Copilot AI changed the title Introduce framework-agnostic UI adapter layer for lit-components Add CSS token migration plan for future UI framework swap May 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants