681 lines
21 KiB
Markdown
681 lines
21 KiB
Markdown
# MUI Migration — Phase 0: Theming Foundation — Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Stand up the MUI theming foundation — install MUI, build `theme.ts` (light+dark from existing tokens), wire the provider + `data-theme` color-scheme bridge + `ThemeContext` sync, apply the token-level palette refresh app-wide, and ship a dev-only `/ui-kit` route proving the theme on the first wrappers (`Button`/`Card`/`TextField`).
|
||
|
||
**Architecture:** MUI's CSS-variable theme is configured with `colorSchemeSelector: "[data-theme='%s']"` so it reads the same `data-theme` attribute `ThemeContext` already writes — one toggle drives both MUI and legacy CSS. A tiny sync component mirrors the attribute into MUI's JS color-scheme state. `ScopedCssBaseline` scopes MUI's reset to migrated subtrees (here, only `/ui-kit`); legacy pages keep `base.css`.
|
||
|
||
**Tech Stack:** React 18.3, Vite 8, TypeScript (strict), MUI v7 (`@mui/material`) + Emotion + MUI X v8 pickers, Vitest (node).
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-06-06-css-mui-migration-design.md` (§3, §4, §7 token-level layer, §8 Phase 0).
|
||
|
||
**Scope note:** This plan is Phase 0 ONLY. The rest of the `ui/` kit (Modal, Toast, Select, Switch, Tabs, DataTable, DatePicker), the AppShell (Phase 1), and the Vozidla pilot (Phase 2) are separate plans.
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
| File | Responsibility | Action |
|
||
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------ |
|
||
| `package.json` | MUI/Emotion/X-pickers deps; `@types/react` reconciled to 18 | Modify |
|
||
| `src/admin/theme.ts` | The MUI theme: cssVariables + colorSchemeSelector, light/dark palettes, typography, shape, component overrides | Create |
|
||
| `src/admin/theme.test.ts` | Unit test asserting theme palette/typography/shape values | Create |
|
||
| `src/admin/ui/MuiProvider.tsx` | Wraps children in MUI `ThemeProvider` + renders the sync component | Create |
|
||
| `src/admin/ui/MuiColorSchemeSync.tsx` | Mirrors `useTheme()` (custom) → MUI `useColorScheme().setMode` | Create |
|
||
| `src/admin/ui/Button.tsx`, `Card.tsx`, `TextField.tsx` | Thin brand wrappers over MUI (stable app-facing API) | Create |
|
||
| `src/admin/ui/index.ts` | Barrel export for the kit | Create |
|
||
| `src/admin/pages/UiKit.tsx` | Dev-only showcase, wrapped in `ScopedCssBaseline` | Create |
|
||
| `src/admin/AdminApp.tsx` | Mount `MuiProvider`; add DEV-only `/ui-kit` route | Modify |
|
||
| `src/admin/variables.css` | Token-level palette refresh (canvas, chip tints) — app-wide | Modify |
|
||
|
||
---
|
||
|
||
## Task 1: Install dependencies and reconcile React types
|
||
|
||
**Files:**
|
||
|
||
- Modify: `package.json` (via npm)
|
||
|
||
- [ ] **Step 1: Install MUI + Emotion + X pickers**
|
||
|
||
Run (date-fns ^4 is already a dependency):
|
||
|
||
```bash
|
||
npm install @mui/material@^7 @emotion/react@^11 @emotion/styled@^11 @mui/x-date-pickers@^8
|
||
```
|
||
|
||
Expected: packages added to `dependencies`; no peer-dependency errors that block install.
|
||
|
||
- [ ] **Step 2: Reconcile `@types/react` to the React 18 runtime**
|
||
|
||
The repo runs `react@^18.3.1` but pins `@types/react@^19`. MUI's component types are sensitive to the `@types/react` major. Align the types to the runtime:
|
||
|
||
```bash
|
||
npm install -D @types/react@^18.3 @types/react-dom@^18.3
|
||
```
|
||
|
||
Expected: devDependencies now show `@types/react@^18.3.x`.
|
||
|
||
- [ ] **Step 3: Verify the project still type-checks and builds**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx tsc -b --noEmit
|
||
npm run build:client
|
||
```
|
||
|
||
Expected: both succeed with no errors (this is the pre-change baseline; if `tsc` was already failing, capture that before proceeding).
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add package.json package-lock.json
|
||
git commit -m "build(mui): add MUI v7 + Emotion + X pickers; align @types/react to 18"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 2: Create `theme.ts` with light/dark palettes (TDD)
|
||
|
||
**Files:**
|
||
|
||
- Create: `src/admin/theme.ts`
|
||
- Test: `src/admin/theme.test.ts`
|
||
|
||
Token values are taken from `src/admin/variables.css` (`[data-theme="light"]` / `[data-theme="dark"]`).
|
||
|
||
- [ ] **Step 1: Write the failing test**
|
||
|
||
Create `src/admin/theme.test.ts`:
|
||
|
||
```ts
|
||
import { describe, it, expect } from "vitest";
|
||
import { theme } from "./theme";
|
||
|
||
describe("MUI theme", () => {
|
||
it("uses the brand fonts", () => {
|
||
expect(theme.typography.fontFamily).toContain("Plus Jakarta Sans");
|
||
expect(String(theme.typography.h1.fontFamily)).toContain("Urbanist");
|
||
});
|
||
|
||
it("maps the brand red per color scheme", () => {
|
||
expect(theme.colorSchemes.light.palette.primary.main).toBe("#c73030");
|
||
expect(theme.colorSchemes.dark.palette.primary.main).toBe("#d63031");
|
||
});
|
||
|
||
it("maps the refreshed light canvas + paper", () => {
|
||
expect(theme.colorSchemes.light.palette.background.default).toBe("#f4f3f1");
|
||
expect(theme.colorSchemes.light.palette.background.paper).toBe("#ffffff");
|
||
});
|
||
|
||
it("maps semantic colors per scheme", () => {
|
||
expect(theme.colorSchemes.light.palette.error.main).toBe("#b91c1c");
|
||
expect(theme.colorSchemes.dark.palette.success.main).toBe("#22c55e");
|
||
});
|
||
|
||
it("uses the base radius of 10", () => {
|
||
expect(theme.shape.borderRadius).toBe(10);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run the test to verify it fails**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx vitest run src/admin/theme.test.ts
|
||
```
|
||
|
||
Expected: FAIL — `Cannot find module './theme'` (or `theme` is undefined).
|
||
|
||
- [ ] **Step 3: Implement `theme.ts` (palettes/typography/shape only — overrides come in Task 3)**
|
||
|
||
Create `src/admin/theme.ts`:
|
||
|
||
```ts
|
||
import { createTheme } from "@mui/material/styles";
|
||
|
||
const FONT_BODY = "'Plus Jakarta Sans', system-ui, sans-serif";
|
||
const FONT_HEADING = "'Urbanist', sans-serif";
|
||
const FONT_MONO = "'DM Mono', Menlo, monospace";
|
||
|
||
export const theme = createTheme({
|
||
cssVariables: {
|
||
// Read the SAME attribute ThemeContext already writes (`data-theme`).
|
||
// The "%s" placeholder is required; value must start with "." or "[".
|
||
colorSchemeSelector: "[data-theme='%s']",
|
||
},
|
||
colorSchemes: {
|
||
light: {
|
||
palette: {
|
||
mode: "light",
|
||
primary: { main: "#c73030" },
|
||
success: { main: "#15803d" },
|
||
warning: { main: "#b45309" },
|
||
error: { main: "#b91c1c" },
|
||
info: { main: "#1d4ed8" },
|
||
background: { default: "#f4f3f1", paper: "#ffffff" },
|
||
text: { primary: "#1a1a1a", secondary: "#555555" },
|
||
divider: "rgba(0,0,0,0.1)",
|
||
},
|
||
},
|
||
dark: {
|
||
palette: {
|
||
mode: "dark",
|
||
primary: { main: "#d63031" },
|
||
success: { main: "#22c55e" },
|
||
warning: { main: "#f59e0b" },
|
||
error: { main: "#ef4444" },
|
||
info: { main: "#3b82f6" },
|
||
background: { default: "#0f0f0f", paper: "#1a1a1a" },
|
||
text: { primary: "#ffffff", secondary: "#a0a0a0" },
|
||
divider: "rgba(255,255,255,0.08)",
|
||
},
|
||
},
|
||
},
|
||
shape: { borderRadius: 10 },
|
||
typography: {
|
||
fontFamily: FONT_BODY,
|
||
h1: { fontFamily: FONT_HEADING, fontWeight: 800 },
|
||
h2: { fontFamily: FONT_HEADING, fontWeight: 800 },
|
||
h3: { fontFamily: FONT_HEADING, fontWeight: 800 },
|
||
h4: { fontFamily: FONT_HEADING, fontWeight: 700 },
|
||
h5: { fontFamily: FONT_HEADING, fontWeight: 700 },
|
||
h6: { fontFamily: FONT_HEADING, fontWeight: 700 },
|
||
button: { textTransform: "none", fontWeight: 600 },
|
||
},
|
||
});
|
||
|
||
// Re-exported for tasks/components that need the mono stack.
|
||
export const fonts = {
|
||
body: FONT_BODY,
|
||
heading: FONT_HEADING,
|
||
mono: FONT_MONO,
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 4: Run the test to verify it passes**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx vitest run src/admin/theme.test.ts
|
||
```
|
||
|
||
Expected: PASS (5 tests).
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add src/admin/theme.ts src/admin/theme.test.ts
|
||
git commit -m "feat(mui): theme.ts with light/dark palettes, brand fonts, data-theme selector"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 3: Add component overrides (the "Soft-SaaS" defaults)
|
||
|
||
**Files:**
|
||
|
||
- Modify: `src/admin/theme.ts`
|
||
- Test: `src/admin/theme.test.ts`
|
||
|
||
- [ ] **Step 1: Add a failing assertion for the overrides**
|
||
|
||
Append to `src/admin/theme.test.ts` (inside the `describe`):
|
||
|
||
```ts
|
||
it("makes buttons pill-shaped and cards 16px by default", () => {
|
||
const btn = theme.components?.MuiButton?.styleOverrides?.root as any;
|
||
expect(btn?.borderRadius).toBe(999);
|
||
const card = theme.components?.MuiCard?.styleOverrides?.root as any;
|
||
expect(card?.borderRadius).toBe(16);
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run to verify it fails**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx vitest run src/admin/theme.test.ts
|
||
```
|
||
|
||
Expected: FAIL — `theme.components` is undefined / `borderRadius` is undefined.
|
||
|
||
- [ ] **Step 3: Add `components` to the `createTheme` call**
|
||
|
||
In `src/admin/theme.ts`, add a `components` key to the `createTheme({...})` object (after `typography`):
|
||
|
||
```ts
|
||
components: {
|
||
MuiButton: {
|
||
defaultProps: { disableElevation: true },
|
||
styleOverrides: {
|
||
root: { borderRadius: 999, paddingInline: "0.95rem" },
|
||
containedPrimary: {
|
||
backgroundImage: "linear-gradient(135deg, #e23a3a, #c01f1f)",
|
||
boxShadow: "0 5px 14px rgba(214,48,49,0.32)",
|
||
},
|
||
},
|
||
},
|
||
MuiCard: {
|
||
styleOverrides: {
|
||
root: {
|
||
borderRadius: 16,
|
||
boxShadow:
|
||
"0 6px 20px rgba(20,20,40,0.06), 0 1px 2px rgba(0,0,0,0.03)",
|
||
},
|
||
},
|
||
},
|
||
MuiChip: {
|
||
styleOverrides: { root: { borderRadius: 999, fontWeight: 700 } },
|
||
},
|
||
},
|
||
```
|
||
|
||
- [ ] **Step 4: Run to verify it passes**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx vitest run src/admin/theme.test.ts
|
||
```
|
||
|
||
Expected: PASS (6 tests).
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add src/admin/theme.ts src/admin/theme.test.ts
|
||
git commit -m "feat(mui): soft-SaaS component defaults (pill buttons, 16px cards, pill chips)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 4: MUI provider + color-scheme sync
|
||
|
||
**Files:**
|
||
|
||
- Create: `src/admin/ui/MuiColorSchemeSync.tsx`
|
||
- Create: `src/admin/ui/MuiProvider.tsx`
|
||
- Modify: `src/admin/AdminApp.tsx`
|
||
|
||
- [ ] **Step 1: Create the sync component**
|
||
|
||
Create `src/admin/ui/MuiColorSchemeSync.tsx`:
|
||
|
||
```tsx
|
||
import { useEffect } from "react";
|
||
import { useColorScheme } from "@mui/material/styles";
|
||
import { useTheme as useAppTheme } from "../../context/ThemeContext";
|
||
|
||
/**
|
||
* ThemeContext is the single owner of the `data-theme` attribute. This mirrors
|
||
* its value into MUI's JS color-scheme state so theme.applyStyles('dark') and
|
||
* useColorScheme().mode stay in sync with the attribute the CSS selector reads.
|
||
*/
|
||
export default function MuiColorSchemeSync() {
|
||
const { theme } = useAppTheme();
|
||
const { mode, setMode } = useColorScheme();
|
||
|
||
useEffect(() => {
|
||
if (mode !== theme) setMode(theme as "light" | "dark");
|
||
}, [theme, mode, setMode]);
|
||
|
||
return null;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Create the provider wrapper**
|
||
|
||
Create `src/admin/ui/MuiProvider.tsx`:
|
||
|
||
```tsx
|
||
import type { ReactNode } from "react";
|
||
import { ThemeProvider } from "@mui/material/styles";
|
||
import { theme } from "../theme";
|
||
import MuiColorSchemeSync from "./MuiColorSchemeSync";
|
||
|
||
export default function MuiProvider({ children }: { children: ReactNode }) {
|
||
return (
|
||
<ThemeProvider theme={theme} defaultMode="dark">
|
||
<MuiColorSchemeSync />
|
||
{children}
|
||
</ThemeProvider>
|
||
);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Mount the provider at the top of `AdminApp`**
|
||
|
||
In `src/admin/AdminApp.tsx`, add the import after the other component imports (e.g. after line 10):
|
||
|
||
```tsx
|
||
import MuiProvider from "./ui/MuiProvider";
|
||
```
|
||
|
||
Then wrap the existing returned tree. Change:
|
||
|
||
```tsx
|
||
return (
|
||
<AuthProvider>
|
||
```
|
||
|
||
to:
|
||
|
||
```tsx
|
||
return (
|
||
<MuiProvider>
|
||
<AuthProvider>
|
||
```
|
||
|
||
and change the matching closing tag at the end of the JSX:
|
||
|
||
```tsx
|
||
</AuthProvider>
|
||
);
|
||
```
|
||
|
||
to:
|
||
|
||
```tsx
|
||
</AuthProvider>
|
||
</MuiProvider>
|
||
);
|
||
```
|
||
|
||
- [ ] **Step 4: Verify the app builds and renders with no console errors**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx tsc -b --noEmit
|
||
npm run build:client
|
||
```
|
||
|
||
Expected: both succeed. (The user runs the dev server separately — do not start it. Verification of live render happens via the `/ui-kit` route in Task 6.)
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add src/admin/ui/MuiProvider.tsx src/admin/ui/MuiColorSchemeSync.tsx src/admin/AdminApp.tsx
|
||
git commit -m "feat(mui): mount MUI provider + sync color scheme to data-theme"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 5: First UI-kit wrappers + barrel
|
||
|
||
**Files:**
|
||
|
||
- Create: `src/admin/ui/Button.tsx`, `src/admin/ui/Card.tsx`, `src/admin/ui/TextField.tsx`, `src/admin/ui/index.ts`
|
||
|
||
- [ ] **Step 1: Create the wrappers**
|
||
|
||
Create `src/admin/ui/Button.tsx`:
|
||
|
||
```tsx
|
||
import MuiButton, { type ButtonProps } from "@mui/material/Button";
|
||
|
||
/** App Button: defaults to the brand primary contained style. */
|
||
export default function Button(props: ButtonProps) {
|
||
return <MuiButton variant="contained" color="primary" {...props} />;
|
||
}
|
||
```
|
||
|
||
Create `src/admin/ui/Card.tsx`:
|
||
|
||
```tsx
|
||
import MuiCard, { type CardProps } from "@mui/material/Card";
|
||
import CardContent from "@mui/material/CardContent";
|
||
|
||
export default function Card({ children, ...props }: CardProps) {
|
||
return (
|
||
<MuiCard {...props}>
|
||
<CardContent>{children}</CardContent>
|
||
</MuiCard>
|
||
);
|
||
}
|
||
```
|
||
|
||
Create `src/admin/ui/TextField.tsx`:
|
||
|
||
```tsx
|
||
import MuiTextField, { type TextFieldProps } from "@mui/material/TextField";
|
||
|
||
/** App TextField: small + outlined + full width by default. */
|
||
export default function TextField(props: TextFieldProps) {
|
||
return <MuiTextField size="small" variant="outlined" fullWidth {...props} />;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Create the barrel**
|
||
|
||
Create `src/admin/ui/index.ts`:
|
||
|
||
```ts
|
||
export { default as MuiProvider } from "./MuiProvider";
|
||
export { default as Button } from "./Button";
|
||
export { default as Card } from "./Card";
|
||
export { default as TextField } from "./TextField";
|
||
```
|
||
|
||
- [ ] **Step 3: Verify type-check**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx tsc -b --noEmit
|
||
```
|
||
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add src/admin/ui/Button.tsx src/admin/ui/Card.tsx src/admin/ui/TextField.tsx src/admin/ui/index.ts
|
||
git commit -m "feat(mui): first ui-kit wrappers (Button, Card, TextField) + barrel"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 6: Dev-only `/ui-kit` showcase route
|
||
|
||
**Files:**
|
||
|
||
- Create: `src/admin/pages/UiKit.tsx`
|
||
- Modify: `src/admin/AdminApp.tsx`
|
||
|
||
- [ ] **Step 1: Create the showcase page**
|
||
|
||
Create `src/admin/pages/UiKit.tsx`:
|
||
|
||
```tsx
|
||
import ScopedCssBaseline from "@mui/material/ScopedCssBaseline";
|
||
import Box from "@mui/material/Box";
|
||
import Stack from "@mui/material/Stack";
|
||
import Typography from "@mui/material/Typography";
|
||
import Chip from "@mui/material/Chip";
|
||
import { Button, Card, TextField } from "../ui";
|
||
import { useTheme } from "../../context/ThemeContext";
|
||
|
||
export default function UiKit() {
|
||
const { theme, toggleTheme } = useTheme();
|
||
return (
|
||
<ScopedCssBaseline>
|
||
<Box sx={{ p: 4, minHeight: "100vh", bgcolor: "background.default" }}>
|
||
<Stack direction="row" alignItems="center" spacing={2} mb={3}>
|
||
<Typography variant="h4">UI Kit</Typography>
|
||
<Button color="inherit" variant="outlined" onClick={toggleTheme}>
|
||
Theme: {theme}
|
||
</Button>
|
||
</Stack>
|
||
|
||
<Stack spacing={3} sx={{ maxWidth: 520 }}>
|
||
<Card>
|
||
<Typography variant="h6" gutterBottom>
|
||
Faktury
|
||
</Typography>
|
||
<Typography color="text.secondary" gutterBottom>
|
||
12 vystavených tento měsíc
|
||
</Typography>
|
||
<Stack direction="row" spacing={1} mb={2}>
|
||
<Chip label="Zaplaceno" color="success" size="small" />
|
||
<Chip label="Po splatnosti" color="error" size="small" />
|
||
</Stack>
|
||
<TextField
|
||
label="Hledat fakturu"
|
||
placeholder="Číslo nebo klient…"
|
||
/>
|
||
<Box mt={2}>
|
||
<Button>Nová faktura</Button>
|
||
</Box>
|
||
</Card>
|
||
</Stack>
|
||
</Box>
|
||
</ScopedCssBaseline>
|
||
);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Register the route, DEV-only**
|
||
|
||
In `src/admin/AdminApp.tsx`, add the lazy import alongside the other lazy pages (after line 11's eager imports / with the `lazy(...)` block):
|
||
|
||
```tsx
|
||
const UiKit = lazy(() => import("./pages/UiKit"));
|
||
```
|
||
|
||
Then, inside `<Routes>`, add a sibling route to `login` (so the showcase renders without the shell), guarded so it is dropped from production builds:
|
||
|
||
```tsx
|
||
{
|
||
import.meta.env.DEV && <Route path="ui-kit" element={<UiKit />} />;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Verify build (prod) excludes it and type-check passes**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx tsc -b --noEmit
|
||
npm run build:client
|
||
```
|
||
|
||
Expected: both succeed. `import.meta.env.DEV` is `false` in the production build, so the route is tree-shaken.
|
||
|
||
- [ ] **Step 4: Manual + Playwright verification**
|
||
|
||
The user runs the dev server. Once it's up, verify at `/ui-kit`:
|
||
|
||
- Card, button (red gradient, pill), chips (tinted), and text field render in the Soft-SaaS style.
|
||
- Clicking **Theme: dark/light** flips `data-theme` and **both MUI components AND the page background** swap — proving the `colorSchemeSelector` bridge works.
|
||
- No new console errors.
|
||
|
||
Capture baseline screenshots with the available Playwright tooling (light + dark) and save under `docs/superpowers/visual-baselines/phase-0-ui-kit-{light,dark}.png`.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add src/admin/pages/UiKit.tsx src/admin/AdminApp.tsx
|
||
git commit -m "feat(mui): dev-only /ui-kit showcase proving the theme + data-theme bridge"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 7: Token-level palette refresh (app-wide)
|
||
|
||
**Files:**
|
||
|
||
- Modify: `src/admin/variables.css`
|
||
|
||
Per spec §7, the token-level palette refresh is applied app-wide so migrated and legacy pages share the refreshed palette. The only token change for Phase 0 is the light canvas (the new look's `#f4f3f1` vs current `#f5f4f2`); chip/structure changes are component-level (MUI) and need no token edit.
|
||
|
||
- [ ] **Step 1: Update the light canvas token**
|
||
|
||
In `src/admin/variables.css`, inside the `[data-theme="light"]` block, change:
|
||
|
||
```css
|
||
--bg-primary: #f5f4f2;
|
||
```
|
||
|
||
to:
|
||
|
||
```css
|
||
--bg-primary: #f4f3f1;
|
||
```
|
||
|
||
- [ ] **Step 2: Verify build**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npm run build:client
|
||
```
|
||
|
||
Expected: succeeds.
|
||
|
||
- [ ] **Step 3: Manual check**
|
||
|
||
With the dev server (user-run), confirm in light mode the app canvas is the refreshed `#f4f3f1` and nothing else shifted structurally. (This is the deliberate, minor app-wide color change noted in the spec — not a no-op.)
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add src/admin/variables.css
|
||
git commit -m "style(tokens): refresh light canvas to #f4f3f1 (two-layer refresh, token level)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 8: Phase-0 release verification
|
||
|
||
**Files:** none (verification + tag)
|
||
|
||
- [ ] **Step 1: Full type-check, unit tests, and build**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx tsc -b --noEmit
|
||
npx vitest run src/admin/theme.test.ts
|
||
npm run build
|
||
```
|
||
|
||
Expected: `tsc` clean; 6 theme tests pass; server + client build succeed.
|
||
|
||
- [ ] **Step 2: Backend test suite still green (server untouched)**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npm test
|
||
```
|
||
|
||
Expected: existing `auth` + `numbering` suites pass (Phase 0 changed no server code).
|
||
|
||
- [ ] **Step 3: Definition-of-done checklist (manual, dev server)**
|
||
|
||
- `/ui-kit` renders Button/Card/TextField/Chip in the Soft-SaaS style in **both** themes.
|
||
- Theme toggle flips `data-theme` and swaps MUI + legacy colors together; MUI's `useColorScheme().mode` matches (no console warnings).
|
||
- No new console errors on any existing page (the provider mount + token refresh are non-breaking).
|
||
- Light canvas is `#f4f3f1`.
|
||
- Production build excludes the `/ui-kit` route.
|
||
|
||
- [ ] **Step 4: Tag/release per the project release process**
|
||
|
||
Follow `CLAUDE.md` "Release Process" (bump `package.json`, build, tag, deploy) when shipping Phase 0. No Prisma migration is involved (frontend-only).
|
||
|
||
---
|
||
|
||
## Self-review notes (for the controller)
|
||
|
||
- **Spec coverage:** Phase 0 items from spec §8 are all covered — deps + `@types/react` (Task 1), `theme.ts` light/dark (Tasks 2–3), provider + `ScopedCssBaseline` + `ThemeContext`↔`setMode` sync (Tasks 4, 6), dev-only `/ui-kit` (Task 6), token-level refresh (Task 7). The full `ui/` kit, AppShell, and Vozidla are explicitly deferred to later plans (scope note).
|
||
- **Type consistency:** `theme` (named export) is used consistently in `theme.test.ts`, `MuiProvider.tsx`. `useTheme` refers to the app's `ThemeContext` (aliased `useAppTheme` in the sync component to avoid colliding with MUI's `useTheme`). Wrappers are default exports re-exported via the barrel.
|
||
- **Open risk to verify in Task 1/6:** exact MUI v7 API for `cssVariables.colorSchemeSelector` + `ThemeProvider` `defaultMode` — confirm against the installed version's docs; if `defaultMode` belongs on a different provider in the installed version, adjust in Task 4.
|