@litfamily/lithermes 1.0.7 → 1.0.9

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/motion-guide.md

@@ -0,0 +1,62 @@
+# Motion guide
+
+Use motion to explain hierarchy, state, or cause and effect. Name the page, components, implementation stack, and excluded areas before specifying choreography. Motion is optional; remove it when the surface communicates just as clearly without it.
+
+## Motion brief
+
+Record the following before implementation:
+
+- **Stack and scope:** framework, styling system, animation package, icon set, tested version pins, and exact components in scope.
+- **Tokens:** colors, spacing, font roles, numeric weights, and breakpoints. Give fluid display type a `clamp()` range, line-height, and system fallback.
+- **Layers:** a short z-index map for page content, navigation, and overlays.
+- **Responsive plan:** named content-driven breakpoints, including a separate mobile navigation when desktop navigation no longer fits.
+- **Motion:** named curve, duration, trigger, moving elements, and reduced-motion result for each sequence.
+- **Media and limits:** existing asset names, initial transfer budget, poster, fallback, lazy-loading point, and device conditions.
+
+Use the page structure and dependency order, not scroll order, to organize the brief: stack and tokens; structure; media and fallbacks; navigation; content; interactions; dependencies and build configuration. Name files or components so implementation cannot invent unrelated sections.
+
+## Curves, durations, and triggers
+
+Use these named curves as defaults; keep values in tokens so the motion family can be adjusted without hunting through components.
+
+| Token | Curve | Duration | Use |
+| --- | --- | ---: | --- |
+| `enter` | `cubic-bezier(0.16, 1, 0.3, 1)` | 420 ms | Short composition or section entrance |
+| `ui` | `cubic-bezier(0.2, 0.8, 0.2, 1)` | 180 ms | Hover, focus, and state feedback |
+| `exit` | `cubic-bezier(0.4, 0, 1, 1)` | 160 ms | Dismissal or removal |
+
+Pair each duration with a named curve. Keep ordinary control feedback below 400 ms; use a longer duration only when progress remains apparent and the user can continue working.
+
+For section reveals, trigger once when at least 15% of the section enters view, with a bottom root margin of 10%. If the observer is unavailable, show the content. A scroll-linked effect must declare its progress interval and output range; keep one dominant movement in the hero.
+
+Stagger only a short, related group: `baseDelay + itemIndex × 60 ms`, capped at 300 ms. Do not stagger an article line by line or delay readable content.
+
+## Per-section and frame budget
+
+- One entrance sequence per section and no more than two simultaneously moving elements.
+- One principal hero effect and at most one animated headline.
+- Prefer `transform` and `opacity`; avoid per-frame `top`, `left`, `width`, and `height`.
+- Keep animation work below 4 ms per frame when measured, leaving time for layout, paint, and input. Check a mid-range device; a desktop GPU is not a phone proxy.
+- Keep controls usable while decoration runs. A 3D scene, cursor tracking, or carousel needs a separately named input path and frame/device budget.
+
+## Media budgets and fallbacks
+
+State the initial transfer budget. Defaults: no more than 1 MB compressed for initial motion media and 150 KB for a video poster. Lazy-load below-the-fold media, size images for their rendered box, and split optional motion code from the initial route.
+
+Every background video has a real poster and a still-image fallback. On small screens, when data saving is enabled, or when playback is unavailable, do not download or autoplay the video; preserve the same message and contrast in the fallback. Group playback behavior together: muted, looping, inline, and autoplay only where allowed. Use an approved asset by its existing name; if none exists, request a real asset or specify a designed still. Never invent a media URL.
+
+## Accessibility and input
+
+Honor `prefers-reduced-motion`: show final content immediately, remove parallax and tilt, and shorten or remove nonessential transitions. Motion must not gate content, expose labels, indicate success by itself, or change keyboard reachability.
+
+Restrict pointer tilt to fine-pointer devices, clamp rotation to ±4°, reset on pointer exit, and leave touch input alone. Compose tilt with other transforms instead of overwriting them. Do not request device orientation or require hover to reveal content.
+
+Keep full headline text in the accessibility tree and readable before an animation package loads. Test with motion enabled, reduced motion, and media unavailable. Focus, keyboard operation, contrast, and reading order must remain complete in all three.
+
+## Review checklist
+
+- Are stack/version pins, scope, tokens, breakpoints, and layers explicit?
+- Does each sequence have a named curve, duration, trigger, and reduced-motion behavior?
+- Is section/hero motion within budget, with no hidden content on observer failure?
+- Do media poster, mobile/data-saving fallback, lazy loading, and transfer limits work?
+- Can a keyboard and screen-reader user complete the same task without motion?

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/operating-lanes.md

