@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/frontend-ui-ux/references/performance-delivery.md

@@ -0,0 +1,89 @@
+# Performance and Delivery Quality
+
+Performance is a user-experience property. Optimize responsiveness and stability without deleting
+useful content or accessibility.
+
+## Budget before optimization
+
+Set measurable contract budgets appropriate to the product:
+
+- largest-content render;
+- layout shift;
+- interaction latency;
+- initial JavaScript and CSS transfer;
+- image and font behavior;
+- route-specific server latency where observable.
+
+Budgets are decision constraints, not guaranteed scores across every device.
+
+## Diagnose the critical path
+
+Inspect navigation, network waterfall, server timing, main-thread work, rendering, layout shifts,
+and interaction traces. Determine whether the constraint is data, code, asset, style, layout, or
+third-party work.
+
+Common root causes:
+
+- render-blocking fonts or styles;
+- oversized hero media;
+- unnecessary client hydration;
+- duplicate dependencies;
+- long main-thread tasks;
+- broad rerender cascades;
+- synchronous measurement and layout thrashing;
+- missing dimensions;
+- expensive effects;
+- unbounded third-party scripts;
+- large lists rendered without need.
+
+## Asset delivery
+
+Use responsive images, appropriate formats, dimensions, lazy loading below the critical region,
+and stable aspect ratios. Subset and preload fonts only when evidence supports it; use a resilient
+fallback strategy. Avoid base64 inflation and decorative video that competes with the primary task.
+
+## JavaScript delivery
+
+Ship only interaction that exists. Split by route or capability when it shortens critical startup
+without creating request fragmentation. Defer analytics and optional widgets responsibly. Do not
+solve a small rendering cost with a large abstraction.
+
+## React diagnosis
+
+Inspect ownership before memoizing:
+
+- repeated state updates;
+- unstable object/function props;
+- over-broad context;
+- effects that write derived state;
+- list identity;
+- expensive calculations repeated per render;
+- client components wrapping mostly static trees;
+- waterfalls caused by sequential fetching.
+
+Use profiler evidence. Memoization adds comparison and complexity; it is not a quality badge.
+
+## Lists and data
+
+Paginate or virtualize only when the collection size and interaction justify it. Virtualization must retain
+keyboard navigation, focus, accessible counts, search, print/export expectations, and stable row
+identity. Avoid rendering hidden tabs or offscreen panels unnecessarily.
+
+## Perceived performance
+
+Communicate honest progress. Skeletons should resemble stable structure and avoid motion overload.
+Optimistic updates require safe rollback. Preserve content during background refresh when stale data
+is still useful and label freshness.
+
+## Audit protocol
+
+1. Test a production-like build.
+2. Record environment, route, state, throttling, and source hash.
+3. Run more than once and report distribution, not one lucky sample.
+4. Inspect trace evidence behind the metric.
+5. Make one attributable correction.
+6. rerun the same scenario.
+7. Check accessibility and functionality did not regress.
+
+A perfect synthetic score is not a reason to remove needed product capability. Report laboratory
+and real-user evidence separately.

package/marketplace/plugins/litcodex/skills/frontend-ui-ux/references/product-direction.md

