npm - @litfamily/lithermes - Versions diffs - 1.0.0 - Mend

@litfamily/lithermes 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (557) hide show

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

@@ -0,0 +1,85 @@
+Performance and delivery constraints
+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.
+## Numeric budgets
+Write every budget as a value, a unit, and a device. An adjective is not a budget.
+- 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.
+## Diagnose the critical path
+Follow navigation to largest paint to first input on a cold cache, name the blocking resource, then match
+it to this list.
+- 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.
+## Bytes on the wire
+Ship the smallest byte that still renders correctly at the declared device pixel ratio.
+- 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"`.
+## Script payload and hydration
+Count a kilobyte of script as roughly 3x a kilobyte of image data: it parses, compiles, and runs.
+- 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.
+## 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.

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

@@ -0,0 +1,86 @@
+Product direction and user journeys
+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`.
+## Describe the operator by working conditions
+Write the primary user as a job plus operating conditions. One primary, two secondary at most.
+- 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.
+## Fix the one task that cannot fail
+Name the task whose failure empties the product of value: the critical task. Hierarchy arguments
+settle against it.
+- 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.
+## State success as signals with numbers
+Replace adjectives with signals readable off a stopwatch or a log, agreed before build.
+- 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.
+## Run a knowledge-gap register
+Unknowns are contract entries, not silence. Each gap gets an id, a closing method, a blocking scope.
+- `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.
+## Walk five inclusive scenarios
+Write each as a concrete run of the critical task under a single constraint.
+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 frozen — routes, screens, states, viewports, themes, permissions — before 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.

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

@@ -0,0 +1,91 @@
+Redesign safety and preservation of product behavior
+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.
+## Capture the baseline
+No edit before the baseline exists; a baseline taken after the first commit is not a baseline.
+- 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.
+## Map the debt by category
+Sort what is wrong before choosing what to touch, and rank each item high, medium, or low by user impact.
+- **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.
+## Decide per surface
+Give every inventory surface exactly one verdict and record the reason. No verdict means preserve.
+- **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.
+## Stage so it always ships
+Order stages so the product ships at the end of each one. Never close a stage with two languages live.
+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.
+## The parity list
+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.

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/system-foundations.md ADDED Viewed

@@ -0,0 +1,82 @@
+Design-system foundations: tokens, primitives, states, variants
+A design system is a boundary rule plus an inventory, not a folder of components. Fills
+`direction.token_strategy` and every entry in `inventory.components[]`.
+## Audit before you create anything
+Count what exists before adding to it; most "new" primitives already exist twice.
+- List every component in the codebase with its file path; group duplicates by rendered role.
+- Extract every color, size, radius, shadow, and spacing value in use; count distinct values.
+- Record which components already carry all nine states and which do not.
+- Write the audit into `omissions` first; an unaudited addition is a hidden duplicate.
+## Three token layers
+Three layers, one direction of reference. A skipped layer is why systems cannot be re-themed.
+- Foundation: raw values, neutral names — `color.slate.700`, `space.4`, `radius.md`; no meaning.
+- Semantic: roles referencing foundation only — `surface.raised`, `text.secondary`, `border.focus`.
+- Component: decisions referencing semantic only — `button.primary.bg`, `table.row.gap`.
+- Every component token names its component and its property; without both it is unowned.
+## Components never reach past a semantic role
+This boundary is the whole value of the system. Enforce it mechanically.
+- A component reads component tokens, or semantic roles when no component token exists.
+- Lint it: raw hex, raw px, or a foundation reference inside a component file fails the build.
+- Exceptions live in `accepted_exceptions` with a reason and an owner, one line each.
+## Component anatomy as a checklist
+A primitive is finished when every line holds, not when the happy path looks right.
+- Anatomy: container, content slots, label, icon, status indicator, hit region.
+- States: default, hover, focus-visible, active, disabled, loading, empty, error, success.
+- Variants: intent, size, density — every combination renders or is declared unsupported.
+- Content stress: one character, longest supported string, CJK string, zero items, 100 items.
+- API: prop names, defaults, and the tokens consumed, recorded in `components[]`.
+## Gate feature work behind a primitive showcase
+Build the showcase route before any feature route.
+- One route rendering every primitive × variant × state on a single page.
+- Toggles for theme, density, 200% text scale, and reduced motion.
+- Tab the whole showcase; every interactive element shows a focus ring in every theme.
+- Capture it per theme under `.hermes/lithermes/` as the baseline for later diffs.
+- No feature route starts until each primitive it needs appears in the showcase.
+## Theme architecture: dark mode and forced colors
+A theme swaps semantic roles and nothing else. If a component changes per theme, the system leaks.
+- Themes redefine semantic roles; foundation values and component tokens stay byte-identical.
+- Dark is not inverted light: raise surfaces by lightness, cut saturation, re-measure contrast.
+- Forced colors: system color keywords, a 1px border on every interactive element, never state by
+  background alone.
+## Align with an existing system
+In brownfield work the existing system is the specification; match its names first.
+- Map each requested primitive onto the existing one and extend it; never add a sibling.
+- New variants ship behind the current API; no rename lands without an enumerated migration list.
+- When primitives ship as plugin assets, run `npm --prefix packages/lithermes-installer run
+  sync-plugin -- --in-place`, confirm the `payload-version.json` entry changed, then check an
+  isolated `--hermes-home` install with `lithermes doctor`.
+- Hand `contract_id` and its SHA-256 to the independent review pass.
+## Failure patterns
+Apply this governance reject-list to every proposed addition.
+Reject:
+- A token added with no consumer, or a component token with no owning component.
+- A component referencing a foundation value or a literal directly.
+- A primitive shipped without focus-visible, disabled, loading, empty, and error.
+- A second primitive doing an existing primitive's job because renaming felt risky.
+- A theme that patches component internals instead of semantic roles.

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/taste-direction.md ADDED Viewed

