deuxui

Files (200)

• NOTICE.md
• SKILL.md
• brand.contract.yaml · assets/brand/
• mark.svg · assets/brand/
• wordmark.svg · assets/brand/
• DESIGN.md · assets/templates/
• PRODUCT.md · assets/templates/
• audit-report.md · assets/templates/
• component-contract.md · assets/templates/
• decision-record.md · assets/templates/
• design.contract.yaml · assets/templates/
• exception.md · assets/templates/
• exceptions.yaml · assets/templates/
• prototype-shell.html · assets/templates/
• ux.config.yaml · assets/templates/
• UX_UI_AGENT_RULES.md · docs/
• deuxui-plan-ideas.md · docs/
• evals.json · evals/
• trigger_queries.json · evals/
• anti-slop.md · references/
• brand.md · references/
• color.md · references/craft/
• composition.md · references/craft/
• density.md · references/craft/
• depth.md · references/craft/
• detail.md · references/craft/
• iconography.md · references/craft/
• imagery.md · references/craft/
• index.md · references/craft/
• motion.md · references/craft/
• space.md · references/craft/
• states.md · references/craft/
• type.md · references/craft/
• voice.md · references/craft/
• defects.yaml · references/
• craft-floor.md · references/design/
• visitor-modes.md · references/design/
• index.md · references/
• loop.md · references/
• adapt-native.md · references/ops/
• adapt.md · references/ops/
• android.md · references/ops/
• animate.md · references/ops/
• audit-native.md · references/ops/
• bolder.md · references/ops/
• clarify.md · references/ops/
• colorize.md · references/ops/
• craft.md · references/ops/
• decide.md · references/ops/
• delight.md · references/ops/
• delta.md · references/ops/
• distill.md · references/ops/
• doctor.md · references/ops/
• document.md · references/ops/
• extract.md · references/ops/
• generate.md · references/ops/
• hooks.md · references/ops/
• index.md · references/ops/
• ios.md · references/ops/
• layout.md · references/ops/
• …and 140 more

SKILL.md (first lines)

# DeuxUI — UX engineering with a verdict

**Deux is French for two — UX and UI.** Design system rules for AI agents: strict
UX/UI best practices, enforced at the token level. Say it *deuce*.

DeuxUI keeps its own contract, in the same format it asks every project for —
`assets/brand/brand.contract.yaml` — and `selftest.py` measures the pages this skill
serves against it with the same detectors. That found twelve findings on its own
review page, and two defects in the detectors. A tool that asks for a declaration and
does not keep one has an argument it does not believe. See `references/brand.md`.

Most interfaces an agent produces look right in the one state the agent looked at.
They fail in the states nobody opens: the empty list, the request that 500s, the
320px phone, the keyboard-only pass, the moment the network drops. And then the
agent reports success, because nothing told it otherwise.

This skill fixes the reporting problem first. It carries a 235-rule contract
derived from WCAG 2.2, platform guidance and named UX research, and it ships
scripts that actually test the testable parts. A rule that was checked says PASS.
A rule that was not says **NOT_RUN** — and NOT_RUN is never a pass, never rounds
up to one, and blocks a release audit when it sits on a safety rule.

Everything else here follows from that. Read `references/loop.md` for the full
execution loop; this page is the map.

## The loop

```
orient (.deuxui/ or init)  ->  classify the surface and the task
   ->  select applicable rules   ->  PRESERVE > MODIFY > COMPOSE > CREATE
   ->  implement                 ->  ux_check.py        (static)
   ->  ux_browser.sh             (runtime, forces the states nobody tests)
   ->  ux_report.py --merge      ->  fix                ->  re-run
   ->  report with the rule matrix, including what was not checked
```

The loop is not ceremony. Each step exists because skipping it is how a specific
class of defect ships. If you are making a one-line copy change, run the static
tier and say so. If you are touching a flow that takes someone's money, run all
three tiers and mean it.

## Four stages, and the gate between them

