saglitzdesign-mcp 0.3.1

package/knowledge/ux/motion-microinteractions.md

@@ -0,0 +1,67 @@
+---
+id: motion-microinteractions
+title: "Motion & Micro-interactions"
+category: ux
+platform: both
+tags: [motion, animation, easing, micro-interactions, transitions]
+sources: ["https://m3.material.io/styles/motion/overview", "https://developer.apple.com/design/human-interface-guidelines/motion"]
+updated: 2026-07-08
+---
+
+# Motion & Micro-interactions
+
+Motion exists to explain (where did this come from?), confirm (did that work?), and delight (sparingly). If an animation does none of these, delete it.
+
+## Duration & easing (memorize)
+
+| Interaction | Duration | Easing |
+|---|---|---|
+| Micro feedback (press, toggle, hover) | 100–150ms | ease-out |
+| Small component (dropdown, tooltip, chip) | 150–200ms | ease-out |
+| Medium (modal, sheet, drawer enter) | 250–300ms | ease-out / emphasized decelerate |
+| Exit animations | ~2/3 of enter (dismiss fast) | ease-in |
+| Screen transitions | 300–350ms | standard curve |
+| Large/expressive (hero, celebration) | 400–600ms | spring |
+
+- **Enter: ease-out** (fast start, gentle landing). **Exit: ease-in.** **Move: ease-in-out.** Never `linear` for UI (only for spinners/progress).
+- Springs (natural, interruptible) are the modern default on mobile — iOS springs, Material 3 Expressive physics. Gesture-driven motion must track the finger 1:1 and be interruptible mid-flight.
+- Nothing UI-blocking longer than ~400ms; users forgive slow apps less than plain ones.
+
+## What to animate
+
+- **Only `transform` and `opacity`** (GPU-composited). Animating width/height/top/margin causes jank; if layout must move, use FLIP or `scale` illusions.
+- Enter pattern: fade + 8–16px rise + optional 0.97→1 scale. Exit: fade + slight fall/scale.
+- Stagger list entrances 20–40ms/item, cap total ≤400ms, first screenful only.
+- Skeletons: shimmer 1–1.5s cycle; crossfade skeleton→content (~200ms).
+
+## Micro-interactions worth building
+
+1. Button press (scale 0.97 / ripple) — every tappable.
+2. Toggle thumb slide + track color (~150ms).
+3. Success moments: checkmark draw-in, brief confetti for milestone completions only.
+4. Pull-to-refresh with progressive indicator.
+5. Like/save: bounce + color pop (the Twitter-heart pattern).
+6. Input focus: border color + subtle ring transition (~150ms).
+7. Number changes: count-up/odometer for stats.
+8. Toast: slide+fade in, auto-dismiss 4–6s with pause on hover.
+
+Celebration budget: one big moment per flow (onboarding done, first success). Confetti everywhere = confetti nowhere.
+
+## Page & scroll motion (web)
+
+- Scroll-driven reveals: subtle (fade + ≤24px translate), once per element, never hide content from users who don't scroll perfectly.
+- Parallax: ≤10–15% speed differential, hero only; disable for `prefers-reduced-motion`.
+- Sticky/scroll-linked storytelling for marketing only; never scroll-jack (override native scroll speed/direction).
+- View Transitions API for page-to-page continuity on web; shared-element transitions on mobile for list→detail (hero image morph).
+
+## Reduced motion (mandatory)
+
+`prefers-reduced-motion: reduce` → kill translation/scale/parallax/auto-play; keep opacity crossfades ≤200ms; keep progress indicators. iOS/Android expose the same setting — respect it natively.
+
+## Anti-patterns
+
+- Animation on every scroll tick; elements flying in from all four directions.
+- >400ms blocking transitions between routine screens; easing `ease` everywhere by default.
+- Looping attention-seeking animation near reading content (wiggling badges).
+- Layout-shifting animation (bouncing accordions pushing content); spinners for <300ms operations (flash).
+- Same celebration for trivial and major actions.

package/knowledge/ux/principles-heuristics.md

