tailwind2-5  Exercise 2: @apply in Component Styles and @reference
===================================================================

Setup: a folder with these files, then   npm install vue vite @vitejs/plugin-vue @tailwindcss/vite tailwindcss   and run  npx vite build  after each change to src/App.vue. Measure the CSS file in dist/assets.

--- package.json ---
{"name":"vue-demo","private":true,"type":"module","dependencies":{"@tailwindcss/vite":"^4.3.3","@vitejs/plugin-vue":"^6.0.10","tailwindcss":"^4.3.3","vite":"^8.3.4","vue":"^3.5.43"}}

--- vite.config.js ---
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [vue(), tailwindcss()] });

--- index.html ---
<!doctype html><html lang="en"><body><div id="app"></div><script type="module" src="/src/main.js"></script></body></html>

--- src/main.js ---
import { createApp } from 'vue';
import App from './App.vue';
import './style.css';
createApp(App).mount('#app');

--- src/style.css ---
@import "tailwindcss";
@theme { --color-brand: oklch(0.55 0.2 260); }

--- src/App.vue, version 1: @apply with nothing else ---
<template><button class="btn text-lg">Save</button></template>
<style scoped>
.btn { @apply bg-brand text-white px-4 py-2; }
</style>

--- version 2: add  @reference "./style.css";  as the first line of the style block ---
--- version 3: @import "tailwindcss"; and the @theme block, inside the component's style block ---
--- version 4: no @apply, theme variables as plain CSS:  .btn { background: var(--color-brand); color: white; padding: calc(var(--spacing) * 2) calc(var(--spacing) * 4); } ---
--- version 5: no style block; the template uses the utility classes:  <button class="bg-brand text-white px-4 py-2 text-lg">Save</button> ---

Results:

version 1   exit code 1
            Error: Cannot apply unknown utility class `bg-brand`. Are you using CSS modules or similar and missing `@reference`?
version 2   exit 0   CSS 4,755 bytes
            .btn[data-v-85b66921]{background-color:var(--color-brand,oklch(55% .2 260));padding-inline:calc(var(--spacing,.25rem) * 4);padding-block:calc(var(--spacing,.25rem) * 2);color:var(--color-white,#fff)}
version 3   exit 0   CSS 10,054 bytes   (the reset rules, box-sizing:border-box, appear 4 times instead of 2)
version 4   exit 0   CSS 4,463 bytes
version 5   exit 0   CSS 4,601 bytes

The same error, and the same fix, applied to a CSS module in a plain Vite project: a file containing  .btn { @apply bg-brand px-4 py-2 text-white; }  failed with the same message, and with
@reference "./style.css";  added it built and produced  ._btn_16twv_2{background-color:var(--color-brand,oklch(55% .2 260));...}

WHY THIS WORKS AS AN ANSWER
---------------------------
A component style block is processed as a separate stylesheet, so it does not know your theme or your utilities; @apply bg-brand fails because "bg-brand" does not exist in that stylesheet. @reference
"./style.css" imports your main file for reference only: the theme and utilities become available to @apply, but none of their CSS is written into the component's output, which is why version 2 is
only 292 bytes bigger than the page with no component style at all (4,755 against 4,463). The path is relative to the component file; my first attempt used "../style.css" from a file that was already in
src/ and failed with "Can't resolve". Version 3 shows the expensive alternative: importing all of Tailwind into the component repeats the reset and the theme, so the CSS is more than double (10,054 bytes) and
grows with every component. Version 4 shows that @apply is not always needed: the theme variables (--color-brand, --spacing) are ordinary CSS variables on :root and work in any component style with no
@reference at all. Version 5 is the recommended default: use the utility classes in the template and keep component style blocks for the few things utilities cannot express.