zeoel-framework 1.0.0

package/.agents/skills/zeoel/skills/design-auditor/references/navigation.md

@@ -0,0 +1,311 @@
+# Navigation Patterns Reference
+
+Navigation is how users find their way through a product. Poor navigation is the single biggest cause of user confusion — not bad visual design, not slow performance, but not knowing where you are or how to get somewhere.
+
+---
+
+## The Core Navigation Question
+
+At any moment in the product, a user should be able to answer three questions instantly:
+1. **Where am I?** — Current location is clearly indicated
+2. **Where can I go?** — Available destinations are visible
+3. **How do I get back?** — Return path is clear
+
+If any of these fail, the navigation is broken.
+
+---
+
+## Navigation Types
+
+### Primary Navigation
+The main way to move between top-level sections of the product.
+
+| Pattern | Use When | Platform |
+|---|---|---|
+| **Top nav bar** | 3–7 primary destinations | Desktop |
+| **Side nav / sidebar** | 5–10 destinations, hierarchical | Desktop SaaS/tools |
+| **Bottom nav bar** | 3–5 primary destinations | Mobile |
+| **Hamburger menu** | Secondary items, overflow | Mobile (not primary) |
+| **Tab bar** | Switching views of same context | Both |
+
+### Secondary Navigation
+Deeper levels within a section.
+
+| Pattern | Use When |
+|---|---|
+| **Tabs** | Parallel views of same content (not different sections) |
+| **Breadcrumbs** | 3+ levels deep in hierarchy |
+| **Sidebar sub-nav** | Multi-level sections in desktop apps |
+| **Segmented control** | 2–4 closely related views |
+
+---
+
+## Active States
+
+The currently active nav item must be **unambiguously distinct** from inactive items.
+
+### What Works
+- **Filled background** on active item (most common, clearest)
+- **Bottom border indicator** (tab bar pattern)
+- **Left border indicator** (sidebar pattern)
+- **Bold weight** on active label
+- **Different color** for active icon + label
+
+### What Doesn't Work
+- Slightly different shade of the same color (too subtle)
+- Color alone with no weight/position change (fails for colorblind users)
+- Only the icon changes, not the label (too easy to miss)
+
+### Contrast Requirement
+Active nav item must have at least **3:1 contrast** against inactive items — not just visually "different."
+
+### Code Pattern
+```css
+.nav-item { color: #6b7280; }
+.nav-item.active {
+  color: #111827;
+  font-weight: 600;
+  background: #f3f4f6;
+  border-left: 3px solid #7c3aed; /* sidebar indicator */
+}
+```
+
+---
+
+## Tabs
+
+Tabs switch between **parallel views of the same content or context**. They are NOT for top-level navigation between different sections.
+
+### ✅ Correct Tab Usage
+- Profile page: Overview | Activity | Settings
+- Message thread: Messages | Files | Members
+- Dashboard: Daily | Weekly | Monthly
+
+### ❌ Incorrect Tab Usage
+- Home | Projects | Settings | Help (these are different sections — use nav)
+- Step 1 | Step 2 | Step 3 (these are sequential — use a stepper)
+
+### Tab Rules
+- **Tabs should be equal weight.** If one tab is visited 90% of the time, reconsider whether tabs are the right pattern.
+- **Always show the active tab clearly** — filled background, bottom border, or bold label.
+- **Don't use tabs for navigation that changes the URL** — tabs are within-page state changes. Use nav for page-level routing.
+- **Overflow handling** — If tabs overflow their container on mobile, scroll horizontally. Never wrap tabs to a second line.
+- **Tab content should be fast** — tab switching should feel instant. Don't put heavy data fetches behind tabs that only load on click.
+
+---
+
+## Breadcrumbs
+
+Breadcrumbs show the hierarchical path to the current page.
+
+### When to Use Breadcrumbs
+- Any page **3 or more levels** deep in a hierarchy
+- Products with complex nested navigation (CMS, file management, settings)
+- When users may arrive directly at a deep page (from search, email link)
+
+### When NOT to Use Breadcrumbs
+- Flat sites with only 1–2 levels
+- Single-page apps where URL doesn't reflect hierarchy
+- Mobile (too small — use a back button instead)
+
+### Breadcrumb Rules
+- **Every crumb is a link** — except the current page (last item)
+- **Current page is not a link** — it can be shown in muted color or without underline
+- **Separator character** — use `/` or `›` — avoid `>` (looks like code) or `→` (implies direction)
+- **Truncate long paths** — if the path is very deep, show first + last 2 levels: `Home / ... / Section / Current Page`
+- **Match the page title** — the last breadcrumb should exactly match the `<h1>` of the current page
+
+```html
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/projects">Projects</a></li>
+    <li><a href="/projects/alpha">Project Alpha</a></li>
+    <li aria-current="page">Settings</li>
+  </ol>
+</nav>
+```
+
+---
+
+## Back Buttons
+
+"Back" is a fundamental navigation primitive — and one of the most commonly broken patterns.
+
+### Rules
+- **Back goes to the previous screen, not the previous URL.** In a multi-step flow, pressing Back should go to the previous step, not the previous browser history entry.
+- **Back in a modal closes the modal to the page behind it** — not to the previous page in history.
+- **Back should not lose user data** — if the user has entered information, warn them before going back ("Go back? Your changes will be lost.") or auto-save.
+- **Back button label should name the destination** — iOS convention: "< Projects" tells the user where they're going. Just "< Back" is acceptable but less helpful.
+- **Always provide a way back** — any screen that can be reached should have an exit path. No dead ends.
+
+### When to Show a Back Button
+- Detail pages within a list (e.g. item detail → back to list)
+- Steps in a flow (step 3 → back to step 2)
+- Modals and drawers (close/back button in header)
+- Any screen without primary navigation visible
+
+---
+
+## Mobile Navigation
+
+### Bottom Navigation Bar
+- **3–5 destinations** maximum. More than 5 = too crowded.
+- **Always show labels** — icon-only bottom nav fails usability testing consistently.
+- **Active state must be clear** — filled icon, label color change, or indicator dot.
+- **Never use for secondary items** — keep primary destinations only.
+- **Safe area** — respect iOS/Android safe area insets so content isn't hidden behind home indicator.
+
+### Hamburger Menu
+- Acceptable for **secondary or overflow navigation**.
+- **Not acceptable** for primary navigation on mobile — it hides destinations, reducing discoverability by 50%+.
+- If you have 3–5 primary destinations, use a bottom nav bar instead.
+
+### Gestures
+- **Swipe back** — respect native back gestures (iOS swipe from left edge, Android back button).
+- Never intercept swipe gestures for something other than navigation without strong justification.
+
+---
+
+## Navigation Accessibility
+
+- **`aria-current="page"`** — mark the active nav item with this attribute for screen readers
+- **Skip navigation link** — provide a "Skip to main content" link as the first focusable element on each page. Essential for keyboard users who don't want to tab through the entire nav on every page.
+- **Keyboard navigation** — nav items must be reachable and activatable by keyboard (Tab + Enter)
+- **Focus management** — when a nav item opens a new section, move focus to the section heading or first interactive element
+
+```html
+<!-- Skip nav link (visually hidden until focused) -->
+<a href="#main-content" class="skip-link">Skip to main content</a>
+
+<!-- Active page indicator -->
+<nav>
+  <a href="/home">Home</a>
+  <a href="/projects" aria-current="page">Projects</a>
+  <a href="/settings">Settings</a>
+</nav>
+```
+
+---
+
+## Common Navigation Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Tabs used for top-level section navigation | Use nav bar or sidebar instead |
+| No active state on current nav item | Add clear visual indicator (background, border, weight) |
+| Breadcrumbs with non-clickable intermediate items | All crumbs except current page must be links |
+| Back button goes to browser history, not app flow | Implement in-app back navigation in multi-step flows |
+| Hamburger menu for primary nav on mobile | Use bottom nav bar for 3–5 primary destinations |
+| Nav changes between sections (items appear/disappear) | Keep nav consistent on every page |
+| No skip navigation link | Add `<a href="#main">Skip to main content</a>` as first element |
+| Active nav item only differs by color | Add weight, background, or position indicator too |
+
+---
+
+## Code-Specific Navigation Checks
+
+When auditing HTML/React/Vue navigation code, check these directly.
+
+### Semantic structure
+```
+<nav> element:
+  → Primary nav wrapped in <nav> → ✅
+  → Nav built with <div> and no role="navigation" → 🟡
+  → Multiple <nav> elements without distinguishing aria-label → 🟡
+    Fix: <nav aria-label="Primary navigation"> / <nav aria-label="Footer navigation">
+
+Nav item elements:
+  → Nav links are <a href="..."> → ✅
+  → Nav links are <button> (for SPA router pushes) → ✅ if keyboard accessible
+  → Nav links are <div onClick> with no role or tabindex → 🔴 Critical
+```
+
+### Active state
+```
+aria-current="page":
+  → Present on the active nav item → ✅
+  → Missing — active state is CSS-only (.active class) → 🟡
+    (screen readers can't detect CSS classes as the current page)
+
+Active visual signal:
+  → Only color change between active and inactive → 🟡
+    (fails colorblind users — need weight, background, or indicator bar too)
+  → Color + font-weight or border-bottom indicator → ✅
+
+Active state contrast:
+  → Extract active and inactive text/icon colors
+  → Run contrast check: active vs inactive must be ≥ 3:1
+  → Less than 3:1 → 🟡 Warning
+```
+
+### Skip navigation link
+```
+Pattern to detect:
+  First <a> element in DOM should be a skip link:
+  <a href="#main-content" class="skip-link">Skip to main content</a>
+
+  Visually hidden until focused:
+  .skip-link {
+    position: absolute;
+    left: -9999px;
+  }
+  .skip-link:focus {
+    left: 0; /* or transform: translateX(0) */
+  }
+
+Check:
+  → Skip link present as first focusable element → ✅
+  → Skip link missing → 🟡 Warning
+  → Skip link present but target ID doesn't exist in DOM → 🔴 Critical
+  → Skip link visible at all times (not just on focus) → 🟢 Tip (valid but not required)
+```
+
+### Tab vs nav misuse
+```
+Tabs (same-page view switching):
+  Correct HTML: role="tablist" > role="tab" (aria-selected) > role="tabpanel"
+  → <nav> used for view switching instead of tablist → 🟡
+  → Tabs without aria-selected on active tab → 🟡
+  → Tab panels without role="tabpanel" → 🟡
+
+Navigation (cross-page section switching):
+  Correct HTML: <nav> > <ul> > <li> > <a href="...">
+  → role="tablist" used for routing between pages → 🟡
+  → Nav uses <a> links (not buttons) → ✅ for page nav
+```
+
+### Keyboard and dropdown handling
+```
+Dropdown menus:
+  → Escape key closes the dropdown → ✅ (check for keydown handler)
+  → Arrow keys navigate within dropdown items → ✅ (ideal)
+  → Dropdown has no keyboard handler at all → 🟡
+  → Dropdown trigger has aria-expanded="true/false" → ✅
+  → aria-expanded missing on dropdown trigger → 🟡
+
+Focus trapping in mobile drawers/hamburger menus:
+  → Focus trapped inside open drawer → ✅
+  → Focus leaves drawer when open → 🟡
+  → Escape closes drawer → ✅
+```
+
+### Breadcrumbs
+```
+Correct structure:
+  <nav aria-label="Breadcrumb">
+    <ol>
+      <li><a href="/">Home</a></li>
+      <li><a href="/projects">Projects</a></li>
+      <li aria-current="page">Alpha</li>
+    </ol>
+  </nav>
+
+Checks:
+  → <nav aria-label="Breadcrumb"> wrapping → ✅
+  → <ol> used (not <ul>) → ✅ (order matters)
+  → Last item has aria-current="page" → ✅
+  → Intermediate items are links → ✅
+  → Intermediate items are plain text, not links → 🟡
+  → No breadcrumb on route with 3+ path segments → 🟡
+```