| Stage | The question | Moves | Gate out of it |
|---|---|---|---|
| **Start** | What is this for, and what world does it live in? | `init` · `shape` · `design` (greenfield) · `uplift` (brownfield) · `comp` · `decide` | A **declared contract**, and a named person who chose a structure |
| **Improve** | Is this the right thing, and does it read? | `live` · `prototype` · `colorize` · `typeset` · `layout` · `animate` · `bolder` · `quieter` · `distill` · `clarify` · `delight` · `polish` | A named person **used a working prototype** and accepted it |
| **Check** | Does it hold up where nobody looks? | `audit` · `harden` · `responsive` · `optimize` · `critique` · `ios` · `android` · `delta` | The rule matrix, with **no unchecked P0** |
| **Maintain** | Is it still the same system six months on? | `document` · `extract` · `ledger` · `doctor` · `hooks` · `operate` | The ledger resolves: every approval names the declaration it was made against |

The stages are the shape of the work; `ux_phase.py` is the part that enforces the
order, and it refuses production UI edits before somebody has accepted a prototype.
Read [`references/ops/phase.md`](references/ops/phase.md) for why that gate exists
and [`references/ops/ledger.md`](references/ops/ledger.md) for what it leaves behind.

**`live` is the one that edits while somebody is looking.** Pick an element in the
running app, see two or three variants **in its own position**, accept one into the
source. Every variant is built from declared values only, one axis at a time, and
accept refuses a variant that introduces a P0 or P1 finding — taste chooses between
admissible options, it does not make an inadmissible one admissible. See
[`references/ops/live.md`](references/ops/live.md).

## Facts that prevent broken work

Read this table first — each row is a failure that reaches real users.

