super-ux 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.33.0 — 2026-08-10
+
+The chain designed landing pages and had nowhere to record that a landing is a
+page a machine reads. This release gives that decision a home, teaches the
+router the words users actually bring, and adds the two copy checks that our
+own interface failed.
+
+### Added
+
+- **`Web surface:` — the second reader gets a field.** A screen that is a
+  public URL now carries five, and each is the design-time twin of a check an
+  audit runs on the live page later, so both ends speak one vocabulary:
+  `Route`, `Answers` (the ONE question this page answers — a second question is
+  a second page), `Indexable`, `Without JS`, `Entity`. `screens.md` answers
+  `Web surfaces: yes|no` once per project, because a declared absence is
+  countable and an unanswered question is not. Contract stays **v4**: the block
+  is optional and additive, nothing to migrate.
+  `ux-flows` asks at the moment it already asks about Figma and the style pack;
+  `ux-audit` checks a built screen against the record; **seo-aeo-audit** joins
+  `sheleg-design` and `task-pipeline` as the third companion, on the same
+  recommend-never-force contract. The reason it lives in the chain and not in
+  an audit: once a page is live its URL is in other people's links and its
+  structure is what an answer engine already quoted, so an audit then finds a
+  problem it can no longer fix.
+- **`test/ux_lint_test.py` — the UX linter gets a fixture harness.** The brand
+  linter has carried one per code since 0.30.0; the older and more central
+  linter had none. Fourteen cases, every rule with its planted defect and its
+  clean twin, wired into CI. The backfill for the checks that predate it is
+  **B-010** on the board — named rather than implied.
+- **B007 — a voice names one brand it admires and one it refuses.** The refused
+  half does the work: it is the only one that can be checked against a draft out
+  loud. Silent while the voice is `draft`, because the references are part of
+  calibrating it and a warning on a freshly seeded project is how a linter
+  teaches people to ignore it on day one.
+- **B026 — a label, button, menu item or title takes no full stop.** Scoped by
+  key prefix rather than by guessing at the text: a message may be a sentence
+  and should be. It found `Nothing selected.` in this project's own installer
+  on its first run.
+- **Four routing rows and the composite brief.** `/ux` now answers to
+  *воронка / funnel / pricing / checkout*, *дизайн / how should it look*,
+  *SEO / чтобы находилось*, and *мобильное приложение / which platform* — every
+  one of which had a capability behind it and no words in front of it. And a
+  brief that names three things is now mapped to three routes, ordered by chain
+  position, with the sequence stated before the first one runs.
+
+### Fixed
+
+- `menu.nothing` in `bin/super-ux.js` ended in a full stop, and the registry
+  agreed with it. Both corrected; B026 is what found it.
+- This project's own `screens.md` now answers the web-surface question (`no`,
+  with the reason), and its `voice.md` names its two references.
+
 ## 0.32.0 — 2026-08-10
 
 A structural audit of 0.31.0 found twenty-two defects that 3427 green checks

package/README.md

@@ -129,7 +129,7 @@ Commands: `/brand` (status → one recommended action), `/brand-init`,
 python3 docs/brand/lint.py
 ```
 
-33 deterministic checks (`B001`..`B073`) — banned words, one action under two names, a figure
+35 deterministic checks (`B001`..`B073`) — banned words, one action under two names, a figure
 with no sourced fact, a field over its limit with the locale coefficient
 applied, blocked AI crawlers, keyword stuffing, humor on a billing screen,
 a locale that lags without saying so. Exit 0 clean, 1 warnings, 2 errors.

package/bin/super-ux.js

@@ -322,7 +322,7 @@ async function menu() {
 
   if (picked.length === 0) {
     if (prompter) prompter.close();
-    console.log('Nothing selected.');
+    console.log('Nothing selected');
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Scenario-driven UI development for AI agents (Claude Code, Cursor, 70+ agents): a versioned design chain in docs/ux/, a scenario-first hard rule, a deterministic drift linter, and evidence-backed UX audits. This package is the installer CLI.",
   "bin": {
     "super-ux": "bin/super-ux.js"

package/plugins/super-ux/scripts/brand_lint.py

@@ -201,6 +201,34 @@ def check_contract(brand_dir: Path) -> list[Finding]:
             "report",
         ))
 
+    # B007 -- a voice defined only by what it is drifts toward the average of
+    # everything. Naming one brand you admire and one you refuse gives the
+    # writer two fixed points, and the refused one does most of the work: it
+    # is the only field that can be checked against a draft out loud.
+    # A `draft` voice has not been calibrated yet and the references are part
+    # of calibrating it, so firing here would put a warning on every freshly
+    # seeded project -- which is how a linter teaches people to ignore it on
+    # day one. The check begins the moment someone claims the voice is done.
+    if voice and status and status != "draft":
+        section = re.search(
+            r"^##\s+Voice references\s*$(.*?)(?=^##\s|\Z)",
+            voice, re.MULTILINE | re.DOTALL,
+        )
+        body = section.group(1) if section else ""
+        admired = re.search(r"\*\*Admired:\*\*\s*(\S.*)", body)
+        refused = re.search(r"\*\*Refused:\*\*\s*(\S.*)", body)
+        missing = [
+            name for name, m in (("Admired", admired), ("Refused", refused))
+            if not m or unfilled(m.group(1))
+        ]
+        if missing:
+            findings.append(Finding(
+                "B007", SEVERITY_WARN, "voice.md", 1,
+                f"`## Voice references` is missing {', '.join(missing)} -- "
+                f"a voice with no brand it refuses to sound like has no edge "
+                f"to be checked against",
+            ))
+
     return findings
 
 