package/.agents/skills/zeoel/skills/design-auditor/references/spacing.md

@@ -0,0 +1,313 @@
+# Spacing & Layout Rules Reference
+
+## The 8-Point Grid System
+
+The most widely-used spacing system in professional UI design. Every spacing and sizing value should be a **multiple of 8**.
+
+### The Scale
+4, 8, 12, 16, 24, 32, 40, 48, 64, 80, 96, 128px
+
+### Why 8?
+- Screens are divisible by 8 (common screen widths: 320, 360, 375, 390, 414, 768, 1024, 1280, 1440...)
+- 8px is small enough for fine-grained control, large enough to be meaningful
+- Values always divide cleanly across pixel densities (1×, 2×, 3×)
+
+### 4-Point Variant
+Some teams use a 4-point base instead. This gives you: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64...
+Fine for dense/compact UIs. Still keep values as multiples of 4.
+
+### What to Put on the Grid
+- Spacing between components
+- Padding inside components
+- Component sizes (widths, heights)
+- Icon sizes (16, 20, 24, 32, 40, 48px)
+
+### Common Off-Grid Values (Red Flags)
+- 3px, 5px, 7px, 9px, 11px, 13px, 17px, 22px, 27px...
+If you see these, ask "why?" — they're usually accidental.
+
+---
+
+## Spacing Vocabulary
+
+| Term | Meaning |
+|---|---|
+| **Padding** | Space *inside* a container (between content and its border) |
+| **Margin** | Space *outside* a component (between it and adjacent things) |
+| **Gap** | Space between items in a flex or grid container |
+| **Gutter** | Space between columns in a grid layout |
+| **Inset** | Uniform padding on all sides |
+
+---
+
+## Content Margins (Page-Level)
+
+The space between the screen edge and the content:
+
+| Screen Size | Common Margin |
+|---|---|
+| Mobile (< 768px) | 16px or 20px |
+| Tablet (768–1024px) | 24px or 32px |
+| Desktop (1024–1440px) | 48px, 64px, or 80px |
+| Wide desktop (1440px+) | Content max-width + auto margins |
+
+**Max Content Width**: Most readable body content caps at **680–800px wide**. Full-width containers can go to 1200–1440px for dashboards/data-heavy layouts.
+
+---
+
+## Component Padding
+
+### Buttons
+
+| Size | Vertical Padding | Horizontal Padding |
+|---|---|---|
+| Small | 6–8px | 12–16px |
+| Medium (default) | 10–12px | 20–24px |
+| Large | 14–16px | 28–32px |
+
+**Touch target rule**: The entire button hit area should be at least **44×44px** (iOS) or **48×48dp** (Android/Material).
+
+### Cards & Panels
+
+| Size | Padding |
+|---|---|
+| Compact (dense dashboards) | 12–16px |
+| Default | 16–24px |
+| Spacious | 24–32px |
+
+Padding should be consistent on all four sides, or use a pattern like more top/bottom than left/right intentionally.
+
+### Form Inputs
+
+- **Height**: 36–40px (small), 44–48px (default), 52–56px (large)
+- **Horizontal padding**: 12–16px
+- **Vertical padding**: enough to center text within the height above
+- **Gap between fields**: 16–24px
+- **Label-to-input gap**: 4–8px
+
+---
+
+## The Law of Proximity
+
+**"Things that are related should be close together. Things that are unrelated should be far apart."**
+
+This is the most important spacing rule to internalize:
+
+✅ Good: A form label is 4–8px above its input. The next form field is 24px below.  
+❌ Bad: Equal spacing between the label and its input, and the label and the previous field.
+
+### Applying Proximity
+
+- Section title → content below: **8–12px gap**
+- Section → next section: **32–64px gap**
+- Card title → card body: **8–12px**
+- Unrelated elements: **32px+**
+
+If two groups of content have the same amount of space between them as within them, add more space between the groups.
+
+---
+
+## Alignment
+
+### Types of Alignment
+
+| Type | When to Use |
+|---|---|
+| **Left edge** | Most common. Body text, list items, form fields |
+| **Right edge** | Numbers in tables, secondary actions (right-side of nav) |
+| **Center** | Short headlines, icons, button labels, hero content |
+| **Baseline** | Text that sits next to each other in a line |
+
+### Grid Alignment
+Elements should align to a shared invisible grid. Things that aren't aligned to something look accidental.
+
+**Check by drawing invisible lines**: Do your left edges line up? Do your top edges line up? If not, it should be intentional, not accidental.
+
+---
+
+## White Space
+
+White space (negative space) is **not empty space** — it's an active design element.
+
+### Why White Space Matters
+- Makes content easier to scan
+- Creates focus on what matters
+- Communicates quality and confidence
+- Reduces cognitive load
+
+### Signs of Insufficient White Space
+- Text runs edge-to-edge in containers
+- Elements feel cramped or cluttered
+- Nothing has visual breathing room
+- Too many elements compete for attention
+
+### Signs of Too Much White Space
+- Content feels lost or disconnected
+- Scroll depth becomes excessive for simple content
+- Relationships between elements are unclear
+
+**Rule of thumb**: When in doubt, add more space than you think you need.
+
+---
+
+## Layout Patterns
+
+### The Column Grid
+
+Most layouts use a **12-column grid** (desktop). This divides evenly into 1, 2, 3, 4, 6, and 12 columns.
+
+Common desktop layouts:
+- **Full width**: 12 columns
+- **Wide content**: 10 columns, 1-column offset each side
+- **Article**: 8 columns (centered)
+- **Sidebar + Content**: 3 + 9 columns, or 4 + 8 columns
+
+Mobile: Usually **1 column** (stacked), or **2 columns** for grids.
+
+### Common Layout Patterns
+
+| Pattern | Use Case |
+|---|---|
+| **Holy Grail** | Header + sidebar + content + sidebar + footer |
+| **Card Grid** | Products, blog posts, gallery items |
+| **Dashboard** | Stats + charts + tables |
+| **Single Column** | Mobile, articles, forms |
+| **Split / Two-Pane** | Settings, email clients, sidebars |
+
+---
+
+## Z-Index & Layering
+
+When elements overlap, they need a clear layer hierarchy:
+
+| Layer | Z-index Range | Examples |
+|---|---|---|
+| Base content | 0–9 | Page content, images |
+| Floating elements | 10–99 | Sticky headers, floating buttons |
+| Dropdowns / tooltips | 100–199 | Dropdown menus, tooltips |
+| Modals / overlays | 200–299 | Modal dialogs, drawers |
+| Notifications / toasts | 300–399 | Toast messages, alerts |
+| Debug / dev tools | 9999+ | Dev tools, onboarding overlays |
+
+**Don't use arbitrary z-index values** like 9999 for normal components. It creates escalation wars.
+
+---
+
+## Common Spacing Mistakes
+
+1. **Inconsistent padding inside cards** — 12px on left, 16px on top. Pick one value and use it everywhere.
+2. **Elements touching the edge** — Content with no margin from the screen or container edge.
+3. **Equal spacing between unrelated items** — Everything looks like one undifferentiated blob.
+4. **Random spacing values** — 13px, 22px, 7px. Use the 8-point grid.
+5. **Overloaded screen density** — Too many things on screen at once. Consider splitting content across multiple screens or using progressive disclosure.
+6. **Missing whitespace in forms** — Fields jammed together with no breathing room between sections.
+7. **Ignoring mobile margins** — Desktop designs often use generous margins that collapse to nothing on mobile.
+
+---
+
+## When to Intentionally Break the 8-Point Grid
+
+The 8-point grid is a rule, not a law. There are legitimate cases where breaking it is the right call — but they should always be **intentional and documented**, never accidental.
+
+### Acceptable Reasons to Break the Grid
+
+**1. Optical correction**
+Sometimes mathematically correct spacing looks visually wrong. A common example: icons with built-in padding that makes them look off-center even when mathematically centered. Adjust by 1–2px to fix what the eye sees, not what the ruler says.
+
+**2. Border compensation**
+A 1px border adds to the total height/width of an element. If a button needs a 44px touch target and has a 1px border, the padding should be `(44 - 2) / 2 = 21px` — off-grid, but correct.
+
+**3. Dense data UIs**
+Tables, spreadsheets, and data grids sometimes need tighter vertical spacing (e.g. 6px or 10px row padding) to show more rows without scrolling. Acceptable when information density is the primary goal.
+
+**4. Line-height alignment**
+When aligning multi-line text with single-line text or icons, tiny spacing adjustments (1–3px) may be needed for optical baseline alignment.
+
+**5. External constraints**
+Third-party components, native platform guidelines (iOS HIG, Material Design), or specific browser rendering may impose constraints that conflict with your grid.
+
+### How to Handle Intentional Breaks
+- **Document it** — Add a comment in code: `/* 6px: optical correction for icon padding */`
+- **Keep it local** — Don't make a "6px" token. The break is specific to this context.
+- **Review it** — Off-grid values should be questioned in design reviews. If it doesn't have a reason, it's accidental.
+
+### The Key Test
+> "Can I explain why this value isn't on the grid?"
+
+If yes → intentional, acceptable.  
+If no → accidental, fix it.
+
+---
+
+## Code-Specific Spacing Checks
+
+When auditing CSS/React/Vue code, verify these directly rather than estimating visually.
+
+### Off-grid value detection
+```
+Collect all padding, margin, gap, width, height values in px.
+
+Not divisible by 4 → 🟡 Warning (off any grid)
+Divisible by 4 but not 8 → 🟢 Tip (on 4pt grid, acceptable but 8pt preferred)
+Divisible by 8 → ✅
+
+Common off-grid values to flag: 3, 5, 6, 7, 9, 10, 11, 13, 14, 17, 18, 22, 26...
+Common on-grid values: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64...
+
+Tailwind arbitrary spacing → always flag:
+  p-[13px], gap-[22px], m-[7px] → 🟡 (use nearest class instead)
+  p-[13px] → p-3 (12px) or p-4 (16px)
+
+Deduplication rule: same off-grid value in 5+ places → one grouped issue:
+  🟡 "padding: 13px — 8 occurrences. Snap to 12px or 16px."
+```
+
+### Padding consistency
+```
+Cards and panels:
+  → Mismatched sides: paddingTop: 16 / paddingLeft: 12 on same component → 🟡
+  → Exception: deliberate asymmetry (e.g. more horizontal padding) is fine
+    if applied consistently across all instances of the same component
+
+Mixed shorthand across similar components:
+  → ComponentA: padding: 16px
+  → ComponentB: padding: 16px 24px
+  → Same component type, different padding pattern → 🟡
+```
+
+### z-index audit
+```
+Expected z-index ranges (from spacing.md z-index table):
+  0–9:    base content
+  10–99:  floating elements (sticky headers, FABs)
+  100–199: dropdowns, tooltips
+  200–299: modals, overlays
+  300–399: toasts, notifications
+  9999+:  dev tools only
+
+Flag as 🟡 Warning:
+  → z-index: 9999 on a modal (correct range is 200–299)
+  → z-index: 99999 on anything except intentional dev overlay
+  → Two elements at the same z-index in an overlapping stacking context
+  → z-index on an element with position: static (has no effect)
+```
+
+### Content margin and max-width
+```
+  → Body/main container with no max-width → 🟢 Tip
+  → max-width > 1440px on text-heavy containers → 🟢 Tip
+  → Outermost container with margin: 0 and no padding → 🟡 (content touches edge)
+  → Container using px margins with no responsive override → 🟡
+```
+
+### Logical properties (RTL readiness)
+```
+Physical → Logical property suggestions (flag as 🟢 Tip unless RTL audit active):
+  margin-left  → margin-inline-start
+  margin-right → margin-inline-end
+  padding-left → padding-inline-start
+  padding-right → padding-inline-end
+  left: / right: on positioned elements → inset-inline-start / inset-inline-end
+
+Upgrade to 🟡 Warning if i18n library is detected or RTL support is requested.
+```