super-ux 0.57.0 → 0.58.1

package/CHANGELOG.md

@@ -1,3 +1,93 @@
+## 0.58.1 — a store title is 30 characters on Google Play too, and two more stores have their limits
+
+`store-copy.md` said a Google Play title takes 50 characters. Google's metadata
+policy says 30 ("Your app title must be 30 characters or less", read
+2026-10-07), so a title written to the old figure would be cut or refused. The
+error was reported by a neighbouring writing agent's research and checked here
+against the policy page before anything changed.
+
+- **Google Play title: 30, not 50.** The limits table now cites each store's own
+  page with the date it was read.
+- **RuStore and Meta Horizon columns.** RuStore: name 30, short description 80,
+  full 4000, up to 5 search tags, no What's new limit stated (publication help
+  page); a name claiming superiority may not pass moderation (RuStore team
+  article, 2023-11-09, cited as such). Meta Horizon: name 40, short description
+  500, long description 1500 (metadata page, updated 2025-08-20). Two figures
+  passed along with the report — a RuStore name of 50 and a Horizon rule on text
+  in screenshots — were not found on the stores' pages and are not stated.
+- **"No plurals" is an English rule.** Matching of inflected forms in other
+  languages is not documented by the stores, so the rule now says to check a
+  form in the store's own search before dropping it.
+
+## 0.58.0 — the look is decided before the frames, and approved on a critique
+
+`ux-flows` picked the style pack itself, from three or four names copied out of
+a catalogue that had grown to dozens, then drew a frame for every state of
+every flow in that one guess and asked for approval of the lot. The approval
+covered the flow and the look at once, on frames nobody had critiqued. This
+release hands the visual decision to its owner and splits the approvals, from
+the family's 2026-10-07 design-pipeline plan, tasks U1–U5 plus the screen
+matrix and the onboarding budget.
+
+- **U1. `/sheleg-design` decides the look; super-ux keeps no pack list.**
+  `ux-flows` step 4, `visual-identity.md`, `/ux`, the Cursor rule, the
+  `screens.md` seed and the README now delegate to the companion's own index,
+  defaults and director record. An underdetermined brief gets **directions
+  before frames**: one key screen in one state, two directions only when the
+  fork is real (rubric first), the human picks on a 2-up mini sheet, then the
+  rest of the frames. `validate_direction_before_frames` refuses a pack name in
+  any of those seven files.
+- **U2. `Style pack: none` keeps the floor.** With sheleg-design installed its
+  `SLOP_MARKERS.md` catalogue applies pack or no pack; where code exists,
+  `npx sheleg-design-skill --lint <dir>` runs and its result is recorded;
+  companion absent or a version without `--lint` → `Markers: NOT_RUN`, never a
+  pass. `visual-identity.md`, `figma-integration.md`, `audit-depth.md`.
+- **U3. Flow approval and art-direction approval are two decisions.** Frames
+  are critiqued with `get_screenshot` against the director record's rubric
+  before approval, findings as region → defect → fix triples, one re-render
+  round (two at most), then `unresolved` to the human. The flow records
+  `Art direction: approved <date> — critique: <where>`; **`U085`** refuses an
+  approval that cites no critique or a path that does not resolve.
+- **U4. `visual-drift` in `ux-audit`.** The live pass compares the build with
+  its Figma frame in the same state, viewport and theme, under the capture
+  record of sheleg-design's `VISUAL_REVIEW.md`; an unfit or missing capture is
+  BLOCKED, never PASS. The live pass is offered by default for
+  `surface_class: flagship` or `ad`, and for landing, onboarding, paywall and
+  store screens when no class is recorded.
+- **U5. Figma is a file per surface.** `foundation.md` → Design tooling
+  records the folder and a `Figma files` table with a row per surface the
+  product has (App / Web / ASO); the "single project file" wording is gone
+  from the template, the contract, `figma-integration.md` and `ux-foundation`.
+- **Every screen declares its states and axes.** States: default, loading,
+  empty, error, offline, long-content, keyboard-up, first-run (those that
+  apply). Axes: `viewport; theme; text; locale`, per screen or as a Design
+  system default. **`U079`** (no states, Figma or not), **`U080`** (no axes or
+  one missing), **`U081`** (a built screen's state with an empty `Story`
+  cell). `U020` now finds the frame column by its header and covers every
+  declared state, not only loading / empty / error / success: a `keyboard-up`
+  row with no frame used to pass.
+- **The onboarding budget is one screen** (R2 of the Apple Design
+  Awards-derived rubric), in `onboarding.md` ON-06 and the flow contract. Flows record `Onboarding:` and `First value:`;
+  **`U082`** refuses a second screen without `Onboarding budget:` citing a
+  director record that exists and discusses onboarding; **`U083`** warns on a
+  flow named for onboarding that declares nothing; **`U084`** on a count with
+  no first value.
+- **Warn first, gate on opt-in.** Existing `screens.md` files are format 1:
+  `U079`, `U080`, `U081`, and `U020` on states beyond loading / empty / error /
+  success, report as **warnings** there, and the lint still exits 0 — what
+  `U020` failed before 0.58.0 still fails. A registry carrying
+  `<!-- screens-format: 2 -->` makes them errors; the seeded `screens.md`
+  writes the marker, so a new project is strict from its first line.
+  `docs/ux/doctor.py` names the migration on a format-1 file and `/ux-update`
+  performs it: one `- **Axes:** …` line in the Design system block, a state
+  list per screen, the lint clean of those warnings, then the marker. This
+  repository's own registry is on format 2. `--strict` still fails on every
+  warning. Measured over all 118 registries on the maintainer's machine: the first
+  cut of this release newly failed 71 of the 80 that passed; this one newly
+  fails none and adds no error anywhere.
+- Evals `EV-06` (visual drift is found) and `EV-07` (one key screen, 2-up,
+  no pack list) join `test/evals/cases.json`; not run in CI, as before.
+
 ## 0.57.0 — short video gets a playbook, a hook filter and a caption linter
 
 `copywriting` covered posts for X, Reddit and LinkedIn and nothing that moves:

