@pheem49/mint 1.8.2 → 1.10.0

package/temp_gridgeist/skills/gridgeist/references/review-checklist.md

@@ -0,0 +1,128 @@
+# Gridgeist Review Checklist
+
+Use this checklist after implementation or for a review-only request. Report only meaningful findings and distinguish observed evidence from inference.
+
+## 1. Product clarity and truth
+
+- Can a first-time user identify the product, audience, primary task, and next action quickly?
+- Does each section or workflow stage answer a distinct question?
+- Is copy specific rather than interchangeable SaaS language?
+- Are authentic product evidence and outcomes visible?
+- Are sample, fictional, estimated, or unverified claims labeled honestly?
+
+## 2. Brand fidelity and direction
+
+- Does the interface preserve recognizable voice, imagery, geometry, palette, and interaction character?
+- Was a brand-derived direction supported by converging visual implementation,
+  assets, or documented conventions rather than product content alone?
+- If a broad replacement direction was provisional, did implementation wait for
+  the user to choose or authorize the recommendation?
+- Does the visual thesis fit the audience and task rather than merely looking fashionable?
+- Is the grid visible, quiet, or invisible for a clear reason?
+- Would the product remain recognizable after removing generic technical chrome?
+
+## 3. Composition and hierarchy
+
+- Is there one clear dominant element in each viewport or workflow stage?
+- Do related elements share alignment and proximity?
+- Does the page alternate density and breathing room intentionally?
+- Do sections vary without losing shared structural logic?
+- Are rules, overlap, asymmetry, or empty space explaining structure rather than adding noise?
+
+## 4. Color and theming
+
+- Do foundation, semantic, and component colors have distinct roles rather than
+  accumulating one-off values?
+- Are foreground/background pairs, borders, focus, destructive actions, and status
+  colors mapped consistently across applicable themes and states?
+- Do hover, active, selected, disabled, loading, success, warning, and error
+  relationships remain coherent without relying on color alone?
+- Are light, dark, forced-color, or user-defined themes handled when the product
+  supports them, without undocumented component exceptions?
+- Does rendered contrast support hierarchy and readability rather than merely
+  passing a token-level calculation?
+
+## 5. Typography, spacing, and geometry
+
+- Are type roles limited, consistent, and appropriate to the brand?
+- Is body text comfortable to read at the rendered width?
+- Do headings wrap deliberately at common breakpoints?
+- Are gaps drawn from a coherent token scale?
+- Are radius, border, shadow, crop, and aspect-ratio choices systematic?
+- Are optical misalignments corrected where mathematical alignment looks wrong?
+
+## 6. Component system
+
+- Do related components share intentional anatomy, tokens, variants, size or
+  density rules, and state behavior?
+- Are variants named from product purpose rather than isolated visual treatments?
+- Do reusable components preserve behavior with long labels, localization, missing
+  media, dynamic data, and loading or error content?
+- Are near-duplicate components or magic values symptoms of a missing shared rule?
+- Are intentional local exceptions documented by product, content, or interaction
+  need instead of convenience?
+- Do component APIs and composition rules preserve semantics, focus, touch, and
+  recovery behavior?
+
+## 7. Responsive behavior
+
+Inspect project-defined widths or, when absent, approximately 360, 768, 1280, and 1600 px.
+
+- Does content and control order still match priority?
+- Do navigation and controls remain usable by touch and keyboard?
+- Are grids and narratives recomposed instead of squeezed or blindly stacked?
+- Are code, tables, artwork, canvas, and media handled without unintended overflow?
+- Do long translated labels, language expansion, zoom, dynamic content, document and in-content language/direction, logical order and properties, and locale-aware dates and numbers remain resilient across LTR and RTL?
+- Do reusable components adapt to narrow and wide containers when viewport-only breakpoints are insufficient? Use container queries only when they fit project conventions and browser support.
+
+## 8. Interaction states and recovery
+
+- Inventory default, hover, focus, active, selected, disabled, loading, empty, error, success, and destructive states when applicable.
+- Does the primary task remain clear in every important state?
+- Do errors explain recovery without destroying valid input?
+- Are destructive actions confirmed or reversible in proportion to risk?
+- Do overlays close with Escape and restore focus correctly?
+- Do pointer, touch, keyboard, and resize behavior preserve the same underlying task?
+
+## 9. Accessibility and constraints
+
+- Use semantic landmarks, headings, buttons, links, labels, and lists.
+- Verify keyboard order, visible and unobscured focus, accessible names, contrast, and non-color state cues around sticky regions, overlays, and scroll containers.
+- Check applicable target-size and spacing requirements, provide a single-pointer alternative for nonessential dragging, and ensure boundaries and state cues survive forced-colors or user-defined high-contrast palettes.
+- Provide useful alternative text or mark decorative visuals appropriately.
+- Respect reduced motion without removing essential feedback.
+- Preserve privacy, safety, data, and platform constraints.
+- Do not turn automated checks into claims of usability, compliance, safety, or user research.
+
+## 10. Implementation quality
+
+- Follow existing component and styling conventions.
+- Reuse real tokens rather than duplicating magic values.
+- Keep components focused and avoid premature abstraction.
+- Avoid unnecessary dependencies and layout-specific JavaScript.
+- Reserve media geometry and inspect font, image, and dynamic-content loading for unintended layout shift; when performance is in scope, measure relevant LCP, INP, and CLS evidence and distinguish local or lab observations from field results.
+- Run the relevant formatter, typecheck, lint, tests, and build.
+- Inspect the rendered result after automated checks pass.
+
+## 11. Verification evidence
+
+Record:
+
+- Viewports and themes actually rendered.
+- Primary flows, input methods, and states actually exercised.
+- Automated commands run and their results.
+- Visual, interaction, accessibility, or content issues observed and corrected.
+- Remaining gaps, assumptions, and checks requiring real users or domain experts.
+
+Never write “verified,” “accessible,” “safe,” or “compliant” when only code inspection or automated checks support the claim.
+
+## Prioritizing findings
+
+| Priority | Meaning |
+|---|---|
+| Critical | Blocks use, comprehension, accessibility, or core responsive behavior |
+| High | Damages hierarchy, brand trust, or a primary workflow |
+| Medium | Creates inconsistency or friction but has a clear workaround |
+| Low | Polish improvement with limited user impact |
+
+For each finding, state the location, evidence, impact, and smallest coherent correction. Group repeated symptoms under one system-level cause.

