Principles

Principles

Concern skills say what each layer may do. These principles say how to decide when there is a choice. They are foundational to any effort that leverages the AutoCSS Architecture. When a principle and a concern skill agree, follow them. When they appear to conflict, surface it to the user — never resolve silently.

Each principle below carries: the rule, the why, how it shows up in this architecture, and the tell (how to catch a violation).

The thesis these principles serve — one UI, every project at once

AutoCSS is not one project's UI; it is every project's UI at once. One presentation layer, served once from one place, called remotely like a font or an image, rendering each back-end's data. This is the claim that makes the architecture matter, and every principle below exists to protect it.

• The stove-pipe it dissolves. In siloed, high-security environments each project is walled off, so it is treated as law that every project starts its front-end from scratch. Frameworks only soften the restart — each project still ships an isolated copy, built independently. Because the data and data-logic differ per project, teams assume the UI must differ too, so every project rebuilds and re-owns its own front-end (and increasingly one overloaded full-stack developer owns both ends). AutoCSS rejects that assumption.
• Why it is now possible. Native declarative browser features — :has(), :empty / :not(:empty), container and style queries, light-dark() — let a single remotely-served UI (not a copy) lay out, style, and render each project's content from the presence and shape of the data itself, with no relationship to that data. For the first time the same UI serves many unrelated back-ends without being forked.
• What that buys. Usability, accessibility, and standards-compliance stop being per-project rework and become one shared channel of effort — fixed once, inherited by every consumer. No framework-per-project stack can match that.
• Consistency and individuality at once. Department heads want a coherent look/feel across a department's apps while each app keeps its own identity for unique requirements. The shared UI provides the coherence; data-presence-driven rendering gives each app its individuality — both from the same source, no fork.
• Each engineer's best work, not a watered-down average. Because presentation and data are air-gapped, UI/UX specialists spend their seniority on UI/UX and data engineers on data — neither is conscripted into the other's craft. The customer gets each person's best, and department heads staff to solve real problems instead of hoping one overloaded generalist covers everything.
• The compounding payoff. Higher-quality apps in less time → better usability → happier, more productive users → more work done at lower total cost. Every app ships faster — a win for users, engineers, and whoever pays for the work.
• Why the principles follow. All eggs in one basket → the basket must be the single most durable, universal thing there is: one dependency, the modern browser. One basket for everyone makes decay catastrophic → future-proofing is existential, and modern-web-guidance + MDN are how the basket stays current and correct (not optional advice). A shared UI can only be worked as its own channel if it is fully isolated from every back-end → air-gapped Separation of Concerns is the enabler, not a nicety.

Hold this as the overall context (Charter §8) on every AutoCSS response: you are never touching one project — you are touching all of them at once, which is why usability, accessibility, and standards compliance are always in force, for every consumer, all the time.

Least Power

• Rule: For any task, use the least powerful technology that expresses the intent declaratively. Ask in order — can HTML do it? If not, can CSS? Only then JS. JS is never used for the presentation layer.
• Why: Less powerful tools are more portable, more inspectable, harder to misuse, and outlive frameworks.
• Shows up: semantic HTML for structure; CSS for all UI/state/visibility; JS only for data transport on the oninput lifecycle.
• Tell: a script doing what a selector could (:has(), :empty, :checked) is a Least-Power violation — re-engineer to the lower tool.

Separation of Concerns (the air-gap)

• Rule: Each concern is independent; a change in one produces no change in another. HTML never names a CSS class; CSS never reads JS state; JS never writes presentation; JSON never carries markup.
• Why: Air-gapped layers can be read, tested, and replaced in isolation, and enable a strict CSP with no unsafe-* (see the security skill).
• Shows up: the four-layer table in the architecture skill; one concern per file.
• Tell: the architecture skill's air-gap test — if an HTML change forces a CSS/JS change, the design is wrong.

DRY — one source of truth

• Rule: Every fact lives in exactly one place. Do not restate a rule, value, or datum that already exists elsewhere.
• Why: Duplication drifts out of sync and doubles maintenance.
• Shows up: canonical laws in ONE file (Autocss-com/ai AGENTS.md); PROGRESS.json as the single backlog source; design tokens as custom properties set once; the @layer order derived from <link> order, not a second master list.
• Tell: a value or rule copied into two files — collapse to one and reference it.

Minimum Entropy / Minimal New Code

• Rule: Adding code or files always increases entropy. The default is to add nothing. The best solution adjusts an existing behavior to meet the ask with no new code.
• Why: Every line and file is future maintenance and future risk.
• Shows up: new utilities/patterns/files only on explicit user instruction; prefer tuning an existing rule over writing a new one.
• Tell: reaching for a new file/function before proving the existing ones cannot express the intent.

Simplicity over Complexity

