Design principles

Summary

Why Neura looks and behaves the way it does. Every visual and API decision in the library traces back to the principles on this page; when something seems oddly conservative or oddly strict, the reason is usually here.

The two eras

Neura's visual identity is a deliberate two-phase strategy, and knowing which phase you're looking at explains most of the design:

Era	What it looks like, and why
0.x – 1.x (now)	Components render pixel-compatible with AUI 5.4, on purpose. A decade of Nsys screens migrates onto Neura without visual regressions, verified by pixel-diffing real portal pages. In this era the brand lives in the parts that can change safely: the color system, the mark, theming, and depth (accessibility, RTL, i18n) that the original never had.
2.0 (planned)	The compatibility shim drops, and with it the obligation to look like 2013. The post-parity design language (type scale, radii, elevation, motion) arrives as one deliberate step, not a slow drift.

In short: looking like AUI today is discipline, not absence of taste. Migration safety first, identity where it's free now, the rest in one planned move.

Principles

1 - Server-rendered first

Neura is built for HTML that arrives from the server: static classes, data-* attributes, auto-init on load, and an imperative API for the dynamic residue. No build step, no framework, no client-side templating is ever required to use it.

2 - Compatibility is a contract, with an end date

The AUI shim is a real, verified surface: behaviors are checked against the original library's source, not its documentation. It is also explicitly temporary: the aui-* / AJS.* spellings drop at 2.0, and new code never uses them.

3 - Accessibility is baseline, not a feature

Keyboard-only focus rings, screen-reader semantics on every overlay, prefers-reduced-motion, Windows High Contrast, and full RTL are part of the definition of "done" for every component, including deliberate breaks from AUI where its patterns were hostile to assistive tech.

4 - Owned color, derived rather than picked

Every brand color stop is generated from one owned anchor (#3f3d9c) by a single OKLCH formula: lightness is solved against WCAG contrast targets, chroma is clamped to gamut, and the output is checked to collide with no other framework's palette. Themes are the same formula at different hues. There is no eyedropper step anywhere.

5 - Zero dependencies

Vanilla JS and CSS for evergreen browsers. jQuery exists only as an optional peer that the compatibility layer picks up when the host page provides it.

6 - Honest documentation

The docs describe Neura on its own terms (the predecessor appears only where compatibility is the subject), demos run exactly the code shown next to them, gotchas and deliberate divergences are written down, and a machine-readable llms.txt gives coding agents the same contract humans get.

The color system

The palette is a formula, not a swatch collection. From the anchor, the ramp derives each role with a contrast target (checked automatically, vs white):

Role	Contrast target
`--neura-color-primary` (header, solid surfaces)	≥ 8.5:1
`--neura-color-link` / `-focus`	≥ 6.0:1
`--neura-color-hero` / button gradient top	≥ 4.6:1 (AA for white text)
Button gradient bottom	≥ 6.0:1
`--neura-color-link-visited`	≥ 6.0:1, fixed owned purple

Changing the brand means changing the anchor and re-running the generator; accessibility comes along automatically. The built-in themes are proof: each is the identical recipe at another hue.