shoc-frontend-new/docs/DESIGN_SYSTEM_MIGRATION.md
Arthur Bassi a0cf7b9ef0
Feat/vite typescript migration (#16)
* chore: add eslint, prettier, husky and commitlint tooling

* ci: add GitHub Actions workflow for lint and build

* build: migrate from CRA to Vite with TypeScript config

* docs: add architecture plan and design system documentation

* fix: scope ESLint to new components and hooks directories

* feat: add HTTP client, query cache and shared utilities

* feat: add theme system and global application styles

* feat: add shared UI, layout and domain badge components

* feat: add auth domain, provider and login page

* feat: add app shell, file-based routing and bootstrap

* feat: add protected layout and dashboard module

* feat: add accounts CRUD module

* feat: add assets CRUD module

* feat: add contacts CRUD module

* feat: add employees CRUD module

* feat: add locations CRUD module

* feat: add calendar events module

* feat: add follow-ups CRUD module

* feat: add PM schedules CRUD module

* feat: add work orders module with dispatch modals

* feat: add vendors CRUD and portal token panel

* feat: add vendor purchase orders module

* feat: add uplifts queue module

* feat: add settings for dropdowns and task templates

* feat: add vendor portal routes and signature capture

* test: add Vitest setup and Playwright login e2e spec

* chore: remove legacy CRA pages, Redux store and JS hooks

* chore: update gitignore and env example for Vite

* docs: translate pt-BR docs and Cursor rules to English

* fix(ci): fix login e2e session mock and prettier formatting

* fix(build): use mjs router script for Node 20 CI compatibility

* chore: remove migration scripts and unused generouted router

* fix(auth): restore JWT and align CRUD with backend routes

* fix(api): add no-content helpers and align paths with backend

* fix(accounts): align detail and mutation payloads with backend

* fix(contacts): resolve detail via GetContacts and map address DTOs

* fix(work-orders): align routes, delete body, and create payload

* fix(vendors): delete vendors via REST route

* fix(pm-schedules): handle empty save and delete responses

* fix(employees): add fallbacks for detail and dropdown calls

* chore(calendar): disable routes until backend exists

* chore(env): switch tracked env vars to Vite prefixes

* fix(api): align frontend contracts with backend review findings

Correct Work Order getById query param, asset site options via Location API,
Employee JobTitleId payload, and remove stale API paths.

* fix(employees,pm-schedules): align forms with backend API contracts

Align PM Schedule form and save payload with PMSchedule_DTO fields.
Bind employee Job Title select to jobTitleId for create/update payloads.
Add regression tests for both flows.

* fix(pm-schedules): gate edit/delete for Dev API contract

Production Dev API exposes only GetList and Save.

Hide unsupported edit/delete UI and block the edit route.

Add regression tests for disabled actions.

* docs(env): document VITE_API_URL must include /api suffix

* refactor(api): extract shared API prefix URL resolution

* feat(build): fail build on misconfigured absolute VITE_API_URL

* test(api): cover API URL contract and prefix resolution

* feat(auth): disable login submit until email and password are valid

* test(auth): align login tests with disabled submit behavior

* Feat/ab/menu-and-header (#17)

* chore(deps): add lucide-react for layout icon migration

* feat(auth): add getPrimaryUserRole helper for header display

* style(theme): add sidebar active tokens and nav group typography

* refactor(menu): migrate nav icons to lucide and trim menu groups

* feat(layout): redesign sidebar, topbar, and admin shell viewport

* chore(menu): hide Reports and Documents from sidebar

---------

Co-authored-by: Arthur Bassi <arthur.winiarski.ranger@outlook.com>

* ci: add frontend PR quality baseline (#18)

* chore(deps): add lucide-react for layout icon migration

* feat(auth): add getPrimaryUserRole helper for header display

* style(theme): add sidebar active tokens and nav group typography

* refactor(menu): migrate nav icons to lucide and trim menu groups

* feat(layout): redesign sidebar, topbar, and admin shell viewport

* chore(menu): hide Reports and Documents from sidebar

* ci: add PR quality baseline checks

* ci: avoid self-matching standards guard

* ci: split frontend quality gates

---------

Co-authored-by: Arthur Bassi <arthur.winiarski.ranger@outlook.com>

---------

Co-authored-by: Arthur Bassi <arthur.winiarski.ranger@outlook.com>
Co-authored-by: Alexandre Brandizzi <alex_brandizzi@hotmail.com>
2026-06-18 14:41:17 -03:00

6.9 KiB

Design System Migration Log

Migration from legacy CSS (index.css, #0c4f6f palette) to Seahaven DS tokens. Strategy: MUI-only.

Phase 1 — Foundation

File Action Reason
src/styles/theme.css Created SoT: 131+ Seahaven tokens + layout/typography/elevation extensions
src/styles/fonts.css Created Montserrat, DM Sans, JetBrains Mono via @fontsource
src/styles/typography.css Created Base html/body/heading/caption/label styles
src/styles/motion.css Created Duration and easing tokens
src/styles/globals.css Refactored Import chain + @custom-variant dark; removed legacy @theme tokens
src/lib/utils.ts Created cn() with clsx + tailwind-merge
src/lib/theme/css-vars.ts Created getCssVar() helper for MUI bridge
package.json Modified Added @fontsource/*, clsx, tailwind-merge

Phase 2 — MUI Bridge

File Action Reason
src/lib/theme/mui-theme.ts Expanded Full palette, typography, shape, shadows, 8 component overrides

Phase 3 — App Shell

File Action Reason
src/components/layout/app-sidebar.tsx Created MUI Drawer + sidebar tokens; replaces Sidebar.js
src/components/layout/app-topbar.tsx Created MUI AppBar + header gradient; replaces Topbar.js
src/app/(protected)/_layout.tsx Modified Uses new layout components
src/main.tsx Modified Removed index.css import
src/app/v/_components/vendor-portal.css Modified Re-tokenized with Seahaven CSS vars
src/index.css Deleted ~487 lines migrated to tokens + TSX shell
src/components/Sidebar.js Deleted Replaced by app-sidebar.tsx
src/components/Topbar.js Deleted Replaced by app-topbar.tsx
src/styles/FormPage.css Deleted Unused (no imports in codebase)

Phase 4 — Shared UI

File Action Reason
src/components/ui/button.tsx Created MUI Button wrapper
src/components/ui/badge.tsx Created MUI Chip wrapper
src/components/ui/page-header.tsx Created PATTERN_001
src/components/ui/empty-state.tsx Created PATTERN_003
src/components/ui/form-field.tsx Created PATTERN_004
src/components/domain/type-badge.tsx Created WO type tokens
src/components/domain/status-badge.tsx Created WO status tokens + API aliases
src/components/domain/doc-badge.tsx Created Completion doc tokens (MUI icons)
src/app/(protected)/workorders/index.tsx Modified WorkOrderStatusBadge replaces generic Chip

Phase 5 — Page refactor

File Action Reason
src/app/(auth)/login.tsx Modified #1a3a5c → var(--color-header-bg-start)
src/app/(protected)/dashboard.tsx Modified border-gray-* → border-border
src/app/(protected)/index.tsx Modified Same as dashboard
src/app/(protected)/settings/dropdowns.tsx Modified Semantic sidebar + active states
src/app/(protected)/settings/task-templates.tsx Modified Semantic borders/text
src/components/common/settings-nav.tsx Modified text-primary, border-border
src/components/common/calendar/calendar-utils.ts Modified Bootstrap hex → Seahaven CSS vars
src/components/common/calendar/calendar-action-bar.tsx Modified Semantic surface classes
src/components/common/calendar/event-calendar.tsx Modified Semantic surface classes
src/components/common/signature-capture.tsx Modified Canvas colors from CSS vars
src/app/(protected)/workorders/_components/dispatch-create-modal.tsx Modified Semantic borders/hover
src/app/(protected)/workorders/_components/dispatch-detail-modal.tsx Modified Semantic borders
src/app/(protected)/workorders/[id].tsx Modified Semantic borders
src/app/(protected)/vendor-pos/[id].tsx Modified Semantic borders

Phase 6 — Docs & validation

File Action Reason
docs/DESIGN_SYSTEM.md Created Token reference and usage guide
docs/DESIGN_SYSTEM_MIGRATION.md Created This file

Visual impact summary

  • Primary color: #0c4f6f → #1c75bc (expected, documented)
  • Body font: Segoe UI 13px → DM Sans 14px
  • Sidebar: #fbfbfb → #f6f8fb with Seahaven active/hover states
  • Header: flat blue gradient → Seahaven multi-stop gradient

Not migrated (intentional)

  • CRUD list pages using default MUI theming — inherit via mui-theme.ts without JSX changes
  • src/app/v/_components/signature-pad.tsx — vendor portal isolated; minor #111 stroke remains