@godxjp/ui 33.7.1 → 33.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "33.7.1",
-  "godxUiMcp": "33.7.1",
+  "version": "33.8.0",
+  "godxUiMcp": "33.8.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
     "LICENSE",
     "DESIGN.md",
     "agent",
+    "skills",
     "dist",
     "scripts/ui-audit.mjs",
     "scripts/prune-css.mjs",

package/scripts/ui-audit.mjs

@@ -235,7 +235,8 @@ const PALETTE =
  * Followed by U+FE0F they are asking for emoji presentation on purpose, and then they ARE emoji —
  * so that spelling is still caught.
  */
-const EMOJI = /\p{Extended_Pictographic}\uFE0F|(?=\p{Extended_Pictographic})\p{Emoji_Presentation}/u;
+const EMOJI =
+  /\p{Extended_Pictographic}\uFE0F|(?=\p{Extended_Pictographic})\p{Emoji_Presentation}/u;
 /** Regional-indicator pairs = emoji flags (🇯🇵) — broken on Win/Linux; use Intl.DisplayNames. */
 const EMOJI_FLAG = /\p{Regional_Indicator}/u;
 
@@ -995,7 +996,9 @@ const RULES = [
     scope: "consumer",
     severity: "warn",
     spansElement: true,
-    matches: (source) => densityMatches(source, ["Card"], CARD_LIMIT),
+    // A dashboard's tiles ARE its surfaces — the same path test kpi-row-off-dashboard uses.
+    matches: (source, rel = "") =>
+      /dashboard/i.test(rel) ? [] : densityMatches(source, ["Card"], CARD_LIMIT),
     message: `${CARD_LIMIT}+ Cards in one file — a Card per section. Mark sections with a Heading and section spacing (PageContainer children, Flex gap="lg"); keep Card for a real boundary (a table surface, a selectable item).`,
   },
   {
@@ -1055,7 +1058,8 @@ const RULES = [
     scope: "consumer",
     severity: "warn",
     spansElement: true,
-    matches: (source) => densityMatches(source, ["Alert"], ALERT_LIMIT),
+    // An Alert behind a condition IS a state (what the message asks Alerts to be); count the standing ones.
+    matches: (source) => densityMatches(source, ["Alert"], ALERT_LIMIT, { skipConditional: true }),
     message: `${ALERT_LIMIT}+ Alerts in one file. An Alert is for a state that blocks or changes the task; field errors belong in FormField, results in a toast, and standing info in plain text.`,
   },
 ];
@@ -1810,9 +1814,45 @@ function* mixedButtonSizeMatches(source) {
 }
 
 /** One finding per file, at the `limit`-th occurrence of any tag in `tags`, naming the count. */