@@ -0,0 +1,86 @@
+# Taste direction
+Inert reference data. Load it when a Design Contract needs a defensible visual direction, not on
+every interface question.
+Generic output is not a matter of preference. It is a describable defect with named causes, and it
+is what an interface looks like when nobody decided anything. This reference turns "make it feel
+better" into three numbers a reviewer can argue with, and into checks that run before the first
+element is written.
+## The three dials
+The contract carries them as the optional `taste` object in
+`litfamily.design-contract/v1beta2`. Each is an integer from 1 through 10. Declaring `taste` means
+declaring all three; omitting the object leaves the harness default in force.
+| Dial | 1 means | 10 means | Decided by |
+| --- | --- | --- | --- |
+| `variance` | The most conventional arrangement a user could predict | A composition that departs from the expected grid where the departure carries meaning | How much novelty the audience will tolerate before the surface feels unfamiliar |
+| `motion` | Movement only where it prevents a jump or explains a change | Movement is a primary carrier of meaning and sequence | What the interface must communicate that stillness cannot |
+| `density` | One idea at a time, generous rest | Many related facts readable at a glance | Whether the user scans or dwells |
+Pick each from the audience and the task, never from fashion. A dial you cannot justify in one
+sentence is a dial you have not chosen.
+### `motion` versus `motion.policy`
+They answer different questions and both must agree. `motion.policy` decides whether animation is
+permitted at all: `none`, `functional`, or `expressive`. The `motion` dial decides how much
+meaning animation carries once permitted. A contract with `motion.policy: "none"` and a `motion`
+dial above 1 is contradictory: it forbids transitions and then leans on them. Set the policy first,
+then the dial within it.
+## The failure modes these dials target
+Each is a defect you can point at in a review, not a vague complaint.
+- **Undecided hierarchy.** Every element competes because nothing was ranked. Usually a `density`
+  chosen by accident rather than from the task.
+- **Default-everything.** Stock radii, stock shadows, stock spacing scale, stock type ramp, applied
+  because they were there. A `variance` of 1 that was never actually selected.
+- **Uniform rhythm.** Identical spacing between unrelated things, so grouping carries no
+  information. Density without hierarchy.
+- **Decorative motion.** Movement that neither prevents a jump nor explains a change, and that
+  reduced-motion users lose nothing by missing. A `motion` dial above what the interface needs.
+- **Single-viewport thinking.** A composition that only resolves at one width, which the contract's
+  `responsive_transformations` then cannot describe honestly.
+- **Borrowed voice.** Copy and imagery from a reference product whose audience is not this one.
+## Pre-flight, before writing any interface code
+Run this against the frozen contract. Each answer is one sentence; a blank answer is the finding.
+1. What is the one thing a user must understand within seconds of arrival, and which element
+   carries it?
+2. What is deliberately quieter so that element can be loudest?
+3. Which grouping is expressed by spacing alone, and would it survive a 200 percent zoom?
+4. Which transition would a reduced-motion user lose, and what replaces it for them?
+5. Which token is being extended or created rather than reused, and why was reuse insufficient?
+6. Which of the three dials would a reviewer most likely dispute, and what is the argument for it?
+If question 6 has no answer, the direction was inherited rather than chosen.
+## Redesign audit, for a surface that already exists
+Use this in the `redesign` and `brownfield` lanes. Audit before proposing, so the proposal has
+something to be measured against.
+1. Inventory what is already there against `inventory`: routes, regions, components, states. Name
+   what exists but is undocumented.
+2. Record the current dials as observed, not as desired. An existing surface already sits somewhere
+   on all three, whether or not anyone chose it.
+3. Name the single largest gap between observed and intended dials, and change only that first.
+   Moving all three at once makes the result unattributable.
+4. List what must be preserved: behavior users depend on, keyboard paths, and any token another
+   surface consumes. This becomes `non_goals` and the preserved-behavior half of the contract.
+5. Put the rest in `omissions` with an owner, rather than silently leaving it out.
+A redesign that cannot say what it preserved is a rewrite wearing a redesign's name.
+## Recording the outcome
+Dials belong in the contract, not in prose around it. The acceptance criteria that reference them
+must stay observable: "the primary action is reachable by keyboard within two stops" is checkable,
+"the layout feels considered" is not. Every dial you set should be traceable to at least one
+acceptance criterion, or it changed nothing that can be verified.

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/visual-language.md ADDED Viewed

