# Coordiation CSS

Coordiation CSS is an independent utility-first CSS compiler for the Coordiation framework. It has no Tailwind dependency and uses the `co-` prefix.

Creator: Wiryo Saputra (`wiryosaputra@coordiation.com`). Coordiation is built to help human and AI teams spend less time rebuilding foundations and more time creating useful products that can help many people.

## Canonical usage

- Base utility: `co-flex`
- Responsive variant: `md:co-grid-cols-3`
- State variant: `hover:co-bg-black`
- Stacked variants: `dark:md:hover:co-text-white`
- Important utility: `!co-hidden`
- Negative utility: `-co-mt-4`
- Arbitrary value: `co-w-[42rem]`
- Typed arbitrary value: `co-text-[length:2rem]`
- Arbitrary property: `co-[mask-type:luminance]`
- ARIA variant: `aria-expanded:co-block`
- Data variant: `data-[state=open]:co-block`
- Descendant/negation variants: `has-checked:co-ring-2`, `not-focus:co-opacity-50`
- Arbitrary selector: `[&.is-ready]:co-block`
- Conditional media: `motion-safe:co-transition`, `pointer-fine:co-cursor-pointer`
- Feature query: `supports-[display:grid]:co-grid`, `not-supports-[display:grid]:co-block`
- Named container query: `@md/sidebar:co-grid-cols-2`
- Arbitrary conditional at-rule: `[@media(pointer:fine)]:co-block`
- Preflight is enabled by default; disable it with `preflight: false` or CLI `--no-preflight`
- Layout: `co-aspect-3/2`, `co-sticky`, `-co-inset-x-4`, `co-break-inside-avoid`, `-co-z-10`, `co-object-[25%_75%]`
- Flex/Grid: `co-flex-[3_1_auto]`, `co-grow-3`, `co-basis-sm`, `co-items-center-safe`, `co-grid-cols-subgrid`, `-co-col-start-2`
- Spacing: `co-pbs-4`, `-co-mbe-2`, `co-gap-x-6`, `co-space-x-reverse`, `co-scroll-pbe-(--offset)`
- Sizing: `co-w-md`, `co-h-dvh`, `co-size-12`, `co-inline-full`, `co-max-inline-lg`, `co-min-block-24`
- Typography: `co-text-sm/6`, `co-font-stretch-condensed`, `co-font-features-(--features)`, `co-tabular-nums`, `co-wrap-anywhere`, `before:co-content-['AI_ready']`
- Backgrounds: `co-bg-black/50`, `co-bg-[url(/hero.svg)]`, `co-bg-linear-to-r/oklch`, `co-from-brand-500`, `co-via-40%`, `co-to-transparent`, `co-bg-position-(--focus)`, `co-bg-size-[auto_12rem]`
- Borders: `co-border-bs-2`, `co-border-e-brand-500/50`, `co-rounded-se-(--radius)`, `focus-visible:co-outline-2`, `-co-outline-offset-2`, `co-ring-2`, `co-inset-ring-brand-500`, `co-divide-x-reverse`, `co-divide-dashed`
- Effects: `co-shadow-lg`, `co-shadow-brand-500/40`, `co-text-shadow-sm`, `co-opacity-50`, `co-mix-blend-multiply`, `co-blur-md`, `co-brightness-125`, `co-drop-shadow-lg`, `co-backdrop-blur-sm`, `co-mask-[url(/mask.svg)]`, `co-mask-clip-content`
- Tables/columns: `co-table-fixed`, `co-border-separate`, `co-border-spacing-x-3`, `co-caption-bottom`, `co-columns-sm`, `co-gap-6`, `co-break-inside-avoid-column`, `co-column-span-all`, `co-column-rule-brand-500`
- Transforms: `-co-translate-x-4`, `co-translate-z-8`, `co-rotate-y-45`, `co-scale-95`, `co-skew-x-6`, `co-transform-3d`, `co-perspective-normal`, `co-perspective-origin-top`, `co-backface-hidden`, `co-zoom-110`
- Transitions/animations: `co-transition`, `co-transition-discrete`, `co-transition-[width,opacity]`, `co-duration-300`, `co-delay-75`, `co-ease-out`, `co-animate-spin`, `motion-reduce:co-animate-none`, `starting:co-opacity-0`
- Interactivity: `co-cursor-(--control-cursor)`, `co-field-sizing-content`, `co-scrollbar-thumb-brand-500`, `co-scrollbar-track-white`, `co-scrollbar-gutter-stable`, `co-snap-x`, `co-snap-mandatory`, `co-snap-always`, `co-touch-pan-y`, `co-touch-pinch-zoom`, `co-will-change-[contents,transform]`
- Logical writing: `co-direction-rtl`, `co-writing-vertical-rl`, `co-text-orientation-upright`, `co-unicode-bidi-isolate`, `co-text-combine-digits-2`, `co-pbs-4`, `co-inset-be-2`, `co-max-inline-lg`, `co-border-s-2`
- Modern color: pair `--co-color-signal` with `--co-color-signal--p3`, then use `co-bg-signal/80`; one-off values use `co-bg-[color:color(display-p3_1_0_0)]`, and gradients can use `co-bg-linear-to-r/display-p3`
- Vite: configure `coordiation({ content: ["src"], cssFile: "src/coordiation.css" })`, import `virtual:coordiation.css` once, and rely on built-in HMR for template/theme edits plus file creation and deletion
- PostCSS: place `coordiation({ content: ["src"], cwd: process.cwd() })` before downstream plugins, add `@coordiation;` only to the intended CSS entry, and let standard dependency/warning messages drive the runner
- CLI: pass literal `--input`, `--output`, and `--content` paths; use `--watch` for portable edit/create/delete polling during development, one-shot mode for production, and `--poll` only when the default 250ms interval needs tuning
- Custom utilities: read project `@co-utility` blocks or the compile result's `customUtilities` manifest before emitting project-specific classes; `co-value()` resolves theme/bare/arbitrary/default values, `co-modifier()` resolves slash modifiers, and negative patterns must be declared separately
- Custom variants: read project `@co-variant` directives or the compile result's `customVariants` manifest before emitting project variant names; selector formats require `&`, conditional shorthand supports media/supports/container, and compound blocks wrap exactly one `@co-slot;`
- Plugin API: inspect the compile result's JSON-safe `plugins` manifest before using plugin-owned utilities or variants; `defineCoordiationPlugin()` can register utilities, variants, theme extensions, source extractors, and safelists, with CSS-first project definitions taking final priority
- CSS toolchain: prefer `compileWithToolchain()` in build integrations; local imports, nesting, and target-aware prefixing are enabled by default, minification is opt-in, and the JSON-safe `toolchain` manifest lists exact targets, imported dependencies, and warnings
- Incremental cache: reuse one `createIncrementalBuildCache()` instance for repeated direct builds; inspect `scan.cache` and `result.cache` for hit/miss data, use the CLI project-local `.coordiation-cache` by default, and treat runtime extractor/plugin functions as process-scoped contracts
- Source maps: enable `sourceMap` for Source Map v3 output across imports, framework generation, transforms, and minification; inspect `result.toolchain.sourceMap`, use native Vite/PostCSS maps, and choose external or inline CLI delivery deliberately
- IntelliSense/LSP: launch `coordiation-language-server --stdio`, configure the same literal CSS entry and prefix as the build, use completion for discovery, hover for compiled CSS, diagnostics for literal/dynamic source problems, and `coordiation/inspectCandidate` for concrete project-aware support
- Agent context: install public `@coordiation/agent` and `@coordiation/cli`, run `coordiation inspect --write` to create `.coordiation/agent-manifest.json`, then request only the task pack with `coordiation context {page|navigation|form|dashboard|pricing|component|theme} --json`; use `--full` only when file-level detail is necessary
- Formatter: use `coordiation-format --check` or `--write`; its API reuses canonical compiler ordering, preserves application-class order, and leaves dynamic expressions unchanged
- Upgrade: inspect `upgradeManifest`, create a `--json` plan, then use `--check` or `--write`; registered transforms share compiler deprecation IDs and never evaluate dynamic source
- Native scanner: call `scanSourcesNative()` and inspect `engine` plus `native.fallbackReason`; use `fallback: false` only when native execution is a hard requirement
- Compatibility: inspect compiler `compatibility` and `deprecations`, use the registered replacement and codemod, and do not infer stable guarantees from a prerelease version
- Icons: read `/icon-registry.json`, select an exact record by `collectionId` and kebab-case `name`, then emit its literal `import` value unchanged; use `@coordiation/icons/linear/{name}` for Solar or `@coordiation/icons/iconsax-line-oval/{name}` for Iconsax Line Oval, and preserve each collection's license metadata
- Human icon discovery: browse `/icons`; clicking any one of the 2,165 icons across Solar Linear and Iconsax Line Oval reveals its collection, exact export, literal import path, renderer example, styling contract, and categories
- Components: read `/component-registry.json` or `/api/components`, select a stable component by exact name, and run `npx @coordiation/cli@next add component {name}`; preserve literal `co-*` classes, explicit client boundaries, native semantics, and the component accessibility contract
- Human component discovery: browse `/components`; every preview exposes its compatible install URL, local import, usage example, client/server boundary, and accessibility requirements
- Themes: read `/theme-registry.json` or `/api/themes`, select an exact stable theme by `name`, then run `npx @coordiation/cli@next add theme {name}`; preserve the documented namespace, semantic section IDs, heading hierarchy, literal asset paths, and accessibility contract
- Human theme discovery: browse `/themes`; every theme exposes a live application preview, exact install command, source files, section map, public asset list, and customization order
- Stable theme names: `editorial-advisor` for professional consultant portfolios and `quiet-journal` for illustrated personal essays, archives, topics, and newsletters

