Web Components – Tailwind Theme Integration

Automated Tailwind Theme Export

This project provides a design system and a set of custom Tailwind utilities (such as text-h1, text-h2, custom colors, etc.) that can be used both internally and in external projects. To ensure all custom utilities are available, the theme is defined in TypeScript and automatically exported to a CommonJS JavaScript file for Tailwind consumption.

How It Works

• The source of truth for the theme is src/tokens/theme.ts (TypeScript).
• A build script (scripts/build-theme.js) generates a CommonJS-compatible theme.js in the project root.
• The generated theme.js is imported in your tailwind.config.js to provide all custom utilities to Tailwind.

Usage in This Project

1. Edit your theme in TypeScript:
   • Make changes in src/tokens/theme.ts.
2. Generate the JS theme:
   • Run:

     npm run build:theme

   • This will create/update theme.js in the root directory.
3. Tailwind config setup:
   • Your tailwind.config.js should look like this:

     const { theme } = require('./theme');
     module.exports = {
       content: ['./src/**/*.{js,ts,jsx,tsx}'],
       theme: {
         extend: theme
       },
       plugins: [],
     };

Usage in External Projects (Consumers)

If you want to use these custom utilities in another project:

1. Install this package as a dependency.
2. Import the generated theme in your Tailwind config:

   const { theme } = require('web-components/theme');
   module.exports = {
     content: [
       './src/**/*.{js,ts,jsx,tsx}',
       './node_modules/web-components/**/*.{js,ts,jsx,tsx}'
     ],
     theme: {
       extend: theme
     },
     plugins: [],
   };

3. Ensure the theme is up to date:
   • If you update the package or its theme, run:

     npm run build:theme

   • (If you use a monorepo, you may want to automate this step in your build pipeline.)

Recommendations

• Always run npm run build:theme after changing the theme in TypeScript.
• Add the build step to your CI/CD pipeline to avoid mismatches between TS and JS theme files.
• Document for consumers that they must use the generated theme.js for full utility support (including custom font sizes like text-h1).
• If you publish this package, ensure theme.js is included in the published files (not gitignored or npmignored).

Troubleshooting

• If custom utilities like text-h1 do not work, ensure:
  • The consumer project is importing the correct theme.js.
  • The build script has been run after any theme changes.
  • The content array in tailwind.config.js includes the package source files.

For questions or improvements, please open an issue or PR!