MonoCSS

MonoCSS is a CSS-architecture audit orchestrator over Monogram. 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.15.0, OpenCLIs build 2026-05-27-232227. The executing binary, OpenCLIs registry, 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.15.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.

Quick Start

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 <file>`, `--styles <dir>`, `--out <dir>`, `--json`
`summarize <audit-dir>`	Prints the compact summary from an existing audit run.	Read-only over the selected output directory.
`plan <audit-dir>`	Generates a prioritized remediation plan from an audit.	Uses existing findings; it does not apply CSS edits.
`prove selector <selector>`	Traces a selector through Monogram’s CSS source graph.	Equivalent proof core: `monogram chain <selector> --depth 2 --strict --lang css`.
`prove scrollbar --selector <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.15.0 has 32 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
`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/<timestamp>.

The compact Writes section embedded in the installed 0.15.0 guide stops at artifact 06. The runtime registry and normalized report contain all 32 probes listed above; this public page records the complete release behavior.

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 <audit-dir> reads the normalized metrics and emits advice only. It never edits CSS. Version 0.15.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

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 for browser DOM evidence, or the appropriate Tauri runtime inspector for application-only surfaces.

Get Started

Articles

So Anthropic

User Guide

Philosophy

Applied Philosophy

Architecture

Gestalt Color

Transparency

Terminal Core

Features

VariableMD

Research

CodexMono

OpenCLIs

vpncli

MonoSurf

AI-CLIs

Quick Start

Complete Command Reference

Audit Artifacts

Normalized Report Contract

Remediation Plan Thresholds

Static and Runtime Proof Boundary

​Quick Start

​Complete Command Reference

​Audit Artifacts

​Normalized Report Contract

​Remediation Plan Thresholds

​Static and Runtime Proof Boundary

Quick Start

Complete Command Reference

Audit Artifacts

Normalized Report Contract

Remediation Plan Thresholds

Static and Runtime Proof Boundary