## Reliability rules for AI agents

1. Query `/api/capabilities` before generating framework-specific code.
2. Use capabilities marked `complete` freely.
3. Use `partial` only when the requested example is explicitly covered by its note or examples.
4. Never emit a `planned` capability as working code.
5. Preserve complete class strings in source so the plain-text scanner can detect them.
6. Prefer theme tokens over arbitrary values.
7. Read `result.toolchain` before assuming browser targets, imported CSS dependencies, or mapped source identities.
8. Treat cache manifests as rebuild observability, never as class-support evidence; compiler rejection and the utility registry remain authoritative.
9. Treat source maps as CSS-origin data, not template-to-class mappings; disable `sourcesContent` when original CSS must not be embedded.
10. Treat language-server completion as discovery and `coordiation/inspectCandidate` as concrete support evidence; never suppress dynamic-candidate diagnostics by guessing runtime strings.
11. Delegate class ordering to the formatter and preserve unknown application classes or dynamic expressions exactly as its manifest specifies.
12. Review the JSON upgrade plan before write mode; never apply a class-like replacement outside registered literal-source boundaries.
13. An installed native package does not prove native execution; report the actual engine and fallback reason.
14. Use deprecation IDs, earliest-removal versions, and registered replacements from the compatibility manifest; feature completeness does not rename a prerelease as stable.
15. Never guess an icon name, assume names are unique across collections, or dynamically concatenate an icon import. Use `collectionId` plus `name` from the registry, keep the recorded import literal for tree-shaking, pass `label` only when the icon conveys otherwise-unavailable meaning, and retain the collection's required attribution.
16. Never invent a component or import it from a runtime UI package. Use an item marked `stable`, install its source into the project, preserve its client boundary, and retain its documented accessibility behavior when customizing.
17. Never reconstruct a theme from its screenshot. Select it by exact registry name, install its source, copy or replace every listed media asset, and preserve its namespace plus semantic structure while customizing identity and content.
18. Read the compact project manifest before broad source inspection. Select one task context pack, keep its checks visible, and report any dynamic-candidate warning instead of guessing runtime classes.

