@umoa/saascfm-css 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026 UMOA. All rights reserved.
+
+This software and its documentation are proprietary to UMOA. No license is
+granted to copy, modify, merge, publish, distribute, sublicense, or sell
+copies of this software, or to use it, except as expressly authorized in
+writing by UMOA.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL UMOA
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @umoa/saascfm-css
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vite plugin that scans your source and generates only the utility classes you use. `w-54`, `mt-12`, `g-8`, `flex-jcc`, `text-primary`.
+
+## Install
+
+```bash
+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"`.
+
+```js
+// vite.config.js (or .ts)
+import cssModule from '@umoa/saascfm-css'
+import * as colors from './src/saascfm-css/_component.tokens'
+
+export default defineConfig({
+  plugins: [cssModule({ colorsModule: colors })],
+})
+```
+
+```js
+// main.js (or .ts)
+import 'virtual:css-module.css'
+```
+
+TypeScript only: add `"types": ["@umoa/saascfm-css/client"]` to `tsconfig.json`.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `srcDir` | `'src'` | folder scanned (plus root `index.html`) |
+| `extensions` | `.vue .js .jsx .ts .tsx .html` | file types scanned |
+| `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 |
+| `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 |
+
+## What is fixed vs. what is yours
+
+Fixed (ships in the package): spacing, gap, layout, typography, cursor, border-style.
+
+Yours (lives in your app): colors. Copy the template folder into your app and rename anything. Pick `ts` or `js`.
+
+```bash
+cp -r node_modules/@umoa/saascfm-css/templates/ts/saascfm-css src/
+```
+
+That creates:
+
+```
+src/saascfm-css/
+  primitives.ts            raw color scale
+  _component.tokens.ts     aggregator: pass this to the plugin
+  tokens/
+    surface.tokens.ts
+    border.tokens.ts
+    status.tokens.ts
+    navigation.tokens.ts
+  CHEATSHEET.md            every class and token
+  RULES.md                 how the folder works, adding tokens, migrating
+```
+
+Then point the plugin at it:
+
+```ts
+import * as colors from './src/saascfm-css/_component.tokens'
+
+plugins: [cssModule({ colorsModule: colors })]
+```
+
+A smaller starter, `templates/ts/minimal/` (one `app.colors` file, 8 primitives, 12 tokens), is also included. Use one or the other, not both.
+
+Keep `.tokens.` in token file names and `primitives.` in the primitives file name. The scanner skips paths containing `.colors.`, `.tokens.` or `primitives.`, so your color definitions do not generate every class.
+
+## Colors
+
+One file exports two objects.
+
+```ts
+export const PRIMITIVES = { 'brand-500': '#3B6FF0', 'white': '#FFFFFF' }
+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.
+- Unknown primitive names print a warning and are skipped.
+- `hl`, `hl-muted`, `vl` read `--border-default` / `--border-muted`, falling back to `currentColor`.
+
+## Numeric classes
+
+`{prefix}-{n?}{number}{suffix?}`
+
+| Prefix | Property |
+| --- | --- |
+| `w` `h` | width, height |
+| `mw` `mh` `minw` `minh` | max/min width/height |
+| `mt` `mr` `mb` `ml` `mtb` `mrl` | margin |
+| `p` `pt` `pr` `pb` `pl` `ptb` `prl` | padding |
+| `g` `gc` `gr` | gap, column-gap, row-gap (no negatives) |
+| `bdrd` | border-radius |
+| `bdw` | border-width, also sets `border-style: solid` |
+| `zdex` | z-index (unitless) |
+
+Suffixes: `p` percent (`w-10p`), `vw` / `vh` (`w` and `h` only: `h-50vh`), `n` negative (`mt-n10`), `d` decimal point (`mt-12d5` = 12.5px, `mt-12d5p` = 12.5%).
+
+## Static classes
+
+| Class | |
+| --- | --- |
+| `bn` | border: none |
+| `auto` | margin: 0 auto |
+| `hl` `hl-muted` `vl` | divider lines |
+| `mcon-480` `640` `768` `1080` `1280` `1440` | max-width container, centered |
+| `bds-solid` `dashed` `dotted` `double` `none` | border-style (emitted last so it overrides `bdw-*`) |
+
+## Layout
+
+Flex: `flex`, `flex-fdr` `fdrr` `fdc` `fdcr`, `flex-wrap` `flex-nowrap`, justify `flex-jcfs` `jcfe` `jcc` `jcsb` `jcsa` `jcse`, align-items `flex-aifs` `aife` `aic` `aist` `aib`, align-content `flex-acfs` `acfe` `acc` `acst` `acsb` `acsa`, align-self `flex-assr` `asc` `ass` `ase`.
+
+Grid: `grid-jist` `jie` `jic` `jistr`, `grid-aist` `aie` `aic` `aistr`.
+
+Other: `align-l` `align-c` `align-r` (text-align), `float-l` `float-r`, `float-c` (position: fixed, centered).
+
+## Typography
+
+| Class | |
+| --- | --- |
+| `nb` `b` `bx` | normal / bold / bolder |
+| `b-100` … `b-900` | font-weight |
+| `light` `lighter` (`b-light` `b-lighter`) | 300 / 100 |
+| `uppercase` `lowercase` `capitalize` `text-none` | text-transform |
+| `i` `underline` | italic, underline |
+| `ow` `ww` | overflow-wrap + hyphens |
+| `fs-1em` `fs-1d5em` `fs-d5em` | font-size, `d` = decimal point |
+
+`ls-0d1em` is letter-spacing (`ls-n0d05em` = -0.05em). `d` is the decimal point; `p` still works there for older apps. In spacing, `p` means percent (`w-10p`).
+
+## Cursor
+
+`cursor-pointer`, `cursor-grab`, `cursor-not-allowed`, and every standard CSS cursor value with the `cursor-` prefix.
+
+## Rules
+
+- Classes must appear as literal text. `` `w-${n}` `` is not detected; `cond ? 'w-10' : 'w-20'` is.
+- Generated classes have normal specificity (one class), so your component CSS wins over them. Set `important: true` to make every class win instead.
+- Add `!` at the end of any class to make just that class `!important`: `mt-12!`, `mt-12d5p!`, `bg-page!`.
+- Output order is fixed so the more specific class wins: `p` before `pt`, `mtb` before `mt`, `mrl` before `ml`. `bds-*` is always last.
+- Dev server regenerates on save and reloads the page.

package/client.d.ts

@@ -0,0 +1 @@
+declare module 'virtual:css-module.css'