@@ -1,85 +1,21 @@
-Operating lanes: new-build, brownfield, redesign, reference-fidelity, design-system
+# Operating lanes
 
-Every UI request runs in exactly one lane, and the lane fixes what you must know before the first edit.
-Name it in `direction.principles`; an unnamed lane defaults to the most destructive reading.
+Select one lane from the product on disk before editing and record it in the Design Contract. These lanes describe change scope; they do not grant repository or host permission. See production.md for request mode and authorization.
 
-## Selecting the lane
+The selected lane is the contract's `lane` value.
 
-Select from what is on disk, not from how the request was phrased.
+| Lane | Choose when | Inspect first | Preserve | Exit check |
+| --- | --- | --- | --- | --- |
+| New-build | No routes, tokens, or components exist | Tasks, audience, stack, platform, locales, inventory | Declared scope and stack | Contract states exist; every inventory item is rendered and reviewed |
+| Brownfield | Add or repair a surface in a working product | Token file, neighboring components, spacing and import conventions | Existing APIs, untouched routes, names | Change fits the current system; untouched surfaces still render |
+| Redesign | Change appearance or flow of a working surface | Baseline captures, controls, states, behavior, performance | URLs, fields, validation, permissions, focus order, meaning | Parity holds against the baseline |
+| Reference-fidelity | A supplied target governs named visual regions | Source files, dimensions, hashes, classified regions | Semantics, live component tree, keyboard and screen-reader behavior | Same-size region review plus live implementation |
+| Design-system | Deliver reusable primitives consumed elsewhere | Every consumer, variant, state, and current API | Existing props, tokens, and consumer output | Consumers pass or have an owned migration |
 
-- No routes, no tokens, no components -> **new-build**.
-- Working product; the request adds or repairs one surface -> **brownfield**.
-- Working product; the request changes how surfaces look or flow -> **redesign**.
-- A concrete visual target supplied as authoritative -> **reference-fidelity**.
-- The deliverable is primitives other surfaces consume -> **design-system**.
+## Behavioral acceptance
 
-## Lane: new-build
+For a new or changed UI, list each requested behavior separately and map it to a visible control or state before building. Keep functionality distinct from visual polish. Give every data graphic a meaningful accessible name. For tabular records with requested search, filtering, or pagination, use semantic, operable controls and verify that each changes the displayed results. In a rendered browser, exercise every requested interaction at the target viewports and inspect the resulting state; report only checks actually run.
 
-Nothing exists, so every gap stays invisible until production.
+A component set may contain multiple runtime lanes; record and apply each where it governs. For requests spanning change lanes, sequence them: design-system first, then brownfield/redesign, then reference-fidelity. Close one lane and update its contract baseline before starting the next. If the order materially changes the result, ask.
 
