stitch2 0.18.0 → 0.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "A design canvas, layout and type checks, component consistency and screen versioning for agent-built UI, on Google's DESIGN.md format.",
   "license": "MIT",
   "author": "ifokeev",

package/skills/stitch2/SKILL.md

@@ -38,6 +38,9 @@ References, read before the first screen:
 2. **Inventory.** List every element the brief names, in order, with its real data. That list is the screen:
    add nothing (status bars, step labels, tips, helper text, extra buttons), drop nothing. Next to each element
    write the catalog component that shows it; adapt or extend components rather than inventing markup.
+   Then list the page's **states**. A page that shows data gets an empty screen and a loading screen, designed
+   with its main screen in the same version; a page that loads or saves data that can fail also gets an error
+   state. Build them with the main screen; they are part of the page (screens.md, Empty, loading and error).
 3. **Hierarchy before markup.** Name the one thing the user came for, the single primary action (the only
    accent-filled element in its region), and what is secondary. Give every text element a type level and a
    colour before writing markup.
@@ -66,7 +69,8 @@ References, read before the first screen:
 6. **Look and critique.** View the render in `<design>/renders/` (crop the first screenful). Score it with the
    rubric in principles.md, fix what fails, repeat 5–6 at most three times.
 7. **Hand over.** Set the version's status to `review`, point the user to it on the canvas, and report what
-   changed, how you answered their notes, and any rubric item you could not satisfy. The user approves; only then
+   changed, how you answered their notes, and any rubric item you could not satisfy. The page's empty and loading
+   screens go to review with it; for a page without them (a form, a static page), say why. The user approves; only then
    does it go into the app (the approved version is the one current version: see screens.md).
 
 ## Commands

package/skills/stitch2/references/principles.md

@@ -56,7 +56,8 @@ short labels never wrap **(check)**.
   axis or month labels, a legend for a colour scale, captions under figures. They add no new facts.
 - Icons that stand for different things look different; one generic glyph repeated down a list says nothing.
 - Charts: one series in the accent, thin lines, few gridlines; label a single line directly instead of a legend.
-- Empty and loading states are designed too: one sentence and one action; skeletons the size of the content.
+- Empty and loading states are designed with every page that shows data: one sentence and one action; skeletons
+  the size of the content (screens.md, Empty, loading and error).
 
 ## Touch and mobile
 
@@ -86,3 +87,5 @@ Score each pass or fail from the render; done when all pass or the failures are
 8. **Data realism:** names, numbers and dates look like a real person's data.
 9. **Consistency:** built from the catalog components; no `reuse` or `consistency` warnings.
 10. **Checks:** `stitch2 check --strict` reports no errors.
+11. **States:** the page has its empty and loading screens (and error when data can fail), built from the same
+    components and layout as the main screen; or the hand-over says why it needs none.

package/skills/stitch2/references/screens.md

@@ -30,6 +30,32 @@ together; `stitch2 screens <page>` lists them. A screen without `<p>-page` is a
   that page, not a new page.
 - Copy `<p>-page` along with the other tags into each new version; the latest version that has it decides the page.
 
+## Empty, loading and error
+
+Every page that shows data has these states, and the app shows them on most first visits: a new user sees the
+empty screen before any other, and every user sees the loading one. Design them with the page's main screen,
+not after it.
+
+- **Which pages:** any page that lists, counts or charts the user's data, or loads it from a server. A form, a
+  dialog, a static page (sign-in, a landing page) needs none; say so in the hand-over.
+- **Names:** `<page>-empty` and `<page>-loading` (`history-empty`, `history-loading`), `<page>-error` when it
+  has one, with the page's `<p>-page`. Same version number and same variants (mobile, desktop) as the main
+  screen. A page whose main screen is a new version gets new versions of its states when they change.
+- **Empty:** the page's header and navigation stay where they are. In place of the content: what this place is
+  for in one sentence, and the one action that fills it ("Create your first routine"). Use the page's own
+  components where they help (a suggested program as a list row), not a large illustration. An empty search or
+  filter result is a different empty: it says nothing matched and how to widen it (clear the filter), and keeps
+  the search field and filters.
+- **Loading:** the same layout as the main screen, with skeletons in place of the data: blocks the size and
+  shape of the rows, cards and numbers that will arrive (typography.md, Text in each state). The header,
+  navigation and buttons that need no data stay real and usable. No spinner in the middle of the page and no
+  "Loading…" text; a spinner belongs only inside a button or a row that is saving. Build skeletons from a
+  catalog component, so every page loads the same way.
+- **Error:** the page's frame stays; where the data would be, one sentence on what failed and a Retry action.
+  Data already shown stays on screen; a failed save says so next to what failed and keeps the user's input.
+- **Partial states** follow the same rules inside a section: an empty list in a page that has other data shows
+  one line and an action in that section only.
+
 ## New version or edit?
 
 - **New version** for every new attempt: a new direction, a regeneration, an export from a generator, a

package/skills/stitch2-app-sync/SKILL.md

@@ -25,6 +25,11 @@ a component rebuilt by hand. The checks can only judge what the canvas draws, so
    single current version and the app matches it.
 4. **App**: the app picks the component up; wire it, then run `stitch2 compare <screen>`.
 
+A page in the app is its main screen and its states: implement its approved empty, loading and error screens with
+it. The app's loader is the loading screen's skeleton, shown until the data arrives, never a blank page or a lone
+spinner; data appearing all at once with no loading state is a bug. A page whose states were never designed goes
+back to the canvas for them first.
+
 Fixing a bug found in the app follows the same path: reproduce it on the canvas (a screen or catalog state that
 shows it), fix the component, check, then the app. If the canvas cannot show the bug, the canvas is missing a
 state: add it.
@@ -69,4 +74,3 @@ Read the findings as:
 2. `stitch2 check --strict` passes on the screens you touched (archived screens excepted).
 3. `stitch2 compare` has no errors for the screens you touched; warnings are explained (a kept feature) or fixed.
 4. The user has seen the canvas versions of anything that changed how a component looks.
-