package/README.md

@@ -219,7 +219,7 @@ fine without either.
 
 | When | Companion | What it adds |
 |---|---|---|
-| At VISUALIZE / BUILD, a frame or a screen is about to be drawn | **[sheleg-design](https://github.com/ssheleg/sheleg-design-skill)** | The look: one locked style pack (palette, type, texture, motion tokens, bans) with ready token CSS: `workbench` for product UI, dashboards and tools; `instrument-console`; `editorial-luxury`; or a new pack on its contract. Plus the motion methodology for cinematic scroll-driven landings. The pack is recorded in `screens.md`; its tokens become the Figma variables *and* the code tokens. `npx sheleg-design-skill` |
+| At VISUALIZE / BUILD, a frame or a screen is about to be drawn | **[sheleg-design](https://github.com/ssheleg/sheleg-design-skill)** | The look. `/sheleg-design` picks one locked style pack (palette, type, texture, motion tokens, bans) from its own index and defaults, keeps a director record of the decision, and holds a visual floor of slop markers that applies even when the answer is no pack. When the brief leaves the look open, one key screen is drawn in two directions and a person picks on a 2-up sheet before any other frame. The pack is recorded in `screens.md`; its tokens become the Figma variables *and* the code tokens. `npx sheleg-design-skill` |
 | After an audit or an Improve pass produced a UX plan | **[task-pipeline](https://github.com/ssheleg/task-pipeline)** | Executes the plan end-to-end through gated stages: spec → plan → subagent build → tests → deploy → docs. `/task-pipeline docs/ux/plans/<file>` |
 
 The boundary that keeps them from fighting: BP-079..090 and BP-130..135 are
@@ -247,7 +247,7 @@ to is a skill nobody runs.
 | skill `copywriting` | Writes in that voice and never writes *to* it: interface strings, errors, empty states, landing and pricing pages, posts and captions, short-video scripts and hooks, changelogs, store listings, ads, lifecycle email. A missing term or an unsourced number is reported, never invented |
 | `/ux` | **The one command**: sets up whatever is missing, reports status across every layer, then offers only the applicable actions with one marked recommended. Idempotent |
 | `/vision` `/ux-init` `/ux-foundation` `/ux-flows` `/ux-update` `/ux-audit` `/ux-rule` `/ux-lint` `/ux-doctor` · `/brand` `/brand-init` `/brand-update` `/brand-lint` `/copy` | Direct controls for when you know exactly what you want; `/ux-rule` installs both hard rules and seeds `lint.py` + `doctor.py`; `/brand-init` seeds `docs/brand/` and its linter |
-| `docs/ux/lint.py` + `/ux-lint` | The deterministic half: missing Figma frames, unresolved SCR/story traces, orphans, built screens without coverage, index desync, ID gaps, broken links. Stdlib-only, exit 1 on problems, so wire it into CI and drift can't merge |
+| `docs/ux/lint.py` + `/ux-lint` | The deterministic half: missing Figma frames, a screen with no states or no render axes, a built state with no story, more than one onboarding screen before the first value with no reason on file, art direction approved with no critique cited, unresolved SCR/story traces, orphans, built screens without coverage, index desync, ID gaps, broken links. Stdlib-only, exit 1 on problems, so wire it into CI and drift can't merge |
 | `cursor/rules/*.mdc` | The same methodology for Cursor: one always-on hard rule + seven agent-requested rules (vision, foundation, flows, scenarios, audit, brand voice, copywriting) |
 | `templates/` | Seeds for `docs/ux/`: the vision skeleton, foundation, flows, screens, scenario base, the folder README, and the audit-report skeleton. Both hard-rule snippets live here as their single source, `claude-rule.md` (scenario-first) and `vision-rule.md` (vision alignment), and the validator fails if a command's embedded copy drifts from them. Seeds for `docs/brand/`: voice, terminology, facts, channels, the string registry, a locale delta, and its folder README. The tree is mirrored into `plugins/super-ux/templates/` (and the seeds each skill names into that skill's own directory) by `test/sync_references.py`, so installed channels carry the seeds their texts point at; the validator refuses drift between the copies |
 
@@ -264,8 +264,8 @@ The contracts every skill reads:
 | [practice-selection.md](plugins/super-ux/skills/references/practice-selection.md) | The deterministic bridge: product profile → mandatory consideration sets → per-artifact checklists → a compliance table where every pulled practice gets a verdict. No silent skips, no cargo cult |
 | [funnel-research.md](plugins/super-ux/skills/references/funnel-research.md) | Reading a funnel market before designing one, `FR-01..FR-07`: where competitor funnels are visible, the four signals that survive when revenue is invisible, the fields that make a corpus comparable, which adjacent categories transfer, the stop before copying, and where each finding lands in the chain. Carried by `ux-foundation` and `ux-flows` |
 | [component-guidelines.md](plugins/super-ux/skills/references/component-guidelines.md) | Which control for which job (radios/select/switch, sheet/alert, modal/disclosure, combobox, nav bar/rail, FAB, dates, toasts) and the platform rules of Apple HIG, Material 3, W3C ARIA APG and GOV.UK |
-| [visual-identity.md](plugins/super-ux/skills/references/visual-identity.md) | The visual layer and its owner: one style pack for the whole product, where it's recorded, how it meets Figma and code, and the division of labor with the craft floors |
-| [figma-integration.md](plugins/super-ux/skills/references/figma-integration.md) · [figma-structure.md](plugins/super-ux/skills/references/figma-structure.md) | The optional Figma surface (on by default): when and how to mock up, and how to structure the file so frames named `SCR-NN/<Screen>/<state>` map 1:1 to `screens.md`, giving deterministic lookup and checkable drift |
+| [visual-identity.md](plugins/super-ux/skills/references/visual-identity.md) | The visual layer and its owner: `/sheleg-design` decides the one style pack, directions come before frames when the brief leaves the look open, the slop-marker floor holds even with no pack, and how the pack meets Figma and code |
+| [figma-integration.md](plugins/super-ux/skills/references/figma-integration.md) · [figma-structure.md](plugins/super-ux/skills/references/figma-structure.md) | The optional Figma surface (on by default): one file per surface (App, Web, ASO), frames critiqued against the director record before anyone approves the look, flow and art direction approved separately, and frames named `SCR-NN/<Screen>/<state>` that map 1:1 to `screens.md`, giving deterministic lookup and checkable drift |
 
 ## Keeping installs current
 

package/cursor/rules/ux-flows.mdc

@@ -25,9 +25,13 @@ recovery edges), `Screens traversed` table (`| Screen | States used here |`
 
 Each screen entry in `screens.md`: `Used by`, `Purpose`, `Elements` (mark
 the ONE primary action), `States` table (`| State | Trigger | Figma frame |
-Behavior |` — a row per loading/empty/error/success that applies),
+Story | Behavior |` — a row per default/loading/empty/error/offline/
+long-content/keyboard-up/first-run state that applies), `Axes`
+(viewport; theme; text; locale — or the Design system default),
 `Wireframe`, `Coverage` (file:line), `Scenarios`, `Resources`, `Status`
-(designed|built|drifted|retired).
+(designed|blocked|built|drifted|retired). A flow that onboards records
+`Onboarding:` and `First value:`; the budget is one screen before the first
+value unless the director record says why.
 
 ## Design rules
 
@@ -40,20 +44,23 @@ Behavior |` — a row per loading/empty/error/success that applies),
   primary action, not pixels); storyboard only when usage context drives
   design.
 - Visual identity BEFORE any frame: `screens.md` → Design system →