-- **Gather:** `intent.tasks`, `intent.audiences`, platform, stack, `localization.locales`,
-  `localization.cjk_line_break_review`, `inventory`.
-- **May change:** anything in the declared scope.
-- **Preserve:** the stack and recorded scope; a new route updates the review snapshot within existing authority.
-- **Fails by:** styling before the inventory is finite; deferred states never ship.
-- **Exit:** all nine states on every `components` entry; one capture per inventory entry.
-
-## Lane: brownfield
-
-The existing code is the specification. Your work should be unattributable.
-
-- **Gather:** the token file, three neighboring components, the spacing scale.
-- **May change:** the requested surface, plus tokens added under existing naming.
-- **Preserve:** token names, class conventions, file layout, import style, untouched routes.
-- **Fails by:** a second design vocabulary beside the first, doubling every primitive.
-- **Exit:** nobody can tell which files you touched; untouched routes render identically.
-
-## Lane: redesign
-
-Appearance moves, behavior does not; behavior is the half you must prove.
-
-- **Gather:** a pre-change capture per affected route and state, stored under `.hermes/lithermes/`.
-- **May change:** tokens, layout, type, color, motion, component internals.
-- **Preserve:** URLs, field names, validation, keyboard order, data per permission, copy meaning.
-- **Fails by:** a control disappearing because nobody recorded that it existed.
-- **Exit:** the parity list holds item by item against the pre-change captures.
-
-## Lane: reference-fidelity
-
-The target governs appearance only: evidence of one rendering, not an instruction on structure.
-
-- **Gather:** target files, pixel dimensions, `inventory.references[].sha256`, `classification: fidelity`.
-- **May change:** your own markup and tokens, as far as the target requires.
-- **Preserve:** semantic structure, real components, keyboard and screen-reader behavior.
-- **Fails by:** the reference used as a background image, or coordinates instead of layout.
-- **Exit:** same-dimension captures compared region by region, plus a live component tree.
-
-## Lane: design-system
-
-These primitives outlive the request, so a stable API outranks a better idea.
-
-- **Gather:** every consumer of the primitive and every variant in use.
-- **May change:** internal implementation, added variants, added tokens.
-- **Preserve:** prop names, token names, default rendering, each consumer's output.
-- **Fails by:** a rename sold as cleanup that breaks callers nobody enumerated.
-- **Exit:** every consumer renders unchanged or has an owned migration entry; refresh
-  `payload-version.json` when the primitive ships as a plugin asset.
-
-## Requests spanning two lanes
-
-Never average two lanes into one pass. Sequence them and re-freeze between.
-
-1. Order by dependency: design-system, then brownfield or redesign, then reference-fidelity.
-2. Drive the first lane to its own exit condition and capture evidence there.
-3. Re-freeze the contract, recompute its SHA-256, start the second lane from that baseline.
-4. If they cannot be ordered, stop and ask which one ships first.
-
-## Failure patterns
-
-Reject:
-
-- Editing before the lane is named in the contract.
-- A design-system change whose consumer list was never enumerated.
-- One combined pass that half-satisfies two lanes' exit conditions.
-- A plugin-asset lane closed without `sync-plugin -- --in-place` and a `lithermes doctor` run
-  on an isolated `--hermes-home`.
+For a plugin-asset change, follow the product's payload sync and doctor procedure in an isolated Hermes home, never a real user home, before calling the lane complete.

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/performance-delivery.md

@@ -1,85 +1,36 @@
-Performance and delivery constraints
+# Performance and delivery
 
-Speed is a contract term with a number beside it, not a cleanup pass after the visuals settle. Fix the
-numbers in `performance` while the inventory is still open, then measure the rendered route.
+Set measurable targets in the performance contract before styling is finished. Treat the values below as web-route starting budgets; adapt them to the product's devices and service level, and record any deviation before measuring.
 
-## Numeric budgets
+Record agreed thresholds in `performance.lcp_ms`, `performance.cls`, and `performance.inp_ms`.
 
-Write every budget as a value, a unit, and a device. An adjective is not a budget.
+## Starting budgets
 
-- LCP <= 2.5 s, INP <= 200 ms, CLS <= 0.1, at p75 on the slowest device in `platform`.
-- TTFB <= 800 ms; usable interaction <= 3.5 s at 4x CPU throttle, 1.6 Mbps.
-- Route payload <= 500 KB compressed: <= 170 KB script, <= 60 KB style, <= 200 KB above-fold imagery.
-- At most 2 font families, 4 files, each <= 40 KB woff2, subset to `locale`.
-- Frame budget 16.7 ms; no task over 50 ms; blocking under 300 ms per route.
+- At p75 on the slowest supported device: LCP ≤2.5 s, INP ≤200 ms, CLS ≤0.1.
+- TTFB ≤800 ms; usable interaction ≤3.5 s at 4× CPU throttle and 1.6 Mbps.
+- Route transfer ≤500 KB compressed: target ≤170 KB script, ≤60 KB styles, ≤200 KB above-fold imagery.
+- Use at most two font families and four files, each ≤40 KB WOFF2; subset for supported locales.
+- At 60 Hz, keep frame work within 16.7 ms; no task over 50 ms and blocking under 300 ms per route.
 
-## Diagnose the critical path
+## Diagnose before optimizing
 
-Follow navigation to largest paint to first input on a cold cache, name the blocking resource, then match
-it to this list.
+Measure cold and warm loads through largest paint and first input. Record the blocking resource and test likely causes: render-blocking scripts/styles, undiscoverable or lazy LCP imagery, delayed fonts, sequential fetches, layout read/write loops, full-list mount, non-async third-party tags, or unnecessary full-document hydration.
 