@@ -0,0 +1,101 @@
+# Product Direction and Research
+
+Use this reference when the interface problem is underspecified, several directions are plausible,
+or product decisions must be separated from visual preferences.
+
+## Frame the decision
+
+Capture:
+
+- audience, environment, frequency, and consequence of failure;
+- the job the interface must make easier;
+- existing behavior that must remain stable;
+- measurable outcome and observable proxy;
+- known constraints: platform, content, brand, schedule, localization, accessibility;
+- non-goals and decisions owned by someone else.
+
+A useful design question has alternatives and a consequence. “Make it modern” is not a decision.
+“Should new operators see guided steps or an expert-dense workspace?” is.
+
+## Knowledge-gap register
+
+For each unknown, record:
+
+| Field | Meaning |
+| --- | --- |
+| Question | What must be learned? |
+| Decision | Which product choice depends on it? |
+| Risk | Cost of being wrong. |
+| Method | Cheapest credible way to learn. |
+| Participants | Whose experience matters? |
+| Stop rule | Enough evidence to decide. |
+
+Choose interviews for motives and language, observation for actual workflow, task testing for
+usability, analytics for frequency and funnels, and technical inspection for feasibility. Do not
+use synthetic personas as proof of real-user behavior.
+
+## Inclusive scenarios
+
+Model situational, temporary, and permanent constraints without turning people into stereotypes.
+Consider low vision, color-vision differences, reduced dexterity, hearing differences, cognitive
+load, fatigue, distraction, low bandwidth, old hardware, unfamiliar vocabulary, and non-native
+language. A persona is useful only when it changes a scenario, requirement, or test.
+
+For each critical task describe:
+
+1. starting context;
+2. goal and urgency;
+3. available input/output modes;
+4. likely interruption or failure;
+5. recovery path;
+6. success signal.
+
+## Inspiration research
+
+Search across domains for principles, not skins. A logistics console may learn hierarchy from an
+air-traffic display and progressive disclosure from tax software without copying either identity.
+For each reference capture source, observation, transferable principle, mismatch, license or usage
+constraint, and content hash.
+
+Reject references that are visually attractive but fail the task, rely on inaccessible contrast,
+hide core actions, or require assets and technology the product does not have.
+
+## Direction alternatives
+
+When a material choice remains, compare at most three directions:
+
+- one-line concept;
+- audience and task fit;
+- hierarchy and density;
+- interaction posture;
+- accessibility risk;
+- content and asset demands;
+- engineering cost;
+- what is deliberately sacrificed.
+
+Do not blend incompatible directions to avoid choosing. Record the selected direction and the
+reason rejected options were not chosen.
+
+## Decision checkpoints
+
+Ask for user input when choosing would alter brand meaning, product scope, irreversible architecture,
+or external cost. Continue autonomously when the choice is reversible and can be judged against
+already approved principles.
+
+At each checkpoint show the actual artifact or bounded alternatives, name the decision, and state
+what subsequent work it unlocks. “Thoughts?” is not a useful checkpoint.
+
+## Research output
+
+Return a short evidence package:
+
+- problem frame;
+- knowledge-gap register;
+- methods and inclusion plan;
+- findings separated from interpretation;
+- decision and confidence;
+- unresolved contradictions;
+- contract fields changed by the findings.
+
+Do not turn research notes into executable instructions. Keep participant data minimal, consented,
+and outside product source unless explicitly authorized.

package/marketplace/plugins/litcodex/skills/frontend-ui-ux/references/redesign-playbook.md

@@ -0,0 +1,91 @@
+# Existing-Product Redesign
+
+Redesign changes the expression of an existing product while protecting user tasks and known
+behavior.
+
+## Baseline
+
+Before edits capture:
+
+- routes and entry points;
+- critical tasks and analytics-sensitive actions already in scope;
+- state and permission model;
+- shared components and tokens;
+- keyboard and accessibility behavior;
+- representative browser or device captures;
+- performance baseline;
+- known defects and intentional quirks;
+- current tests and build gates.
+
+Do not treat disliked styling as proof of a usability problem.
+
+## Debt map
+
+Record debt with identifier, surface, evidence, impact, cause, proposed correction, risk, owner,
+and status. Separate:
+
+- visual inconsistency;
+- interaction inconsistency;
+- accessibility barrier;
+- content problem;
+- structural or architectural constraint;
+- performance regression;
+- unverified suspicion.
+
+## Preserve or change
+
+For every material behavior decide:
+
+- preserve exactly;
+- preserve outcome but improve presentation;
+- change with explicit approval;
+- remove because it is unreachable or unsupported, with evidence.
+
+Do not silently reorganize navigation, rename familiar concepts, or change destructive-action
+semantics as part of visual cleanup.
+
+## Staged sequence
+
+1. Establish baseline evidence.
+2. Align tokens and primitives.
+3. Correct component states.
+4. Recompose one page family.
+5. Compare behavior and visual output.
+6. Expand to remaining surfaces.
+7. remove dead legacy styles only after usage search and runtime verification.
+
+Keep changes attributable. A system-wide rewrite and page redesign in one opaque patch makes
+regression analysis harder.
+
+## Before and after
+
+Use the same:
+
+- route and seeded data;
+- state;
+- viewport and device scale;
+- theme and locale;
+- authentication role;
+- content;
+- capture method.
+
+Show improvements and regressions. Do not select a broken “before” and a flattering unrelated
+“after.”
+
+## Design debate
+
+When direction remains disputed, frame a concrete choice. Present the strongest case for each
+option, users served and underserved, accessibility consequences, technical tradeoffs, and
+evidence. Record the decision; do not endlessly hybridize.
+
+## Regression guard
+
+Verify task completion, keyboard behavior, screen-reader semantics, error recovery, responsive
+transforms, localization, and performance against baseline. A visually cleaner screen can still be
+a failed redesign if it obscures actions or changes behavior.
+
+## Closeout
+
+Update the debt register: resolved, accepted, deferred, or invalidated. Temporary exceptions need
+an owner and review condition. Preserve the rationale so future work does not reintroduce rejected
+patterns.

