agentplugged 0.0.0-stage → 1.0.0

package/dist/method/skills/write-ux-spec/references/tokens-and-sketches.md

@@ -0,0 +1,83 @@
+# Tokens, elements and sketches
+
+Read this when you write the visual identity, the screen sketches or the table of elements.
+`npx agentplugged docs check` reads all three; run it after each.
+
+## Tokens: in the header, once
+
+When the product has a brand identity (`launch/identity.md`, skill `write-brand`), its tokens are the
+source: use them by name (`{color.accent}`) and do not define them again; a token given another value
+here is a problem. Its fixed rules also apply to the mock-ups.
+
+The header of `ux.md` carries a `tokens` block. Groups: `color`, `type`, `space`, `radius`,
+`shadow`. Each is a map of named values; a name is letters, digits, `-` or `_`.
+
+```yaml
+tokens:
+  color:
+    background: { light: "#FFFFFF", dark: "#101114" }
+    primary: "#0F62FE"
+    on-primary: "{color.background.light}"   # an alias to another token
+  type:
+    body: { family: "system-ui", size: 16px, weight: 400, line: 1.5 }
+  space: { "1": 4px, "2": 8px, "4": 16px }
+  radius: { md: 8px }
+```
+
+- A colour is a hexadecimal value, or `light` and `dark` hexadecimal values. Nothing else
+  (`blue`, `rgb(…)`) passes.
+- Anywhere else in the specification a token is written `{color.primary}`; the path follows the
+  block (`{type.body.size}`). `docs check` refuses a `{token}` the block does not define, and
+  an alias to nothing. Sizes, colours and durations written inline where a token exists are
+  an excess (see the checklist).
+- Native platforms: a type role may be a phrase (`body: "platform body style"`) when the
+  platform owns the real value. Say it once in Foundation.
+- A specification written before this block may keep its tables of `` `color.primary` ``
+  names; moving them to the header is a good update, never a condition.
+
+## On top of a UI system the product keeps
+
+When the creator keeps a component library or a UI system (their own, or one the product
+adopts), do not specify again what it gives:
+
+1. Foundation names it; the header says `ui_system: <name>`.
+2. `tokens` holds only the difference: the brand colours, the type swaps, the radii that
+   override the system's.
+3. A thing the system already gives is written `{ui.button}` or `{ui.focus-ring}`: with
+   `ui_system` declared these always resolve, without a token. Components then hold only
+   what differs (a state, a variant, a rule of behaviour).
+4. The choice of the library is Alex's. Note the preference in Foundation and stay with
+   whatever the architecture decides; when it changes, update the delta.
+
+## Elements to build: `UX-n`
+
+The table "Elements to build" numbers what the stories must carry: each component, each state
+worth a story's attention, each accessibility fix the check found. One row each (`UX-1`,
+`UX-2`…), kind, description, where. Never renumber; a thing no longer wanted stays, its
+description beginning `(retired)`.
+
+Once stories exist, `docs check` and the readiness gate refuse an element no story names in
+its Context or acceptance criteria. That is the way a state or a fix is not forgotten between
+the specification and the build. Number what a developer would otherwise reinvent, not every
+label.
+
+## Sketches: one per screen
+
+Under "Screen sketches" (keep that title, and "Key screens": the checks find the sections by
+them, in English or as « Croquis des écrans », « Écrans clés »), one `### <screen name>` per screen of the architecture (the key
+screens first). Each holds a drawing in a code block, every region marked `[1]`, `[2]`…, and
+the list `1.`, `2.`… saying what each region holds and its states. The numbers match in both
+places, start at 1, have no gap; two regions at least.
+
+```
++------------------------+
+| [1] date, count        |
+| [2] task rows          |
+|            [3] add     |
++------------------------+
+```
+
+A story of the interface takes the sketch of its screen as an acceptance criterion: "given
+the screen, when it opens, then its regions 1 to 3 are those of the sketch in `ux.md`". The
+sketch is not pixels: the layout order, the grouping and what each region does. Pixels and
+colours are tokens or the page.