-- Synchronous script or unsplit stylesheet in `<head>`.
-- LCP image set in CSS or marked `loading="lazy"`, so discovery waits on layout.
-- Typeface with no `preload` and no `font-display`: invisible text, then reflow.
-- Sequential fetches — the child request starts only after the parent mounts.
-- Layout thrash: `offsetHeight` read between writes inside a loop.
-- A list that renders every row at mount.
-- Analytics or chat tag on the critical path with no `async` and no timeout.
-- Whole-document hydration for a route that is mostly static markup.
+Ship correctly sized media: AVIF with WebP fallback where supported; cap raster width near 2× the largest rendered CSS box; set intrinsic dimensions or aspect ratio; lazy-load below-fold images only; prioritize the LCP image. Split code by route and interaction; load charts, editors, and animation only where needed. Prefer server-rendered static content with focused hydration when the route allows it.
 
-## Bytes on the wire
+Virtualize only after measurement (around 200 rows or 2,000 nodes is a starting point). Preserve find-in-page and anchors where possible; variable-height lists need a measurement strategy, and accessible virtual tables need row-count and row-index metadata.
 
-Ship the smallest byte that still renders correctly at the declared device pixel ratio.
+## Perceived speed
 
-- AVIF with WebP fallback; cap raster width at 2x the largest CSS box that shows it.
-- `width`/`height` or `aspect-ratio` on every `img`; missing intrinsic size is the usual CLS source.
-- `loading="lazy"` below the fold only; the LCP element takes `fetchpriority="high"`.
+Acknowledge an action within 100 ms even if completion takes longer. Keep progress near the affected control, preserve final geometry while loading, and never add artificial delay to hide slow work.
 
-## Script payload and hydration
+## Audit and decision
 
-Count a kilobyte of script as roughly 3x a kilobyte of image data: it parses, compiles, and runs.
+For each route, record revision, viewport, pixel ratio, theme, device, throttle, cold/warm run, core metrics, resource bytes, longest task, and element count. Compare each measured value with its contract budget. Fix the highest-impact cause, rerun, and choose:
 
-- Split by route first, then at interaction boundaries — modal, editor, chart, map.
-- Load charting, rich-text, and animation libraries on the interaction that needs them.
-- Server-render markup and hydrate islands; document hydration pays for static regions.
+- **SHIP:** all agreed budgets pass.
+- **OPTIMIZE:** name the breached budget, cause, and owner.
+- **RESCOPE:** the requested design cannot meet the budget as stated.
+- **EXCEPTION:** record rationale, owner, expiry, and evidence internally.
 
-## Virtualized lists and their cost
-
-Virtualize above a measured threshold only. Below it the machinery costs more than the rows.
-
-- Threshold near 200 rows or 2,000 nodes, measured rather than assumed.
-- Variable row heights need a measurement cache or the scrollbar jumps mid-scroll.
-- Find-in-page and anchor links stop reaching unrendered rows; state the fallback.
-- Supply `aria-rowcount` and `aria-rowindex`; the DOM no longer holds the full set.
-
-## Felt speed against recorded speed
-
-Both must pass. A good number under an empty rectangle still reads as broken.
-
-- Skeleton matching final geometry within 100 ms; never a full-page spinner.
-- Acknowledge a tap inside 100 ms even when the result needs 2 s.
-- Never pad a delay to look deliberate; that hides the regression.
-
-## Audit protocol
-
-Run in order, stop at the first failed budget, and end on one of four decisions.
-
-1. Record route, viewport, device pixel ratio, theme, throttle profile, 40-hex source revision.
-2. Capture one cold-cache and one warm-cache load of that route.
-3. Extract LCP, INP, CLS, TTFB, bytes per resource type, longest task, element count.
-4. Mark each against its contract number PASS or FAIL, measured value beside it.
-5. For every FAIL name one cause above plus its one-line fix.
-6. Apply the single highest-leverage fix, then repeat steps 2-4.
-7. Decide: **SHIP** (all PASS), **OPTIMIZE** (named cause and owner), **RESCOPE** (the budget is
-   unreachable as designed), or **EXCEPTION** (an `accepted_exceptions` entry with owner, rationale,
-   expiry, evidence pointer).
-
-## Failure patterns
-
-Reject:
-
-- A performance claim with no measured value attached.
-- Warm-cache numbers from a developer laptop presented as p75 field data.
-- A bundle called optimized but never re-measured after the change.
-- Virtualization on a 40-row table, breaking find-in-page for no gain.
-- A breached budget edited in the contract to match the build.
+Do not report warm-cache laptop numbers as field p75, call an unmeasured bundle optimized, virtualize a small list without evidence, or edit the target to match a failing build.

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/product-direction.md