package/marketplace/plugins/litcodex/skills/frontend-ui-ux/references/system-foundations.md

@@ -0,0 +1,114 @@
+# Design-System Foundations
+
+Use this reference to establish or align tokens, primitives, components, themes, and governance.
+
+## Audit first
+
+Inventory existing styles, CSS variables, theme providers, component packages, icons, fonts,
+spacing utilities, focus treatments, documentation, and tests. Identify duplicates by semantics,
+not merely by equal values. Two gray values may represent different roles; two “primary” tokens
+may be accidental forks.
+
+Classify each item:
+
+- sound and reusable;
+- sound but undocumented;
+- inconsistent and safe to consolidate;
+- legacy but behaviorally sensitive;
+- missing.
+
+Do not replace a working system simply to introduce preferred tooling.
+
+## Three token layers
+
+### Foundation values
+
+Raw palettes, font families, type steps, spacing steps, radii, shadows, durations, easing curves,
+and dimensions. Names describe the value family, not a UI purpose.
+
+### Semantic roles
+
+Meaning across themes: canvas, surface, raised surface, text, muted text, divider, action,
+selection, focus, danger, warning, success, and information. Components consume these by default.
+
+### Component decisions
+
+Exceptions specific to a stable component contract, such as dialog width, table row density, or
+button padding. Component tokens should not become a second global palette.
+
+Keep aliases acyclic. Every token needs a supported theme value. Deprecations name a replacement
+and a removal condition.
+
+## Component anatomy
+
+For every shared component specify:
+
+- purpose and non-purpose;
+- semantic element or accessibility pattern;
+- slots and content constraints;
+- variants driven by meaning;
+- sizes driven by context;
+- states and state transitions;
+- keyboard and focus behavior;
+- responsive behavior;
+- localization risks;
+- theming and token dependencies;
+- performance considerations;
+- test and visual scenarios.
+
+Prefer composition over boolean-prop explosions. A variant should express a product distinction,
+not every one-off visual tweak.
+
+## Primitive showcase gate
+
+Before building broad screens, render representative primitives together:
+
+- type scale and long-form text;
+- semantic color roles in every theme;
+- buttons, links, fields, selectors, and destructive actions;
+- cards, panels, tables, lists, and overlays;
+- empty, loading, error, success, disabled, and focus states;
+- long CJK labels, text expansion, zoom, and forced colors.
+
+Fix systemic problems here. Page-level patches should not compensate for broken primitives.
+
+## Naming and ownership
+
+Names should express intent and survive visual changes. Avoid names tied to a literal hue, one page,
+or implementation framework when the concept is shared. Assign an owner for system-wide decisions,
+and record why an exception exists.
+
+## Theme architecture
+
+Themes change semantic values, not document meaning. Validate:
+
+- contrast in each theme;
+- visible focus without relying on a single hue;
+- illustrations and logos on each surface;
+- browser-native control styling;
+- charts with distinguishable patterns or labels;
+- system color-scheme integration;
+- no flash of the wrong theme during startup.
+
+## Alignment workflow
+
+1. Map existing values to semantic roles.
+2. Resolve collisions and gaps.
+3. Introduce aliases before migrating consumers.
+4. Move one component family at a time.
+5. Compare representative states.
+6. Remove dead values only after usage search and runtime verification.
+
+## Governance
+
+A healthy system includes change rationale, adoption guidance, visual and behavioral examples,
+accessibility requirements, versioning policy, and a debt register. Measure success by reduced
+inconsistency and faster safe delivery, not by token count.
+
+Reject:
+
+- arbitrary value additions without semantic need;
+- copied component APIs that do not fit the product;
+- hidden styling escape hatches;
+- theme literals embedded in feature code;
+- system documentation that cannot be traced to shipped primitives.

