arfan
refactor-css-plan.md

Refactor CSS to Tailwind CSS + Daisy UI

Goal

Replace existing custom CSS in src/ and styles/ with Tailwind CSS and Daisy UI components, in incremental steps with tests after each.

Steps

Step 1: CDN Setup

Tasks:

  • No installation required.
  • In head.ts head, add: 
    <link href="https://cdn.jsdelivr.net/npm/daisyui@5" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<link href="https://cdn.jsdelivr.net/npm/daisyui@5/themes.css" rel="stylesheet" type="text/css" />

Stop and test: Reload the app, add a Daisy UI class (e.g. btn) to a component, verify the style applies.

Step 2: Remove Global CSS Resets

Tasks:

  • Locate any global resets (e.g. reset.css) in styles/.
  • Create a new file styles/daisy-ui.css.
  • Move necessary reset rules into daisy-ui.css under Tailwind’s @layer base.
  • Comment out or remove old import statements for resets in src/index.tsx or App.tsx.
  • Import styles/daisy-ui.css in the main CSS entry (e.g., index.css).

Stop and test: Confirm global styles (default fonts, margins) remain appropriate.

Step 3: Consolidate CSS Imports

Tasks:

  • Add @import statements in styles/index.css for each CSS file (markdown.css, callout.css, blockquote.css, accordion.css, tabs.css, tables.css, etc.) so they remain separate but are included via index.css.
  • Update head.ts to only include a single <link> for index.css.
  • Update config.ts to reference only cssUrl for index.css.
  • Remove individual stylesheet links in buildHead.

Stop and test: Reload the app and verify all styles apply correctly with only index.css.

Step 3.5: Refactor Template Structure

Tasks:

  • Refactor HTML in src/handlers.ts to wrap layout elements (toggle button, sidebar, main content, toc-sidebar) in a common layout wrapper for easier styling.
  • Extract sidebar toggle and sidebar container into a separate component or partial.
  • Ensure IDs and classNames remain unchanged after refactoring. Stop and test: Confirm layout renders identically after refactor.

Step 4: Migrate Component Styles

Tasks:

  • Inventory components using custom CSS classes (search className=" in src/).
  • Components to migrate:
    • Callouts (callout, callout-info, callout-warning, callout-error, callout-tip, callout-note)
    • Error messages (error-message)
    • Sidebar toggle (sidebar-toggle)
    • Sidebar container (sidebar)
    • Main content container (main-content, content-container)
    • Table of contents sidebar (toc-sidebar)
    • Navigation menu (doc-nav, active)
  • For each component:
    • Replace class names with Tailwind/Daisy UI classes.
    • Remove related CSS rules from styles/.

Stop and test: Verify component layout and styles.

Step 5: Apply Daisy UI Components

Tasks:

  • Identify common UI patterns (buttons, cards, forms).
  • Replace with Daisy UI prebuilt classes (e.g. btn, card).

Stop and test: Check visual consistency and responsiveness.

Step 6: Refactor Layout & Utilities

Tasks:

  • Replace custom grid/flex layouts with Tailwind utilities.
  • Update margins, paddings to use utility classes.

Stop and test: Validate page layouts across breakpoints.

Step 7: Clean Up

Tasks:

  • Delete unused CSS files in styles/.
  • Remove obsolete imports in code.
  • Run production build to confirm no CSS errors.

Stop and test: Build succeeds, UI unchanged.

Proceed one step at a time and pause after each for testing.