@@ -348,6 +376,12 @@ def _looks_like_copy(literal: str) -> bool:
 DIRECTIVES = {"use strict", "use client", "use server"}
 
 
+LABEL_KEY_RE = re.compile(
+    r"^(button|cta|label|title|heading|header|menu|tab|nav|placeholder"
+    r"|action|link|toggle|chip|badge)\b", re.IGNORECASE
+)
+
+
 def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
     """B020-B025 -- the registry, the code and the casing agree."""
     findings: list[Finding] = []
@@ -369,6 +403,24 @@ def check_consistency(brand_dir: Path, sources: dict) -> list[Finding]:
                 f"keeps one name across the whole flow",
             ))
 
+    # B026 -- a label is a name, not a statement, so it ends with nothing.
+    # Scoped by key prefix rather than by guessing at the text: a message may
+    # be a sentence and should be, while a button that ends in a full stop is
+    # the single most common tell that prose leaked into a control.
+    for row in rows:
+        if not LABEL_KEY_RE.match(row["key"]):
+            continue
+        text = row["text"].rstrip()
+        if not text.endswith(".") or text.endswith("..") or text.endswith("…"):
+            continue
+        if ". " in text:      # genuinely several sentences -- a different defect
+            continue
+        findings.append(Finding(
+            "B026", SEVERITY_WARN, "strings.md", 0,
+            f"`{row['key']}` ends in a full stop: \"{text}\". A label, button, "
+            f"menu item or title is a name and takes no terminal punctuation",
+        ))
+
     for row in rows:
         location = row["location"]
         file_part = location.split(":")[0]

package/plugins/super-ux/scripts/ux_lint.py

@@ -89,10 +89,10 @@ def figma_enabled(foundation: str) -> bool | None:
     return m.group(1).lower() == "enabled"
 
 
-def screen_blocks(text: str) -> dict[str, str]:
-    """Map SCR-id -> its section body (from its header to the next ### / ##)."""
+def entry_blocks(text: str, prefix: str) -> dict[str, str]:
+    """Map PREFIX-id -> its section body (from its header to the next ### / ##)."""
     out: dict[str, str] = {}
-    parts = re.split(r"^###\s+(SCR-\d+):", text, flags=re.MULTILINE)
+    parts = re.split(rf"^###\s+({prefix}-\d+):", text, flags=re.MULTILINE)
     # parts = [pre, id1, body1, id2, body2, ...]
     for i in range(1, len(parts), 2):
         sid = parts[i]
@@ -102,6 +102,77 @@ def screen_blocks(text: str) -> dict[str, str]:
     return out
 
 