-function* densityMatches(source, tags, limit) {
+/**
+ * The JS token before a JSX element, as the expression that places it: `?` / `:` (a ternary
+ * branch), `&&` / `||` (a guard), `=>` (a callback, e.g. `.map`), `return`, or "" when the element
+ * is a plain JSX child. An opening `(` is skipped — `cond ? (\n  <Alert` reads as `?`.
+ */
+function placementBefore(source, index) {
+  let i = index - 1;
+  while (i >= 0 && (/\s/.test(source[i]) || source[i] === "(")) i -= 1;
+  if (source[i] === "?" || source[i] === ":") return source[i];
+  if (source.slice(i - 1, i + 1) === "&&" || source.slice(i - 1, i + 1) === "||") return "&&";
+  if (source.slice(i - 1, i + 1) === "=>") return "=>";
+  if (/\breturn$/.test(source.slice(Math.max(0, i - 5), i + 1))) return "return";
+  return "";
+}
+
+/**
+ * ≥limit elements of `tags` that can be on screen TOGETHER. Mutually exclusive branches of one state
+ * count once: the else branch of a ternary (`a ? <X/> : <X/>`) is the same slot as its `?` branch,
+ * and a function that returns the element from several `if`s returns ONE of them — gino-cloud's
+ * 実習生詳細 had 6 Badge tags and showed at most 3. `skipConditional` drops elements behind a
+ * condition altogether (a guard, a ternary, a `.map`).
+ */
+function* densityMatches(source, tags, limit, { skipConditional = false } = {}) {
   const hits = [];
-  for (const { tag, index } of jsxElements(source)) if (tags.includes(tag)) hits.push(index);
+  const returnedIn = new Set(); // function starts that already returned one of `tags`
+  for (const { tag, index } of jsxElements(source)) {
+    if (!tags.includes(tag)) continue;
+    const how = placementBefore(source, index);
+    if (skipConditional && (how === "?" || how === ":" || how === "&&" || how === "=>")) continue;
+    if (how === ":") continue;
+    if (how === "return" || how === "?") {
+      const head = source.slice(0, index);
+      const arrows = [...head.matchAll(/=>\s*\{/g)];
+      const fn = Math.max(head.lastIndexOf("function "), arrows.at(-1)?.index ?? -1);
+      if (returnedIn.has(fn)) continue;
+      returnedIn.add(fn);
+    }
+    hits.push(index);
+  }
   if (hits.length >= limit) yield { 0: `${hits.length} in this file`, index: hits[limit - 1] };
 }
 

package/skills/godxjp-ui-design/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: godxjp-ui-design
+description: Design do/don't rules for @godxjp/ui interfaces, learned from real review feedback. Use when designing, redesigning, or reviewing any web UI built with @godxjp/ui — pages, app shells, topbars, status chips. Grows as reviewers flag issues.
+---
+
+# @godxjp/ui — Design Do / Don't
+
+Concrete rules for interfaces built with `@godxjp/ui`, accumulated from actual reviewer feedback —
+treat each as a hard rule. Combine them with the `@godxjp/ui` MCP authority (`search_components`,
+`get_component`, `list_anti_ai_tells`, `list_redesign_checks`) and industry patterns for the
+surface being designed.
+
+Sibling skills: `godxjp-ui-form` (forms and inputs), `godxjp-ui-navigation`.
+
+## DO
+
+- **Status chips / labels never wrap to a second line.** A `Badge` must stay on ONE line — icon +
+  text inline, never the icon stacked above the text. Pass a leading icon through the Badge `icon`
+  prop as a *component reference* (`icon={BadgeCheck}`), NEVER as an inline child
+  (`<Badge><BadgeCheck/> 確認済み</Badge>` column-stacks and wraps). This is `@godxjp/ui` cardinal
+  rule #35 ("Status chips never wrap"). It applies to every verified/pending/active-style chip on
+  every surface.
+
+## DON'T
+
+- **Don't give a sticky top bar a semi-transparent background + `backdrop-filter`.** A
+  `position: sticky` topbar with `background: hsl(var(--background) / 0.96)` +
+  `backdrop-filter: blur/saturate` samples and tints from whatever renders behind it — colourful
+  content scrolling underneath, or the browser's red automation/debug banner — so the bar picks up
+  a stray pink/red wash. Use a FULLY OPAQUE background (`hsl(var(--background))`, no alpha, no
+  `backdrop-filter`) so the bar is always clean whatever is behind it.
+
+- **Don't strip the signed-in user's profile (avatar + name) from the global topbar / header.** It
+  is the orientation anchor — the user must always see *who they are signed in as* in the top
+  right, even when the page body already has its own identity hero. Leaving only a locale switcher
+  + "Sign out" makes the topbar look empty or broken. Keep the profile chip (avatar + name) in the
+  `Topbar` `end` slot; the page hero is additive, not a replacement.

package/skills/godxjp-ui-form/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: godxjp-ui-form
+description: Rules for building forms with @godxjp/ui. Use when creating or changing any form, create/edit screen, or labelled input in an app that installs the @godxjp/ui npm package. Covers page-not-modal, mandatory Form + FormField, content-sized input widths (GOV.UK Design System), and the escape hatch (open an issue on the library instead of hand-rolling). Not for apps that vendored their own copy of the components and have their own form rules.
+---
+
+# Form rules (@godxjp/ui)
+
+> Applies only to apps that install the `@godxjp/ui` npm package. **Out of scope:** apps that
+> vendored their own copy of the components into their source tree — they have no MCP server and
+> no `node_modules/@godxjp/ui`, and follow their own form and input-width rules.
+
+Seven rules, each distilled from defects MEASURED in a production app and approved one by one by
+its owner. A violation is a bug, not a style preference.
+
+Sibling skills: `godxjp-ui-design` (visual do/don't rules), `godxjp-ui-navigation`.
+
+## 1. A form with 3 or more fields is its own PAGE, not a modal
+
+Give it its own route (for example a TanStack file route with a trailing `_` so it does not nest:
+`accounts_.new.tsx`; in an Inertia app, a shell route `Inertia::render('<page>')` that passes NO
+data, with the page fetching from the API itself).
+A `Sheet`/drawer is also an overlay and does NOT replace a page — even though `dialog-form-too-big`
+does not catch a `Sheet`.
+Inlining a create form as a `Card` **above the list** is also forbidden (one app had seven screens
+rejected for it). The "Create" button in the page header `extra` leads to a `…/new` route; after
+saving, return to the detail page or the list.
+A `Dialog` is ONLY for: confirmations (delete…), very short 1–2 field forms (editing a signature),
+and quick pickers. As the owner put it: "I really hate opening things in a modal — a page with a
+lot of content must be created as its own page."
+
+## 2. ALWAYS wrap in `<Form>` — no orphan FormField, no bare control
+
+```tsx
+<Form layout="horizontal" labelWidth="11rem" controlWidth="28rem" asChild>
+  <Flex direction="col" gap="md">
+    <FormField id="…" label={…} required>…</FormField>
+  </Flex>
+</Form>
+```
+- Desktop default is `layout="horizontal"` (label on the left — the antd convention); the kit
+  collapses to vertical below a breakpoint on its own (`collapseBelow`). Do NOT write your own
+  media query.
+- Use `asChild` when the form element is owned by another library, or when submitting through a
+  button `onClick`.
+- `required` on `FormField` adds the `*` itself — do not draw your own.
+
+## 3. Size inputs to their CONTENT (GOV.UK Design System)
+
+"Make text inputs the right size for the content they're intended for" —
+https://design-system.service.gov.uk/components/text-input/
+- Cap for the whole form: `controlWidth="28rem"` on `<Form>` (about 45 Latin characters).
+- Override per field (`controlWidth` on `FormField`) when the length is KNOWN: a port `7rem`, an
+  enum of 2–3 options `10rem`, a short name / preset `14rem`, a textarea for a Japanese letter
+  `36rem`.
+- Never let a 2-option select stretch to full width — the owner caught this one by hand.
+
+## 4. Do NOT lay out fields yourself
+
+Do not wrap `FormField`s in a hand-rolled horizontal `Flex` row (labels misalign at the top — a
+measured bug). To weld several controls into ONE row under ONE label, use `<Flex attached>` (the
+former `SpaceCompact`) inside a single `FormField`, with each control keeping its own
+`aria-label`. For a grid of fields, use `<Form columns={2}>` (a `ResponsiveGrid`), not your own grid.
+
+## 5. Discovery before writing JSX
+
+Call `search_components` (MCP) or read `node_modules/@godxjp/ui/docs/` FIRST.
+Neighbouring code is not the standard — it may be a bug nobody has caught yet.
+
+## 6. Gates after writing
+
+`node node_modules/@godxjp/ui/scripts/ui-audit.mjs <files>` must report 0 errors, together with
+the repository's own type-check, tests and build. The audit enforces these rules through
+`bare-control-needs-formfield`, `formfield-needs-form`, `dialog-form-too-big` and
+`select-width-hint`; when the kit ships further rules, the audit takes over more of this list.
+
+## 7. Escape hatch = OPEN AN ISSUE, do not hand-roll
+
+When `Form` / `FormField` / `<Flex attached>` cannot cover a case (a layout the kit does not
+support, a missing prop, an audit rule that blocks wrongly), do NOT hand-roll a workaround. Open an
+issue on the @godxjp/ui repository (`godx-jp/godxjp-ui`) describing the use case and the proposed
+API, then either wait or use the closest kit-valid approach with a `// TODO(godxjp-ui#<n>)`
+comment. Fix it upstream, not at the call site.

package/skills/godxjp-ui-navigation/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: godxjp-ui-navigation
+description: Navigation design rules (sidebar menu, per-role landing page, phone bottom bar, links between pages, breadcrumbs, in-page tabs) for multi-role business apps built with @godxjp/ui. Use BEFORE adding or changing a menu item, adding a page, or changing a role's landing page, and whenever navigation is criticised as confusing ("I can't tell what anything in this menu is for"). Covers the procedure (tasks → menu tree → walkthrough → measure), 28 sourced rules (NN/g, Material 3, Apple HIG, GOV.UK, SAP Fiori, Shopify Polaris and others) and an illustrative pattern for inspection and compliance apps.
+---
+
+# Navigation for multi-role business apps (@godxjp/ui)
+
+One question: **for a person in this role, doing this task, where does the first click go — and are
+they sure it is right?** A menu is not a database diagram. A menu is each role's list of *tasks*,
+ordered by frequency.
+
+Distilled from measured failures in a real multi-role app: 17 menu items grouped by data type
+("Records / Standards / Supplies / Master data"), three overlapping entries for one task ("Log an
+inspection / Inspections / Checklists"), a Settings area that was a dead end, every role seeing every
+item, and a phone layout with nothing but a drawer. The owner's verdict: *"I can't tell what anything
+in this menu is for."* Full sources: [references/principles.md](references/principles.md) (28 rules,
+with the URL behind each one). An app may keep its own industry benchmark notes (competitor
+comparisons, domain vocabulary) in its own repository; they do not belong in this package.
+
+## 1. Procedure — the order is the rule
+
+1. **Tasks first, screens second.** For each role (e.g. frontline staff, branch manager, head-office
+   reviewer), list their 5–10 *most frequent tasks* in their own words ("log this morning's opening
+   checklist", "is this batch still within its expiry date", "which branches are late on their
+   checklists"). Sort by frequency. This is the only input to the menu.
+2. **Split into 3 zones: Do · Set up · Review.** Daily work goes at the top; setup (templates,
+   recipes, configuration) goes in its own group or at the end; settings/admin go at the bottom.
+3. **Write the menu tree as text for each role** (level 1 → level 2 → page). For each item: label,
+   destination page, which roles see it.
+4. **Walk through the tree (no users needed)** — 8–10 tasks per role, written WITHOUT the words used
+   in the menu. At each level answer the 4 cognitive-walkthrough questions: will the user try to do
+   the right thing · will they *notice* the right item · does the label *match* their goal · after
+   clicking, can they tell they arrived. Record the expected first click and any **competing label**
+   (two labels pulling at the same task = a defect). Critical tasks must be "certainly right" on the
+   first click.
+5. **Measure on the real app after building it** (a manual or agent-driven test pass): inventory
+   every page → its entries and exits, which menu item is highlighted, dead ends, orphan pages. If
+   you have users, run a tree test: critical tasks need >90% success.
+6. Changing the menu structure is a **redesign** → bring a proposal (tree per role + old → new table +
+   walkthrough results) to the project owner for approval before writing code.
+
+## 2. Hard rules
+
+**Count and form**
+- Phone: **bottom bar with 3–5 items** (the middle one may be a ＋ quick-log button); everything else
+  goes under "More". Never put setup on the bottom bar. Desktop: **an always-visible sidebar**, not
+  only a ☰ button. Choose by window width, not by device. (@godxjp/ui's `MobileShell` has a bottom
+  bar — use it; don't rely on a drawer alone.)
+- Sidebar at most **2 levels**, groups with short headings; each role sees **≤ ~7 primary items**.
+  Anything deeper → list → detail inside the page.
+
+**Grouping and labels**
+- Group by **task / work area**. Never group by data table, org chart or developer vocabulary
+  ("Master data", generic "Records").
+- A label is a short noun of 1–3 words, **in the words users say**, always with text (an icon only
+  supports it). The page title (H1 and `<title>`) **matches** the menu label. One concept = one name
+  everywhere, in every language (check every locale: e.g. not five strings sharing the root "記録"
+  split across two groups).
+- **Each destination appears once** in the menu. Two items leading to the same kind of record = a
+  defect.
+- Action buttons (Log/Create) are **not menu items**: one prominent primary button (top of the menu,
+  or the ＋ in the middle of the bottom bar) for the #1 task; child objects are created right inside
+  their parent's page.
+
+**Per role**
+- Each role has its **own fixed landing page**: frontline staff → "Today" (due, overdue, my tasks);
+  managers/head office → "Overview" (completion rate, exceptions by branch).
+- **Hide** items a role will never use (filter the menu by the current user's permissions); **dim it
+  and say why** when it is only temporarily blocked. The menu never changes with data state.
+- Branch scope is a single control (All / Group / Branch); a person who belongs to only one branch
+  doesn't see it. Standards authored by head office carry a "From head office" label.
+
+**Between pages**
+- Lists are for finding; a detail page is for one object (top: key facts + actions; below: sections or
+  tabs). Scanning a code opens the detail page directly.
+- **No dead ends:** a detail page lists its related objects with a **count**, a few preview rows, a
+  pre-filtered "View all" and an in-place "Create" — **both directions** (inspection → batch, and
+  batch → its inspections).
+- From a dashboard or notification, link **straight to the record**, or to a list that is *already
+  filtered correctly* — never to an unfiltered list.
+- Breadcrumbs show **hierarchy** (not history), from level 3 down; every crumb is a real page; the last
+  crumb is the parent when the H1 already names the object; use the record's **real name**, not
+  "Batch"/"Item". The breadcrumb and the highlighted menu item must name **the same parent**.
+- In-page tabs: 1–2 words, the most-used tab first, with a count; tab state + filters + scope live **in
+  the URL**; Back restores scroll position, page and filters. "All" sits in the same place on every
+  page.
+- Deep links rebuild the normal parent path (Back goes to the parent list). Every child page has a
+  highlighted menu item — no page leaves the menu "with the lights off".
+
+## 3. Illustrative pattern: inspection and compliance operations
+
+An example only, for apps that run recurring checks across many sites:
+
+- **Do / Set up / Review** are kept apart; templates are authored on desktop only.
+- Typical set: Home · Inspections (records) · Templates · Schedule · **Actions** · Incidents · Assets ·
+  Analytics · (Branches/Users in organization settings).
+- A failed item is handled right **inside the flow** (a required step; 3 or more fields means a page or
+  step, not a popup) → an "Open nonconformity" button right under the item; nonconformities/actions
+  stay **permanently linked** to their source record.
+- Staff land on "Today" plus a separate place for "Overdue/Missed"; managers land on a rate table plus
+  exceptions.
+- Phone bottom bar: 4–5 task items (e.g. Today · Inspections · ＋Log · Nonconformities · More).
+- Vocabulary: avoid "Reports"/"レポート" as the label for *records* (in English "Reports" means
+  analytics; in Japanese "レポート" often means an individual record).
+
+## 4. Self-check gate (before asking for approval / before merging)
+
+- [ ] A task table per role and a text menu tree per role exist; each role ≤ ~7 primary items; phone
+      3–5 items.
+- [ ] Walkthrough of 8–10 tasks per role: no step answered "no"; no pair of competing labels.
+- [ ] No duplicate destinations; no grouping by data table; label = H1 = `<title>`, consistent across
+      every locale.
+- [ ] Menu filtered by permission; landing page per role; bottom bar present on phones.
+- [ ] Page inventory: 0 dead ends, 0 orphan pages, every child page has a highlighted menu item that
+      matches its breadcrumb.
+- [ ] Every detail page links both ways to related objects, with counts and a pre-filtered "View all".
+- [ ] Tabs/filters/scope live in the URL; Back keeps the position.
+- [ ] Structural change → the project owner has approved the proposal.
+
+When @godxjp/ui can't do something you need (bottom bar, menu filtering, scope switcher), open an issue
+on the @godxjp/ui repository with the use case instead of hand-rolling it (the same rule as the
+`godxjp-ui-form` skill).