package/dist/method/skills/write-ux-spec/references/ux-checklist.md

@@ -0,0 +1,74 @@
+# UX specification checklist
+
+Run every check before showing the specification to the creator. Fix what fails; when a fix
+needs the creator, ask them, one question at a time, or open a `decision` checkpoint.
+
+## Header and identifiers
+
+- The header is the first thing in the file and holds `id: ux`, `kind: ux`, `owner: stella` and
+  `links`: `prd` and every `PU-n` and `EF-n` the specification covers, all active in the PRD.
+- No `status`, `state`, `cost`, `spent`, `budget_spent` or `progress` key.
+- No requirement identifier is defined: none opens a line, a list item, a heading or a first
+  table cell.
+- No `<…>` placeholder is left from the template, no value marked `(sample)` (the sample
+  colours `#FFFFFF`, `#111111`, `#1A1A1A`, `#F2F2F2`, `#0F62FE`, `#78A9FF`, sizes `16px`, `24px`, `400`, `600`, `1.5`, `1.25`, spacings
+  `4px`, `8px`, radius `8px`) unless the creator chose that exact value, no sample link (`PU-1`,
+  `EF-1`) the specification does not cover, and no `screen-sample.html`.
+- No `[open: G-…]` mark remains for a decision the creator already answered, and none sits at
+  the start of a line or before an identifier.
+- `npx agentplugged docs check` reports no problem.
+
+## Coverage
+
+- Every journey of the PRD has a key flow, with its moment of value and its failure path.
+- Every screen serves at least one journey, and every journey lands on screens.
+- Every flow names the requirements it covers; the "Traceability" table agrees with the flows.
+- Every screen lists the states that apply (empty, loading, error, success, offline, permission
+  denied), with what the user sees.
+- Nothing in the specification asks for a capability the PRD does not state: such a need is an
+  open question.
+
+## Visual identity
+
+- Every colour token has a hexadecimal value for each mode the product supports.
+- Every token used in the text (`{…}`) is defined once, in the `tokens` block of the header
+  (`docs check` refuses one that is not); on a UI system the product keeps, `ui_system` is
+  declared and the tokens hold only the difference.
+- Every component used in a flow has a visual specification and a behaviour.
+- The visual direction is the one the creator chose; every guess is marked `[assumption]`.
+
+## Screens, sketches and pages
+
+- Every screen of the architecture has a sketch whose regions are numbered the same in the
+  drawing and in the list; the key screens (two to four) each have a page, or `none` by the
+  creator's choice.
+- Each page was drawn from the tokens and the sketch, shows the product's own words, and
+  `ux.md` states once that the specification wins over any page.
+- Every component, state and accessibility fix a story must carry is a `UX-n` of "Elements to
+  build", none renumbered.
+
+## Accessibility
+
+- Every item of `references/accessibility-check.md` has a result in "Accessibility check".
+- No blocking finding is left without a fix or the creator's explicit acceptance.
+
+## Excess (over-specification)
+
+A specification says each thing once, at the level a builder needs. Each excess is a finding,
+minor unless it hides a decision; for an independent verdict, ask a sub-agent for the method
+`judgment` (skill `critique-deliverable`), reported in its closed form.
+
+- **One home per value.** A size, colour or duration written inline that a token already names,
+  or that a rule would give.
+- **One home per fact.** Content copied from the PRD that its identifier would carry.
+- **A reader per section.** Ask who would miss it; a section nobody builds from, or a story
+  about the brand that settles no choice, goes.
+- **Reachable.** A screen or a state that no journey of the PRD reaches.
+
+## Form
+
+- The terms are those of the PRD's glossary.
+- Tables are used where they read better than prose; no section is padded.
+- No guidance comment and no "Generated by agentplugged" line is left.
+- The stack and the code are left to Alex and the developers: a preference is noted, never
+  decided.