AGENTS.md
Oddlynew UX and UI Principles for Websites
Read this first. This organization is a skill organization: a small, focused body of maintained knowledge that an agent reads before doing UX or UI work on a website. It is small by design and it grows by research passes, not by pasting. Maintained by Oddlynew GmbH.
Purpose
State what the recognised authorities on UX and UI agree on, where they disagree, and what the evidence says, so that an agent building or reviewing a website screen can apply it without re-researching. Readers: any agent doing UX or UI work on a website.
Copy and interface text: the sibling skill organization Copy and Messaging Principles owns the words (copywriting, persuasion evidence, positioning to page copy, content design, agent-facing copy, plan and limit copy). Read its Principles for any screen with text; this organization keeps layout, interaction and visual design. The two are separate foundations: each stands on its own evidence, and neither depends on the other.
Starting material
This organization grew from earlier private guides on UX and UI. Consuming agents start with Principles and follow its source references. A new research pass also reads the Research log and relevant open questions before adding evidence.
The author of those private guides reported that agents worked better after reading them. Treat that account as anecdotal motivation, not a measured effect size. The Evaluation pack defines how to investigate the contribution; no paired trials have run yet. Distil evidence into this organization, cite it, and go beyond earlier material rather than copying it wholesale.
Routes
Read the relevant Principles first. Before designing, follow How to do UX and UI; use Worked examples for a concrete decision, the Design review playbook to review a screen, and the Site coherence pass with its Skill for a whole site. The Evaluation pack tests whether access improves delivered work; its trials are not yet run. Do not create competing summaries or read every source by default. Update the owner that holds the changed claim or method.
Principles: the canonical distilled list. Keep each principle together under its own heading: its rule, evidence class, sources, application, and limits. Practical priorities are labeled as synthesis, not universal experimental rankings.
Sources: maintain one document per authority or body of work. The directory below points to the maintained notes. Each records what was actually read, source URLs and dates, the evidence class, transfer limits, and tensions. Add a source owner only when a new body of evidence warrants one.
Conflicts and open questions: genuine source tensions, scope mismatches, hypotheses, and uncovered evidence. State when judgment or product-specific testing is needed; do not silently erase a disagreement.
Myths: unsupported, contradicted, and overgeneralized claims, with distinct verdicts and evidence. Keep this route so later agents do not restore attractive shortcuts.
Research log: append-only pass history. Record date, agent, provider and model name, sources, earlier claims rechecked, changes, contradictions, actual verification, and remaining gaps.
Applied knowledge
Worked examples: eight original fictional cases with situation, proposed change, rationale, counterexample, and acceptance check. Includes textual comparison exhibits and three composition alternatives; these are not tested product screenshots.
Design review playbook: six conditional evergreen prompts, visual-craft checks, choosing and keeping one illustration style per role on a site, a complete-journey procedure, finding template, prioritization, and writeback from actual corrections.
Evaluation pack: paired with/without-corpus protocol, six disclosed practice tasks, scoring, cost and correction records, and limits on independent and held-out claims. Protocol prepared; no trials, runner, or schedule installed.
How to do UX and UI: aim, modelled minds, and lanes: a method for the thinking before a design and the panel rounds around it: aim where technology and demand will be, write the context down first, model opposed personas, judge in lanes (text, visualization, UI detail, everything together). Method under trial, no measured effect.
Site coherence pass: a method for making a whole website read as one site: one capture set reviewed by several lenses before and after building, a measuring consistency audit, owner calls in batches or delegated picks, one slice per pull request, modelled attention heatmaps with their validation, and a fit pass for one first screen that feels good and overwhelming at once. Method under trial, run several times on one site.
Skill: run a site coherence pass: the steps an agent follows for that method, and what the consistency audit and the attention heatmap renderer do, so either can be rebuilt.
Source directory
Nielsen Norman Group: heuristics, mental models, navigation, disclosure, visual hierarchy, design systems, and research method.
Ben Shneiderman: current author-published Eight Golden Rules and their limits.
Bruce Tognazzini: discoverability, consistency, work preservation, and historical latency guidance.
W3C WCAG 2.2: normative accessibility authority and selected criteria.
Google web.dev: Core Web Vitals and responsiveness versus completion.
GOV.UK Design System: questions, persistent labels, tabular comparison, validation timing, locatable errors, and transaction review.
Google Research: goal-based measurement and aesthetic first impressions; abstract-level coverage is explicit.
Microsoft Human-AI and HAX: research-derived guidance, its evaluation scope, and website transfer.
Baymard validation research: timing of inline feedback, and its direct disagreement with GOV.UK on validating when a person leaves a field.
W3C ARIA Authoring Practices: tab activation, modal focus, and illustrative implementation references. This is informative guidance, distinct from WCAG requirements.
How this organization grows
A research pass is one agent, one model, one session. It reads the current Principles and Research log, picks sources not yet covered or claims not yet verified, and writes to the routes above.
Each pass verifies at least one claim from an earlier pass against the primary source, and records the result in the Research log even when nothing changed.
Run passes with agents from different providers. Disagreement between passes goes to Conflicts and open questions, never silently overwritten.
When models improve, rerun the passes. The Principles document is rewritten as if the new understanding had always been known; the Research log keeps the history.
Every claim carries its evidence next to it: a source document in this organization, or a URL with the date read. A claim without evidence is marked as such.
Learn from use: after an actual design task, follow the correction-to-learning method. Add a reusable case or change the existing owner, preserve counterexamples, and append evidence to Research log. Keep illustrative, implementation-tested, and user-observed labels distinct. A product-specific brand preference is not a general UI rule.
Writing rules
English. No em-dashes. High signal per sentence. Put the point first.
Short quotations only; distil in your own words and cite. Do not reproduce long passages from books or articles.
Website scope. Mobile apps, desktop software and games are out of scope unless a principle transfers and the transfer is stated.
Keep the accessibility baseline (WCAG AA) as a requirement, not a preference.
Ownership and status
Maintained by Oddlynew. This is a public organization: anyone can read it, signed in or not.