-  `Style pack`. Empty and no design system in the project → pick a pack with
-  the **sheleg-design** companion skill (`workbench` for product UI /
-  dashboards / tools, `instrument-console`, `editorial-luxury`, or a new
-  pack on its contract; cinematic scroll pages also take its motion
-  methodology) and record the pack + token file. Missing → offer the
-  one-time install once (`npx sheleg-design-skill`) and continue on platform
-  defaults; recommend, don't force. The pack owns palette/type/motion and
-  its bans; BP-079..090 stay the floors it must clear. Never invent a look
-  per screen.
-- Figma mockups optional (default on): if the foundation's Design tooling
-  enables Figma and a Figma MCP is available, mirror each screen into a
-  frame built on the pack's tokens (they become the Figma variable
-  collections) applying visual-craft practices (BP-079..090), and link every
-  screen row to its frame; ask the user once at the start of design.
+  `Style pack`. Empty and no design system in the project →
+  `/sheleg-design` decides from its own pack index and defaults and keeps
+  the director record; record the pack + token file. A brief that leaves
+  the look open gets directions first: one key screen in one state, two
+  directions only when the fork is real, the human picks on a 2-up sheet,
+  then the rest. Missing → offer the one-time install once
+  (`npx sheleg-design-skill`) and continue on platform defaults; `none`
+  still keeps the sheleg-design slop-marker floor where it is installed.
+  The pack owns palette/type/motion and its bans; BP-079..090 stay the
+  floors it must clear. Never invent a look per screen.
+- Figma mockups optional (default on): one Figma file per surface (App /
+  Web / ASO). If the foundation's Design tooling enables Figma and a Figma
+  MCP is available, mirror each screen-state into a frame built on the
+  pack's tokens applying BP-079..090, and link every state to its frame.
+  Critique the frames with `get_screenshot` (region → defect → fix) before
+  approval; the art direction is approved separately from the flow and the
+  approval cites the critique.
 - Backwards mode (existing product): reconstruct flows as they ARE from
   code with file:line evidence, tag `inferred` until confirmed; gaps
   between is/should become the improvement backlog.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.57.0",
