@ericrisco/rsc 3.3.1 → 3.5.0

package/skills/ui-engineering/SKILL.md

@@ -1,113 +0,0 @@
----
-name: ui-engineering
-description: "Use when the question is how interface should be BUILT — component boundaries, state that belongs in the URL vs the component, loading/empty/error states, forms, optimistic updates, build vs adopt. NOT the visual system (`design`), NOT framework mechanics (`react`/`nextjs`)."
-tags: [interface, frontend, architecture, components, state, craft]
-recommends: [design]
-profiles: [core, full]
-origin: risco
----
-
-# UI engineering — the decisions between the design and the framework
-
-There is a layer that neither the design skill nor the framework skill owns. The design says what
-the screen should be. The framework says how its API works. **In between sits every decision that
-makes an interface either durable or a maintenance tax** — and it is where most interface work
-actually goes wrong.
-
-Nothing here is framework-specific. These decisions are the same in React, Vue, Svelte, SwiftUI and
-plain HTML; only the syntax moves.
-
-## The one rule
-
-**State goes to the outermost place that still needs it, and no further.** Almost every interface
-tangle is that rule broken in one of two directions: state hoarded in a component that others need,
-or state hoisted into a global store that only one component ever reads.
-
-| Where the state lives | When that is right |
-| --- | --- |
-| **The URL** | Anything a user would bookmark, share, or expect the back button to restore: filters, tabs, pagination, the open item |
-| **The server** | Anything that outlives the session or belongs to more than one user |
-| **A shared parent** | Two siblings genuinely need it, and it dies with the screen |
-| **The component** | Nobody else reads it: hover, focus, an open menu, an in-flight draft |
-
-The most common and most expensive mistake is the first row: state that belongs in the URL kept in a
-component. It looks fine until someone reloads, shares a link, or presses back — and then the
-interface silently loses what the user did.
-
-## Every state, not just the happy one
-
-An interface is not finished when it renders data. It is finished when it renders **all five**:
-
-| State | The question it answers | The usual failure |
-| --- | --- | --- |
-| **Loading** | "Is it working?" | A spinner where the shape is already known — use the shape |
-| **Empty** | "Is it broken, or is there nothing?" | Blank. It must say which, and what to do next |
-| **Error** | "What now?" | A message with no action. Every denial carries its own way out |
-| **Partial** | "Some of it failed" | Ignored entirely; the screen shows a half-truth |
-| **Success** | "It worked" | Silence, so the user does it twice |
-
-The empty state is the one that gets skipped, and it is the first state a new user ever sees.
-
-## Component boundaries
-
-A component earns its existence by **hiding a decision**, not by being reused. Splitting for reuse
-alone produces the worst interfaces: a wrapper around a wrapper, each passing props through, none
-owning anything.
-
-Draw the boundary where:
-
-- it owns a piece of state nothing outside needs;
-- it can be described in one sentence without "and";
-- swapping its internals changes nothing outside it.
-
-Do **not** draw a boundary because a file is long. Long is not a defect; a file that does two
-unrelated things is, and it is usually short.
-
-## Forms
-
-Forms are where interfaces most often insult people, and the rules are unglamorous:
-
-- **Validate on blur, not on keystroke.** Telling someone their email is invalid while they are on
-  the third character is scolding them for not having finished.
-- **Never clear what they typed.** Not on error, not on refresh, not on navigation. Their input is
-  theirs.
-- **Disable the submit only while submitting**, never as a way of enforcing validity — a disabled
-  button with no reason is a dead end.
-- **The error goes next to the field**, and says what to do, not what is wrong.
-
-## Optimistic updates
-
-Show the result before the server confirms **only** when you can honestly undo it. That means: the
-operation is idempotent, the failure is rare, and reverting it is visible and comprehensible.
-
-Optimism on a destructive or an expensive action is a lie you will have to retract in front of the
-user. Deleting, paying, sending — those wait.
-
-## Build or adopt
-
-Adopting a component costs bundle size, an API you did not design, and an upgrade you will owe
-later. Building costs the accessibility work you will get wrong.
-
-The split is not about difficulty, it is about **who is the authority on the behaviour**:
-
-- **Adopt** for behaviour with a specification you would otherwise be reimplementing badly: focus
-  trapping, combobox semantics, date handling, virtualisation.
-- **Build** for anything that is your product's own logic wearing a UI, or where the library gives
-  you 60% and you fight the remaining 40% forever.
-
-## Anti-patterns → STOP
-
-| If you're about to… | Reality / Fix |
-| --- | --- |
-| Put a filter or tab selection in component state | It belongs in the URL. Reload, share and back are part of the interface. |
-| Add a global store because passing props feels tedious | Tedious is not broken. Global state that one component reads is a leak with ceremony. |
-| Ship a screen with only the loaded state | Loading, empty, error and partial are not extras. The empty one is what a new user sees first. |
-| Split a component because the file got long | Length is not the defect. Two unrelated responsibilities are, and they are usually short. |
-| Show a delete as done before the server confirms | Optimism on a destructive action is a lie you will retract in public. |
-| Reach here for how the framework's hooks work | That is `../react/SKILL.md` or `../nextjs/SKILL.md`. This skill decides what to build; those decide how to express it. |
-
-## See Also
-
-- `../design/SKILL.md` — the visual system these decisions serve, its motion layer, and the
-  browser-measured critique that judges the result.
-- `../accessibility/SKILL.md` — the ground under focus, semantics and forms.

package/skills/ui-engineering/evals/cases.yaml

@@ -1,38 +0,0 @@
-skill: ui-engineering
-
-should_trigger:
-  - prompt: "Where should the filter state live — component, context or the URL?"
-    why: "The canonical case: the one rule this skill exists to apply."
-  - prompt: "How should I split these components? The file is getting big."
-    why: "Component boundaries, and the file-length premise is one this skill corrects."
-  - prompt: "We only render the loaded state. What else does this screen need?"
-    why: "The five states are the checklist this skill owns."
-  - prompt: "¿Valido el formulario mientras escribe o al salir del campo?"
-    why: "Form behaviour, in Spanish; the trigger is the decision, not the language."
-  - prompt: "Should I use a component library for the date picker or build it?"
-    why: "Build vs adopt, decided by who owns the behaviour's specification."
-  - prompt: "Can we show the delete as done immediately and roll back if it fails?"
-    why: "Optimistic updates, and this is the case where the answer is no."
-
-should_not_trigger:
-  - prompt: "Design the pricing page — layout, type scale, the colour system."
-    route_to: "design"
-    why: "The visual system is decided before this layer has anything to build."
-  - prompt: "My useEffect runs twice in development and I don't understand why."
-    route_to: "react"
-    why: "Framework mechanics. This skill decides what to build, not how the framework behaves."
-  - prompt: "The dropdown animation feels cheap, what duration should it use?"
-    route_to: "design"
-    why: "Once the component exists, how it moves is motion craft."
-  - prompt: "Grade this dashboard and tell me if it is actually good."
-    route_to: "design"
-    why: "Judging a finished screen is the critique loop, not the build decisions."
-  - prompt: "Set up the Next.js App Router with server actions for this project."
-    route_to: "nextjs"
-    why: "Stack setup is the stack skill's; this one is framework-agnostic by construction."
-
-capability:
-  - prompt: "Our search page keeps its query and filters in component state. Users complain the back button loses everything. What is wrong and what is the fix?"
-    why: "The single most expensive instance of the one rule, stated as a real symptom rather than as theory."
-  - prompt: "This list screen shows a spinner, then rows. What states are we missing and why does each matter?"
-    why: "Forces the five-state checklist, including the empty state that a new user sees first."