| Fact | Consequence |
|---|---|
| **NOT_RUN is not PASS.** | The single most common dishonesty in agent UI work is reporting a check that never ran. If you did not test it, say NOT_RUN. |
| **The happy path is the smallest part of the work.** | Empty, loading, error, offline, stale, permission-denied and conflict are states a user will reach. `ux_browser.sh --api` forces them for you. |
| **Hover does not exist on touch or keyboard.** | Anything revealed only on hover is invisible to a large share of users. Mirror it on `focus-visible`. |
| **Tailwind v4 changed `outline-none`.** | In v4 it sets `outline-style:none`; the old forgiving behaviour is now `outline-hidden`. The default ring also dropped 3px to 1px. The checks branch on your installed major version. |
| **`100vh` is wrong on phones.** | It ignores retracting browser chrome, so your footer hides under the URL bar. Use `dvh`, or `svh` when you need the smallest stable height. |
| **`:invalid` fires before the user types.** | It paints an error on an untouched required field. Use `:user-invalid`. |
| **A clickable `div` or `Card` is not a button.** | No keyboard, no role, no name. If it already contains buttons, you also get two competing targets and a `stopPropagation` workaround. |
| **Contrast fails by tiny margins.** | Indigo-500 with white text is 4.47:1 — it fails 4.5:1 and no human eye will catch it. Only measurement will. |
| **Colour cannot be guessed from source.** | Tailwind v4 themes are OKLCH `--color-*` variables. The checks resolve colours from your project; unresolvable pairs report NOT_RUN instead of a made-up verdict. |
| **The static tier is heuristic.** | It scans source text and is wrong sometimes. Each finding is tagged with its detector's *declared* confidence -- not a measured precision -- and counts read "N matched, M listed" because a capped list is not a total. Lead with the rule matrix, not the finding count. The runtime tier is what settles arguments. |
| **Creating is easier than reading.** | This is why agents turn mature apps into a collage of unrelated screens. The preserve ladder exists to make that cost visible. |
| **An exception may lower a PROJECT rule, never a STANDARD.** | You can document a deviation. You cannot relabel a failed WCAG criterion as passing. |
| **Design craft is checked against a declaration, never against taste.** | `.deuxui/design.contract.yaml` states the type roles, colour roles, one depth metaphor, radii and motion band *before* the code is written. The `S-CONTRACT-*` checks then compare the artifact to it. With no contract they report NOT_RUN — an undeclared system cannot be conformed to, and "is this beautiful?" has no decision procedure while "does this match what was declared?" does. |
| **The 20 UX laws now carry verdicts — 14 measured, 5 by attestation.** | Each enforceable law is indexed to the detectors that adjudicate one of its `verify:` clauses, and the report rolls them up. A law whose only evidence is a human attestation says `attested only` instead of passing as measured. The rule ID is still the finer-grained claim, so cite `NUM-004` when you mean the threshold and `LAW-02` when you mean the principle. |
| **215 of the 235 rules have an automated detector; the other 20 are the manual tier.** | Every rule is accounted for and every P0 is automated. The 20 are judgement calls no checker can settle — is this the right amount of complexity to reveal, is this density right for this task — and they report NOT_RUN until a person records an answer. Coverage is not conformance. |
| **The contract is declared before the code, and that order is now measured.** | Entering the `comp` phase snapshots the contract's hash, the git head and every UI file's hash; entering `verify` compares against it. A contract declared with no file changed since is a contract written to describe code that already existed — it will always show conformance, so every `S-CONTRACT-*` PASS behind it would be circular. `A-PHASE-ORDER` FAILs on exactly that. |
| **An approval whose declaration cannot be produced is not an approval.** | A decision records the hash of the contract it was made against, and a hash with no bytes behind it is a fingerprint of a document nobody kept. `ux_ledger.py` archives the contract under that hash every time one is derived, gated or approved, so `show DEC-003` prints what was declared at the time. When it cannot, it says so — printing *today's* contract beside an old approval would make every past decision look as though it were made with today's information, which is the worst thing a record can do. `A-CONTRACT-ARCHIVED` reports it to the gate. |
| **A drawing cannot be used, so it cannot tell you whether the thing works.** | There are two review stages. A wireframe settles structure; a working prototype settles usability, and `build` is gated on the second. `ux_proto.py` generates a real, clickable prototype from the contract — the five states as a switch, a form that validates, a dialog that traps focus, an undo that puts the row back — and `ux_review.py` hosts it beside the current product so a person can Alt-click any element and say what is wrong in their own words. |
| **A direction is approved by a person, against what they were actually shown.** | `ux_question.py` serves the comps as a page and records who chose, when, why, and the hash of what was on screen. It refuses an unnamed chooser, an agent's name, a reason under 40 characters, and a timeout — nobody choosing means NOT_RUN, never a default. Editing an approved comp afterwards makes the record stale and the build gate says so. |
| **The report audits itself.** | `GOV-005/006/008`, the `QA-*` and several `MEASURE-*` rules are about the report, not the product — no scan of an app can tell you whether the agent describing it invented a result. `ux_report.py` checks that every PASS names a detector that ran, that unknowns are declared, and that project config has not been used to weaken a standard. |

## Orient

Before changing anything, find out what already exists.

```bash
python3 scripts/ux_ledger.py state                  # the whole record in one page
python3 scripts/ux_ledger.py log --limit 20         # and how it got that way
python3 scripts/ux_check.py <project> --signals     # stack, theme vars, inventory
cat .deuxui/PRODUCT.md .deuxui/DESIGN.md          # if they exist
```

`ux_ledger.py state` is the first thing to run in a project that has been worked on
before. It reports the declaration field by field, what the code is actually built
with, which approval each stage is currently standing on, and what is still open —
and it keeps those four apart, because a contract declaring one thing over a
component library that does another is a conflict neither one reveals alone.

If `.deuxui/` is missing, follow `references/workflows/init.md`. It builds the
project memory by **inspecting** the repo — package manifest, theme variables,
component directories, routes — and asks only the two or three things it genuinely
cannot infer. Interrogating someone for twenty answers is the fastest way to make
a skill go unused.

Three layers, and they settle conflicts in this order: the **rules** in this skill
are universal; **PRODUCT.md** owns audience, jobs and risk; **DESIGN.md** owns the
visual system. When PRODUCT and DESIGN disagree, DESIGN wins on visual decisions
and PRODUCT wins on strategic ones. When either disagrees with a safety or
accessibility rule, the rule wins — see the priority order in `references/rules/00-governance.md`.

## Modes

From kryptobaseddev/awesome-skills, MIT.

More from kryptobaseddev/awesome-skills