Human release tracker: `/release-check`
Machine-readable capability manifest: `/api/capabilities`
Machine-readable utility registry: `/api/utilities`
Attribute and selector variant documentation: `/docs/variants/attribute-selectors`
Conditional variant documentation: `/docs/variants/conditional-rules`
Preflight documentation: `/docs/core/preflight`
Layout utility documentation: `/docs/utilities/layout`
Flexbox and Grid documentation: `/docs/utilities/flex-grid`
Spacing documentation: `/docs/utilities/spacing`
Sizing documentation: `/docs/utilities/sizing`
Typography documentation: `/docs/utilities/typography`
Background utility documentation: `/docs/utilities/backgrounds`
Border, outline, ring, and divide documentation: `/docs/utilities/borders-rings`
Effects, filter, backdrop-filter, and mask documentation: `/docs/utilities/effects`
Table and multi-column documentation: `/docs/utilities/tables-columns`
Transform and perspective documentation: `/docs/utilities/transforms`
Transition and animation documentation: `/docs/utilities/transitions`
Interactivity documentation: `/docs/utilities/interaction`
Logical properties and writing modes: `/docs/core/logical-properties`
Modern color and Display-P3: `/docs/core/modern-color`
Complete Vite installation and HMR guide: `/docs/installation/using-vite`
Complete PostCSS integration guide: `/docs/installation/using-postcss`
Complete standalone CLI and watch guide: `/docs/installation/using-cli`
Complete CSS-first custom utility guide: `/docs/core/custom-utilities`
Complete CSS-first custom variant guide: `/docs/core/custom-variants`
Complete JavaScript Plugin API guide: `/docs/core/plugin-api`
Complete CSS toolchain guide: `/docs/tooling/css-toolchain`
Complete incremental build cache guide: `/docs/tooling/incremental-cache`
Complete Source Map v3 guide: `/docs/tooling/source-maps`
Complete IntelliSense and LSP guide: `/docs/tooling/language-server`
AI agent manifests and task context packs: `/docs/tooling/agent-context`
Complete class formatter guide: `/docs/tooling/formatter`
Complete upgrade and codemod guide: `/docs/tooling/upgrade`
Complete native scanner guide: `/docs/tooling/native-scanner`
Compatibility and deprecation policy: `/docs/core/compatibility`
Solar Linear icon library and attribution: `/docs/icons/solar-linear`
Iconsax Line Oval icon library and provenance: `/docs/icons/iconsax-line-oval`
Interactive visual browser for all 2,165 icons: `/icons`
Machine-readable icon registry: `/icon-registry.json`
Open-code component architecture and installation: `/docs/components`
Interactive component catalog: `/components`
Machine-readable component manifest: `/component-registry.json`
Coordiation component catalog: `/r/registry.json`
Installable application theme guide: `/docs/themes`
Interactive application theme showcase: `/themes`
Machine-readable theme manifest: `/theme-registry.json`
Coordiation theme catalog: `/r/themes/registry.json`
Stable themes: `editorial-advisor`, `quiet-journal`, `finance-dashboard`, `industrial-forge`, and `mono-portfolio`