@@ -1,86 +1,33 @@
-Product direction and user journeys
+# Product direction and user journey
 
-Settle who the surface serves, what they must finish, and how finishing is measured before any
-direction, token, or component exists. Fills `intent.tasks`, `intent.audiences`, `intent.constraints`.
+Use this reference when the request adds a product journey or changes who it serves. Record decisions in the task and Design Contract; do not invent a persona exercise for a small visual fix.
 
-## Describe the operator by working conditions
+Map audiences, tasks, qualities, and constraints to the contract's `intent`.
 
-Write the primary user as a job plus operating conditions. One primary, two secondary at most.
+## Define the operator and critical task
 
-- The job, the decision they answer for, and what a wrong decision costs them.
-- Screen class, input method, assistive technology: pointer, keyboard, touch, reader.
-- Frequency and dwell — 40 visits a day at 20 seconds is a different product from one monthly hour.
-- Expertise tier: first-run, occasional, resident. Only residents tolerate dense layouts.
+Describe the primary operator by job, device/input, assistive technology where relevant, expertise, usage frequency, and the cost of a wrong decision. Add only secondary audiences that change the design.
 
-## Fix the one task that cannot fail
+State the critical task as verb + object + observable completion condition. Record the current and intended steps, what must remain visible, and competing tasks that must not displace it.
 
-Name the task whose failure empties the product of value: the critical task. Hierarchy arguments
-settle against it.
+## Set success measures
 
-- Phrase it as verb, object, and the condition that means finished.
-- Today's step count, and the count you commit to.
-- The two rival tasks forbidden from taking its screen space.
+Choose observable measures before implementation: time to first useful action, completion rate, errors, keyboard completion, and one counter-signal that would indicate a regression. Use task-appropriate numbers rather than adjectives.
 
-## State success as signals with numbers
+## Track material unknowns
 
-Replace adjectives with signals readable off a stopwatch or a log, agreed before build.
+For each unknown, record an id, how it will be resolved, and which decision it blocks. A gap blocks only the work that depends on it. Resolve by measurement or a focused question, then update its status; keep assumptions in the internal contract, not in reader-facing copy.
 
-- Seconds to first meaningful action, first-run and returning users measured separately.
-- Completion rate, plus the error rate you refuse to exceed.
-- Keyboard-only completion of the critical task: mandatory, never a stretch goal.
-- One counter-signal whose increase proves the design regressed.
+## Walk representative scenarios
 
-## Run a knowledge-gap register
+For a new or materially changed journey, exercise the task with the relevant constraints: low vision/zoom, keyboard, screen reader, low bandwidth, and a longer or CJK locale. State the input, expected completion, and failure boundary. For a narrow component change, select only the scenarios it can affect.
 
-Unknowns are contract entries, not silence. Each gap gets an id, a closing method, a blocking scope.
+## Compare choices and checkpoints
 
-- `G1` peak rows per operator at p95 — count in the production store; blocks table versus list.
-- `G2` share of accounts on CJK locales — read the locale column; blocks type scale, `localization.cjk_line_break_review`.
-- Mirror every gap into `omissions` and move `status` forward as it closes.
-- A gap blocks only the surfaces it touches. Close it by measurement or one direct question.
+When a material product or visual direction remains open, present up to three distinct choices with beneficiaries, tradeoffs, and reversal cost. Do not fabricate alternatives when the request already settles the direction.
 
-## Walk five inclusive scenarios
+Use decision checkpoints only where the choice affects downstream work: operator/task, direction, inventory, and evidence review. Note the selected choice and reason so the implementation and reviewer share the same baseline.
 
-Write each as a concrete run of the critical task under a single constraint.
+## Handoff
 
