Tailwind CSS Component Integration Protocol

Version: 1.0
Date: October 12, 2025
Status: MANDATORY FOR ALL COMPONENT WORK

---

Executive Summary

This protocol defines the exact, tested procedure for integrating third-party Tailwind CSS components (Pagedone, Meraki UI, etc.) into our Nx monorepo. This procedure has been validated to work with both Storybook and production apps.

Critical Finding: The issue was never about Tailwind versions. Both Pagedone and Meraki UI work with any modern Tailwind CSS version because they use standard utility classes. The problem was monorepo configuration.

---

Required Versions (Per Repository Policy)

All versions must comply with the pre-October 2024 dependency policy defined in /README.md:

{
  "tailwindcss": "3.4.10",
  "postcss": "8.4.47",
  "autoprefixer": "10.4.20"
}

Rationale: Tailwind v3.4.10 was the last stable release before October 2024, ensuring full GitHub Copilot compatibility.

---

Component Library Requirements

Pagedone

• Version: Any (uses standard Tailwind classes)
• Installation: npm install pagedone (optional - we extract HTML/CSS directly)
• Tailwind Requirement: Standard Tailwind CSS (no specific version)
• Documentation: https://pagedone.io/docs/installation

Meraki UI

• Version: Free (open-source components)
• Installation: Copy-paste HTML (no package installation)
• Tailwind Requirement: Standard Tailwind CSS (works with CDN or installed)
• Documentation: https://merakiui.com/
• GitHub: https://github.com/merakiuilabs/merakiui

Key Insight: Neither library requires special Tailwind versions. They use standard utility classes that work across Tailwind v2, v3, and v4.

---

Monorepo Structure

cloudalt-frontend/
├── packages/
│   ├── ui-web/              # Generic components (cross-brand)
│   ├── ui-{brand}/          # Brand-specific components
│   ├── config/
│   │   └── tailwind-preset.js  # Shared Tailwind configuration
│   └── storybook/           # Component development workspace
│       ├── .storybook/
│       │   ├── main.ts
│       │   └── preview.ts
│       ├── postcss.config.js
│       ├── tailwind.config.js
│       └── styles/tailwind.css
└── apps/
    └── {brand}/{app}/web/
        ├── postcss.config.js
        ├── tailwind.config.js
        └── styles/tailwind.css

---

STEP-BY-STEP INTEGRATION PROCEDURE

Phase 1: Obtain Component Code

1. Navigate to component library (Pagedone or Meraki UI)
2. Find desired component and copy the HTML
3. DO NOT modify class names or structure yet
4. Save HTML to a temporary file for reference

Phase 2: Create React Component

Location: packages/ui-web/src/components/{ComponentName}/

ComponentName.tsx

import React, { useState } from 'react';

export interface ComponentNameProps {
  // Define props based on component requirements
}

export const ComponentName: React.FC<ComponentNameProps> = ({
  // Props
}) => {
  // Convert HTML to JSX
  // Keep ALL Tailwind classes exactly as provided
  return (
    <section className="...">
      {/* Component JSX */}
    </section>
  );
};

export default ComponentName;

Critical Rules:

• ✅ Keep Tailwind classes exactly as provided by Pagedone/Meraki UI
• ✅ Convert HTML attributes to JSX (class → className, for → htmlFor)
• ✅ Add TypeScript types for props
• ❌ DO NOT modify or “improve” Tailwind classes
• ❌ DO NOT add custom CSS

Export Component:

index.ts

export { ComponentName } from './ComponentName';
export type { ComponentNameProps } from './ComponentName';

Update Package Index:

packages/ui-web/src/index.ts

export { ComponentName } from './components/ComponentName';
export type { ComponentNameProps } from './components/ComponentName';

Phase 3: Create Storybook Story

Location: packages/storybook/stories/{ComponentName}.stories.tsx

import type { Meta, StoryObj } from '@storybook/react';
import { ComponentName } from '@cloudalt-frontend/ui-web';

const meta: Meta<typeof ComponentName> = {
  title: 'Components/ComponentName',
  component: ComponentName,
  tags: ['autodocs'],
};

export default meta;
type Story = StoryObj<typeof ComponentName>;

export const Default: Story = {
  args: {
    // Add default props
  },
};

Phase 4: Verify in Storybook

yarn storybook

Navigate to http://localhost:6006/ and verify:

• ✅ Component renders correctly
• ✅ All styles apply properly
• ✅ Interactive elements work
• ✅ Responsive design works
• ✅ Dark mode works (if applicable)

If component doesn’t render correctly:

1. Check browser console for errors
2. Verify Tailwind config scans the correct paths
3. Confirm component is exported from ui-web

Phase 5: Configure Web App

Required Files for Each Web App:

1. PostCSS Configuration

// apps/{brand}/{app}/web/postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

2. Tailwind Configuration

// apps/{brand}/{app}/web/tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [require('../../../../packages/config/tailwind-preset.js')],
  content: [
    './index.html',
    './src/**/*.{js,jsx,ts,tsx}',
    '../../../../packages/ui-web/src/**/*.{js,jsx,ts,tsx}',
    '../../../../packages/ui-{brand}/src/**/*.{js,jsx,ts,tsx}',
  ],
};

