@umoa/saascfm-css 0.1.1 → 0.2.0

package/README.md

@@ -8,12 +8,12 @@ Vite plugin that scans your source and generates only the utility classes you us
 npm i -D @umoa/saascfm-css
 ```
 
-Works with TypeScript or plain JavaScript. Use `vite.config.js`, the `js` template and `main.js` if you are not on TypeScript. The package ships ESM and CommonJS, so it loads whether or not your `package.json` has `"type": "module"`.
+Works with TypeScript or plain JavaScript. If you are not on TypeScript, use `vite.config.js`, the `js` template (import it with `.js`) and `main.js`, and set `"type": "module"` in your `package.json`. The package ships ESM and CommonJS, so it loads whether or not your `package.json` has `"type": "module"`.
 
 ```js
 // vite.config.js (or .ts)
 import cssModule from '@umoa/saascfm-css'
-import * as colors from './src/saascfm-css/_component.tokens'
+import * as colors from './src/saascfm-css/_component.tokens.ts'
 
 export default defineConfig({
   plugins: [cssModule({ colorsModule: colors })],
@@ -36,6 +36,7 @@ TypeScript only: add `"types": ["@umoa/saascfm-css/client"]` to `tsconfig.json`.
 | `spacing` `layout` `typography` `cursor` `border` | `true` | turn a module off with `false` |
 | `colorsModule` | none | your `PRIMITIVES` and `TOKENS` |
 | `primitiveClasses` | `true` | `false` removes the `blue-500` / `bg-blue-500` classes |
+| `primitiveVars` | `false` | `true` also writes every primitive as a CSS variable on `:root` (`--brand-500`), so `var(--brand-500)` works in your own CSS |
 | `important` | `false` | `true` adds `!important` to every generated declaration |
 | `exclude` | `[".colors.", ".tokens.", "primitives."]` | file paths containing these are not scanned, so your color definitions do not generate every class |
 
@@ -64,10 +65,10 @@ src/saascfm-css/
   RULES.md                 how the folder works, adding tokens, migrating
 ```
 
-Then point the plugin at it:
+Then point the plugin at it. Use the file extension (`.ts` or `.js`); Vite 8's native config loader requires it. In TypeScript projects, `allowImportingTsExtensions` must be enabled in the `tsconfig` that covers `vite.config.ts`.
 
 ```ts
-import * as colors from './src/saascfm-css/_component.tokens'
+import * as colors from './src/saascfm-css/_component.tokens.ts'
 
 plugins: [cssModule({ colorsModule: colors })]
 ```
@@ -88,6 +89,7 @@ export const TOKENS = { 'text-brand': 'brand-500', 'bg-card': 'white' }
 - `PRIMITIVES`: name → color. Each generates `name` (color), `bg-name`, `border-name`. `rgba`/`hsla` values generate the color class only.
 - `TOKENS`: name → primitive name, or any CSS color. Each becomes `--name` on `:root`.
 - Token names are yours. The first word decides the class: `text-*` → `color`, `bg-*` → `background-color`, `border-*` → `border-color`. Any other prefix (`nav-*`, `tabb-*`, `shadow-*`) is a CSS var only.
+- Primitives are classes only by default. Set `primitiveVars: true` to also get a variable for each one (`--brand-500`). You do not need to spread `PRIMITIVES` into `TOKENS` for this. A token with the same name overrides the primitive's variable.
 - Unknown primitive names print a warning and are skipped.
 - `hl`, `hl-muted`, `vl` read `--border-default` / `--border-muted`, falling back to `currentColor`.
 

package/dist/index.cjs

@@ -369,11 +369,10 @@ function cssModule(options = {}) {
   const primitives = colorsModule["PRIMITIVES"];
   const useColor = !!(tokens || primitives);
   if (useColor) {
-    if (tokens) {
-      const resolved = resolveTokens(tokens, primitives ?? {});
-      COLOR_ROOT_VARS = generateRootVars(resolved);
-      COLOR_RULES = buildColorUtilityRules(resolved);
-    }
+    const resolved = tokens ? resolveTokens(tokens, primitives ?? {}) : {};
+    const rootVars = { ...options.primitiveVars && primitives ? primitives : {}, ...resolved };
+    if (Object.keys(rootVars).length) COLOR_ROOT_VARS = generateRootVars(rootVars);
+    COLOR_RULES = buildColorUtilityRules(resolved);
     if (primitives && options.primitiveClasses !== false) {
       PRIMITIVE_COLOR_RULES = buildPrimitiveRules(primitives);
     }

package/dist/index.d.cts

@@ -10,6 +10,7 @@ interface CssModuleOptions {
     border?: boolean;
     colorsModule?: Record<string, unknown>;
     primitiveClasses?: boolean;
+    primitiveVars?: boolean;
     exclude?: string[];
     important?: boolean;
 }

package/dist/index.d.ts

@@ -10,6 +10,7 @@ interface CssModuleOptions {
     border?: boolean;
     colorsModule?: Record<string, unknown>;
     primitiveClasses?: boolean;
+    primitiveVars?: boolean;
     exclude?: string[];
     important?: boolean;
 }

package/dist/index.js

@@ -335,11 +335,10 @@ function cssModule(options = {}) {
   const primitives = colorsModule["PRIMITIVES"];
   const useColor = !!(tokens || primitives);
   if (useColor) {
-    if (tokens) {
-      const resolved = resolveTokens(tokens, primitives ?? {});
-      COLOR_ROOT_VARS = generateRootVars(resolved);
-      COLOR_RULES = buildColorUtilityRules(resolved);
-    }
+    const resolved = tokens ? resolveTokens(tokens, primitives ?? {}) : {};
+    const rootVars = { ...options.primitiveVars && primitives ? primitives : {}, ...resolved };
+    if (Object.keys(rootVars).length) COLOR_ROOT_VARS = generateRootVars(rootVars);
+    COLOR_RULES = buildColorUtilityRules(resolved);
     if (primitives && options.primitiveClasses !== false) {
       PRIMITIVE_COLOR_RULES = buildPrimitiveRules(primitives);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umoa/saascfm-css",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "SaaSCFM scan-and-generate utility CSS for Vite: w-54, mt-12, g-8, text-primary.",
   "type": "module",
   "main": "./dist/index.cjs",

package/templates/js/saascfm-css/RULES.md

@@ -19,7 +19,7 @@ The folder belongs to your app. The plugin never imports it by path; you pass `_
 
 ```ts
 import cssModule from '@umoa/saascfm-css'
-import * as colors from './src/saascfm-css/_component.tokens'
+import * as colors from './src/saascfm-css/_component.tokens.js'
 
 plugins: [cssModule({ colorsModule: colors })]
 ```
@@ -72,6 +72,8 @@ Each token becomes a CSS variable on `:root`. The first word of the name decides
 </style>
 ```
 
+Primitives are classes only. To also get a CSS variable for every primitive (`var(--brand-500)`), set `primitiveVars: true` in the plugin options. No change to the token files is needed.
+
 A token value can be a primitive (`P['neutral-900']`), a primitive name as a string (`'neutral-900'`), or any CSS color or value (`'#fff'`, `'rgba(0,0,0,.4)'`, `'56px'`). A string that looks like a primitive name but doesn't exist prints a warning and is skipped.
 
 ### When to use which
@@ -89,7 +91,7 @@ A token value can be a primitive (`P['neutral-900']`), a primitive name as a str
 ## Adding a token file
 
 1. Create `tokens/my-feature.tokens.js`
-2. `import { PRIMITIVES as P } from '../primitives'`
+2. `import { PRIMITIVES as P } from '../primitives.js'`
 3. `export const MY_FEATURE_TOKENS = { 'bg-banner': P['brand-50'] }`
 4. Import it in `_component.tokens.js` and spread it into `TOKENS`
 

package/templates/js/saascfm-css/_component.tokens.js

@@ -1,9 +1,9 @@
-import { NAVIGATION_TOKENS } from './tokens/navigation.tokens'
-import { STATUS_TOKENS }     from './tokens/status.tokens'
-import { SURFACE_TOKENS }    from './tokens/surface.tokens'
-import { BORDER_TOKENS }     from './tokens/border.tokens'
+import { NAVIGATION_TOKENS } from './tokens/navigation.tokens.js'
+import { STATUS_TOKENS }     from './tokens/status.tokens.js'
+import { SURFACE_TOKENS }    from './tokens/surface.tokens.js'
+import { BORDER_TOKENS }     from './tokens/border.tokens.js'
 
-import { PRIMITIVES }        from './primitives'
+import { PRIMITIVES }        from './primitives.js'
 
 export const TOKENS = {
   ...NAVIGATION_TOKENS,

package/templates/js/saascfm-css/tokens/border.tokens.js

@@ -1,4 +1,4 @@
-import { PRIMITIVES as P } from '../primitives'
+import { PRIMITIVES as P } from '../primitives.js'
 
 export const BORDER_TOKENS = {
   'border-default': P['neutral-200'],

package/templates/js/saascfm-css/tokens/navigation.tokens.js

@@ -1,4 +1,4 @@
-import { PRIMITIVES as P } from '../primitives'
+import { PRIMITIVES as P } from '../primitives.js'
 
 export const NAVIGATION_TOKENS = {
   'nav-bg':                      P['neutral-50'],

package/templates/js/saascfm-css/tokens/status.tokens.js

@@ -1,4 +1,4 @@
-import { PRIMITIVES as P } from '../primitives'
+import { PRIMITIVES as P } from '../primitives.js'
 
 export const STATUS_TOKENS = {
   'text-status-error':        P['red-500'],

package/templates/js/saascfm-css/tokens/surface.tokens.js

@@ -1,4 +1,4 @@
-import { PRIMITIVES as P } from '../primitives'
+import { PRIMITIVES as P } from '../primitives.js'
 
 export const SURFACE_TOKENS = {
   'text-primary':    P['neutral-900'],

package/templates/ts/saascfm-css/RULES.md

@@ -19,7 +19,7 @@ The folder belongs to your app. The plugin never imports it by path; you pass `_
 
 ```ts
 import cssModule from '@umoa/saascfm-css'
-import * as colors from './src/saascfm-css/_component.tokens'
+import * as colors from './src/saascfm-css/_component.tokens.ts'
 
 plugins: [cssModule({ colorsModule: colors })]
 ```
@@ -72,6 +72,8 @@ Each token becomes a CSS variable on `:root`. The first word of the name decides
 </style>
 ```
 
+Primitives are classes only. To also get a CSS variable for every primitive (`var(--brand-500)`), set `primitiveVars: true` in the plugin options. No change to the token files is needed.
+
 A token value can be a primitive (`P['neutral-900']`), a primitive name as a string (`'neutral-900'`), or any CSS color or value (`'#fff'`, `'rgba(0,0,0,.4)'`, `'56px'`). A string that looks like a primitive name but doesn't exist prints a warning and is skipped.
 
 ### When to use which
@@ -89,7 +91,7 @@ A token value can be a primitive (`P['neutral-900']`), a primitive name as a str
 ## Adding a token file
 
 1. Create `tokens/my-feature.tokens.ts`
-2. `import { PRIMITIVES as P } from '../primitives'`
+2. `import { PRIMITIVES as P } from '../primitives.ts'`
 3. `export const MY_FEATURE_TOKENS = { 'bg-banner': P['brand-50'] }`
 4. Import it in `_component.tokens.ts` and spread it into `TOKENS`
 

package/templates/ts/saascfm-css/_component.tokens.ts

@@ -1,9 +1,9 @@
-import { NAVIGATION_TOKENS } from './tokens/navigation.tokens'
-import { STATUS_TOKENS }     from './tokens/status.tokens'
-import { SURFACE_TOKENS }    from './tokens/surface.tokens'
-import { BORDER_TOKENS }     from './tokens/border.tokens'
+import { NAVIGATION_TOKENS } from './tokens/navigation.tokens.ts'
+import { STATUS_TOKENS }     from './tokens/status.tokens.ts'
+import { SURFACE_TOKENS }    from './tokens/surface.tokens.ts'
+import { BORDER_TOKENS }     from './tokens/border.tokens.ts'
 
-import { PRIMITIVES }        from './primitives'
+import { PRIMITIVES }        from './primitives.ts'
 
 export const TOKENS = {
   ...NAVIGATION_TOKENS,

package/templates/ts/saascfm-css/tokens/border.tokens.ts

@@ -1,4 +1,4 @@
-import { PRIMITIVES as P } from '../primitives'
+import { PRIMITIVES as P } from '../primitives.ts'
 
 export const BORDER_TOKENS = {
   'border-default': P['neutral-200'],

package/templates/ts/saascfm-css/tokens/navigation.tokens.ts

@@ -1,4 +1,4 @@
-import { PRIMITIVES as P } from '../primitives'
+import { PRIMITIVES as P } from '../primitives.ts'
 
 export const NAVIGATION_TOKENS = {
   'nav-bg':                      P['neutral-50'],

package/templates/ts/saascfm-css/tokens/status.tokens.ts

@@ -1,4 +1,4 @@
-import { PRIMITIVES as P } from '../primitives'
+import { PRIMITIVES as P } from '../primitives.ts'
 
 export const STATUS_TOKENS = {
   'text-status-error':        P['red-500'],

package/templates/ts/saascfm-css/tokens/surface.tokens.ts

@@ -1,4 +1,4 @@
-import { PRIMITIVES as P } from '../primitives'
+import { PRIMITIVES as P } from '../primitives.ts'
 
 export const SURFACE_TOKENS = {
   'text-primary':    P['neutral-900'],