> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MonoCSS
> Audit CSS architecture, explain cascade and token drift, prove selector ownership, and identify the runtime geometry still needing browser evidence.
MonoCSS is a CSS-architecture audit orchestrator over
[Monogram](/ai-clis/monogram/overview). It gathers static evidence about import
order, `!important` debt, token coupling, raw colors, scrollbar ownership, and
runtime inline-style bypasses, then tells the reviewer which claims still need
live DOM geometry.
*Published contract: `monocss 0.16.0`, OpenCLIs build
`2026-07-20-111510`. The executing binary, OpenCLIs installed state, and public CDN
metadata agree on this release.*
*Registry ownership: the canonical `docs_url` is this page, the public product
homepage is `https://monolex.ai`, and MonoCSS pairs with Monogram for source
proof, MonoSurf or Kernel CLI for runtime DOM proof, and Monoflow for temporal
context. Repository ownership remains `monolex/monolex`; no public source URL is
advertised while that repository is private.*
Version 0.16.0 has root help, but no per-command help parser. Use bare
`monocss`, `monocss help`, or root `monocss --help`. `audit --help` is an
unknown audit option, `summarize --help` treats `--help` as an audit directory,
and `status --help` still runs the status probe.
## Release Identity
`latest.json` and all five platform entries record clean source commit
`9221412fba57808e8d01a8bd22ef8a58de13e5cc`. The following archive and
extracted-payload hashes were verified from build `2026-07-20-111510`:
| Platform | Archive SHA-256 | Extracted payload SHA-256 |
| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `darwin-aarch64` | `c1aed2904e609c6b3ffe2da365adc9ac2de68484ee3e03206e3ca34145587726` | `5b9a924156cc5d2393ea032152028485e5df4fcdd75c3ed805d5e0efa9616e6c` |
| `linux-x86_64` | `bc0e4d61337f3cd570cf3fc0676b7c05665d27e55c01933be1353a938033446f` | `691419df49722780a100c414ea4bf47594d3d394bb743cd06a9312e474af239c` |
| `linux-aarch64` | `69f8f736763951d389e605bdbdf33ba9e110d3fc345c68602836a80ae1e8619c` | `7bbf791cdeb1b3eaa9e0f964077aab0f55ff0a199b76d9786fc27c7513212dd9` |
| `windows-x86_64` | `3aea760b6ca6bb05fee6641d013e37328e0d7a636d033fb147ee97fb610d8367` | `868f356787e0e1241071a468315f0b189c27f030820cf5ba4a2c798cf00175bb` |
| `windows-aarch64` | `c87a111eadd3eb495f78a4e5951df4f0bb4d97623526f5bf4677545112fde308` | `5b8ff25d623f462a1b0209976ff3f752bea52aadb6dae57a7d96a0ae11f82578` |
Artifact availability, hash integrity, executable signature, and runtime DOM
proof are separate layers. A published binary does not by itself prove a CSS
finding or the final rendered geometry.
## Quick Start
```bash theme={null}
openclis install monocss
monocss --version
monocss status
monocss audit --entry src/styles/main.css --styles src/styles
```
Read the generated `SUMMARY.md` first. Raw artifacts are supporting evidence,
not the required starting point.
## Complete Command Reference
| Command | What it does | Important controls |
| --------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `audit` | Runs the complete source CSS audit and writes a normalized report directory. | `--entry `, `--styles `, `--out `, `--json` |
| `summarize ` | Prints the compact summary from an existing audit run. | Read-only over the selected output directory. |
| `plan ` | Generates a prioritized remediation plan from an audit. | Uses existing findings; it does not apply CSS edits. |
| `prove selector ` | Traces a selector through Monogram's CSS source graph. | Equivalent proof core: `monogram chain --depth 2 --strict --lang css`. |
| `prove scrollbar --selector ` | Runs static selector proof and prints the live DOM metrics still required. | Requires later runtime measurement for geometry. |
| `status` | Reports the Monogram index status MonoCSS depends on. | Read-only readiness check. |
| `mcp-schema` | Prints the OpenCLIs CLI-to-MCP schema. | Six callable schema entries: `audit`, `summarize`, `plan`, `prove_selector`, `prove_scrollbar`, and `status`. `--mcp-schema` is an alias. |
| `help` | Prints the installed guide. | No arguments also print the guide. |
## Audit Artifacts
An `audit` run writes `00-monogram-stats.txt`, then one raw artifact for each
probe in registry order. Version 0.16.0 has 33 probes:
| Artifact | Evidence |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `00-monogram-stats.txt` | Source-index readiness and scope |
| `01-css-order.json` | Import and cascade order |
| `02-important-report.json` | `!important` classifications, including removable and competing declarations |
| `03-css-token-coupling.json` | Static design-token coupling |
| `04-scrollbar-static.txt` | Static scrollbar and overflow ownership plus the DOM proof request |
| `04b-scroll-owner-inventory.txt` | CSS and inline scroll owners diffed against the canonical `scrollbar.css` identity inventory, plus unresolved runtime assignments |
| `05-inline-runtime-styles.txt` | JavaScript/TypeScript inline-style bypass candidates |
| `06-raw-color-literals.txt` | Raw color literals outside token policy |
| `07-z-index.txt` | z-index count, peak value, and extreme escalation |
| `08-media-query.txt` | Media-query count and hot files |
| `09-motion.txt` | Transition/animation declarations and hot files |
| `10-font-family.txt` | Font-family declarations and ownership hot spots |
| `11-position-escape.txt` | Absolute/fixed positioning escapes |
| `12-transition-all.txt` | `transition: all` performance and ownership smells |
| `13-calc.txt` | `calc()` expression hot spots |
| `14-magic-px.txt` | Hardcoded pixel-value frequency and distinct spacing values |
| `15-var-fallback.txt` | Undefined bare tokens, fallback-only orphans, and runtime-defined exclusions |
| `16-id-selectors.txt` | Styled ID selectors and specificity concentration |
| `17-vendor-prefix.txt` | Legacy `-webkit-`, `-moz-`, and `-ms-` prefixes |
| `18-overflow.txt` | Overflow modes, including hidden-content clipping risk |
| `19-font-size-px.txt` | Hardcoded pixel font sizes outside a type scale |
| `20-important-structural.txt` | `!important` on z-index, position, or display |
| `21-display-none.txt` | Hidden/toggled element hot spots |
| `22-duration-values.txt` | Distinct transition and animation duration values |
| `23-outline-none.txt` | Removed focus outlines and accessibility review points |
| `24-box-shadow.txt` | Untokenized elevation/shadow declarations |
| `25-pointer-events-none.txt` | Interaction-blocking pointer-event declarations |
| `26-rem-em.txt` | Relative-unit usage for comparison with hardcoded pixels |
| `27-user-select-none.txt` | Unselectable-text declarations |
| `28-important-property.txt` | `!important` debt grouped by property |
| `29-text-overflow.txt` | Truncation and white-space ownership |
| `30-dead-css.txt` | Conservatively detected class definitions with no static reference |
| `31-reduced-motion.txt` | Reduced-motion coverage and universal-guard detection |
| `32-token-graph.txt` | Cross-language CSS↔TypeScript token definitions, reads, writes, fallbacks, and dead edges |
| `monocss-report.json` | Normalized machine report |
| `SUMMARY.md` | Human/agent entry summary |
The default output root is `.niia/monocss-audit/`.
The compact `Writes` section embedded in the installed 0.16.0 guide stops at
artifact 06 but includes the new 04b artifact. The runtime registry and normalized report contain all 33 probes
listed above; this public page records the complete release behavior.
### Scroll-owner inventory
The 0.16.0 `scroll_owner` probe closes the gap between “a scrollbar rule
exists” and “every scrolling container has an intentional owner”:
```text theme={null}
domain CSS overflow rules ─┐
HTML/TS inline overflow ───┼─▶ identify selector/id/class/tag ─▶ compare with scrollbar.css
runtime style assignments ─┘ │
classified · exception · UNCLASSIFIED ─────┘
│
└─▶ live DOM proof for unresolved identity/geometry
```
It strips comments from the inventory, resolves CSS declarations back to their
selector headers, and scans HTML plus TypeScript templates for inline overflow
owners. The report separates unclassified inline owners (highest native-
scrollbar risk) from unclassified CSS owners. Runtime `.style.overflow*` or
`setProperty("overflow…")` assignments are listed separately because static
analysis may find the write site without proving which element receives it.
The normalized finding exposes `owners_css`, `owners_inline`, `classified`,
`exceptions`, `unclassified_css`, `unclassified_inline`, `runtime_assigns`,
and `inventory_available`. If `scrollbar.css` cannot be read, the probe marks
the diff degraded instead of claiming every owner is truly unclassified.
## Normalized Report Contract
With `audit --json`, stdout contains the same report written to
`monocss-report.json`:
| Field | Meaning |
| -------------------------------- | ------------------------------------------------------------------------ |
| `version`, `generated_at`, `cwd` | Tool identity, audit time, and audited working directory |
| `entry_css`, `style_dir` | Explicit audit scope |
| `index_state` | Monogram status, detail, and changed-file list |
| `findings[]` | One normalized result per registry probe |
| `dom_proof_required[]` | Runtime claims static evidence cannot close |
| `next_commands[]` | Suggested selector, scrollbar, CSS, important, and token-coupling proofs |
Each finding carries `id`, `artifact`, executed `command`, `success`, `headline`,
`extra_lines`, probe-specific `metrics`, report `sections`, and an optional
`dom_proof` request. A raw subprocess artifact is evidence; the finding is the
stable machine-facing interpretation.
## Remediation Plan Thresholds
`monocss plan ` reads the normalized metrics and emits advice only.
It never edits CSS. Version 0.16.0 gates these plan items:
| Priority | Probe and threshold | Recommended direction |
| -------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| P0 | `z_index`: an extreme value exists or maximum ≥ 1000 | Replace escalation with a named layer scale |
| P1 | `id_selectors`: at least 50 distinct styled IDs | Move shared ownership toward classes |
| P1 | `important`: redundant + conflicting declarations ≥ 50 | Remove unopposed declarations, then resolve competing owners |
| P1 | `reduced_motion`: at least 20 motion declarations without a global guard | Add one universal reduced-motion policy |
| P1 | `var_fallback`: at least one undefined bare `var(--x)` | Define the missing themed token; the declaration currently drops |
| P2 | `var_fallback`: at least 5 fallback-only orphan tokens | Define real shared tokens without metric-gaming |
| P2 | `magic_px`: at least 30 distinct pixel values | Introduce a spacing scale |
| P2 | `font_size_px`: at least 100 declarations | Introduce an accessible type scale |
| P2 | `overflow`: at least 50 hidden declarations | Review containers for clipped content |
| P2 | `raw_color`: at least 100 literals | Move owned colors into tokens |
| P2 | `dead_css`: at least 50 candidates | Prove no dynamic/DOM usage before deleting |
Thresholds are prioritization policy, not proof that a finding is safe to fix.
Every suggested change must be re-audited and, where requested, verified in the
live DOM.
## Static and Runtime Proof Boundary
```text theme={null}
MonoCSS + Monogram
import order · selector ownership · token coupling · static risks
↓
MonoSurf or app browser inspection
computed style · client/offset widths · real gaps · overflow owner
```
`prove scrollbar` explicitly asks for `scrollbarGutter`, left/right padding,
`clientWidth`, `offsetWidth`, first-child edge gaps, overflow ownership, and
inline-style ownership. A clean static trace cannot prove those live values.
Use [MonoSurf](/monosurf/index) for browser DOM evidence, or the appropriate
Tauri runtime inspector for application-only surfaces.