Making styles more standard and documenting it

Documentation/index.md

@@ -23,6 +23,18 @@ This library includes specialized components for:
 
 ## Getting Started
 
+### Importing Styles
+
+The library ships pre-compiled utility styles that must be imported once in your application entry point (e.g. `main.tsx`):
+
+```typescript
+import '@cratis/components/styles';
+```
+
+This is required because the components use Tailwind utility classes that are compiled into the package at build time. Without this import the layout, spacing, and sizing of components will not render correctly. The import works with any bundler (Vite, webpack, Rollup) regardless of whether your application uses Tailwind.
+
+### Importing Components
+
 All components are exported from the main package and can be imported as needed:
 
 ```typescript

Source/package.json

@@ -84,7 +84,7 @@
             "require": "./dist/cjs/Toolbar/index.js",
             "import": "./dist/esm/Toolbar/index.js"
         },
-        "./styles": "./dist/styles.css"
+        "./styles": "./dist/esm/tailwind-utilities.css"
     },
     "scripts": {
         "prepare": "yarn g:build",

Source/scripts/copy-css.sh

@@ -9,7 +9,8 @@ find . -name '*.css' \
   -not -path './node_modules/*' \
   -not -path './dist/*' \
   -not -path './.storybook/*' \
-  -not -name 'tailwind.css' | while read -r file; do
+  -not -name 'tailwind.css' \
+  -not -name 'tailwind-utilities.css' | while read -r file; do
 
   # Remove the leading './'
   relative_path="${file#./}"

rollup.config.mjs

@@ -9,15 +9,21 @@ import { dirname, join, resolve } from 'path';
 
 /**
  * Rollup plugin that compiles the Tailwind entry CSS through PostCSS after the
- * bundle is written, producing a self-contained dist/styles.css that consumers
- * can import once to get all utility classes used by the components.
+ * bundle is written, producing a self-contained tailwind-utilities.css written
+ * into both the ESM and CJS output directories.
+ *
+ * Because Rollup's external rule preserves CSS imports verbatim in the output
+ * JS, the `import './tailwind-utilities.css'` added to index.ts will be kept
+ * in dist/esm/index.js and dist/cjs/index.js.  Vite (or any bundler) in the
+ * consuming app then finds the CSS file sitting next to the JS and injects it
+ * automatically — no manual import required in the consumer app.
  *
  * Without this step the utility classes (e.g. p-2, gap-1, w-10 …) only exist
  * in the package's source JSX and would never be generated by the consuming
  * app's own Tailwind build, because node_modules is typically excluded from
  * content scanning.
  */
-function compileTailwind(sourceDir, distDir) {
+function compileTailwind(sourceDir, cjsPath, esmPath) {
     let hasRun = false;
     return {
         name: 'compile-tailwind',
@@ -26,21 +32,23 @@ function compileTailwind(sourceDir, distDir) {
             hasRun = true;
 
             const inputFile = resolve(sourceDir, 'tailwind.css');
-            const outputFile = resolve(distDir, 'styles.css');
 
             const { default: postcss } = await import('postcss');
             const { default: tailwindcss } = await import('@tailwindcss/postcss');
             const { default: autoprefixer } = await import('autoprefixer');
 
             const css = readFileSync(inputFile, 'utf8');
-            const result = await postcss([tailwindcss({ base: sourceDir }), autoprefixer]).process(css, {
-                from: inputFile,
-                to: outputFile,
-            });
 
-            mkdirSync(dirname(outputFile), { recursive: true });
-            writeFileSync(outputFile, result.css);
-            console.log('✓ Compiled Tailwind utilities → dist/styles.css');
+            for (const outputDir of [cjsPath, esmPath]) {
+                const outputFile = resolve(outputDir, 'tailwind-utilities.css');
+                const result = await postcss([tailwindcss({ base: sourceDir }), autoprefixer]).process(css, {
+                    from: inputFile,
+                    to: outputFile,
+                });
+                mkdirSync(dirname(outputFile), { recursive: true });
+                writeFileSync(outputFile, result.css);
+            }
+            console.log('✓ Compiled Tailwind utilities → dist/{cjs,esm}/tailwind-utilities.css');
         },
     };
 }
@@ -78,7 +86,6 @@ function generatePackageJson(cjsPath, esmPath) {
 
 export function rollup(cjsPath, esmPath, tsconfigPath, pkg) {
     const sourceDir = dirname(tsconfigPath);
-    const distDir = resolve(sourceDir, 'dist');
     return {
         input: "index.ts",
 
@@ -130,7 +137,7 @@ export function rollup(cjsPath, esmPath, tsconfigPath, pkg) {
                 }
             }),
             generatePackageJson(cjsPath, esmPath),
-            compileTailwind(sourceDir, distDir),
+            compileTailwind(sourceDir, cjsPath, esmPath),
         ]
     };
 }