Initial: pi-skill — 68 skills, 43 extensions, 11 themes for Pi

.context/hallmark-comparison.md

@@ -0,0 +1,365 @@
+# Hallmark vs. Current Design Skill — Comparison Analysis
+
+**Hallmark:** https://github.com/Nutlope/hallmark  
+**Purpose:** Anti-AI-slop design skill for Claude Code, Cursor, Codex  
+**1,314 stars · 88 forks · MIT License**
+
+---
+
+## Quick Summary
+
+| Dimension | Hallmark | Current Design Skill |
+|---|---|---|
+| **Primary focus** | Landing page / UI generation with structural variety | Brand assets, CIP mockups, logos, slides, banners, icons |
+| **Target output** | Complete pages (HTML/CSS) | Static assets (logos, PDFs, presentations) |
+| **Design philosophy** | Macrostructure variety + 60-gate slop test | Design token system + generative AI (Gemini) |
+| **Integration style** | Skill that orchestrates AI coding agents | Skill that invokes scripts + AI models directly |
+| **Diversification** | Mandatory — tracks history to prevent repetition | Not built-in — relies on user prompts for variety |
+| **Quality gates** | 60-gate slop test + pre-emit self-critique | Quality bar in `design.md` (visual, not automated) |
+| **Documentation** | 60+ reference files, 21 macrostructures, 36 component archetypes | ~20 reference files, 13 cover patterns, 4 document types |
+
+---
+
+## Architecture Comparison
+
+### Hallmark — Page-First Design System
+
+Hallmark is fundamentally about **generating complete landing pages** that don't look AI-generated. Its architecture revolves around:
+
+```
+SKILL.md (orchestrator)
+  └── references/
+        ├── macrostructures/     ← 21 named page shapes (Bento Grid, Manifesto, etc.)
+        │     └── 01-bento-grid.md through 21-component-playground.md
+        ├── components/         ← 36 component archetypes (H1-H9 heroes, S1-S5 section heads, etc.)
+        ├── genres/             ← 4 genre packs (editorial, modern-minimal, atmospheric, playful)
+        ├── structure.md        ← 6-axis structural fingerprint system
+        ├── slop-test.md        ← 60-gate quality checklist + pre-emit self-critique
+        ├── anti-patterns.md    ← Explicitly banned AI patterns
+        ├── typography.md       ← 2+1 font discipline
+        ├── motion.md           ← Motion on/cut detection + microinteraction rules
+        ├── responsive.md        ← Mobile non-negotiables (320/375/414/768px)
+        ├── custom-theme.md      ← Custom OKLCH palette construction for brand-specific briefs
+        ├── study.md             ← Extract DNA from screenshots/URLs
+        └── verbs/              ← audit, redesign, study command implementations
+```
+
+**Core mechanism:** Pick a macrostructure → select theme + nav + footer archetypes → run slop test → emit. Diversification is enforced via `.hallmark/log.json` tracking.
+
+### Current Design Skill — Asset-First Design System
+
+Current design skill is fundamentally about **generating design assets** (logos, business cards, presentations) using AI models. Its architecture:
+
+```
+SKILL.md (orchestrator + routing)
+  └── references/
+        ├── logo-design.md          ← 55 styles, 30 palettes, 25 industry guides
+        ├── logo-style-guide.md
+        ├── logo-color-psychology.md
+        ├── logo-prompt-engineering.md
+        ├── cip-design.md            ← 50 deliverables, 20 styles, 20 industries
+        ├── cip-style-guide.md
+        ├── cip-deliverable-guide.md
+        ├── cip-prompt-engineering.md
+        ├── slides-create.md         ← HTML presentations with Chart.js
+        ├── slides-layout-patterns.md
+        ├── slides-copywriting-forms.md
+        ├── slides-strategies.md
+        ├── slides-html-template.md
+        ├── banner-sizes-and-styles.md ← 22 art direction styles
+        ├── social-photos-design.md
+        ├── icon-design.md            ← 15 styles, 12 categories
+        └── design-routing.md
+  └── scripts/
+        ├── logo/search.py, generate.py, core.py
+        ├── cip/search.py, generate.py, render-html.py, core.py
+        └── icon/generate.py
+  └── design.md (design system — palette logic, typography, cover patterns)
+```
+
+**Core mechanism:** Parse user intent → route to appropriate script or sub-skill → invoke Gemini AI → render HTML or export screenshot.
+
+---
+
+## Detailed Feature Comparison
+
+### 1. Scope & Output Types
+
+| Feature | Hallmark | Current Design Skill |
+|---|---|---|
+| Landing pages / full UI | ✅ Full macrostructure + components | ❌ No page generation |
+| Design tokens / CSS | ✅ OKLCH tokens per theme, custom-theme OKLCH builder | ✅ `tokens.json` via palette.py for PDFs |
+| Logo generation | ❌ Not a focus | ✅ 55 styles, Gemini AI |
+| Business card / stationery | ❌ Not a focus | ✅ CIP mockups, 50 deliverables |
+| Presentations / slides | ❌ Not a focus | ✅ HTML + Chart.js |
+| Banners / social media | ❌ Not a focus | ✅ 22 styles, multi-platform |
+| Icon design | ❌ Not a focus | ✅ 15 styles, SVG generation |
+| Logo wall / proof strips | ✅ Component archetypes (T2) | ❌ Not included |
+| Interactive UI components | ✅ 36 component archetypes, 8-state checklist | ❌ No UI component focus |
+
+**Verdict:** Hallmark and current skill are **non-overlapping in scope**. Hallmark focuses on page-level UI generation; current skill focuses on design asset creation. They could be **complementary** — Hallmark for landing pages, current skill for brand/asset work.
+
+### 2. Design Philosophy
+
+**Hallmark philosophy: Structural variety over visual variety.**
+
+> *"Two pages by Hallmark for two different briefs should not share a macrostructure or theme. They should feel like different sites, not colour-swaps of the same template."*
+
+Hallmark achieves this through:
+- **21 named macrostructures** — each a complete page shape (Bento Grid, Manifesto, Long Document, etc.)
+- **Diversification rule** — mandatory tracking of past outputs via `.hallmark/log.json`
+- **6-axis structural fingerprint** — heading placement, body composition, divider language, button voice, image treatment, reveal pattern
+- **Theme rotation** — 22 named themes across 4 genre clusters
+- **60-gate slop test** — explicit AI pattern detection (gradient text, centered-everything hero, 3-feature equal columns, etc.)
+
+**Current skill philosophy: Content-rooted design tokens.**
+
+> *"Every design decision must be rooted in the document's content and purpose."*
+
+Current skill achieves this through:
+- **Mood-based palette logic** — 10 mood types → base palette selection
+- **One accent rule** — accent appears only on geometric elements, section rules, callout borders
+- **13 cover patterns** — pattern selection based on document type (report, proposal, resume, etc.)
+- **2-font ceiling** — display + body only
+- **Design token system** — semantic layers (display, h1, h2, h3, body, caption, meta)
+
+**Verdict:** Hallmark is more **proactive** about preventing sameness (enforced tracking + diversification rules). Current skill is more **reactive** (relies on content description to guide decisions).
+
+### 3. Quality Assurance
+
+**Hallmark — 60-gate automated checklist:**
+
+- **Visual gates (1-8):** Inter font check, gradient check, 3-column equal grid check, nested cards, gradient text, card side-stripe, centered hero, pure black/white
+- **Structural gates (9-10):** Same fingerprint check, section-only whitespace
+- **Microinteraction gates (11-19):** `transition-all`, uniform hover-scale, bouncy easings, multi-hover, animating width/height, focus ring fade, success toast, hover delay, auto-rotating pause
+- **Diversification gates (20-35):** Stamp presence, macrostructure repetition, Specimen fall-through, token improvisation
+- **Layout-safety gates (36-38):** Horizontal scroll, decorative text position, interactive bar centering
+- **Typography gates (39-40):** 3+ font check, outlier face overuse
+- **Input-state gates (41-45):** Border-width changes, focus ring built from border, form height mismatch, helper-text collapse, disabled opacity-only
+- **Contrast gates (46-50):** Body text 4.5:1, large text 3:1, button text contrast, accent ink pairing, dark section text flip
+- **Nav/footer/hero slop gates (51-55):** N1 fingerprint, Ft3 fingerprint, centered-everything, padding asymmetry, decorative-without-purpose
+- **Pre-emit self-critique (6 axes):** Philosophy, Hierarchy, Execution, Specificity, Restraint, Variety — each scored 1-5, <3 triggers revision
+
+**Current skill — Manual quality bar:**
+
+- Cover has clear visual identity (not generic AI)
+- Body text readable at arm's length
+- Every page belongs to the same document
+- No element bleeds off edge or overlaps
+- Page numbers correct
+- Accent appears <8 times per page average
+
+**Verdict:** Hallmark's quality assurance is **far more systematic and automated**. The 60-gate checklist with concrete rules (e.g., "pure #000 or #fff base color" = fail) is more actionable than "a designer would not be embarrassed" quality bar.
+
+### 4. Color Systems
+
+| Aspect | Hallmark | Current Skill |
+|---|---|---|
+| Color format | OKLCH (required — `oklch(...)` throughout) | Hex + RGB, occasional named CSS |
+| Theme system | 22 named catalog themes + custom OKLCH builder | 10 mood-based palette presets |
+| Neutral handling | Tinted toward anchor hue (min 0.005 chroma) — modern-minimal allows zero-chroma | Neutral grays, all generated from mood |
+| Accent usage | Strict 5% max footprint rule (except atmospheric ~20%) | Geometric elements, rules, callout borders |
+| Dark mode | Atmospheric genre (dark paper themes: Bloom, Midnight, Terminal) | Darkroom cover pattern only |
+| Token block | Named tokens (`--color-accent`, `--color-paper-3`) — inline values banned | `tokens.json` with semantic token names |
+| Contrast verification | APCA Lc or WCAG ratio required, with explicit threshold checks | WCAG 4.5:1 guidance, not enforced |
+
+**Verdict:** Hallmark's color system is more **prescriptive** (OKLCH required, tokens mandatory, 5% accent limit). Current skill is more **flexible** (hex acceptable, mood-driven selection).
+
+### 5. Typography
+
+| Aspect | Hallmark | Current Skill |
+|---|---|---|
+| Font pairing rule | 2+1 discipline (display, body, outlier for wordmark/stat) | 2 maximum (display + body) |
+| Recommended fonts | Geist Sans (modern-minimal), serif/sans pairs for editorial | Playfair Display, Syne, Fraunces, etc. for covers; system fonts for body |
+| Type scale | CSS clamp-based (`clamp(2.5rem, 5vw + 0.5rem, 4.75rem)`) | Fixed pt scale (54pt display → 8pt meta) |
+| Mono usage | Terminal genre uses monospace for body | Courier Prime for terminal pattern cover |
+| Number treatment | Tabular nums for stats, `font-variant-numeric: tabular-nums` | Numeric blocks in fixed-width layout |
+| Display size range | Up to `clamp(3rem, 6vw + 1rem, 6rem)` for atmospheric | 54pt fixed for cover, 22pt for h1 |
+
+**Verdict:** Similar philosophy (2-3 faces max, role-based pairing), different approach. Hallmark uses **fluid CSS clamp** sizing; current skill uses **fixed pt sizes** (better for print/PDF).
+
+### 6. Component Library
+
+**Hallmark** has 36 component archetypes with variation knobs:
+
+| Category | Count | Examples |
+|---|---|---|
+| Heroes (H1-H9) | 9 | Marquee, Split Diptych, Stat-Led, Letter, Photographic, Demo video clipped, Mockup split, Custom illustration |
+| Section heads (S1-S5) | 5 | Left margin numbered, Hanging, Sticky pinned, Inline no break, Bottom anchored |
+| Feature blocks (F1-F6) | 6 | Bento grid, Sticky scroll stack, Tabular spec sheet, Step sequence, Annotated screenshot, Product card grid |
+| CTAs (C1-C4) | 4 | Outlined chip, Inline form-as-CTA, Typographic link, Sticky bottom bar |
+| Testimonials (T1-T4) | 4 | Pull quote with marginalia, Logo wall (hairline), Single huge quote, Numbered stat strip |
+| Navigation (N1-N10) | 10 | Wordmark+2 links, Floating chip, Side rail, ⌘K-only, Floating pill, Newspaper masthead, Brutal slab, Terminal command, Edge-aligned minimal, Floating-on-scroll-morph |
+| Footers (Ft1-Ft8) | 8 | Mast-headed, Inline rule single line, Index style columns, Dense colophon, Statement, Letter close, Newsletter-first, Marquee scroll |
+
+**Current skill** has no explicit component library — it's asset-focused.
+
+**Verdict:** Hallmark has a **comprehensive component system** with variation knobs for diversification. Current skill has no UI component architecture.
+
+### 7. Responsive Design
+
+**Hallmark — rigorous mobile-first:**
+
+- Mandatory verification at **4 widths**: 320px, 375px, 414px, 768px
+- Explicit horizontal scroll prevention (`html { overflow-x: clip }` — not `hidden`)
+- Per-archetype mobile collapse rules in component-cookbook
+- Button/clickable text must not wrap to 2 lines (WCAG)
+- Grid tracks use `minmax(0, 1fr)`, never bare `1fr`
+- Display headers use `overflow-wrap: anywhere; min-width: 0`
+
+**Current skill — PDF-focused, not responsive:**
+
+- Design system is for print/A4 documents
+- Social photos have platform-specific sizes
+- No responsive breakpoint system
+
+**Verdict:** Hallmark is **web-native and mobile-first**. Current skill is **print/screenshot-oriented**.
+
+### 8. Motion & Microinteractions
+
+| Aspect | Hallmark | Current Skill |
+|---|---|---|
+| Motion detection | Scans `package.json` for framer-motion, gsap, motion, lenis, lottie | Not applicable (static output) |
+| Motion stance | Motion-on vs motion-cut (affects animation choices) | Static PDFs/HTML |
+| Reveal patterns | 6 options: fade-up stagger, horizontal sweep, type-unmask, number-tick, typewriter, none | Not applicable |
+| Hover effects | Strict rules: no `transition-all`, no uniform `scale(1.05)`, max 1 hover effect per element | Not applicable |
+| Focus rings | Must use `outline` (not `border`), appear instantly (no fade-in) | Not applicable |
+| Reduced motion | Mandatory `@media (prefers-reduced-motion: reduce)` fallback | Not applicable |
+| 8-state component checklist | Default, hover, :focus-visible, :active, disabled, loading, error, success | Not applicable |
+
+**Verdict:** Hallmark has a **comprehensive microinteraction system**. Current skill doesn't address motion (static output).
+
+### 9. Verbs & Commands
+
+| Command | Hallmark | Current Skill |
+|---|---|---|
+| Default (build) | Pick macrostructure, theme, run slop test, emit | Route to appropriate sub-skill |
+| `audit <target>` | Score existing code against anti-patterns, ranked punch list, no edits | Not implemented |
+| `redesign <target>` | Keep content/IA/brand, rebuild visual layer within existing implementation | Not implemented |
+| `study <screenshot\|URL>` | Extract DNA (macrostructure, type-pairing, color anchor) from reference | Not implemented |
+| `generate` | N/A (output is code, not AI image) | Logo, CIP, slides, banners, icons |
+
+**Verdict:** Hallmark has **deeper UI-focused commands** (audit, redesign, study). Current skill has **generative commands** (logo, CIP, slides).
+
+### 10. Pre-flight Scanning
+
+Hallmark has an explicit **6-signal pre-flight scan**:
+
+1. `design.md` — locked design system (overrides everything)
+2. Font stack — next/font, @fontsource, Google Fonts link, Tailwind `theme.extend.fontFamily`
+3. Palette — OKLCH in `:root`, Tailwind colors, `tokens.json`, `design-tokens.json`
+4. Microinteraction stance — framer-motion, gsap, motion, lenis, lottie installed?
+5. Spacing scale — Tailwind `theme.extend.spacing`, `--space-*` pattern, 4pt or 8pt scale
+6. Framework — Next.js, Astro, Vue, Svelte, Remix, vanilla
+
+**Current skill** doesn't have a pre-flight scan — it generates fresh output based on prompt content.
+
+**Verdict:** Hallmark is designed to **integrate with existing codebases**. Current skill is designed to **generate standalone assets**.
+
+---
+
+## What Each Does Well
+
+### Hallmark — Strengths
+
+1. **Anti-AI-slop enforcement** — The 60-gate checklist explicitly bans the most recognizable AI patterns. This is a genuine innovation.
+2. **Structural variety** — 21 macrostructures × 22 themes × 36 component archetypes × 10 nav + 8 footer patterns = massive variety without randomness.
+3. **Diversification tracking** — `.hallmark/log.json` prevents the same macrostructure/theme appearing twice in a row.
+4. **Component 8-state checklist** — Every interactive component must have code for all 8 states (default, hover, focus, active, disabled, loading, error, success).
+5. **Mobile verification** — Mandatory check at 4 widths with specific rules.
+6. **Pre-emit self-critique** — 6-axis scoring (Philosophy, Hierarchy, Execution, Specificity, Restraint, Variety) before handing back output.
+
+### Current Design Skill — Strengths
+
+1. **Asset breadth** — Logo (55 styles), CIP (50 deliverables), slides, banners (22 styles), icons (15 styles), social photos — comprehensive design asset coverage.
+2. **AI model integration** — Gemini for logo, CIP, icons — direct model invocation without code generation.
+3. **PDF design system** — `design.md` with 13 cover patterns, mood-based palettes, restraint principles — well-suited for document design.
+4. **Script infrastructure** — BM25 search engine for styles/colors/industries, generate scripts for logos/CIP/icons, render-html.py for presentations.
+5. **Print-ready output** — Fixed pt sizes, CMYK guidance for print, bleed specs — designed for physical deliverables.
+
+---
+
+## Critical Gaps
+
+### Hallmark Gap vs. Current Skill
+
+- No logo/brand asset generation
+- No CIP deliverables (business cards, letterhead, etc.)
+- No slide/presentation generation
+- No banner design
+- No icon library generation
+- No PDF/document generation
+- No print design (fixed sizes, CMYK, bleed)
+- No social media image generation
+
+### Current Skill Gap vs. Hallmark
+
+- **No landing page/UI generation** — biggest gap
+- **No structural variety enforcement** — can produce repetitive outputs
+- **No component library** — no UI component patterns
+- **No mobile responsiveness system** — social photos have sizes but no responsive breakpoints
+- **No microinteraction rules** — static output only
+- **No pre-flight scan** — generates fresh without considering existing codebase
+- **No slop detection** — no systematic AI-pattern prevention
+- **No diversification tracking** — no history-based output variation
+- **No OKLCH color system** — hex-based
+- **No typography scale system** — just cover/heading/body categories
+
+---
+
+## Integration Possibilities
+
+Hallmark and current design skill are **complementary, not competing**:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    User Request                         │
+└─────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┴───────────────┐
+              ▼                               ▼
+    ┌─────────────────────┐       ┌─────────────────────┐
+    │   Hallmark          │       │   Current Design    │
+    │   (landing pages,   │       │   (logos, CIP,      │
+    │    UI components)   │       │    slides, banners) │
+    └─────────────────────┘       └─────────────────────┘
+              │                               │
+              └───────────────┬───────────────┘
+                              ▼
+                    ┌─────────────────────┐
+                    │   Unified Output     │
+                    │   (pages with        │
+                    │    branded assets)  │
+                    └─────────────────────┘
+```
+
+**Potential integration points:**
+
+1. **Hallmark → Current skill:** Hallmark generates a landing page; current skill generates the logo/branding assets that Hallmark uses.
+2. **Current skill → Hallmark:** Logo from current skill → Hallmark pre-flight scan detects brand colors → Hallmark uses them in custom theme construction.
+3. **Shared design.md:** Both could read a common `design.md` file — current skill writes it after CIP generation, Hallmark reads it as the project design system.
+4. **Hallmark audit → current skill redesign:** Hallmark audits an existing page, identifies structural issues; current skill generates replacement assets (logos, icons) as part of the redesign.
+
+---
+
+## Recommendation
+
+**Hallmark fills a critical gap in the current design skill — page-level UI generation with structural variety.**
+
+The current skill excels at **design asset creation** (logos, CIP, slides, banners, icons). Hallmark excels at **landing page/UI generation** with anti-AI-slop enforcement. Together they cover a much wider design scope.
+
+**Key priorities if integrating Hallmark concepts into current skill:**
+
+1. **Add structural variety enforcement** — track past outputs, enforce macrostructure/theme diversification
+2. **Implement slop detection** — systematic anti-pattern checklist (gradient text, centered heroes, etc.)
+3. **Add component library** — 36 component archetypes with variation knobs
+4. **Add mobile responsiveness system** — breakpoints, horizontal-scroll prevention, 44px touch targets
+5. **Switch to OKLCH** — better color math, chromaticity preservation, perceptual uniformity
+6. **Add 8-state component checklist** — default, hover, focus, active, disabled, loading, error, success
+7. **Add pre-flight scan** — detect existing code, fonts, palette, motion stance before generating
+
+**Priority if keeping separate but complementary:**
+
+- Create a routing layer that delegates "landing page" requests to Hallmark and "asset" requests to current skill
+- Share a common `design.md` format so logo/CIP outputs can feed Hallmark inputs
+- Consider a shared `.hallmark/` log for tracking design history across both skills