frontend-html-to-react-integration

name	Frontend HTML to React Integration
description	Standard operating procedure and best practices for converting raw HTML/Tailwind mockup files into modular React pages within the Maple Tools project.

Frontend HTML to React Integration

This skill documents the systematic approach to translating a static HTML mockup (usually containing raw Tailwind CSS) into a fully functional and integrated React page in the Maple Tools (SoraIndex) ecosystem.

1. Anatomy of the Mockup

Before writing code, analyze the provided .html file:

• Discard Global Elements: The mockup often contains navigation bars (SideNavBar / TopNavBar). Identify these and ignore them, as the main app layout (Sidebar.tsx, App.tsx) already handles global navigation.
• Identify State Boundaries: Look for inline onclick handlers, modals, or tab switching. These will need to be translated into useState hooks.

2. Component Creation

Create a new TypeScript React file (e.g., src/renderer/src/pages/[PageName].tsx).

• Copy the core <main> or content wrapper from the HTML.
• Convert class to className.
• Ensure self-closing tags (e.g., <input />, <img />, <br />) are properly closed to satisfy JSX syntax rules.
• Replace generic onclick="document.getElementById(...).classList.add(...)" with React state logic (onClick={() => setIsOpen(true)}).

3. Style and Token Adaptation (Crucial)

The project relies heavily on the Daybreak Core design system (Light/Dark mode tokens). Mockups may contain hardcoded specific colors or non-standard utility classes (like bg-neutral-900 or text-rose-300).

Map them to Project Semantic CSS Variables:

• Backgrounds: Use bg-background for the main canvas. Use bg-surface-container, bg-surface-container-low, bg-surface-container-highest for cards and modals.
• Text: Use text-on-surface for primary text and headings. Use text-on-surface-variant for secondary readouts, subtitles, or metadata.
• Brand/Accent: Replace arbitrary pink/red styling with text-primary, bg-primary, shadow-primary/20.
• Borders/Dividers: Use border-outline-variant/30 or bg-outline-variant/30 rather than border-white/10.

4. Reusing Shared Components

Do not reinvent the wheel if the mockup introduces a repeating UI pattern:

• Search and Top Bar: If the page features a top search bar, do not code a custom input field. Import the shared <TopBar /> component from src/components/TopBar.tsx. Mount it at the top of the new page and supply it with placeholder and onSearch props.
• Let the shared component handle common logic (e.g., "Enter" keypress handling, theme toggling, quick stats).

5. Integrating Layout and Overlays

• Positioning: The global layout inside App.tsx has a left margin for the sidebar (ml-64) and acts as a scroll container. Your new page should generally be wrapped in a <div className="relative min-h-full bg-background">.
• TopBar Spacer: Because the TopBar component is fixed top-0 and visually occupies h-16, add pt-16 or pt-24 padding to the top of your page wrapper to prevent content from hiding beneath the header.

6. Routing Hookup

• Add the component import and the <Route /> definition in src/renderer/src/App.tsx.
• Open src/renderer/src/components/Sidebar.tsx and append a new NavItem to the navItems array to expose the page in the app menu. Order the items according to user requirement (e.g., move it to "/" to make it the designated home page).