+  "version": "0.58.1",
   "scripts": {
     "test": "python3 test/validate.py && python3 test/brand_lint_test.py && python3 test/display_copy_test.py && python3 test/ux_lint_test.py && python3 docs/ux/lint.py && python3 docs/brand/lint.py && node test/installer_test.js && npm run test:audit",
     "test:audit": "for t in test/audit_regressions/*.py; do python3 \"$t\" || exit 1; done"

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

@@ -40,6 +40,19 @@ ADDITIVE = [
 
 ARTIFACTS = ["vision.md", "foundation.md", "flows.md", "screens.md", "scenarios.md"]
 
+# `screens.md` format 2 (0.58.0): the screen matrix — a state list and render
+# axes per screen, a frame for every declared state, a story per state once
+# built — is a gate. Format 1 gets the same findings as lint warnings. The
+# upgrade is content, so the doctor names it and never stamps the marker.
+SCREENS_FORMAT = re.compile(r"<!--\s*screens-format:\s*(\d+)\s*-->")
+SCREENS_MIGRATION = (
+    "screens.md is on format 1: U079/U080/U081 (and U020 for states beyond "
+    "loading/empty/error/success) are lint warnings, not a gate. To migrate: "
+    "add `- **Axes:** viewport: …; theme: …; text: …; locale: …` to the Design "
+    "system block, give every screen a state list, run the linter until those "
+    "warnings are gone, then add `<!-- screens-format: 2 -->` under the title."
+)
+
 # Names the contract owns, and the near-misses seen in the wild.
 RENAMES = {
     "ux-scenarios.md": "scenarios.md",
@@ -89,7 +102,13 @@ def diagnose(ux: Path) -> dict:
         if f.exists() and needle not in f.read_text(encoding="utf-8", errors="ignore"):
             missing_additive.append(label)
 
+    screens_format = None
+    if present.get("screens.md"):
+        m = SCREENS_FORMAT.search((ux / "screens.md").read_text(encoding="utf-8", errors="ignore"))
+        screens_format = int(m.group(1)) if m else 1
+
     return {
+        "screens_format": screens_format,
         "present": present,
         "markers": markers,
         "effective": min(known) if known else None,
@@ -148,6 +167,9 @@ def report(ux: Path, d: dict) -> int:
     for label in d["missing_additive"]:
         print(f"  optional, absent: {label}")
 
+    if d.get("screens_format") == 1:
+        print(f"  migration offered: {SCREENS_MIGRATION}")
+
     print("  OK — on the current contract" if problems == 0 else f"  {problems} problem(s)")
     return problems
 
@@ -222,6 +244,8 @@ def main() -> int:
             flags.append("loose-audits")
         if d["audits"] and not d["present"].get("scenarios.md"):
             flags.append("audits-without-base")
+        if d.get("screens_format") == 1:
+            flags.append("screens-format-1")
         print(f"{ux}  {state}{'  ' + ','.join(flags) if flags else ''}")
         return 0
 

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

@@ -136,6 +136,121 @@ CITED_PATH = re.compile(
 )
 
 
+# The four axes a screen is rendered across, by the names the contact sheet
+# uses for its columns. A fifth axis is allowed; these four are required.
+AXES = ("viewport", "theme", "text", "locale")
+AXES_FIELD = re.compile(r"\*\*Axes:\*\*[ \t]*(.*)")
+
+# A cell or value that is still the template's placeholder, or a dash, says
+# nothing — the same as an empty cell.
+def _unfilled(value: str) -> bool:
+    v = value.strip()
+    return (not v or v in ("-", "—", "–")
+            or bool(re.fullmatch(r"<[^>]*>", v)))
+
+
+def state_table(body: str) -> tuple[list[str], list[list[str]]]:
+    """(lower-cased headers, rows) of a screen's States table, found by header.
+
+    The table is the one whose first header cell is `State`. Columns are read
+    by their header name, never by their position after the state name — the
+    position is what let U020 read a `Behavior` cell as a frame link.
+    """
+    lines = body.splitlines()
+    for i, line in enumerate(lines):
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if not line.strip().startswith("|") or not cells or cells[0].lower() != "state":
+            continue
+        headers = [c.lower() for c in cells]
+        rows: list[list[str]] = []
+        for row in lines[i + 1:]:
+            s = row.strip()
+            if not s.startswith("|"):
+                break
+            if re.fullmatch(r"\|[\s:|-]+\|?", s):
+                continue  # the separator row
+            rows.append([c.strip() for c in s.strip("|").split("|")])
+        return headers, rows
+    return [], []
+
+
+def declared_states(body: str) -> list[str]:
+    """State names a screen declares — its table rows, or an inline list."""
+    _, rows = state_table(body)
+    names = [r[0] for r in rows if r and r[0]]
+    if names:
+        return names
+    m = re.search(r"\*\*States:\*\*[ \t]*([^\n|]+)$", body, re.MULTILINE)
+    if m and not _unfilled(m.group(1)):
+        return [s.strip() for s in re.split(r"[,;]", m.group(1)) if s.strip()]
+    return []
+
+
+def axes_value(text: str) -> str | None:
+    """The `**Axes:**` value in a block, wrapped lines joined; None when absent."""
+    value = field_body(text, AXES_FIELD)
+    return None if value is None else " ".join(value.split())
+
+
+def missing_axes(value: str) -> list[str]:
+    """Which of the four required axes a declaration leaves out or leaves blank."""
+    found: dict[str, str] = {}
+    for part in value.split(";"):
+        if ":" not in part:
+            continue
+        name, _, val = part.partition(":")
+        found[name.strip().lower()] = val
+    return [a for a in AXES if _unfilled(found.get(a, ""))]
+
+
+# The registry format a `screens.md` opted into. Format 2 (0.58.0) makes the
+# screen matrix -- states, axes, stories, a frame for every declared state --
+# a gate; format 1 reports the same findings as warnings, because turning them
+# on as errors newly failed 71 of 80 passing real registries on upgrade. The marker is an
+# HTML comment, so it is read from the RAW file: `read()` strips comments.
+SCREENS_FORMAT = re.compile(r"<!--\s*screens-format:\s*(\d+)\s*-->")
+FORMAT_HINT = (" (a warning while screens.md is format 1 — add the missing "
+               "fields, then `<!-- screens-format: 2 -->` to make it a gate)")
+
+
+def screens_format(path: Path) -> int:
+    """1 unless the file carries `<!-- screens-format: N -->`."""
+    try:
+        m = SCREENS_FORMAT.search(path.read_text(encoding="utf-8"))
+    except OSError:
+        return 1
+    return int(m.group(1)) if m else 1
+
+
+def legacy_frameless(body: str) -> set[str]:
+    """The states the pre-0.58 U020 flagged: one of four names, cell read by
+    position. Kept so a format-1 registry fails exactly where it always did."""
+    out = set()
+    for state, rest in re.findall(r"^\s*\|\s*(loading|empty|error|success)\s*\|(.*)\|\s*$",
+                                  body, re.MULTILINE | re.IGNORECASE):
+        cells = [c.strip() for c in rest.split("|")]
+        frame = cells[1] if len(cells) >= 2 else ""
+        if not frame or frame in ("-", "—", "<frame deep-link>", "<frame link>"):
+            out.add(state.lower())
+    return out
+
+
+def section(text: str, heading: str) -> str:
+    """The body of `## <heading>` up to the next `## `, or ''."""
+    m = re.search(rf"^##[ \t]+{re.escape(heading)}[ \t]*$", text, re.MULTILINE)
+    if not m:
+        return ""
+    return re.split(r"^##\s", text[m.end():], maxsplit=1, flags=re.MULTILINE)[0]
+
+
+def resolves(ref: str, ux: Path, root: Path) -> bool:
+    """A cited local path exists — relative to the project root or to docs/ux."""
+    path = ref.split("#", 1)[0].strip()
+    if not path:
+        return False
+    return (root / path).exists() or (ux / path).exists()
+
+
 def screen_blocks(text: str) -> dict[str, str]:
     """Map SCR-id -> its section body."""
     return entry_blocks(text, "SCR")
@@ -737,6 +852,70 @@ HOST_TARGET = {"claude": "CLAUDE.md", "codex": "AGENTS.md", "gemini": "GEMINI.md
 HOST_MARKER = {"claude": ".claude", "codex": ".codex", "gemini": ".gemini"}
 
 
+# The onboarding budget (R2 of the design-award rubric): at most one onboarding screen before
+# the first value. A flow states the count in `Onboarding:` and the destination
+# in `First value:`; more than one screen needs `Onboarding budget:` pointing at
+# the director record that says why. The linter checks the record exists and
+# talks about onboarding — whether the reason is good is a person's call.
+ONBOARDING_NAME = re.compile(r"onboarding|first[- ]run|онбординг", re.IGNORECASE)
+LOCAL_REF = re.compile(r"(?<![\w/])([\w.-]+(?:/[\w.-]+)+\.[A-Za-z]{1,5}(?:#[\w-]+)?)")
+
+
+def check_onboarding(flows: str, ux: Path, root: Path) -> None:
+    names = {fid: name for fid, _, name in entry_names(flows, "FLW")}
+    for fid, body in entry_blocks(flows, "FLW").items():
+        declared = field_body(body, re.compile(r"\*\*Onboarding:\*\*[ \t]*(.*)"))
+        if declared is None:
+            if ONBOARDING_NAME.search(names.get(fid, "")):
+                warn(f"[U083] flows.md: {fid} reads as onboarding and declares no "
+                     f"**Onboarding:** — list the screens before the first value "
+                     f"(or `none`) so the budget can be counted")
+            continue
+        count = len(set(re.findall(r"\bSCR-\d+\b", declared)))
+        first = field_body(body, re.compile(r"\*\*First value:\*\*[ \t]*(.*)"))
+        if not stated(first):
+            warn(f"[U084] flows.md: {fid} counts onboarding screens and names no "
+                 f"**First value:** — the budget is counted against a destination "
+                 f"nobody wrote down")
+        if count <= 1:
+            continue
+        budget = field_body(body, re.compile(r"\*\*Onboarding budget:\*\*[ \t]*(.*)")) or ""
+        ref = LOCAL_REF.search(budget)
+        if not ref:
+            err(f"[U082] flows.md: {fid} puts {count} onboarding screens before the "
+                f"first value — the budget is one; more needs **Onboarding budget:** "
+                f"citing the director record that justifies it")
+        elif not resolves(ref.group(1), ux, root):
+            err(f"[U082] flows.md: {fid} cites '{ref.group(1)}' for its onboarding "
+                f"budget, which does not exist")
+        else:
+            record = (root / ref.group(1).split("#")[0])
+            if not record.exists():
+                record = ux / ref.group(1).split("#")[0]
+            if "onboarding" not in read(record).lower():
+                err(f"[U082] flows.md: {fid} cites '{ref.group(1)}' for its onboarding "
+                    f"budget and the record never mentions onboarding")
+
+
+# Flow approval and art-direction approval are two decisions. The second is made
+# on frames that were critiqued first, so an approval names the critique it
+# read — a director record section, a file, or a link — and a local one resolves.
+def check_art_direction(flows: str, ux: Path, root: Path) -> None:
+    for fid, body in entry_blocks(flows, "FLW").items():
+        value = field_body(body, re.compile(r"\*\*Art direction:\*\*[ \t]*(.*)"))
+        if not value or not value.strip().lower().startswith("approved"):
+            continue
+        if re.search(r"https?://\S+", value):
+            continue
+        ref = LOCAL_REF.search(value)
+        if not ref:
+            err(f"[U085] flows.md: {fid} records art direction approved and cites no "
+                f"critique — the approval names the frame critique it was made on")
+        elif not resolves(ref.group(1), ux, root):
+            err(f"[U085] flows.md: {fid} cites '{ref.group(1)}' as its critique, "
+                f"which does not exist")
+
+
 def active_hosts(root: Path) -> list[str]:
     """Hosts present in this project, by their marker directory. When none is
     detectable the target defaults to Claude, matching the seed default."""
@@ -971,6 +1150,15 @@ def main() -> int:
     if has_screens:
         fig = figma_enabled(foundation)
         screens_root = project_root
+        default_axes = axes_value(section(screens, "Design system"))
+        gated = screens_format(ux / "screens.md") >= 2
+
+        def matrix(msg: str) -> None:
+            """U079-U081 and the widened U020: errors on format 2, warnings before."""
+            if gated:
+                err(msg)
+            else:
+                warn(msg + FORMAT_HINT)
         for sid, body in screen_blocks(screens).items():
             # Read by value, not matched against a copy of the enum: the copy
             # was one value short of the contract for as long as `blocked`
@@ -979,15 +1167,57 @@ def main() -> int:
             status = declared_status(body)
             if status == "retired":
                 continue
-            # every state row present in the States table
-            state_rows = re.findall(r"^\s*\|\s*(loading|empty|error|success)\s*\|(.*)\|\s*$",
-                                    body, re.MULTILINE | re.IGNORECASE)
+            # The state list is required whatever the tooling: it is the rows of
+            # the contact sheet, and a screen with none is reviewed in the one
+            # state somebody happened to render.
+            states = declared_states(body)
+            if not states:
+                matrix(f"[U079] screens.md: {sid} declares no states — list the ones "
+                    f"that apply (default, loading, empty, error, offline, "
+                    f"long-content, keyboard-up, first-run)")
+            # Axes are the sheet's columns. A screen may inherit the project's
+            # default from the Design system block, and override it.
+            axes = axes_value(body)
+            if axes is None:
+                axes = default_axes
+            if axes is None:
+                matrix(f"[U080] screens.md: {sid} declares no **Axes:** and the Design "
+                    f"system sets no default — name viewport, theme, text and locale")
+            else:
+                gaps = missing_axes(axes)
+                if gaps:
+                    matrix(f"[U080] screens.md: {sid} axes leave out {', '.join(gaps)} — "
+                        f"write `name: values` for each of {', '.join(AXES)}")
+            headers, rows = state_table(body)
+            frame_col = next((i for i, h in enumerate(headers)
+                              if "figma" in h or "frame" in h), None)
+            story_col = next((i for i, h in enumerate(headers)
+                              if re.search(r"\b(?:stor(?:y|ies)|preview)\b", h)), None)
             if fig is not False:  # enabled or default-on
-                for state, rest in state_rows:
-                    cells = [c.strip() for c in rest.split("|")]
-                    frame = cells[1] if len(cells) >= 2 else ""
-                    if not frame or frame in ("-", "—", "<frame deep-link>", "<frame link>"):
-                        err(f"[U020] screens.md: {sid} state '{state}' has no Figma frame link")
+                frameless: list[str] = []
+                if rows:
+                    for row in rows:
+                        frame = row[frame_col] if frame_col is not None and frame_col < len(row) else ""
+                        if _unfilled(frame):
+                            frameless.append(row[0])
+                else:
+                    frameless = list(states)
+                # What the old rule caught stays an error on every format;
+                # only the newly covered states wait for the opt-in.
+                legacy = legacy_frameless(body)
+                for state in legacy:
+                    err(f"[U020] screens.md: {sid} state '{state}' has no Figma frame link")
+                for state in frameless:
+                    if state.lower() not in legacy:
+                        matrix(f"[U020] screens.md: {sid} state '{state}' has no Figma frame link")
+            # A Story column is the build-side twin of the frame: once a screen
+            # is built, each state it declares can be shown on its own.
+            if story_col is not None and status == "built":
+                for row in rows:
+                    story = row[story_col] if story_col < len(row) else ""
+                    if _unfilled(story):
+                        matrix(f"[U081] screens.md: {sid} is built and state '{row[0]}' "
+                            f"names no story — the state cannot be rendered on its own")
             cov_m = re.search(r"\*\*Coverage:\*\*\s*(.+)", body)
             cov = cov_m.group(1).strip() if cov_m else ""
             if status == "built" and (not cov or cov.lower().startswith("none")):
@@ -1023,6 +1253,8 @@ def main() -> int:
     check_jobs(foundation, scenarios, flows, screens)
     check_vision(ux, vision)
     check_web_surface(screens, flows)
+    check_onboarding(flows, ux, project_root)
+    check_art_direction(flows, ux, project_root)
     check_links(ux)
 
     # --- Report ---

package/templates/flows.md

@@ -10,6 +10,10 @@ node and edge. -->
 - **Goal:** <observable end state for the user>
 - **Entry points:** <all of them: screen, deep link, push, empty-state CTA>
 - **Success exit:** <where the user lands on success>
+- **First value:** <SCR-ID / step where the user first gets what they came for>
+- **Onboarding:** <SCR-IDs shown before the first value, or none; budget is one>
+- **Onboarding budget:** <only past one screen: the director record that justifies it>
+- **Art direction:** <pending | approved YYYY-MM-DD — critique: <record#critique or link>>
 - **Task analysis:**
   1. <user-visible micro-step; cut everything that doesn't serve the job>
 - **Flow:**

package/templates/foundation.md

@@ -50,11 +50,18 @@ even when the answer is "none":
 ## Design tooling
 
 <!-- Visual mockups in Figma are optional (default on). Ask the user at the
-start of design; record the choice here (see figma-integration). The Figma
-file and design-system details live in docs/ux/screens.md (the UI map);
-this section just records the on/off choice and the file location.
+start of design; record the choice here (see figma-integration). Figma is a
+set of files in the product's folder, one per surface the product has; the
+design-system details and frame links live in docs/ux/screens.md (the UI
+map). This section records the on/off choice and where the files are.
 - **Figma:** enabled | disabled
-- **Figma file:** <url — one project file, one page per feature/flow group>
+- **Figma folder:** <team / project the product's files live in>
+- **Figma files:**
+  | Surface | File | Holds |
+  |---------|------|-------|
+  | App | <url> | every SCR-NN frame of the product |
+  | Web | <url> | landing, pricing, docs pages |
+  | ASO | <url> | store screenshots, icon, preview frames |
 -->
 
 ## User stories

package/templates/screens.md

@@ -1,5 +1,9 @@
 # UI Screen Registry
 
+<!-- screens-format: 2 -->
+<!-- The line above puts this registry on format 2: the screen matrix
+(states, axes, a frame per state, a story per built state) is a lint gate.
+Keep it. -->
 <!-- Managed with super-ux (ux-contract v4). The design map: every screen and
 state with its Figma frame, wireframe, code coverage, and related UX/UI
 resources. Update in the same change as any interface change; when Figma is
@@ -14,10 +18,14 @@ whose code diverges from its record here is a "drifted" finding. -->
 ## Design system
 
 <!-- Style pack = the locked visual identity every frame and built screen obeys.
-Pick it with the sheleg-design companion skill (workbench for product UI /
-dashboards / tools, instrument-console, editorial-luxury, or a new pack on its
-contract) before drawing anything; record its token file below. -->
-- **Style pack:** <pack name, or "none — platform defaults">
+/sheleg-design chooses it from its own pack index and defaults, before any
+frame is drawn (directions first when the brief leaves the look open), and
+writes the director record. "none" declines a pack, not the slop-marker
+floor. Axes = the columns every screen is reviewed across; a screen's own
+**Axes:** line overrides this default. -->
+- **Style pack:** <the pack /sheleg-design chose, or "none — platform defaults">
+- **Director record:** <docs/design/<surface>/director-record.md, or "none">
+- **Axes:** viewport: <widths>; theme: <light, dark, …>; text: <default, 200%, …>; locale: <locales>
 - **Figma library:** <url/name, or "none — platform defaults">
 - **Tokens in code:** <where color/type/spacing tokens live, e.g. src/theme/tokens.ts>
 - **Component source:** <shared UI components dir, e.g. src/components/>
@@ -42,13 +50,15 @@ the problem it can no longer fix. -->
 - **Used by:** <FLW-… and the step(s)>
 - **Purpose:** <the job step this screen serves>
 - **Elements:** <each element; mark the ONE primary action>
-- **States:**
-  | State | Trigger | Figma frame | Behavior |
-  |-------|---------|-------------|----------|
-  | success | default | <frame deep-link> | <what shows> |
-  | empty | <trigger> | <frame deep-link> | <prompt to act> |
-  | error | <trigger> | <frame deep-link> | <message + recovery> |
-  | loading | <trigger> | <frame deep-link> | <skeleton/progress> |
+- **States:** (every one that applies: default, loading, empty, error,
+  offline, long-content, keyboard-up, first-run, product-specific ones)
+  | State | Trigger | Figma frame | Story | Behavior |
+  |-------|---------|-------------|-------|----------|
+  | default | <trigger> | <frame deep-link> | <story/preview, once built> | <what shows> |
+  | empty | <trigger> | <frame deep-link> | <story> | <prompt to act> |
+  | error | <trigger> | <frame deep-link> | <story> | <message + recovery> |
+  | loading | <trigger> | <frame deep-link> | <story> | <skeleton/progress> |
+- **Axes:** (only when this screen differs from the Design system default)
 - **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>