• Rule: Prefer the simpler construction. "Simplicity is the ultimate sophistication."
• Why: Simple systems are readable end-to-end by any qualified person and fail in obvious ways.
• Shows up: flat semantic markup over nested wrappers; one obvious way to do each thing; CSS Grid instead of wrapper-and-flex stacks.
• Tell: if explaining the mechanism needs a diagram of layers, look for the simpler expression first.

Universal Compatibility & Interoperability

• Rule: Build on web standards so the output works everywhere the platform does, and so other systems can embed it without a fight.
• Why: Standards are the widest, longest-lived contract.
• Shows up: keeping our own styles in low-priority @layers so a consumer's unlayered styles win by default (see the css layers reference); zero framework lock-in.
• Tell: a construction that only works inside this app's assumptions, not as a portable static resource.

Browser-Native Accessibility (baked-in)

• Rule: Prefer cross-browser, browser-native accessibility features and engineer the UI to depend on them — accessibility is a load-bearing part of the design, not a bolt-on.
• Why: Native semantics and states are free, correct, and survive refactors.
• Shows up: :focus-visible, native form control states, semantic elements, keyboard-operable state machines; honoring prefers-reduced-motion / forced-colors (see the css a11y reference).
• Tell: a control that is invisible to keyboard/AT (e.g. a focusable element hidden with display:none) — fix so native accessibility carries it.

Minimum O&M

• Rule: Minimize the operations-and-maintenance surface: fewer moving parts, fewer dependencies to patch, fewer build steps.
• Why: The cheapest system to run is the one with the least to maintain.
• Shows up: no bundler/compiler, no runtime dependencies, static shell deployable anywhere.
• Tell: a convenience that adds an ongoing operational burden (a service to keep alive, a dependency to keep patched).

Future-Proofing — zero third-party dependencies

• Rule: Zero third-party (non-native-browser) dependencies. Third-party = any code that cannot render natively in an evergreen browser without help.
• Why: The platform outlives every framework; native features do not get abandoned.
• Shows up: no npm runtime packages, no CDN scripts; self-host fonts and assets; use cutting-edge native CSS instead of libraries (anchor positioning instead of Popper, popover instead of a menu lib).
• Tell: a CDN <link>/<script> or an npm runtime import — replace with the native capability or self-host.

Usability — for end-users AND future developers

• Rule: Optimize for the people who use the surface daily and the developers who maintain it. Both deserve clarity.
• Why: A system only succeeds if both audiences can work with it.
• Shows up: data rendered as <ul>/<li> so CSS can reshape it on the user's terms (list/card views); names that describe the concern so the next developer isn't misled (see the naming skill).
• Tell: a choice that helps the machine but confuses a person reading the code or using the app.

Reuse before Create

• Rule: Review and reuse existing functions, patterns, and files before making new ones.
• Why: Reuse keeps entropy low and behavior consistent.
• Shows up: each skill catalogues the permitted utilities; check them first.
• Tell: writing a helper that duplicates one already in assets/js/ or a pattern already in a skill.

Never New Patterns

• Rule: All patterns here are already established and documented in a skill. If a task seems to need a new pattern, the design is wrong — re-engineer until an existing pattern fits.
• Why: A fixed pattern vocabulary is what makes the system readable end-to-end.
• Shows up: state machines, oninput lifecycle, data-flow rendering, @layer cascade — the whole vocabulary lives in the skills.
• Tell: inventing a mechanism not found in any skill — stop and find the established one.

Verify and cite (standards-first)

• Rule: Never guess. Verify feature behavior and support against authoritative sources (MDN Web Docs + BCD, the modern-web-guidance reference) and cite them. Those sources are advisory and subordinate — on any conflict, the AutoCSS rules win, but the duty to consult and reconcile is canonical.
• Why: A claim of correctness is not correctness; the platform moves and only fresh checks catch drift.
• Shows up: the css references' dated "Baseline & support" sections; @supports feature-detection over assumption.
• Tell: an assertion about support or behavior with no source and no recent check.

When principles conflict

Surface the conflict to the user with the trade-off named. The user is the sole arbiter. Never pick silently, and never let one principle quietly override another without saying so.

Baseline & support

Checked against MDN as of 2026-07-16.

• :has() — Baseline Widely available — https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:has
• :empty — Baseline Widely available — https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:empty
• light-dark() — Baseline Newly available — https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark

Canonical rules: https://github.com/Autocss-com/ai/blob/main/AGENTS.md

Reference

• MDN Web Docs (authoritative platform reference): https://developer.mozilla.org/
• W3C TR index (standards): https://www.w3.org/TR/
• W3C — Rule of Least Power: https://www.w3.org/2001/tag/doc/leastPower.html
• AutoCSS Architecture + Response Integrity Charter (canonical): https://github.com/Autocss-com/ai/blob/main/AGENTS.md