@litfamily/lithermes 1.0.7 → 1.0.9

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

@@ -0,0 +1,69 @@
+# Slop register
+
+Scan the rendered surface before making a taste judgment. DET rows are observable signals; a JUDG or DET-assist row is a prompt for a reviewer, never an automatic verdict. Fix the underlying repetition, empty decoration, or fake content in the cheapest order: delete, use the platform, reuse an existing design value, correct the value, then add. A brand rationale or real data binding may make a visual signal intentional; record that evidence rather than suppressing the signal.
+
+| Rule | Signal | Method | Threshold | Severity | Cheapest relevant fix |
+| --- | --- | --- | --- | --- | --- |
+| SLOP-001 | Cloned split-hero repetition | DET | run length ≥ 3 consecutive sections | MEDIUM | Break the run with a full-width, stacked, or bento section before the 3rd repeat (correct) |
+| SLOP-002 | Identical tile-grid repetition | DET | ≥ 4 identical tiles in one grid, where each tile's child shape is icon/svg/img + heading + text. A grid rendered as ul, ol or table is a data collection and is skipped (Delta 1: the calibrated n ≥ 4 floor; every clean reference has a legitimate 3-item grid) | MEDIUM | Vary tile size/structure per item, or switch one instance to a different layout family (correct) |
+| SLOP-003 | Nested card shells / unfilled bento cells | DET-assist, JUDG verdict | nesting depth ≥ 3, or cell count ≠ content-item count | MEDIUM | Collapse the redundant wrapper, or reshape the grid to match the content count (delete) |
+| SLOP-004 | Split-header filler paragraph | DET-assist, JUDG verdict | short column < 15 words, no distinct role, AND JUDG finds no real second message | MEDIUM | Stack headline and body vertically instead of splitting them (correct) |
+| SLOP-005 | Layout family reused verbatim across the page | DET | repeat count ≥ 3 (raised from ≥ 2 — reusing one layout family exactly twice on a longer page is ordinary, deliberate design-system consistency; ≥ 3 aligns with SLOP-001's consecutive-run floor) | MEDIUM | Give the repeat's second occurrence a different layout family (correct) |
+| SLOP-006 | Monotonous spacing rhythm | DET | page has ≥ 5 distinct visual regions AND ≥ 10 samples, dominant bucket > 85% of samples, ≤ 3 distinct nonzero buckets (raised from > 60% / whole-page sampling — a restrained, intentional 3-token spacing system on a simple page is good practice, not slop) | MEDIUM | Introduce a real multi-step spacing scale and apply it by relationship, not by habit (correct) |
+| SLOP-007 | Decorative empty space with no hierarchy role | JUDG | — | LOW (WARN) | Remove the gap or attach it to a real grouping decision (delete) |
+| SLOP-008 | Default purple/blue "AI" gradient palette | DET | HSL hue 260°–310° with a channel spread ≥ 50/255, on heading text (h1–h3 or ≥ 20px) or on any gradient stop; brand-consistency exemption applies (Delta 1: the earlier 220°–280° band pulled in ordinary brand blues near 221°–224°) | MEDIUM (calibration: never fired on any of the 19 clean/real pages in this task pack — a narrow single-pattern check, not a validated near-universal tell; downgraded from HIGH) | Swap in a neutral base plus one hue rooted in the actual brand, per the existing lila guardrail (correct) |
+| SLOP-009 | Gradient-filled headline text | DET | co-occurrence present | MEDIUM | Replace with a solid color and a weight or size change (correct) |
+| SLOP-010 | Glow / bloom halo on primary actions or headings | DET | shared glow test, not a focus state, and the same glow recurring on ≥ 2 unrelated elements | MEDIUM when the same glow recurs on ≥ 2 unrelated elements (Delta 1: a genericness tell is at most MEDIUM); a single glow is reported once under CF-404 (LOW), never twice | Use the shadow-as-border recipe (offset + soft neutral blur) instead, or drop the shadow (correct) |
+| SLOP-011 | Floating blob / sphere decoration | DET-assist, JUDG verdict | presence AND JUDG finds no stated purpose (a single deliberate atmospheric blob is a common, often well-regarded accent on modern SaaS marketing pages, not by itself a tell) | MEDIUM | Remove, or tie it to an actual focal point in the layout (delete) |
+| SLOP-012 | Decorative dot/grid background with no referent | DET | presence, no adjacent data element, AND ≥ 1 co-occurring slop signal (a dot-grid or blueprint texture alone is a common, tasteful choice on developer-tool sites, not inherently a tell) | MEDIUM | Remove unless the grid is standing in for a real chart (delete) |
+| SLOP-013 | Over-rendered noise hiding the layout | JUDG | — | LOW (WARN) | Reduce opacity or remove; if kept, confine it to a fixed non-scrolling layer (correct) |
+| SLOP-014 | Glassmorphism used as unexamined default | JUDG | — | LOW (WARN) | Drop the blur for a solid surface unless the brief earns it (delete) |
+| SLOP-015 | Fake pseudo-border accent stripe | DET | any one of (a)/(b)/(c) reaching ≥ 2 occurrences in one rounded scope; variant (b) alone reaches threshold at ≥ 1 | MEDIUM | Drop the stripe; carry the same emphasis in the card's own fill or an icon (delete) |
+| SLOP-016 | Reflex default sans font | DET-assist, JUDG verdict | any match on the fixed list (Geist family excepted) AND JUDG finds no declared rationale | MEDIUM | Pick a less common face tied to the product's own voice, or state why the common one was kept (correct) |
+| SLOP-017 | Serif reached for without a stated reason | DET-assist, JUDG verdict | any match on the shortlist AND no rationale recorded | MEDIUM | Switch to a sans display face, or keep the serif only with a recorded rationale (correct) |
+| SLOP-018 | Giant headline over a weak tiny subhead | DET-assist, JUDG verdict | ratio ≥ ~3.5 with subhead below ~14px, AND JUDG confirms it reads as an afterthought | MEDIUM | Raise the subhead's role in the scale or shorten the headline pairing (correct) |
+| SLOP-019 | Too many type moods on one page | DET | > 3 distinct families, icon fonts excluded. Chosen over impeccable's stricter 1-family "distill" ceiling because distill is a deliberate reduction workflow, not a general craft floor; krehel's general guidance ("rarely use more than three") is used instead | MEDIUM | Cut back to the stated ceiling for the page (delete) |
+| SLOP-020 | Lazy all-caps overuse | DET | leaf text length > ~40 chars under text-transform: uppercase, majority-cased-script text only | LOW | Reserve uppercase for short labels only; sentence-case the rest (correct) |
+| SLOP-021 | Washed-out gray secondary text on a colored surface | DET | text L 40–70%, S < 10%, background chromatic | MEDIUM (cross-ref **CF-201** — craft floor owns the canonical contrast-floor check this overlaps; kept here for the reflex-default pattern itself) | Tint the secondary text from the surface's own hue instead of plain gray (correct) |
+| SLOP-022 | More than one accent hue competing per screen | JUDG, DET-assist | > 1 accent hue family, fill-surfaces ≥ 24×24px only, status colors excluded | MEDIUM (cross-ref **CF-205** — craft floor owns the canonical one-accent-per-view threshold and the identical filled-surface/status-role-excluded histogram method; this row restates the same finding as a genericness signal, see Section C's CF-205 catalogue entry for the executable algorithm) | Pick one accent per view and demote the rest to neutral (correct) |
+| SLOP-023 | Pure black or pure white as a base surface | DET | exact match, outside the declared-dark-theme exception | LOW | Shift to an off-black/off-white a few percent toward the brand's neutral (correct) |
+| SLOP-024 | Spring/bounce easing on routine feedback | DET | keyword match, or bezier outside that range, on a routine control | MEDIUM (cross-ref **CF-505** — craft floor owns the canonical threshold and the executable scanAnimationTimingIssues algorithm in Section C; this row is a cross-reference, not a second implementation) | Replace with a settled ease-out curve, or a spring config with bounce fixed at 0 (correct) |
+| SLOP-025 | Entrance animation scaling in from zero | DET | scale start ≤ ~0.1 | MEDIUM (cross-ref **CF-503** — craft floor's floor is 0.95, tighter than this row's ~0.1; craft floor owns the canonical threshold) | Start near 0.95, never 0 (correct). Note: an absolutely-positioned icon swap/cross-fade is a distinct convention with its own recipe (scale: 0.25 → 1, never 0.5 or 0.6) — don't fold that case into this general entrance-scale floor |
+| SLOP-026 | Animating layout-triggering properties for motion | DET | any layout property present outside the disclosure exception | MEDIUM (cross-ref **CF-508** — craft floor owns the canonical threshold; the slop angle is the reflex choice, not just the cost) | Animate transform/opacity instead (correct) |
+| SLOP-027 | Decorative infinite pulse/blink with no bound state | DET | presence, no bound-state signal of any of the above kinds | LOW | Remove, or slow it and bind it to the real status it claims to show (delete) |
+| SLOP-028 | Motion fired on every routine, high-frequency interaction | JUDG, DET-assist | transition duration > ~150ms on a selector in the fixed high-frequency set | LOW (cross-ref **CF-506** — craft floor's ≤150ms high-frequency ceiling is the same threshold, scoped to a repeated-selector/scrollable-container gate) | Make the routine case instant or ≤150ms; save longer motion for rare, meaningful moments (correct) |
+| SLOP-029 | Eyebrow/kicker label templated above most headings | DET | count > ceil(sectionCount / 3), where sectionCount = the number of visible h2; visible elements only | MEDIUM (Delta 1: a genericness tell is at most MEDIUM) | Drop the eyebrow; the heading and the section's place on the page already carry the context (delete) |
+| SLOP-030 | Section numbering used as decoration | DET-assist, JUDG verdict | any match, ≥ 2 distinct index values, AND JUDG finds no real ordering behind it — the ubiquitous "01/02/03 — how it works" pattern describing a genuinely sequential process is not itself a defect | MEDIUM | Remove the numbering; if progression matters, name the step itself instead of counting it (delete) |
+| SLOP-031 | Unreleased-looking version/status stamp in marketing copy | DET-assist, JUDG verdict | any match AND JUDG finds no real release-notes context | MEDIUM | Remove the stamp unless the brief is genuinely about a launch/preview status (delete) |
+| SLOP-032 | Decorative status dot with no bound state | DET | presence, no bound attribute | LOW | Remove, or reserve it for an actual live/availability signal (delete) |
+| SLOP-033 | Middle-dot / locale-time separator strip overused | DET | · count ≥ 3 on one line, OR ≥ 2 co-occurring locale/weather tokens on one line | LOW | Prefer line breaks or columns to chained middle-dots; drop the locale strip unless the brief is genuinely place/time relevant (delete) |
+| SLOP-034 | Decorative word strip at the hero's foot | DET | presence within the bottom 15% of the hero's bbox, no <a>/real status content inside, not a compliance-badge strip | MEDIUM | Remove, unless it is a real sticky navigation strip or genuine build/status info (delete) |
+| SLOP-035 | Scroll-cue label or arrow at the first viewport | DET | presence | LOW | Remove; a visitor at the top of the page already knows the page continues (delete) |
+| SLOP-036 | Marketing buzzword filler | DET | count ≥ 1 | MEDIUM (Delta 1: a genericness tell is at most MEDIUM) | Replace with a specific, product-true claim (correct) |
+| SLOP-037 | Fabricated placeholder brand wordmark | DET-assist, JUDG verdict | any match on the fixed list AND JUDG confirms it is not the product's real name | MEDIUM (Delta 1) | Name the product from the brief itself, or invent one name tied to what it actually does (correct) |
+| SLOP-038 | Generic placeholder person name (the "Jane Doe" effect) | DET | any match | MEDIUM | Replace with a specific, locale-appropriate name (correct) |
+| SLOP-039 | Aphoristic "Not X. Y." cadence repeated | DET | combined count ≥ 3 | LOW | Vary sentence rhythm; keep the device to at most one use per page (correct) |
+| SLOP-040 | Em-dash (or flourish en-dash) anywhere in shipped copy | DET | count ≥ 1 in the main scope (zero tolerance unchanged, see Open Question 3); each carve-out hit is reported separately at LOW | MEDIUM (Delta 1: a dash neither blocks nor misleads a visitor; carve-out hits: LOW) | Rewrite with a period, comma, or parentheses instead (correct) |
+| SLOP-041 | Fabricated-looking numeric claim | JUDG, DET-assist | ≥ 1 candidate after the exclusions, with no source/mock marker in its block, AND JUDG finds no real origin for it | MEDIUM | Cite the real figure, label it as an example, or cut the number entirely (correct) |
+| SLOP-042 | Duplicate call-to-action wording for one intent | JUDG, DET-assist | > 1 distinct label per intent, same page | LOW | Pick one label for that intent and reuse it everywhere on the page (correct) |
+| SLOP-043 | Div-built fake product screenshot | DET-assist, JUDG verdict | any of (a)/(b)/(c) with no real-media or focusable descendant, AND JUDG confirms a stand-in rather than a real component preview | MEDIUM once JUDG confirms (tier Inferred, the same posture MD-011 takes for its JUDG items); a DET-assist hit alone is a review candidate, never a finding by itself | Use a real screenshot, a generated image, or a real component preview instead (correct / platform) |
+| SLOP-044 | Fake build/version footer inside a mock preview | DET-assist, JUDG verdict | any match AND JUDG finds no real changelog/docs surface | MEDIUM | Remove; this is CLI-fixture flavor with nothing to say to a visitor (delete) |
+| SLOP-045 | Decorative identical stat/KPI columns | DET-assist, JUDG verdict | ≥ 4 same-shape stat siblings (≥ 3 beside a marketing CTA), AND JUDG finds KPIs were not requested or a figure has no real source | MEDIUM once JUDG confirms (tier Inferred, MD-011's JUDG posture); a DET-assist hit alone is a review candidate, since an accurate stats banner is a legitimate pattern until judged otherwise | Remove unless the brief actually asked for KPI display, and back any kept number with a real source (delete) |
+| SLOP-046 | Decorative gauge/sparkline/progress element with a hard-coded value | DET-assist, JUDG verdict | candidate present, AND JUDG finds no real data point behind it | MEDIUM | Remove unless it encodes a real, current data point (delete) |
+| SLOP-047 | Illegible ticker-scale logo wall | DET | distinct-logo count ≤ 6, AND median rendered logo height < 20px at the 1440px RS viewport. The 20px floor is a house default: the corpus names the failure ('unreadable mosquito logos') without a size, and neither reference clone publishes one; recalibrate on labeled logo walls before tightening | MEDIUM | Slow it down, enlarge the logos, or replace the loop with a static row if the count is this small (correct) |
+| SLOP-048 | Autoplay carousel dots with no real function | DET | candidate present, autoplay declared or observed, and none of the accessible-binding signals present | LOW | Remove the dots or wire them to real keyboard/AT-reachable navigation (correct) |
+| SLOP-049 | Generic silhouette/egg avatar standing in for a person | DET | match against the fixed list | LOW | Use a believable photo placeholder or a deliberate illustrated style instead (correct) |
+| SLOP-050 | Category label printed under every logo in a trust wall | DET | any match | LOW | Drop the caption; the logo alone carries the credibility (delete) |
+| SLOP-051 | Illustration assembled from an excessive primitive count | JUDG, DET-assist | all DET-assist conditions met (≥ 8 primitives, ≥ 200×200px, ≥ 3 fills, ≤ 2 text elements, no pattern) AND JUDG confirms a stand-in scene. The constants are impeccable's published ones (it reads declared width/height or viewBox; this row reads the rendered box), not yet calibrated on this family's pages | MEDIUM | Commission or simplify the illustration; don't primitive-stack a substitute (correct) |
+| SLOP-052 | Busy geometric mask faking a photographic edge | DET | polygon: ≥ 10 vertices and mostly off-grid; path(): ≥ 3 curve segments (impeccable's published constants) | LOW | Use a real photographic crop, or a simple deliberate shape (correct) |
+| SLOP-053 | Emoji glyphs standing in for a real icon set | DET-assist, JUDG verdict | any match AND JUDG finds no stated emoji-policy exception | LOW | Replace with the project's chosen icon set (correct) |
+| SLOP-054 | Hover transform applied to the image element itself | DET | rule targets the image node itself | LOW | Move the transform to the container; animate the frame, not the picture (correct) |
+| SLOP-055 | Recurring cluster of generic tells appearing together | JUDG | ≥ 2 co-occurring DET hits on one component escalates the row from WARN to a real finding | MEDIUM (escalated); LOW (WARN) below that | Break up the combination; vary the visual language for that component specifically (correct) |
+| SLOP-056 | Overall "could be any competitor's product" genericness | JUDG | — | LOW (WARN), holistic-only | No single fix; return to the specific rows above that are contributing to the impression and act on those (correct) |
+| SLOP-057 | Broken image source | DET | any match | HIGH | Fix or replace the source, or remove the element (correct / delete) |
+| SLOP-058 | Dead link | DET (derived — an attribute scan cannot see an attached handler) | any match | HIGH (nav/primary) / MEDIUM (decorative) | Point it at a real destination, or make it a real button if it has no destination (correct) |
+| SLOP-059 | Button with no type/handler inside a form | DET inside a form; JUDG outside one | missing type on a button whose form owner has ≥2 submit-capable buttons (a lone typeless button is the intended implicit submit) | HIGH (inside a form only) | Add an explicit type="button" (or "submit" when that is genuinely intended) (correct) |
+| SLOP-060 | Placeholder / lorem text | DET | any match | LOW | Replace with real, brief-specific copy (correct) |
+| SLOP-061 | Marquee / scrolling ticker on text | DET | any match | LOW | Replace with a static row, or add a real pause/stop control (correct) |
+| SLOP-062 | Modal opened by reflex with no real interruption need | JUDG | — | LOW (WARN) | Replace with an inline panel, toast, or disclosure (correct) |
+| SLOP-063 | Monospace used as a "technical" costume | JUDG | — | LOW (WARN) | Switch to the page's normal text face unless the content is genuinely code/data (correct) |

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

@@ -1,82 +1,37 @@
-Design-system foundations: tokens, primitives, states, variants
+# Design-system foundations
 
-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[]`.
+Treat a design system as shared boundaries and a consumer inventory, not a folder of components. Record its token strategy and every delivered primitive in the Design Contract.
 
-## Audit before you create anything
+Record the reuse, extension, or creation choice in `direction.token_strategy`.
 
-Count what exists before adding to it; most "new" primitives already exist twice.
+## Audit, then add
 
-- 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.
+Before creating a primitive, locate existing components with the same rendered role, inspect their APIs and consumers, count current tokens, and list state/variant gaps. Extend the existing primitive when it fits; avoid parallel components without a specific reason.
 
-## Three token layers
+Organize tokens in one direction:
 
-Three layers, one direction of reference. A skipped layer is why systems cannot be re-themed.
+1. **Foundation:** neutral raw values, such as space, radius, and palette steps.
+2. **Semantic:** roles that refer to foundations, such as surface-raised or text-secondary.
+3. **Component:** a named component property that refers to semantic roles.
 
-- 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.
+A component should not reach into foundation values or embed raw color/spacing. Lint these boundaries where possible; record an owned exception with reason when a real constraint requires one.
 
-## Components never reach past a semantic role
+## Specify the component contract
 
-This boundary is the whole value of the system. Enforce it mechanically.
+For each component, name anatomy, API/defaults, token dependencies, variants, and supported states: default, hover where available, focus-visible, active, disabled, loading, empty, error, and success. Stress short and longest real strings, CJK, zero items, and representative large collections. Unsupported combinations should be explicit.
 
-- 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.
+A showcase route is useful when the deliverable is a reusable system or many variants need coordinated review. Include theme, density, text scale, and reduced-motion controls; do not make it a prerequisite for an unrelated feature.
 
-## Component anatomy as a checklist
+## Themes and existing APIs
 
-A primitive is finished when every line holds, not when the happy path looks right.
+Themes should change semantic roles, not component internals. Dark mode needs its own contrast measurements. Forced-colors mode should retain visible boundaries and state without relying on background color alone.
 
-- 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[]`.
+In brownfield work, preserve token names, props, defaults, and consumer rendering. Put new variants behind existing APIs; enumerate consumers before a rename. For a shipped plugin asset, follow the payload sync and isolated-install/doctor procedure after editing.
 
-## Gate feature work behind a primitive showcase
+## Reject
 
-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.
+- A token with no consumer or an unnamed component token.
+- A component using raw values instead of semantic roles.
+- A second primitive that duplicates an existing job without a migration reason.
+- A delivered control missing focus, disabled, loading, or failure states.
+- A theme that forks component internals rather than semantic roles.

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

@@ -1,85 +1,29 @@
-Visual language: type, color, surface, depth, borders, icons
+# Visual language
 
-Every visual decision is a role with a name, not a value someone liked. Fills
-`direction.token_strategy` and `direction.principles`.
+Choose roles and reusable values for typography, color, imagery, depth, icons, and data. Keep those decisions in the token strategy so components do not develop their own vocabulary.
 
-## Define type by role, not by font name
+## Type and color
 
-Name the jobs text does, then assign faces once. A font list is not a typographic system.
+Define roles such as display, page title, section title, body, metadata, labels, and tabular numerals. A useful starting cap is six sizes and three weights; body copy should be at least 16 px, with 14 px reserved for dense tables. Name font fallbacks and loading behavior.
 
-- 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.
+Use semantic color roles for surfaces, text, borders, actions, and status. One accent should have a consistent meaning; a second accent needs a stated reason. Status must include a word, icon, or shape as well as color. Measure rendered contrast in every supported theme:
 
-## Bind color to meaning, not to a palette
+- Body text: at least 4.5:1; 24 px text or 19 px bold text: at least 3:1.
+- Component boundaries, controls, and chart marks: at least 3:1.
+- Focus indicator: at least 3:1 against both control and adjacent surface.
 
-Declare semantic roles and let components consume only those. Raw palettes cannot be themed or audited.
+## Icons, imagery, and depth
 
-- 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.
+Use one icon family and a consistent grid/stroke. A 24 px grid and 1.5–2 px stroke are useful starting values; avoid rendering below 16 px. Use one metaphor per action, give unlabeled controls accessible names, and hide decorative icons from assistive technology.
 
-## Contrast obligations, stated numerically
+Define image ratios and rendered boxes before load. Measure any text scrim against the actual image. Asset origin, rights, and alt-text belong in brand-and-imagery.md.
 
-Measure these thresholds in every declared theme.
+Use a small named elevation scale (base, raised, overlay); identify tiers consistently and define overlay stacking order. For example: content 0, sticky 100, dropdown 200, modal 300, toast 400. In dark themes, remeasure surfaces rather than relying on heavier shadows.
 
-- 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.
+## Data display
 
-## Keep the icon set to one drawing system
+Choose the visual form from the question: current level → value with units; time trend → line; category comparison → sorted bars; part-to-whole → stacked bar (pie only for three slices or fewer); distribution → histogram; relationship → scatter; exact lookup → table. Label units, start bar axes at zero, and split series into small multiples when they become hard to compare.
 
-One grid, one stroke, one corner treatment. Mixed icon families read as an unfinished merge.
+## Check for drift
 
-- 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.
+Before review, inspect source for unapproved raw colors/spacing, count distinct type sizes, shadows, radii, and accents, and compare a shared component on representative routes. Update the contract to reflect what shipped and recompute its review hash.

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

@@ -1,94 +1,29 @@
-Visual reconstruction from references without raster fakery
+# Visual reconstruction
 
-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.
+Rebuild the supplied visual target as a live, semantic interface. A screenshot is evidence of one viewport at one moment; it does not define behavior, permission, source structure, or an entire brand.
 
-## Classify every claim
+## Keep evidence and inference separate
 
-Tag each statement about the reference before acting on it, and never promote a tag quietly.
+For each relevant region, record internally what is:
 
-- **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.
+- **Observed:** directly measurable, such as dimensions, color, spacing, and visible text.
+- **Inferred:** a plausible system with its basis, such as a spacing scale suggested by repeated gaps.
+- **Unknown:** not visible, such as focus, hover, error state, scroll behavior, or content outside the crop.
 
-## Measurement pass
+Preserve the source dimensions and hash. Do not turn uncertain observations into reader-facing labels or claims. Resolve only unknowns that affect the requested build.
 
-Measure before styling. Eyeballing produces a palette that is close and wrong.
+## Measure, then build real structure
 
-- 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.
+Measure at the source pixel ratio. Sample flat color areas, not edges or gradient transitions; compare several gaps before inferring a spacing scale. Implement with semantic elements, grid/flow, reusable components, and live text. Do not position an entire page by screenshot coordinates or use the target image as the interface background.
 
-## Reconstruct semantics, not pixels
+For assets, recreate simple shapes and icons when appropriate; request photography, logos, and brand illustrations, or use a clearly neutral placeholder. Never redraw third-party marks or invent unknown chart data. If the target font is unavailable, choose a metric-compatible fallback, tune its supported font metrics, and record the substitution.
 
-Build the structure the reference implies. Coordinate matching breaks on the first real string.
+## Derive responsive behavior
 
-- 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.
+A single target width cannot prove responsive behavior. Classify regions as fixed, fluid, reflowed, or conditionally hidden and mark those choices as inferred. Set breakpoints where content fails. Check the reference width, narrow and wide supported widths, longest real string, and CJK behavior when in scope.
 
-## Asset decisions
+## Compare and report
 
-Decide per asset: recreate, request, or substitute. Record the decision.
+Capture the build at the target dimensions and compare important regions: bounds, type, spacing, color, radius, content, and state. Fix the largest measured deltas, then recapture. After three iterations with no improvement, stop and report the remaining mismatch plainly.
 
-- **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.
+Use “pixel perfect” only when same-size captures cover every declared reference, all measured regions match, no placeholder or undeclared font remains, no material unknown affects rendering, and an independent reviewer passes the same revision and contract hash. Otherwise describe the result as a match at the measured regions. Keep observed/inferred/unknown detail in the internal review record.

package/assets/lithermes-plugin/skills/frontend-ui-ux/resources/THIRD-PARTY-NOTICE.txt

@@ -12,3 +12,18 @@ recorded in PROVENANCE.json.
 No upstream scripts, templates, CLI, installers, manifests, screenshots, previews,
 documentation, premium features, host integrations, code-example columns,
 documentation-URL columns, or google-fonts.csv data are included.
+
+Craft-floor and slop-register mechanisms were independently re-expressed after
+studying pbakaus/impeccable (https://github.com/pbakaus/impeccable), by Paul
+Bakaus, Apache License, Version 2.0, consulted at commit 9d715cc. No source
+file, prose, or fixture from that project is reproduced here.
+
+Mode, review-format, and routing-governance mechanisms were independently
+re-expressed after studying jakubkrehel/skills
+(https://github.com/jakubkrehel/skills), Copyright (c) 2026 Jakub Krehel,
+MIT License, consulted at commit 267330e. No source or prose is reproduced.
+
+Anti-slop catalogue and responsive value checks were independently re-expressed
+after studying the ui-skills.com playbook (https://www.ui-skills.com/playbook),
+sourced from github.com/ibelick/ui-skills, Copyright (c) 2026 Julien Thibeaut,
+MIT License. No source or prose from the site or repository is reproduced.