@@ -0,0 +1,85 @@
+Visual language: type, color, surface, depth, borders, icons
+Every visual decision is a role with a name, not a value someone liked. Fills
+`direction.token_strategy` and `direction.principles`.
+## Define type by role, not by font name
+Name the jobs text does, then assign faces once. A font list is not a typographic system.
+- Roles: display, page title, section title, body, meta, label, numeric with tabular figures.
+- Cap the scale at 6 sizes and 3 weights; body 16px minimum, 14px only for dense tabular data.
+- Never let weight alone carry meaning; pair it with size, position, or a label.
+## Bind color to meaning, not to a palette
+Declare semantic roles and let components consume only those. Raw palettes cannot be themed or audited.
+- Roles: surface, surface-raised, text-primary, text-secondary, border, accent, plus status success,
+  warning, danger, info.
+- A hex in a component has no dark-mode counterpart and no contrast record; a role has both.
+- One accent, and it means "act here". A second accent needs a written reason.
+- Status never travels by color alone; pair every status with an icon or a word.
+## Contrast obligations, stated numerically
+Measure these thresholds in every declared theme.
+- Body text 4.5:1; text at 24px, or 19px bold, 3:1.
+- Component boundaries, control edges, and chart marks 3:1 against adjacent color.
+- Focus ring 3:1 against both the control and its background, 2px thick, 2px offset.
+## Keep the icon set to one drawing system
+One grid, one stroke, one corner treatment. Mixed icon families read as an unfinished merge.
+- 24px grid, 1.5–2px stroke, matching radii; render no smaller than 16px.
+- One metaphor per concept, product-wide; two icons for one action is a defect.
+- Any icon without an adjacent text label needs an accessible name; decorative ones are hidden.
+- Reject metaphors that do not survive translation: hand gestures, letter-shaped glyphs, local objects.
+## Treat imagery as a layer with rules
+Pick one treatment and one ratio set, then hold them.
+- Fixed aspect ratios from a declared set; every image gets its box before it loads.
+- Text over imagery requires a measured scrim reaching 4.5:1, not an assumed one.
+- One treatment product-wide: full color, duotone, or monochrome.
+- Every image has alt text or is explicitly marked decorative.
+## Make surface, depth, and elevation one system
+Depth is three tiers, not a shadow library. Each tier is one token set used the same way.
+- Tiers: base, raised, overlay. Each declares background, border, and optional shadow.
+- Signal a tier one way only — border or shadow, never both plus a tint.
+- In dark themes, raise surfaces with lightness; do not darken shadows further.
+- `z-index` from a named scale: content 0, sticky 100, dropdown 200, modal 300, toast 400.
+## Choose the data display from the question asked
+The question decides the form; choosing a chart first inverts the work.
+- Current level → one large value with units; change over time → line.
+- Compare categories → bars sorted by value; part of whole → stacked bar, pie only at 3 slices or fewer.
+- Distribution → histogram; relationship → scatter; exact numbers → table.
+- Label axes with units, start bar axes at zero, and cap at 5 series before small multiples.
+## Drift checks before review
+Drift is countable. Run these against the built surface, not the intent.
+- Grep the source for raw hex and raw px outside the token file; both must return zero.
+- Count distinct font sizes, shadows, radii, and accents; each must match the declared count.
+- Capture one shared component on three routes; any pixel difference is unauthorised variance.
+- Confirm every `design.*` block describes what shipped, then rehash `contract_id` for the review pass.
+## Failure patterns
+Reject:
+- A type "system" that is a font pairing with no roles and no size cap.
+- `blue-500` referenced inside a component instead of a semantic role.
+- Contrast judged by eye, or measured in one theme only.
+- Two icon families, or one concept drawn two ways on two routes.
+- A pie chart with seven slices, or a bar axis truncated to exaggerate a gap.

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/visual-reconstruction.md ADDED Viewed