-1. Low vision — 200% zoom over 200% OS text scale; nothing clipped, no horizontal scroll.
-2. Keyboard only — whole task on Tab, Enter, Escape, arrows; focus visible, never trapped.
-3. Screen reader — landmarks in order, every control named, every async result announced.
-4. Low bandwidth — 3G-class link; usable at first paint, no reflow when late assets arrive.
-5. Unfamiliar language — labels 40% longer, CJK line breaking correct, no silent truncation.
-
-## Hand over bounded alternatives
-
-Give the next stage a choice set with stated costs, not one answer dressed as inevitable.
-
-- Three directions, each optimising a different axis: speed, breadth, or guidance.
-- One line per direction: who gains, who pays, reversal cost — cheap, moderate, structural.
-- One direction marked do-not-build, with the reason.
-
-## Set decision checkpoints
-
-Name the points where work halts for a decision; each writes one line — chosen, rejected, reason.
-
-- `CP1` operator and critical task accepted, before direction work; `CP2` direction chosen, before
-  token work.
-- `CP3` inventory recorded — routes, screens, states, viewports, themes, permissions — and evolved during build
-  and before `/start-work`.
-- `CP4` evidence complete, before the independent review pass.
-
-## Ship the research package
-
-The next stage receives a package. Whatever is missing cannot be argued about later.
-
-- Operator, critical task, numeric signals, checkpoint log with dates.
-- The gap register, with statuses and blocking scopes.
-- Five scenarios verbatim, three directions, the disqualified one.
-- `contract_id` with its SHA-256, so the independent review pass audits the same text.
-
-## Failure patterns
-
-Reject:
-
-- A persona with a name and a photograph but no device, session length, or input method.
-- "Modern", "intuitive", or "more engaging" standing in for a signal.
-- An empty gap register, or accessibility deferred to a checklist instead of five task runs.
-- `/start-work` entered before `CP3`, or a transcript handed over instead of the package and hash.
+Give the next stage the operator, critical task, success measures, open gaps, chosen direction, inventory, and contract id/hash when one exists. A concise task record is more useful than an unfiltered discussion transcript.

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/production.md

@@ -1,13 +1,25 @@
-# From direction to a working surface
+# From request to working surface
 
-Hermes loads this document through the selected frontend-ui-ux skill. Read the request as a scope boundary: an explicit build deserves implementation; a critique deserves findings. The natural-route context and conditional UI context guide behavior but do not grant file or host permissions. A mention of a UI in a backend explanation is not a redesign request.
+Use the selected frontend-ui-ux skill to interpret the request, not to expand it. An explicit build request authorizes the named interface change; critique or planning stays read-only. A UI mentioned as context is not a redesign request. Natural-route context helps choose behavior but grants no file or host permission.
 
-Before editing, identify the actual page, stack, user task, preserved brand elements and actions/states. Keep this direction note small enough to revise. The evidence-capable v1beta2 contract remains the final inventory for verification, and evolves during the build. Older references that call this a freeze describe a versioned review snapshot, not an extra approval gate or a requirement to finish JSON before writing UI. Review/plan-only intent remains read-only even if other guidance says implement.
+## Bound the work
 
-There is no mandatory interview. Ask only when two plausible answers would materially change scope, architecture, permissions, accessibility, or visual direction. Ask one high-impact question at a time, wait for its answer, then resolve the next material uncertainty in a later turn; continue for as many rounds as materially necessary. Retain earlier answers across rounds in the conversation and task-local direction note, reread them on resume, and do not re-ask a resolved question. If a brief lists competing visual directions and leaves them undecided, that choice is still open: calling each option "acceptable" is not a choice or a delegation. Ask it in a separate round after higher-impact questions are answered; you may recommend one option in the question, but do not declare a default for it or start building until the user chooses. A brief that gives no visual direction at all is different: use the authored default direction without asking. Defaults cover only what the brief settles, what it explicitly hands to you, and details that do not materially change the result. When the brief already bounds the work, state the default and proceed without pausing for an interview. Review, plan, and keyword-only requests remain read-only. A cancellation suspends new writes and captures partial status; resumption reuses confirmed assets and source.
+Before editing, identify the target route/component, repository and permitted paths, stack, user task, existing brand, behaviors and states to preserve, and requested outcome. Keep the direction note concise. Use the evidence-capable v1beta2 Design Contract as an evolving inventory; do not block a bounded build on completing JSON first or add a routine approval gate.
 
-When the brief does not specify another direction, use the authored tokens in `references/default-editorial-pixel.json` and make an original, task-specific pixel illustration the primary visual anchor. Render each cell at least 6 CSS px and preserve crisp integer-grid edges with nearest-neighbor scaling; do not smooth or blur the illustration. Build the surrounding editorial hierarchy with generous spacing, compact display lines, a terminal accent and deliberate asymmetry. A rounded abstract symbol or a generic gradient cannot stand in for the task-specific illustration. Keep pixel art decorative when the task is conveyed in real text; add meaningful alternative text when it conveys unique content. Never borrow a reference site's artwork, proprietary font or copy.
+There is no mandatory interview. Ask only when two plausible answers materially change scope, architecture, permissions, accessibility, or visual direction. Ask one high-impact question at a time, retain earlier answers across rounds, and do not re-ask a resolved question. Continue for as many rounds as materially necessary; when the brief is bounded, state the default and proceed. Review, plan, and keyword-only requests remain read-only.
 
