# Principles > The foundational engineering principles every AutoCSS effort obeys, one section per principle. These sit beneath the concern skills (html/css/javascript/json/…) and decide trade-offs when a task could be solved more than one way. Use when choosing an approach, justifying a design, resolving "which tool", or reviewing whether a change earns its place. - Skill: `autocss-com/principles` (Agent Skill) - Install (CLI): `npx skillmds@latest add autocss-com/principles` - Raw SKILL.md: https://api.skillmd.com/api/skills/autocss-com/principles/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: Autocss-com (https://skillmd.com/u/autocss-com) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/autocss-com/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 `` 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 `@layer`s 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 ``/`