package/temp_gridgeist/skills/gridgeist/references/system-contract.md

@@ -0,0 +1,109 @@
+# Gridgeist System Contract
+
+Use this reference when Create or Redesign work introduces or changes visual-system
+decisions. Apply it proportionally: a narrow repair may need only the affected
+tokens, component, and states; a greenfield or multi-surface interface needs a
+broader contract.
+
+## Reconcile sources before defining values
+
+Inspect the sources that actually exist:
+
+- explicit user constraints and the selected or aligned direction;
+- established visual implementation, brand assets, and documented brand rules;
+- product content, tasks, data, and other authentic evidence;
+- rendered desktop and mobile behavior;
+- CSS variables, theme configuration, utility conventions, and design tokens;
+- component libraries, local primitives, variants, and state implementations;
+- design documentation, including `DESIGN.md` when present.
+
+Treat disagreement as a finding. Do not silently let an aspirational document
+override working product behavior, or let accidental implementation drift erase an
+intentional brand rule. Mark meaningful signals as preserve, evolve, or replace and
+state the product reason for a replacement.
+
+Source reconciliation does not authorize a visual thesis. Content and product facts
+may determine hierarchy, density, and authentic material, but do not by themselves
+make a broad replacement direction brand-derived. Complete the alignment gate before
+defining replacement tokens or component rules when materially different theses
+remain credible.
+
+## Define the smallest complete contract
+
+Record decisions in the project's native implementation format whenever possible.
+Use this compact contract in reasoning or handoff when several dimensions change:
+
+| Dimension | Minimum relevant decisions |
+|---|---|
+| Color and themes | Canvas, surface, text, muted, border, accent, destructive, focus, and applicable status roles; foreground/background pairs; light, dark, forced-color, or user-theme behavior when supported |
+| Typography | Display, heading, body, label, metadata, and code roles only when needed; family and fallback, size, weight, line height, tracking, measure, language coverage, and loading behavior |
+| Layout and spacing | Container behavior, tracks, gutters, spacing rhythm, section density, alignment anchors, and transformations across viewport or container ranges |
+| Shape, surface, and depth | Radius, border, shadow, texture, elevation, and adjacency roles; avoid values that differ without a product or state reason |
+| Component grammar | Shared anatomy, variants, sizes or density, state behavior, content limits, composition rules, and narrow-container behavior |
+| Media and motion | Crop, aspect ratio, loading and empty behavior, motion causality, duration or easing roles, and reduced-motion treatment |
+
+Do not invent every category for completeness. Omit roles the product does not need,
+but cover every dimension changed by the work.
+
+## Use token layers deliberately
+
+- **Foundation tokens** hold raw palette, type, spacing, radius, and motion values.
+- **Semantic tokens** express purpose such as canvas, text-muted, border-strong,
+  action-primary, focus-ring, success, warning, or destructive.
+- **Component tokens or variants** bind semantic roles to a component only when a
+  shared component needs a stable exception.
+
+Prefer semantic tokens in implementation. Keep foreground/background pairs and
+interaction-state relationships explicit. Reuse an existing scale when it is
+coherent; consolidate accidental near-duplicates instead of adding another magic
+value. A token file is evidence of intent, not proof that rendered contrast,
+hierarchy, or behavior is correct.
+
+## Define component grammar
+
+For each component family affected by the work:
+
+1. Identify its product job and required anatomy.
+2. Keep variants task-based, such as primary, secondary, quiet, or destructive,
+   rather than naming them after isolated visual treatments.
+3. Define only justified sizes or density modes and preserve usable targets.
+4. Cover applicable default, hover, focus, active, selected, disabled, loading,
+   empty, error, success, and destructive behavior.
+5. Keep state cues visible without relying on color alone.
+6. Define content stress behavior: long labels, missing media, localization,
+   dynamic data, overflow, and narrow or wide containers.
+7. Reuse existing primitives and repository conventions unless changing them is an
+   explicit, system-level decision.
+
+Do not require a particular component library. A coherent local primitive is better
+than importing a dependency solely to make the contract look formal.
+
+## Treat DESIGN.md as optional interoperability
+
+When a `DESIGN.md` file exists:
+
+- inspect its tokens and rationale during discovery;
+- trace relevant values into the theme, components, and rendered interface;
+- report stale, conflicting, unreachable, or one-off values;
+- preserve or update it only within the user's authorized scope.
+
+When it does not exist, do not create one automatically. Create or update a
+`DESIGN.md` only when the user requests a portable design-system artifact or the
+authorized work explicitly requires durable system documentation. Keep exact values
+machine-readable and explain the rationale in prose. Use an existing validator when
+available, but do not add a package, CLI, or network dependency without need and
+authorization.
+
+The project implementation remains the delivery target. A portable artifact does
+not replace rendered, responsive, interaction, or accessibility verification.
+
+## Keep the contract proportional
+
+- **Narrow repair:** preserve the established system; document only the affected
+  token, component rule, and states.
+- **Single surface:** define the system decisions needed for that page or workflow
+  and map them to reusable project tokens and primitives.
+- **Multiple surfaces or greenfield:** define the broader contract, show how shared
+  components inherit it, and identify any intentional local exceptions.
+- **Review:** diagnose drift and recommend the smallest coherent correction; do not
+  create or edit an artifact without authorization.