@@ -0,0 +1,57 @@
+---
+id: principles-heuristics
+title: "UX Principles & Heuristics"
+category: ux
+platform: both
+tags: [heuristics, usability, cognition, fitts-law, hicks-law]
+sources: ["https://www.nngroup.com/articles/ten-usability-heuristics/", "https://lawsofux.com/"]
+updated: 2026-07-08
+---
+
+# UX Principles & Heuristics
+
+The evaluation backbone. Every design review should walk these.
+
+## Nielsen's 10 heuristics (operationalized)
+
+1. **Visibility of system status** — every action gets feedback within 100ms; loading >1s shows progress; background work shows state (saving…/saved).
+2. **Match to the real world** — user vocabulary, not system vocabulary; natural ordering; familiar metaphors.
+3. **User control & freedom** — undo > confirm; back always works; easy exit from every flow; cancel long operations.
+4. **Consistency & standards** — internal consistency (one pattern per job) and platform conventions (don't reinvent share/back/tabs).
+5. **Error prevention** — constraints over corrections: good defaults, disabled-invalid combinations explained, confirm irreversible, autosave.
+6. **Recognition over recall** — show options, don't make users remember codes/paths; recently-used surfaces; visible state.
+7. **Flexibility & efficiency** — shortcuts for experts (keyboard, gestures, command palette) that stay invisible to novices; smart defaults for everyone.
+8. **Aesthetic & minimalist design** — every element competes for attention; cut what doesn't serve the current task.
+9. **Help users recognize & recover from errors** — plain-language errors: what happened, why, what to do; preserve user input.
+10. **Help & documentation** — contextual help at point of need (tooltips, inline hints) beats manuals.
+
+## Behavioral laws to apply
+
+- **Fitts's Law**: important targets = big and close. Thumb zone on mobile (bottom half); screen edges/corners on desktop are "infinite" targets.
+- **Hick's Law**: decision time grows with options. Progressive disclosure; recommended defaults; 3-tier pricing not 7.
+- **Jakob's Law**: users spend most time on other sites — meet conventions, spend novelty budget only on your core differentiator.
+- **Miller's Law / chunking**: group into 5–7 chunks (phone numbers, card numbers, nav sections).
+- **Peak–end rule**: invest in the flow's peak moment and its ending (success states, confirmations, celebrations).
+- **Von Restorff**: the one visually-different element gets remembered — that's why one primary CTA works.
+- **Doherty threshold**: keep system response <400ms to keep users in flow; use optimistic UI where safe.
+- **Goal-gradient**: show progress; users accelerate near completion (progress bars start pre-filled ~10%).
+- **Tesler's Law**: complexity is conserved — absorb it in the system (autodetect, defaults) rather than pushing to users.
+
+## Cognitive load rules
+
+- One primary job per screen. Screens that do everything do nothing.
+- Progressive disclosure: advanced options behind "Show more"; wizard steps over mega-forms.
+- Defaults do the work: 90% of users never change them — make defaults the recommended path.
+- Blank-slate anxiety: never open on an empty canvas without a starting template/example.
+
+## Feedback timing budget
+
+| Delay | Requirement |
+|---|---|
+| <100ms | Feels instant; no indicator needed |
+| 100ms–1s | Subtle feedback (button state), no spinner |
+| 1–3s | Spinner/skeleton |
+| >3s | Progress + explanation; allow cancel |
+| >10s | Progress + time estimate; allow backgrounding + notify |
+
+Skeletons beat spinners for content layout; optimistic UI (assume success, reconcile on failure) beats both for social actions.

package/knowledge/ux/spacing-layout.md

@@ -0,0 +1,68 @@
+---
+id: spacing-layout
+title: "Spacing, Grids & Layout"
+category: ux
+platform: both
+tags: [spacing, grid, layout, whitespace, responsive]
+sources: ["https://m3.material.io/foundations/layout/understanding-layout/overview", "https://developer.apple.com/design/human-interface-guidelines/layout"]
+updated: 2026-07-08
+---
+
+# Spacing, Grids & Layout
+
+## The 8-point system
+
+All spacing, sizes, and positions on an 8px grid; 4px for fine adjustments (icon padding, tight label gaps).
+
+Canonical scale: **4, 8, 12, 16, 24, 32, 48, 64, 96, 128**.
+
+| Token | Use |
+|---|---|
+| 4 | icon↔label gap, chip padding |
+| 8 | related elements (label↔input) |
+| 12–16 | component internal padding; between fields |
+| 24 | between component groups; card padding (roomy) |
+| 32–48 | between subsections |
+| 64–96(–128) | between page sections (marketing) |
+
+**Proximity is grouping**: spacing must encode hierarchy — gap within a group < gap between groups, always. Most "cluttered" designs violate this, not the amount of content.
+
+## Screen margins & containers
+
+- Mobile app: 16px side margins (20–24px roomier feel); iOS safe areas + Android gesture insets always respected.
+- Web content container: 1140–1280px max-width for marketing; prose max 65–72ch; dashboards can go fluid with 24px gutters.
+- Section vertical padding (marketing): 80–120px desktop, 48–64px mobile.
+
+## Grids
+
+- Web: 12-column, 24px (desktop) / 16px (mobile) gutters. Columns for alignment discipline — content blocks span 6/8/12, not arbitrary widths.
+- Mobile app: single column with consistent margins; 2-column card grids for galleries/dashboards (8–12px gap).
+- Breakpoints (practical): 640 / 768 / 1024 / 1280. Design mobile-first; at each breakpoint reflow (stack→2-col→3-col), don't just shrink.
+- Vertical rhythm: consistent section spacing multiplied from the same scale; align baselines across columns.
+
+## Layout patterns that work
+
+- **F-pattern** for text-heavy pages (front-load first two paragraphs & left edge); **Z-pattern** for sparse hero layouts (logo → nav → visual → CTA).
+- Alternating image/text rows ("zig-zag") for feature sections — cap at 3–4 before it gets monotonous; break with a full-width band or bento grid.
+- Bento grids: mixed-size tiles in one gap system; every tile same radius/gap; 1–2 hero tiles max.
+- Split-screen hero: 50/50 or 60/40 copy/visual; copy side carries the CTA above the fold.
+- Sticky sidebar/summary (checkout, docs TOC) after content exceeds viewport.
+
+## Alignment rules
+
+- Pick one left edge per screen region and never violate it by 1–2px — "almost aligned" reads as sloppy faster than unaligned.
+- Optical alignment beats mathematical: icons/triangles need 1–2px nudges; text baseline alignment over bounding-box centering.
+- Don't center-align multi-line body text or forms; center is for short display content.
+
+## Density modes
+
+- Consumer/marketing: generous (1.5–2× the spacing you first try).
+- Productivity/data tools: compact rows (32–40px), 8–12px paddings — but keep grouping ratios intact.
+- If offering both, make density a token multiplier, not a redesign.
+
+## Anti-patterns
+
+- Random values (13px, 18px, 27px) — every off-scale value is future inconsistency.
+- Equal spacing everywhere (no hierarchy — the "gray soup" layout).
+- Full-width text lines on desktop (>90ch), content hugging viewport edges on mobile.
+- Horizontal page scroll at any breakpoint; fixed heights that clip translated/longer text.

package/knowledge/ux/typography.md

@@ -0,0 +1,63 @@
+---
+id: typography
+title: "Typography — Scale, Pairing, Rhythm"
+category: ux
+platform: both
+tags: [typography, fonts, type-scale, readability, variable-fonts]
+sources: ["https://m3.material.io/styles/typography", "https://developer.apple.com/design/human-interface-guidelines/typography"]
+updated: 2026-07-08
+---
+
+# Typography — Scale, Pairing, Rhythm
+
+Typography is 90% of interface design. Most "this looks off" problems are type problems.
+
+## Type scale (modern product default)
+
+Build from 16px base with a ~1.2–1.25 ratio; round to sensible values:
+
+| Token | Size / line-height | Use |
+|---|---|---|
+| display | 48–72px / 1.1, -2% tracking | Hero headlines (marketing) |
+| h1 | 32–40px / 1.15–1.2 | Page title |
+| h2 | 24–28px / 1.25 | Section |
+| h3 | 20px / 1.3 | Subsection/card title |
+| body-lg | 18px / 1.6 | Marketing body, intros |
+| body | 16px / 1.5–1.6 | Default UI + reading text |
+| body-sm | 14px / 1.45 | Secondary UI, table cells |
+| caption | 12–13px / 1.4 | Meta, timestamps — never for primary content |
+
+- Mobile: clamp display/h1 down ~30–40% (72→44, 40→28). Use CSS `clamp()` for fluid scaling.
+- Never below 12px anywhere; never below 16px for mobile inputs (iOS zoom).
+- Weights: 400 body, 500–600 UI emphasis/buttons, 600–700 headings. Avoid <400 under 18px.
+- Hierarchy through **size + weight + color (3 levels: primary ~90% opacity, secondary ~60–65%, disabled ~38%)** — not through more fonts.
+
+## Readability rules
+
+- Line length: 45–75 characters (~60ch ideal); set `max-width: 65ch` on prose.
+- Line height: inverse to size — body 1.5–1.6, headings 1.1–1.25.
+- Letter-spacing: slightly negative on large headings (-1–2%), neutral body, +2–8% only for small ALL-CAPS labels.
+- Left-align body text; center only short headings/blurbs (≤3 lines).
+- Paragraphs: space between (8–12px) or indent — not both.
+- Numbers in tables/timers: `font-variant-numeric: tabular-nums`.
+
+## Font selection & pairing
+
+- **One family is enough** for most products (headings via weight/size). Two max: distinctive heading + workhorse body.
+- Safe modern UI families: Inter, Geist, SF Pro (iOS system), Roboto/Google Sans (Android), plus grotesques (Söhne-like) for brand.
+- Pair by contrast, not similarity: geometric sans display + humanist sans body; serif display (editorial feel: Fraunces, Tiempos) + sans body.
+- System font stacks are legitimate for apps: zero load cost, native feel.
+- Platform: iOS uses SF Pro + Dynamic Type text styles (Large Title 34, Title1 28, Body 17, Caption 12); Material uses the 15-style role scale (Display/Headline/Title/Body/Label × L/M/S). Respect user font-size settings — support Dynamic Type / sp units.
+
+## Web font performance (SEO-relevant)
+
+- WOFF2 only; subset to used scripts; ≤2 families, ≤4 total weight files — or one variable font.
+- `font-display: swap` (or `optional` for strict CLS); preload the primary text font; self-host (no third-party CSS blocking).
+- Match fallback metrics (`size-adjust`, `ascent-override`) to kill layout shift.
+
+## Anti-patterns
+
+- 3+ typefaces; hierarchy expressed by ALL CAPS everywhere; justified text on web.
+- Gray-on-gray body text below 4.5:1 "because aesthetic".
+- Fixed px font sizes ignoring user preferences (use rem / Dynamic Type / sp).
+- Thin (100–300) weights for UI text; decorative fonts for anything users must read fast.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "saglitzdesign-mcp",
+  "version": "0.3.1",
+  "description": "SaglitzDesign — expert MCP server for mobile app & website design: UI, UX, buttons, design languages, SEO and GEO guidance backed by a curated knowledge base and real-world pattern research.",
+  "type": "module",
+  "bin": {
+    "saglitzdesign-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "knowledge",
+    "!knowledge/examples/images",
+    "scripts/regenerate-examples.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "design",
+    "ui",
+    "ux",
+    "seo",
+    "geo",
+    "design-system",
+    "mobile-design",
+    "web-design",
+    "claude"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/HalidSaglam/saglitzdesign-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HalidSaglam/saglitzdesign-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HalidSaglam/saglitzdesign-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "author": "Saglitz Design"
+}

package/scripts/regenerate-examples.md

@@ -0,0 +1,61 @@
+# Regenerating the visual example library
+
+The `get_design_examples` tool serves real screenshots of design patterns.
+Those image files are **not** shipped with this repo or the npm package — only
+the metadata in `knowledge/examples/ios.json` and `knowledge/examples/web.json`
+is. Without the images, the tool still works, degrading to description + source
+link ("link mode").
+
+If you have access to the [Mobbin](https://mobbin.com) MCP tools, you can
+rebuild the local image library so `get_design_examples` returns real images.
+
+## Option A — let an agent do it (recommended)
+
+In an MCP client that has both this filesystem and the Mobbin MCP connected,
+give the agent this instruction:
+
+> Load the Mobbin tools:
+> `ToolSearch "select:mcp__mobbin__search_screens,mcp__mobbin__search_flows,mcp__mobbin__search_sections"`.
+>
+> For every entry in `knowledge/examples/ios.json` and
+> `knowledge/examples/web.json`, find the matching screen on Mobbin (search by
+> the entry's `app` + `pattern` + `title`), download its screenshot to the path
+> in the entry's `image` field (relative to `knowledge/examples/`), and verify
+> each file is a valid image over 15 KB. Do not change the JSON. Report how many
+> images were restored and which entries could not be matched.
+
+## Option B — add your own examples
+
+You don't need Mobbin at all. Append objects to either JSON file and drop the
+image alongside:
+
+```json
+{
+  "id": "web-hero-acme",
+  "title": "Acme — split hero with product demo",
+  "platform": "web",
+  "app": "Acme",
+  "pattern": "hero",
+  "description": "What this screen does well, concretely.",
+  "tags": ["hero", "landing", "cta", "demo"],
+  "mobbin_url": "https://…(or any source URL)",
+  "image": "images/web-hero-acme.jpg"
+}
+```
+
+Put the file at `knowledge/examples/images/web-hero-acme.jpg`. Rules the loader
+enforces:
+
+- `id`, `title`, `pattern`, `tags`, `image` are required; `mobbin_url` is the
+  shown source link.
+- `platform` must be `ios` or `web`.
+- If the image file is missing, the entry still loads and serves in link mode.
+- JPEG and WebP are supported (`.jpg` / `.webp`).
+
+Restart the server after adding files — the example index is built at startup.
+
+## Licensing note
+
+Screenshots you collect are third‑party content. Keep them local; do not
+commit them to a public repository or include them in a published package. The
+`knowledge/examples/images/` directory is git‑ignored for exactly this reason.