+def screen_blocks(text: str) -> dict[str, str]:
+    """Map SCR-id -> its section body."""
+    return entry_blocks(text, "SCR")
+
+
+WEB_SURFACE_FIELDS = ("Route", "Answers", "Indexable", "Without JS", "Entity")
+
+
+def web_surfaces_declared(screens: str) -> bool | None:
+    """True/False from the project-level declaration; None if unstated."""
+    m = re.search(r"\*\*Web surfaces:\*\*\s*(yes|no)\b", screens, re.IGNORECASE)
+    if not m:
+        return None
+    return m.group(1).lower() == "yes"
+
+
+def check_web_surface(screens: str, flows: str) -> None:
+    """A screen a crawler will read is designed as one, or declared not to be.
+
+    The rule this enforces is decided at design time and cannot be recovered
+    by an audit: by the time a landing is live, its URL is in other people's
+    links and its structure is what an answer engine already quoted. So the
+    chain records the five things a later audit checks -- and a project with
+    no public page says so once, because a declared absence is countable and
+    an unanswered question is not.
+    """
+    declared = web_surfaces_declared(screens)
+    blocks = {
+        sid: body for sid, body in screen_blocks(screens).items()
+        if "**Web surface:**" in body
+    }
+
+    if declared is None:
+        warn(
+            "screens.md: no **Web surfaces:** declaration — answer yes or no once "
+            "(a public page a search or answer engine reads?). An unanswered "
+            "question reads as no, and this one cannot be fixed after launch"
+        )
+    elif declared is False and blocks:
+        for sid in sorted(blocks):
+            err(
+                f"screens.md: declares no web surfaces but {sid} carries a "
+                f"**Web surface:** block — one of the two is wrong"
+            )
+    elif declared is True and not blocks:
+        warn(
+            "screens.md: declares web surfaces but no screen carries a "
+            "**Web surface:** block"
+        )
+
+    for sid, body in sorted(blocks.items()):
+        for field in WEB_SURFACE_FIELDS:
+            if f"**{field}:**" not in body:
+                err(f"screens.md: {sid} web surface block is missing **{field}:**")
+
+    # A declaration of "no" is silence, so it must not be able to hide a flow
+    # that plainly starts on the web. This is the one contradiction the
+    # declaration cannot absorb.
+    if declared is False:
+        for fid, body in sorted(entry_blocks(flows, "FLW").items()):
+            m = re.search(r"\*\*Entry point:\*\*\s*(.+)", body)
+            if not m:
+                continue
+            entry = m.group(1).strip()
+            if re.match(r"https?://|/\S", entry):
+                warn(
+                    f"flows.md: {fid} starts at a URL ({entry.split()[0]}) while "
+                    f"screens.md declares no web surfaces — one of the two is wrong"
+                )
+
+
 VISION_SECTIONS = [
     "1. Essence",
     "2. Core idea",
@@ -266,6 +337,7 @@ def main() -> int:
                 warn(f"screens.md: {sid} is 'built' but has no Coverage")
 
     check_vision(ux, vision)
+    check_web_surface(screens, flows)
     check_links(ux)
 
     # --- Report ---

package/templates/brand/voice.md

@@ -56,3 +56,11 @@ Conventions rather than character. Each is decided again in
 Copied from the pack, kept here so the audit can look for it by name.
 
 <the degenerate form this voice collapses into when overdone>
+
+## Voice references
+
+<!-- Two fixed points. The refused one does most of the work: it is the only
+half that can be checked against a draft out loud ("this is the thing we said
+we would never sound like"). Required once Status leaves `draft`. -->
+- **Admired:** <brand or product, and the ONE thing it does that you want>
+- **Refused:** <brand or product, and the ONE thing it does that you refuse>

package/templates/screens.md

@@ -23,6 +23,17 @@ contract) before drawing anything; record its token file below. -->
 - **Component source:** <shared UI components dir, e.g. src/components/>
 - **Assets:** <icons/illustrations location>
 
+## Web surfaces
+
+<!-- Does this product have pages a search engine or an AI answer engine will
+read — a landing, pricing, docs, blog? Answer once, here. "no" silences the
+check; flip it to "yes" the moment a public page is designed, and give every
+public screen the **Web surface:** block shown below. This is decided at design
+time on purpose: once a page is live its URL is in other people's links and its
+structure is what an answer engine already quoted, so an audit afterwards finds
+the problem it can no longer fix. -->
+- **Web surfaces:** no
+
 ## Screens
 
 <!-- One entry per screen (see ux-contract v4 for field rules):
@@ -38,6 +49,12 @@ contract) before drawing anything; record its token file below. -->
   | empty | <trigger> | <frame deep-link> | <prompt to act> |
   | error | <trigger> | <frame deep-link> | <message + recovery> |
   | loading | <trigger> | <frame deep-link> | <skeleton/progress> |
+- **Web surface:** (only when this screen is a public URL; all five required)
+  - **Route:** </pricing — the path, readable and stable>
+  - **Answers:** <the ONE question this page answers; a second question is a second page>
+  - **Indexable:** <yes | no + why | canonical → /other-path>
+  - **Without JS:** <what a reader gets with no JS executed — the answer, or nothing>
+  - **Entity:** <schema.org type + the thing it describes, matched to visible content>
 - **Wireframe:** wireframes/SCR-01.md (optional)
 - **Coverage:** <file:line, or "none yet">
 - **Scenarios:** <SCN-… touching this screen>