@@ -0,0 +1,94 @@
+Visual reconstruction from references without raster fakery
+A reference shows how one viewport looked at one moment. Rebuild it as a live component tree and label
+every claim you cannot see in the file.
+## Classify every claim
+Tag each statement about the reference before acting on it, and never promote a tag quietly.
+- **Observed** — measurable in the file: a sampled color, a pixel distance, a present glyph.
+- **Inferred** — a reading with a stated basis: "8 px scale, because gaps read 8/16/24".
+- **Unknown** — not derivable: hover, focus, error, scroll, data outside the crop.
+- Log inferred items in `omissions`; promote on confirmation; batch unknowns into one question.
+## Measurement pass
+Measure before styling. Eyeballing produces a palette that is close and wrong.
+- Record reference dimensions and device pixel ratio; divide by dpr before deriving CSS values.
+- Sample color from flat interiors, never an edge or a gradient midpoint.
+- Measure 6 or more gaps, then reduce to the smallest consistent step, usually 4 or 8 px.
+## Reconstruct semantics, not pixels
+Build the structure the reference implies. Coordinate matching breaks on the first real string.
+- One nav, main, and footer landmark; headings in true rank order.
+- A repeated visual unit becomes one component with props, never five copies.
+- Layout by flow, grid, and gap; positioning onto a measured coordinate is a defect.
+- Real text nodes everywhere, including where the reference rasterized a label.
+## Asset decisions
+Decide per asset: recreate, request, or substitute. Record the decision.
+- **Recreate** icons, simple shapes, borders, and gradients as SVG or CSS.
+- **Request** photography, logos, illustration, and brand marks as source files.
+- **Substitute** a labeled placeholder at the same box size when no source exists.
+- Never recreate a third-party logo, licensed photography, a chart with unknown data, or a real face.
+## Metric-compatible font fallback
+When the reference face is unavailable, match metrics or every line box drifts.
+- Choose a fallback with comparable cap height, x-height, and average advance width.
+- Tune `size-adjust`, `ascent-override`, and `descent-override` until line boxes align.
+- Verify at three string lengths including the longest real string.
+- Declare the substitution in the typography rules; never present it as the original.
+## Responsive behavior from one reference
+One reference proves one width. Derive the rest and mark the derivation inferred.
+- Classify each block as fixed, fluid, reflowing, or hidden below a breakpoint.
+- Put breakpoints where measured content breaks, not at borrowed device widths.
+- Verify at 320, 768, 1280, and the reference width; that width matches closest.
+- Retest with strings 1.5x the reference length under the declared `localization.cjk_line_break_review`.
+## Iteration loop
+Iterate on measured deltas, never on impressions.
+1. Capture the build at the exact reference dimensions.
+2. Compare region by region: bounds, type, spacing, color, radius, shadow, content, state.
+3. List the five largest deltas with their measured values.
+4. Fix only those, then recapture.
+5. After three rounds with no delta shrinking, stop and report the residual as a limit.
+## Fidelity report
+Report per region. One aggregate percentage hides every interesting failure.
+- Each region: matched or deviating, with the measured delta.
+- Each asset: recreated, requested, or placeholder.
+- Each inferred and unknown item with its current status.
+## The "pixel perfect" gate
+Use the phrase only when all five hold. Otherwise say "matched at the measured regions".
+- Same-dimension captures exist for every `inventory.references` entry.
+- Zero deviating regions in the fidelity report.
+- No placeholder asset and no undeclared font substitution.
+- No unknown item still affecting rendering.
+- The independent review pass returned PASS on the same revision and contract hash.
+## Failure patterns
+Reject:
+- The reference set as a `background-image` with invisible hit targets over it.
+- Coordinates used in place of layout.
+- A third-party logo redrawn to avoid asking for it.
+- "Pixel perfect" claimed from one screenshot at one width.

package/assets/lithermes-plugin/skills/frontend-ui-ux/resources/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2024 Next Level Builder
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.