package/marketplace/plugins/litcodex/skills/frontend-ui-ux/references/taste-direction.md

@@ -0,0 +1,27 @@
+# Taste direction
+
+Use this reference when a product needs a bounded visual direction. The `taste` object is optional and additive in `litfamily.design-contract/v1beta2`. It does not replace the contract inventory, acceptance criteria, accessibility requirements, or evidence rules.
+
+## The three dials
+
+Record each dial as an integer from 1 through 10. Use the values as a relative target for the product. Do not treat them as a universal quality score.
+
+| Dial | Low values | High values |
+| --- | --- | --- |
+| `variance` | Repeated forms, restrained contrast, and a predictable visual rhythm | More variation in scale, shape, contrast, or composition while keeping the task path clear |
+| `motion` | Little or no movement beyond necessary state feedback | More expressive transitions and choreography when they improve orientation or feedback |
+| `density` | More whitespace, fewer simultaneous choices, and slower information scanning | More information in the same area with tighter grouping and stronger hierarchy |
+
+State the reason for each value in the surrounding design direction. A high value does not permit visual noise. A low value does not permit weak hierarchy.
+
+## Accessibility and reduced motion
+
+Accessibility outranks taste. Keep readable contrast, keyboard access, target size, focus visibility, screen-reader structure, zoom support, and forced-colors behavior in the base contract. Treat `motion` as a preference for the default experience, not permission to ignore `prefers-reduced-motion`.
+
+Define a reduced-motion result for every animated behavior. Remove or shorten non-essential movement. Preserve the state change, focus result, and task feedback without relying on motion. Record a conflict when a taste target would harm accessibility. Resolve the conflict in favor of the accessible behavior.
+
+## Evidence use
+
+Taste records design intent. It does not prove a rendered result. Use the design contract hash, declared inventory, binary acceptance criteria, and the visual-qa evidence manifest for verification. Compare the rendered result with the selected values during review. Record the observed difference as evidence. Do not turn a subjective preference into a PASS claim.
+
+Omit `taste` when the team has no stable direction to record. Adding the object later is safe because v1beta2 defines it as optional and additive. The validator rejects unknown taste keys, non-integer values, and values outside 1 through 10.

package/marketplace/plugins/litcodex/skills/frontend-ui-ux/references/visual-language.md

@@ -0,0 +1,86 @@
+# Visual Language
+
+This reference covers typography, color, iconography, imagery, surfaces, and data display.
+
+## Typography
+
+Select type by script coverage, rendering quality, licensing, delivery cost, and product voice.
+Define roles rather than styling arbitrary tags:
+
+- display: rare, expressive, short;
+- page title: clear location and purpose;
+- section title: scanning hierarchy;
+- body: sustained reading;
+- label: controls and metadata;
+- data: alignment and numeric clarity;
+- code: technical literals only.
+
+Use a constrained scale with deliberate line heights. Test real content at narrow and wide measures,
+200% zoom, bold text, mixed Latin/CJK, punctuation, numbers, URLs, and user-generated strings.
+Fallback fonts must preserve metrics closely enough to avoid layout collapse. Never assume a font
+is available because a mockup used it.
+
+## Color
+
+Build semantic roles from contrast needs and product meaning. Separate:
+
+- canvas and layered surfaces;
+- primary and secondary text;
+- action and selection;
+- border and focus;
+- positive, caution, destructive, and informational feedback;
+- categorical and sequential data encodings.
+
+Check contrast in the actual component states, including disabled and placeholder content. Color
+cannot be the only signal. Provide text, icon shape, underline, pattern, or position as needed.
+Reserve the strongest chroma for decisions and status, not decoration everywhere.
+
+## Iconography
+
+Use one coherent construction: stroke weight, optical size, corner behavior, fill policy, and
+metaphor vocabulary. Icons adjacent to text are usually decorative; standalone controls require
+an accessible name. Test mirrored meaning in right-to-left layouts. Do not substitute emoji for
+product icons when rendering varies across platforms.
+
+## Imagery
+
+State the role before selecting an image: evidence, explanation, identity, atmosphere, or content.
+Choose crop behavior, focal point, aspect ratio, loading strategy, alt text, and failure fallback.
+Decorative images use empty alternative text; informative images describe their purpose in
+context. Avoid text embedded in imagery when it must localize or remain accessible.
+
+## Surface and depth
+
+Create hierarchy with spacing, tone, borders, and typography before relying on shadow. Define a
+small elevation model tied to overlap and interaction. Excessive cards fragment reading order;
+excessive glass effects reduce contrast and increase compositing cost. Corners should express a
+system, not default to the same large radius on every object.
+
+## Data display
+
+Choose the representation from the analytical question:
+
+- exact values: table;
+- change over time: line or area with restrained fill;
+- magnitude comparison: aligned bars;
+- distribution: histogram, box plot, or density;
+- relationship: scatterplot;
+- part-to-whole: stacked bars when comparison remains legible;
+- flow or hierarchy: specialized diagram only when topology is the task.
+
+Start axes honestly, label units, expose source and freshness, handle missing values explicitly,
+and provide a table or textual summary for complex visuals. Use direct labels when possible.
+Patterns, shapes, and annotations must survive grayscale and color-vision differences.
+
+## Direction checks
+
+A coherent language answers:
+
+- What receives attention first?
+- What is interactive?
+- What is dangerous or irreversible?
+- What belongs together?
+- What is secondary but still discoverable?
+- How does the interface behave under stress: errors, long content, low bandwidth, zoom?
+
+If the answers rely on decorative novelty rather than stable hierarchy, revise the foundation.