-Existing branding wins over defaults. Choose line breaks after fitting actual Korean/Latin copy, and adjust the proposed tokens instead of clipping the title. Keep body leading comfortable. Narrow layouts should restructure the composition, not merely shrink a desktop screenshot. Preserve native semantic elements, tab order, visible focus, validation recovery and programmatic labels. Check empty-state transitions: `.empty[hidden] { display: none; }` must win over a class display rule. An animated accent must have a useful static or reduced-motion state.
+If a brief lists competing visual directions, treat them as undecided or unchosen. "acceptable" is not a choice or a delegation. Ask about the open direction in a separate round; do not declare a default or start building. Only when the brief gives no visual direction may the reversible authored default apply without asking.
 
-Exercise the main action in a real browser at 320, 390 and 1440 CSS pixels; record viewport dimensions, focus, error handling, successful action and overflow. Capture the exact built revision. A missing native capture capability yields a named gap; an authorized external local replay may supplement it only when labeled separately. Keep previous failure captures and never turn a green validator into a visual PASS. Finish with working files and an inspected preview, with the unresolved boundary stated plainly.
+## Direction defaults and preservation
+
+Use existing brand and system values where present. When no brand, direction, or subject-implied medium is supplied, start from default-editorial-pixel.json and create an original, task-specific pixel illustration as the primary visual anchor: crisp integer-grid edges, each cell at least 6 CSS px, nearest-neighbor scaling. A generic gradient or rounded symbol is not a substitute. Keep the illustration decorative when live text conveys the task; otherwise provide meaningful alternative text. Never borrow a reference site's artwork, proprietary font, or copy.
+
+Choose a visual medium that fits the subject and audience before applying a house default. Use imagery only with appropriate use rights, and never imply that illustrative stock material documents a real subject. For a fictional concept, provide complete, coherent sample content and label it as such in accompanying documentation; for real entities, use supplied or verified facts and never present invented details as verified facts. Remove authoring notes and unfinished prompts from the delivered interface. Keep consistent naming and visual identity across the page. Check text against its background at desktop and phone widths for legibility and overlap.
+
+Fit actual Korean and Latin strings before choosing line breaks. Narrow screens should restructure the layout rather than shrink a desktop composition. Preserve semantic elements, keyboard order, visible focus, validation recovery, and programmatic labels. Ensure a hidden attribute still wins over a component display utility (for example, .empty[hidden] { display: none; }). Give animated accents a useful static state.
+
+## Build and inspect
+
+Use the declared stack and request scope. Exercise the main action in a real browser at 320, 390, and 1440 CSS px when those dimensions suit the surface; inspect focus, validation/error recovery, success, and overflow. Capture the exact built revision. Preserve prior failure captures. If a native capture path is unavailable, name the gap; any authorized external replay must be labeled separately. A clean validator does not prove visual quality.
+
+Keep capture manifests and review labels in internal project evidence, not as UI copy. Finish with the working files or preview and only the material unresolved boundary.

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/redesign-playbook.md

@@ -1,91 +1,38 @@
-Redesign safety and preservation of product behavior
+# Redesign and behavior parity
 
-A redesign changes how a working product looks while it keeps working; the risk is silent behavior loss,
-not ugliness. Capture the old surface before editing, or nothing can judge the new one.
+A redesign changes appearance while preserving a working product's behavior. Capture the baseline before editing so every change can be judged against the same source revision.
 
-## Capture the baseline
+## Freeze the baseline
 
-No edit before the baseline exists; a baseline taken after the first commit is not a baseline.
+For each affected route, capture relevant screens, states, viewports, themes, controls, validation, empty/error copy, keyboard order, and current performance. Keep originals immutable in the project's internal evidence area and identify them by source revision and capture hash.
 
-- Every route, screen, state, and viewport at the pre-change 40-hex source revision.
-- Per surface: controls, validation text, empty and error copy, keyboard order.
-- Current performance numbers, so a regression is provable instead of arguable.
-- Theme per capture; a dark-only baseline proves nothing about light.
-- Stored under `.hermes/lithermes/`, keyed by `capture_sha256`, immutable.
+## Inventory the change
 