Critical: Content paths MUST include:

• App’s own source files
• packages/ui-web (generic components)
• Brand-specific UI package

3. CSS Entry Point

/* apps/{brand}/{app}/web/styles/tailwind.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  html, body {
    margin: 0;
    padding: 0;
    font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  }
}

4. Import CSS in App

// apps/{brand}/{app}/web/src/main.tsx
import '../styles/tailwind.css';

5. Vite Configuration

// apps/{brand}/{app}/web/vite.config.ts
export default defineConfig(() => ({
  // ... other config
  css: {
    postcss: './postcss.config.js',
  },
  // ... other config
}));

Phase 6: Use Component in App

// apps/{brand}/{app}/web/src/app/app.tsx
import { ComponentName } from '@cloudalt-frontend/ui-web';

export function App() {
  return (
    <div>
      <ComponentName {...props} />
    </div>
  );
}

Phase 7: Verify in App

yarn nx run {app}:serve

Navigate to http://localhost:4200/ and verify:

• ✅ Component renders identically to Storybook
• ✅ All styles apply
• ✅ Responsive design works
• ✅ No console errors

---

Troubleshooting Guide

Problem: Component renders but has no styling

Root Cause: Tailwind not scanning the component’s source files.

Solution:

1. Check tailwind.config.js content paths
2. Ensure paths use correct relative paths (e.g., ../../../../packages/ui-web/src/**/*.{js,jsx,ts,tsx})
3. Restart dev server after config changes

Problem: Component works in Storybook but not in app

Root Cause: App’s Tailwind config doesn’t match Storybook’s.

Solution:

1. Compare content arrays in both configs
2. Ensure app scans all necessary package paths
3. Verify PostCSS is configured correctly

Problem: Some Tailwind classes work, others don’t

Root Cause: Class name conflicts or purging issues.

Solution:

1. Check if using v3 or v4 syntax (don’t mix)
2. Verify no custom CSS overriding Tailwind
3. Clear build cache: rm -rf node_modules/.vite

Problem: Tailwind version errors

Root Cause: Attempting to use Tailwind v4 features with v3.

Solution:

1. Stick to v3.4.10 per repository policy
2. Avoid v4-specific syntax (@import "tailwindcss", @source)
3. Use v3 syntax (@tailwind base, @tailwind components, @tailwind utilities)

---

Asset Management

Local Images

If component uses images:

1. Store in: packages/assets/{category}/{component-name}/
2. Copy to app public folder: apps/{brand}/{app}/web/public/images/
3. Reference in component: /images/{filename}

CDN Images

Components from Pagedone/Meraki often use CDN URLs - these work as-is.

---

Testing Checklist

Before considering integration complete:

• Component renders in Storybook
• All interactive features work in Storybook
• Component renders identically in target app
• Responsive design works (test mobile, tablet, desktop)
• Dark mode works (if applicable)
• No console errors or warnings
• TypeScript types are correct
• Component is exported from package index
• Story is documented with controls
• Assets are properly referenced

---

Common Mistakes to Avoid

1. ❌ Modifying Tailwind classes from original component
2. ❌ Forgetting to add package to Tailwind content paths
3. ❌ Using relative imports instead of package aliases
4. ❌ Not restarting dev server after config changes
5. ❌ Mixing Tailwind v3 and v4 syntax
6. ❌ Installing incompatible Tailwind versions
7. ❌ Not testing in both Storybook and app

---

Version Compatibility Matrix

Tool/Library	Required Version	Rationale
Tailwind CSS	3.4.10	Last pre-Oct 2024 release
PostCSS	8.4.47	Compatible with Tailwind 3.4.10
Autoprefixer	10.4.20	Compatible with PostCSS 8.4.47
Pagedone	Any	Uses standard Tailwind classes
Meraki UI	Latest	Uses standard Tailwind classes
Storybook	8.6.14	Current repo version
React	18.3.1	Current repo version

---

Emergency Recovery

If Tailwind setup is completely broken:

# 1. Remove all Tailwind-related packages
yarn remove tailwindcss postcss autoprefixer @tailwindcss/postcss @tailwindcss/vite @tailwindcss/cli

# 2. Reinstall correct versions
yarn add -D tailwindcss@3.4.10 postcss@8.4.47 autoprefixer@10.4.20

# 3. Verify all configs use v3 syntax
# Check: @tailwind directives (not @import "tailwindcss")
# Check: tailwind.config.js exists (not using @source)

# 4. Clear caches
rm -rf node_modules/.vite
rm -rf dist

# 5. Restart everything
yarn nx reset
yarn install

---

Maintenance

Review Frequency: Quarterly or when major Tailwind versions release

Update Procedure:

1. Check if new Tailwind version is pre-October 2024 compatible
2. Test in isolated branch
3. Verify all existing components still work
4. Update this document if procedures change

---

References

• Tailwind CSS v3 Documentation
• Pagedone Documentation
• Meraki UI Components
• Nx Monorepo Guide
• Repository README - Dependency Policy

---

Last Updated: October 12, 2025
Next Review: January 2026
Protocol Owner: Development Team