package/marketplace/plugins/litcodex/skills/frontend-ui-ux/references/visual-reconstruction.md

@@ -0,0 +1,88 @@
+# Visual Reconstruction from Images
+
+Use when screenshots, scans, or generated images are the main source for code.
+
+## Evidence discipline
+
+Inspect the image before editing. Record image dimensions and hash. Separate:
+
+- directly observable geometry, colors, text, alignment, and visible assets;
+- plausible inference about grid, semantics, typography, and responsive rules;
+- unknown interaction, hidden state, accessibility, and backend behavior.
+
+Do not turn unknowns into confident implementation requirements.
+
+## Measurement pass
+
+Identify:
+
+1. frame and likely viewport;
+2. outer gutters and content bounds;
+3. major horizontal and vertical anchors;
+4. repeated spacing intervals;
+5. type roles and approximate metrics;
+6. color roles, not just sampled values;
+7. borders, radii, elevation, and overlays;
+8. media crops and focal points;
+9. visible component states;
+10. clipping that may indicate scroll or capture artifacts.
+
+Use ratios and relationships before literal pixels. A single image cannot establish every
+breakpoint.
+
+## Semantic reconstruction
+
+Infer the document and control structure from meaning. A visually styled row may be a list, table,
+navigation item, radio group, or disclosure; choose from behavior and content, not appearance.
+Build accessible semantics even when the reference does not reveal them.
+
+## Asset decisions
+
+For each asset choose:
+
+- reuse an authorized provided file;
+- recreate with CSS or vector primitives;
+- substitute an explicitly approximate neutral asset;
+- generate a new reference image when authorized;
+- request the missing asset when identity or fidelity depends on it.
+
+Never extract or fabricate a protected asset merely because it is visible. Record substitutions.
+
+## Typography
+
+Estimate family class, weight, size, line height, tracking, and measure separately. If the exact
+font is unavailable or unlicensed, select a metric-compatible fallback and label the result
+approximate. Test CJK and symbol coverage.
+
+## Responsive inference
+
+Create rules that preserve:
+
+- hierarchy;
+- alignment;
+- content priority;
+- touch and keyboard access;
+- image focal points;
+- readable measure.
+
+At additional viewports, transform rather than crop the desktop scene. Mark inferred behavior in
+the contract and verify it as a design decision, not as source fidelity.
+
+## Iteration loop
+
+1. Implement the structural skeleton.
+2. Capture at the reference dimensions.
+3. Compare major regions and alignment.
+4. Fix system-level causes before local offsets.
+5. Compare type and spacing.
+6. Compare color, borders, and imagery.
+7. Exercise hidden states and other viewports.
+8. Run accessibility and interaction checks.
+
+Avoid piling arbitrary offsets onto an incorrect grid.
+
+## Fidelity report
+
+Report matched relationships, intentional departures, inferred behavior, unavailable assets or
+fonts, and evidence paths. “Pixel perfect” is appropriate only when the source and actual images
+were compared under controlled rendering and all declared tolerances passed.