-## Map the debt by category
+Classify existing issues by user impact: token debt, structural semantics, missing states, inconsistent patterns, accessibility, or measured performance. Give each affected surface one verdict:
 
-Sort what is wrong before choosing what to touch, and rank each item high, medium, or low by user impact.
+- **Preserve:** correct; leave it untouched and guard it.
+- **Change:** keep structure/behavior while updating tokens or presentation.
+- **Replace:** new internals, same external behavior and URL.
+- **Remove:** name an owner, evidence of use, and redirect or replacement.
 
-- **Token debt** — raw hex or px sitting where a token already exists.
-- **Structural debt** — divs standing in for landmarks and heading rank.
-- **State debt** — components with no focus, loading, empty, error, or disabled rendering.
-- **Consistency debt** — three button variants doing one job.
-- **Accessibility debt** — contrast, target size, label, and focus-order failures.
-- **Performance debt** — breached budgets carried forward with their measured values.
+## Migrate in working slices
 
-## Decide per surface
+When tokens or primitives change, introduce compatibility values first, convert one low-risk route end to end, then migrate the remaining routes in priority order. Remove old aliases only when consumers are migrated. Keep each intermediate revision usable and send the complete affected surface to independent review.
 
-Give every inventory surface exactly one verdict and record the reason. No verdict means preserve.
+## Verify parity
 
-- **Preserve** — correct today: do not touch it, and guard it.
-- **Change** — same structure and behavior, new tokens, layout, or type.
-- **Replace** — new implementation, identical external behavior and URL.
-- **Remove** — requires an owner, a usage number, and a redirect or replacement.
+Compare before and after item by item:
 
-## Stage so it always ships
+- URLs, query parameters, and deep links.
+- Fields, defaults, validation rules, and error meaning.
+- Data exposure for each permission.
+- Keyboard order, focus restoration, and shortcuts.
+- Meaning of user-facing copy.
 
-Order stages so the product ships at the end of each one. Never close a stage with two languages live.
+A clearer sentence may change wording; it may not change a product claim.
 
-1. Land tokens and primitives, aliasing the old values to the new names.
-2. Convert one low-traffic route end to end as the proof.
-3. Convert the rest in traffic order, capturing after each route.
-4. Delete aliases and dead styles only after the last route converts.
-5. Send the whole surface to the independent review pass, not stage by stage.
+## Resolve disagreement and guard the result
 
-## The parity list
+Bound unresolved choices to two options and a short review round (two exchanges or 15 minutes). Record the selected option and why the other lost. If still tied, prefer the option that preserves more behavior.
 
-Every item holds before and after. A visual improvement never buys a parity exception.
-
-- Same URLs, query params, and deep links resolving to the same content.
-- Same fields, defaults, validation rules, and error text.
-- Same data visible per permission; nothing newly exposed or hidden.
-- Same keyboard order, focus return points, and shortcut bindings.
-- Same copy meaning; wording may tighten, claims may not move.
-
-## Debate on a clock
-
-Bounded debate improves the result; open debate replaces it. Timebox and record the option that lost.
-
-- Two options maximum, each carrying one capture or one paragraph.
-- Two exchanges or 15 minutes, whichever ends first.
-- Decide against `direction.principles`, then log the rejected option in `omissions`.
-- Still tied: ship the option preserving more behavior and revisit with usage data.
-
-## Regression guards
-
-Guard the preserve verdicts mechanically. Intention is not a guard.
-
-- Capture-diff every preserve surface at every declared viewport.
-- Assert contrast and focus order on each converted route.
-- Fail the build on new raw hex or raw px outside the token file.
-- Re-run the performance budgets per converted route.
-- Check CJK line breaking at the narrowest viewport when `locale` includes CJK.
-
-## Closeout
-
-Close only when the removal list is empty and captures pair up one to one.
-
-- Every remove verdict executed, or deferred with an owner and a date.
-- Baseline and post-change captures paired in the evidence manifest.
-- Contract re-frozen, SHA-256 recomputed, `payload-version.json` refreshed if plugin assets changed.
-
-## Failure patterns
-
-Reject:
-
-- A baseline captured after editing began.
-- "Improved" copy that changes what the product promises.
-- Removing a control because nobody could explain it.
-- Two design languages live past the end of a stage.
-- Parity waived because the new version looks better.
+Mechanically protect preserved surfaces. Capture-diff them at declared viewports; check contrast, focus, performance budgets, and CJK breaking where applicable. Close only when removals are resolved or have an owner/date and before/after captures are paired against the current contract hash.