imhcode 1.0.0

package/skills/design-auditor/references/typography.md

@@ -0,0 +1,273 @@
+# Typography Rules Reference
+
+## Font Hierarchy
+
+A well-structured type system has 3–4 levels:
+
+| Level | Purpose | Typical Size | Weight |
+|---|---|---|---|
+| Display / H1 | Hero titles, page names | 32–72px | Bold or Black |
+| H2 / Section | Section headings | 24–36px | SemiBold or Bold |
+| H3 / Subsection | Sub-groupings | 18–24px | Medium or SemiBold |
+| Body | Main reading content | 14–16px | Regular |
+| Caption / Label | Supporting info, metadata | 11–13px | Regular or Medium |
+
+**Rule**: Each level should be visually distinct from adjacent levels. If H2 and H3 look the same, one of them is doing nothing.
+
+---
+
+## Font Pairing
+
+### The 2-Font Rule
+Use a maximum of **2 typefaces** in one design:
+- One for **headings** (display, expressive)
+- One for **body** (readable, neutral)
+
+Optionally, use one font family with different weights (Bold for headings, Regular for body). This always looks cohesive.
+
+### Good Pairing Patterns
+- **Serif heading + Sans-serif body** — Classic, trustworthy (e.g., Playfair + Inter... wait, avoid Inter. Try Playfair + Source Sans)
+- **Sans-serif heading + Sans-serif body** — Clean, modern (different weights of the same family)
+- **Display/decorative heading + Simple body** — Expressive but readable
+
+### Font Families to Avoid (Overused / Generic)
+- Inter (massively overused in AI-generated UIs)
+- Roboto (Android default, feels generic)
+- Arial / Helvetica (system fallback, no personality)
+- Times New Roman (dated unless intentionally retro)
+
+### Better Alternatives
+**For body text**: Source Sans 3, DM Sans, Nunito, Lato, Figtree, Plus Jakarta Sans
+**For headings**: Fraunces, Syne, Clash Display, Cabinet Grotesk, Satoshi, Bricolage Grotesque
+**For monospace/code**: JetBrains Mono, Fira Code, IBM Plex Mono
+
+---
+
+## Size Scale
+
+Use a **modular scale** — sizes based on a ratio, not arbitrary numbers:
+
+### Major Third Scale (1.25×)
+12 → 15 → 19 → 24 → 30 → 38 → 48 → 60px
+
+### Perfect Fourth Scale (1.333×)
+12 → 16 → 21 → 28 → 37 → 50px
+
+### Practical Scale (Most Common)
+12, 14, 16, 18, 20, 24, 28, 32, 36, 48, 60, 72px
+
+**Minimum sizes**:
+- Body text: **16px** (14px acceptable, 12px only for captions)
+- Mobile body: **16px** minimum (browsers auto-zoom below this)
+- Tiny labels: **11px** minimum, never smaller
+
+---
+
+## Line Height (Leading)
+
+| Text Type | Line Height Multiplier |
+|---|---|
+| Large headings (40px+) | 1.1–1.2× |
+| Medium headings (24–40px) | 1.2–1.35× |
+| Body text | 1.4–1.6× |
+| Captions / small text | 1.3–1.5× |
+
+**Example**: 16px body text → line-height: 24px (1.5×)
+
+**Never use line-height: 1** for multi-line text. It's unreadable.
+
+---
+
+## Line Length (Measure)
+
+- **Optimal**: 60–75 characters per line (~550–680px at 16px)
+- **Acceptable**: 45–90 characters
+- **Too wide**: 100+ characters (eye has to travel too far)
+- **Too narrow**: Under 40 characters (too many line breaks, choppy)
+
+In CSS: `max-width: 65ch` is a great rule for body text containers.
+
+---
+
+## Letter Spacing (Tracking)
+
+- **Body text**: 0 or very slightly positive (0–0.01em)
+- **Small caps / all caps**: Always add letter spacing (0.05–0.1em). All-caps with no tracking looks cramped.
+- **Large display text**: Often slightly negative (-0.02 to -0.04em). Tighter feels more premium.
+- **Never**: Negative letter spacing on body text (hurts readability)
+
+---
+
+## Text Contrast (WCAG)
+
+| Text Type | Minimum Contrast Ratio |
+|---|---|
+| Normal text (under 18px regular / 14px bold) | 4.5:1 |
+| Large text (18px+ regular or 14px+ bold) | 3:1 |
+| UI components (borders, icons) | 3:1 |
+| Decorative text | No requirement |
+
+**How to check**: Use a contrast checker. Common tools: Figma's built-in accessibility checker, WebAIM Contrast Checker, or browser devtools.
+
+**Common failures**:
+- Light gray body text on white (#999 on white = ~2.8:1 — fails!)
+- Yellow or light green text on white
+- Any low-opacity text overlay on images without a dark scrim
+
+---
+
+## Alignment Rules
+
+- **Left-align body text** in most Western/LTR languages. It's the most readable.
+- **Center-align** only for short text: headlines, CTAs, hero text, labels.
+- **Never center-align** long body paragraphs. It's exhausting to read.
+- **Right-align** numbers in tables (so decimal points align).
+- **Avoid justified text** on the web (creates uneven word spacing, looks bad without hyphenation).
+
+---
+
+## Common Typography Mistakes
+
+1. **Using too many font sizes** — Pick 4–5 and stick to them. Designers call this a "type ramp."
+2. **All caps body text** — Extremely hard to read in long form. Reserve for labels and buttons only.
+3. **Bold everything** — If everything is bold, nothing is bold. Bold = emphasis, use sparingly.
+4. **Underlining non-links** — Users will click underlined text expecting it to be a link.
+5. **Low-contrast text** — The single most common accessibility failure. Always check.
+6. **Inconsistent alignment** — Some centered, some left-aligned, some right-aligned with no system = chaos.
+7. **No hierarchy** — Everything the same size = wall of text.
+
+---
+
+## Fluid Typography (clamp())
+
+Static type sizes break at breakpoints. Fluid typography scales smoothly between a minimum and maximum size based on viewport width.
+
+### How clamp() Works
+
+```css
+font-size: clamp(MIN, PREFERRED, MAX);
+```
+
+- **MIN** — smallest the text should ever be (e.g. on narrow mobile)
+- **PREFERRED** — fluid value using `vw` (viewport width) units
+- **MAX** — largest the text should ever be (e.g. on wide desktop)
+
+### Common Fluid Type Values
+
+```css
+/* Body text: 16px → 18px */
+font-size: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
+
+/* H2: 24px → 36px */
+font-size: clamp(1.5rem, 1.2rem + 1.5vw, 2.25rem);
+
+/* H1: 32px → 60px */
+font-size: clamp(2rem, 1.5rem + 2.5vw, 3.75rem);
+
+/* Display: 48px → 80px */
+font-size: clamp(3rem, 2rem + 5vw, 5rem);
+```
+
+### When to Use Fluid Typography
+- Headings and display text — biggest win
+- Hero sections and large callouts
+- Any text that appears at very different sizes across breakpoints
+
+### When NOT to Use It
+- Body text (usually fine staying at 16px)
+- Labels, captions, small UI text (should stay fixed and readable)
+- When you need pixel-perfect control at specific breakpoints
+
+### The Rule
+Fluid type should never drop below its minimum readable size. Always test `clamp()` values at the narrowest viewport you support.
+
+---
+
+## Type Scale Role-Mapping Algorithm (Type Scale Stack Widget)
+
+When the Type Scale Stack widget is triggered, font sizes must be classified into roles. Use this exact algorithm — do not guess:
+
+```
+Step 1: Collect all unique fontSize values from the design/code.
+  (For code: convert rem/em to px — see conversion table below)
+
+Step 2: Sort values descending (largest first).
+
+Step 3: Assign roles by relative position and frequency:
+  Position 1 (largest unique size, used rarely, 1–3 instances):
+    → h1 / Display
+
+  Position 2 (second largest, used a handful of times):
+    → h2 / Heading
+
+  Position 3 (if exists, mid-range, section-level):
+    → h3 / Subheading
+
+  Most frequent size overall (appears most across the design):
+    → body
+
+  Sizes between h3 and body (if gap exists):
+    → label / overline
+
+  Smallest unique size (used rarely, supporting text):
+    → caption / helper
+
+Step 4: Flag these automatically:
+  - Any body candidate < 14px → 🔴 Critical
+  - Any caption/helper < 11px → 🔴 Critical
+  - Two adjacent role sizes within 2px of each other → 🟡 (indistinct)
+  - Scale ratio between body and h2 < 1.25 → 🟡 (too flat — no clear hierarchy)
+  - More than 6 distinct font sizes in one frame/component → 🟡 (scale too complex)
+  - Same font size used for two different visual roles → 🟡 (relies on weight alone — fragile)
+
+Step 5: Pass extracted sizes + roles as data to the Type Scale Stack widget.
+  If no font size data found: skip widget silently — do not render with placeholder data.
+```
+
+---
+
+## Code Font Size Extraction
+
+### rem / em to px conversion
+Base: 16px (browser default). If the design sets a different root font-size, use that instead.
+
+| rem value | px equivalent |
+|---|---|
+| 0.625rem | 10px |
+| 0.6875rem | 11px |
+| 0.75rem | 12px |
+| 0.8125rem | 13px |
+| 0.875rem | 14px |
+| 0.9375rem | 15px |
+| 1rem | 16px |
+| 1.125rem | 18px |
+| 1.25rem | 20px |
+| 1.5rem | 24px |
+| 1.875rem | 30px |
+| 2rem | 32px |
+| 2.25rem | 36px |
+| 3rem | 48px |
+
+### Tailwind text-* class to px mapping
+| Class | Size |
+|---|---|
+| text-xs | 12px |
+| text-sm | 14px |
+| text-base | 16px |
+| text-lg | 18px |
+| text-xl | 20px |
+| text-2xl | 24px |
+| text-3xl | 30px |
+| text-4xl | 36px |
+| text-5xl | 48px |
+| text-6xl | 60px |
+| text-7xl | 72px |
+
+Collect all text-* classes in use, map to px, then run the role-mapping algorithm above.
+
+### clamp() fluid type audit
+When `clamp(MIN, PREFERRED, MAX)` is found:
+  → Extract MIN and MAX values
+  → Run role-mapping algorithm using MAX values (desktop)
+  → Separately verify MIN values are above minimums (body ≥ 14px, caption ≥ 11px)
+  → Flag if MIN drops below readable threshold even if MAX is fine

package/skills/design-system/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: design-system
+description: Use this skill to generate or audit design systems, check visual consistency, and review PRs that touch styling.
+origin: ECC
+---
+
+# Design System — Generate & Audit Visual Systems
+
+## When to Use
+
+- Starting a new project that needs a design system
+- Auditing an existing codebase for visual consistency
+- Before a redesign — understand what you have
+- When the UI looks "off" but you can't pinpoint why
+- Reviewing PRs that touch styling
+
+## How It Works
+
+### Mode 1: Generate Design System
+
+Analyzes your codebase and generates a cohesive design system:
+
+```
+1. Scan CSS/Tailwind/styled-components for existing patterns
+2. Extract: colors, typography, spacing, border-radius, shadows, breakpoints
+3. Research 3 competitor sites for inspiration (via browser MCP)
+4. Propose a design token set (JSON + CSS custom properties)
+5. Generate DESIGN.md with rationale for each decision
+6. Create an interactive HTML preview page (self-contained, no deps)
+```
+
+Output: `DESIGN.md` + `design-tokens.json` + `design-preview.html`
+
+### Mode 2: Visual Audit
+
+Scores your UI across 10 dimensions (0-10 each):
+
+```
+1. Color consistency — are you using your palette or random hex values?
+2. Typography hierarchy — clear h1 > h2 > h3 > body > caption?
+3. Spacing rhythm — consistent scale (4px/8px/16px) or arbitrary?
+4. Component consistency — do similar elements look similar?
+5. Responsive behavior — fluid or broken at breakpoints?
+6. Dark mode — complete or half-done?
+7. Animation — purposeful or gratuitous?
+8. Accessibility — contrast ratios, focus states, touch targets
+9. Information density — cluttered or clean?
+10. Polish — hover states, transitions, loading states, empty states
+```
+
+Each dimension gets a score, specific examples, and a fix with exact file:line.
+
+### Mode 3: AI Slop Detection
+
+Identifies generic AI-generated design patterns:
+
+```
+- Gratuitous gradients on everything
+- Purple-to-blue defaults
+- "Glass morphism" cards with no purpose
+- Rounded corners on things that shouldn't be rounded
+- Excessive animations on scroll
+- Generic hero with centered text over stock gradient
+- Sans-serif font stack with no personality
+```
+
+## Examples
+
+**Generate for a SaaS app:**
+```
+/design-system generate --style minimal --palette earth-tones
+```
+
+**Audit existing UI:**
+```
+/design-system audit --url http://localhost:3000 --pages / /pricing /docs
+```
+
+**Check for AI slop:**
+```
+/design-system slop-check
+```

package/skills/design-tokens-system/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: design-tokens-system
+description: >-
+  Cross-platform design token architecture using Style Dictionary, Tokens Studio,
+  and CSS custom properties. Three-layer token system (primitive→semantic→component).
+---
+
+# Design Tokens System
+
+## Overview
+
+Design tokens are the single source of truth for design decisions (colors, typography, spacing, shadows). This skill covers a three-layer token architecture that ensures consistency across web, mobile, and design tools.
+
+## When to Use
+
+- Building or maintaining a design system
+- Ensuring consistency between Figma designs and code
+- Supporting multiple themes (light/dark, brand variants)
+- Creating cross-platform token pipelines (web + iOS + Android)
+
+## Three-Layer Token Architecture
+
+```
+┌──────────────────────────┐
+│   Component Tokens       │  ← button-bg, card-shadow, input-border
+│   (Context-specific)     │
+├──────────────────────────┤
+│   Semantic Tokens        │  ← color-primary, color-danger, spacing-md
+│   (Meaning-based)        │
+├──────────────────────────┤
+│   Primitive Tokens       │  ← blue-500, gray-100, 16px, 700
+│   (Raw values)           │
+└──────────────────────────┘
+```
+
+### Layer 1: Primitive Tokens
+
+```css
+:root {
+  /* Colors — raw palette values */
+  --primitive-blue-50: oklch(0.97 0.01 250);
+  --primitive-blue-500: oklch(0.6 0.2 260);
+  --primitive-blue-900: oklch(0.25 0.1 260);
+  --primitive-gray-50: oklch(0.98 0 0);
+  --primitive-gray-900: oklch(0.15 0 0);
+
+  /* Spacing — raw scale */
+  --primitive-space-1: 0.25rem;  /* 4px */
+  --primitive-space-2: 0.5rem;   /* 8px */
+  --primitive-space-4: 1rem;     /* 16px */
+  --primitive-space-6: 1.5rem;   /* 24px */
+  --primitive-space-8: 2rem;     /* 32px */
+
+  /* Typography — raw values */
+  --primitive-font-sans: 'Inter', system-ui, sans-serif;
+  --primitive-font-mono: 'JetBrains Mono', monospace;
+  --primitive-weight-regular: 400;
+  --primitive-weight-semibold: 600;
+  --primitive-weight-bold: 700;
+}
+```
+
+### Layer 2: Semantic Tokens
+
+```css
+:root {
+  /* Intent-based colors */
+  --color-primary: var(--primitive-blue-500);
+  --color-on-primary: white;
+  --color-surface: var(--primitive-gray-50);
+  --color-on-surface: var(--primitive-gray-900);
+  --color-danger: oklch(0.6 0.2 25);
+  --color-success: oklch(0.65 0.2 145);
+
+  /* Semantic spacing */
+  --spacing-xs: var(--primitive-space-1);
+  --spacing-sm: var(--primitive-space-2);
+  --spacing-md: var(--primitive-space-4);
+  --spacing-lg: var(--primitive-space-6);
+  --spacing-xl: var(--primitive-space-8);
+
+  /* Semantic typography */
+  --font-heading: var(--primitive-font-sans);
+  --font-body: var(--primitive-font-sans);
+}
+
+/* Dark theme overrides ONLY semantic tokens */
+.dark {
+  --color-primary: var(--primitive-blue-400);
+  --color-surface: var(--primitive-gray-900);
+  --color-on-surface: var(--primitive-gray-50);
+}
+```
+
+### Layer 3: Component Tokens
+
+```css
+:root {
+  /* Button tokens */
+  --button-bg: var(--color-primary);
+  --button-text: var(--color-on-primary);
+  --button-padding-x: var(--spacing-md);
+  --button-padding-y: var(--spacing-sm);
+  --button-radius: 0.5rem;
+
+  /* Card tokens */
+  --card-bg: var(--color-surface);
+  --card-padding: var(--spacing-lg);
+  --card-radius: 0.75rem;
+  --card-shadow: 0 1px 3px rgba(0,0,0,0.1);
+
+  /* Input tokens */
+  --input-bg: var(--color-surface);
+  --input-border: var(--primitive-gray-300);
+  --input-focus-ring: var(--color-primary);
+  --input-padding: var(--spacing-sm) var(--spacing-md);
+}
+```
+
+## Style Dictionary Pipeline
+
+```json
+// config.json
+{
+  "source": ["tokens/**/*.json"],
+  "platforms": {
+    "css": {
+      "transformGroup": "css",
+      "buildPath": "build/css/",
+      "files": [{ "destination": "tokens.css", "format": "css/variables" }]
+    },
+    "ios": {
+      "transformGroup": "ios-swift",
+      "buildPath": "build/ios/",
+      "files": [{ "destination": "Tokens.swift", "format": "ios-swift/class.swift" }]
+    }
+  }
+}
+```
+
+## Guidelines
+
+1. **Never skip layers** — always go Primitive → Semantic → Component
+2. **Theme at the semantic layer** — dark mode overrides semantic tokens, not primitives
+3. **Use OKLCH** for perceptually uniform color manipulation
+4. **Name tokens by intent**, not by value (`color-danger`, not `color-red`)
+5. **Automate token sync** between Figma (Tokens Studio) and code (Style Dictionary)
+6. **Document every token** with its purpose and usage context
+
+## Anti-Patterns
+
+- ❌ Component tokens referencing primitive tokens directly (skip semantic layer)
+- ❌ Naming tokens by color value (`--blue-button`) instead of intent (`--button-primary`)
+- ❌ Hardcoding values in components instead of using tokens
+- ❌ Having separate token files for light/dark — use CSS custom property overrides
+- ❌ Over-tokenizing — not every CSS value needs to be a token

package/skills/development-workflows/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: development-workflows
+description: development workflows patterns and best practices
+---
+# Development Workflows
+
+This skill provides development workflows guidelines. Load the agent's primary skills for detailed implementation patterns.

package/skills/development-workflows/cross-model-workflow/cross-model-workflow.md

@@ -0,0 +1,55 @@
+# Cross-Model (Claude Code + Codex) Workflow
+
+based on [claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) and [codex-cli-best-practice](https://github.com/shanraisshan/codex-cli-best-practice)
+
+## Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│              CROSS-MODEL CLAUDE CODE + CODEX WORKFLOW                   │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  STEP 1: PLAN                                          Claude Code      │
+│  ─────────────                                         Opus 4.6         │
+│  Open Claude Code in plan mode (Terminal 1).           Plan Mode        │
+│  Claude interviews you via AskUserQuestion.                             │
+│  Produces a phased plan with test gates.                                │
+│                                                                         │
+│  Output: plans/{feature-name}.md                                        │
+│                                                                         │
+│                              ▼                                          │
+│                                                                         │
+│  STEP 2: QA REVIEW                                     Codex CLI        │
+│  ──────────────────                                    GPT-5.4          │
+│  Open Codex CLI in another terminal (Terminal 2).                       │
+│  Codex reviews plan against the actual codebase.                        │
+│  Inserts intermediate phases ("Phase 2.5")                              │
+│  with "Codex Finding" headings.                                         │
+│  Adds to the plan — never rewrites original phases.                     │
+│                                                                         │
+│  Output: plans/{feature-name}.md (updated)                              │
+│                                                                         │
+│                              ▼                                          │
+│                                                                         │
+│  STEP 3: IMPLEMENT                                     Claude Code      │
+│  ──────────────────                                    Opus 4.6         │
+│  Start a new Claude Code session (Terminal 1).                          │
+│  You implement phase-by-phase                                           │
+│  with test gates at each phase.                                         │
+│                                                                         │
+│                              ▼                                          │
+│                                                                         │
+│  STEP 4: VERIFY                                        Codex CLI        │
+│  ────────────────                                      GPT-5.4          │
+│  Start a new Codex CLI session (Terminal 2).                            │
+│  Codex verifies the implementation                                      │
+│  against the plan.                                                      │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## How cross-model workflow actually looks in production
+
+![Cross-Model Workflow](assets/cross-model-workflow.png)
+
+*Last Updated: 2026-03-06*

package/skills/development-workflows/rpi/.claude/agents/code-reviewer.md

@@ -0,0 +1,21 @@
+---
+name: code-reviewer
+description: Meticulous, constructive reviewer for correctness, clarity, security, and maintainability.
+model: opus
+---
+# Review focus
+- Correctness & tests; security & dependency hygiene; architectural boundaries.
+- Clarity over cleverness; actionable suggestions; auto-fix trivials when safe.
+
+# Output format (review.md)
+# CODE REVIEW REPORT
+- Verdict: [NEEDS REVISION | APPROVED WITH SUGGESTIONS]
+- Blockers: N | High: N | Medium: N
+## Blockers
+- file:line — issue — specific fix suggestion
+## High Priority
+- file:line — principle violated — proposed refactor
+## Medium Priority
+- file:line — clarity/naming/docs suggestion
+## Good Practices
+- Brief acknowledgements