oh-my-customcode 0.56.0 → 0.58.0

package/templates/.claude/skills/impeccable-design/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: impeccable-design
+description: AI design language for production-grade UI — 10 commands covering typography, color, motion, layout, and UX writing quality
+scope: core
+user-invocable: false
+version: 1.0.0
+source:
+  type: external
+  origin: github
+  url: https://github.com/pbakaus/impeccable
+---
+
+## Purpose
+
+Impeccable is a design language for producing intentional, production-grade UI. It defines a vocabulary of steering commands that guide an AI toward specific design dimensions — typography, color, motion, layout, and UX writing — while actively avoiding the generic patterns associated with AI-generated interfaces.
+
+## Commands
+
+### 10 Selected Commands
+
+| Command | Trigger phrases | Description |
+|---------|----------------|-------------|
+| **critique** | "review design", "UX feedback" | UX design review: hierarchy, clarity, emotional resonance, and intentionality across the interface |
+| **audit** | "design audit", "quality check" | Systematic quality checks across all design dimensions simultaneously |
+| **typeset** | "fix fonts", "typography" | Fix font choices, weight contrast, scale, line-height, tracking, and type pairing |
+| **colorize** | "add color", "color palette" | Introduce strategic color using OKLCH; construct tinted neutral palettes, avoid pure black/white |
+| **animate** | "add motion", "animation" | Add purposeful motion using the 100ms/300ms/500ms rule; eliminate decorative or distracting animation |
+| **normalize** | "align design system" | Align output with design system standards: spacing scales, token usage, component consistency |
+| **polish** | "final pass", "ship ready" | Pre-ship quality sweep across all design dimensions, including AI slop test |
+| **clarify** | "improve copy", "UX writing" | Improve UX copy: labels, microcopy, empty states, error messages, button specificity |
+| **arrange** | "fix layout", "spacing" | Fix layout structure, whitespace, alignment, and visual rhythm |
+| **adapt** | "responsive", "mobile" | Adapt design decisions for different devices, screen sizes, and input modes |
+
+### Command Detail
+
+#### critique
+Holistic UX review. Evaluates information hierarchy, interaction clarity, emotional resonance, and whether design decisions feel intentional. Surfaces both friction points and missed opportunities. Output: prioritized list of issues with impact level (critical / moderate / minor).
+
+#### audit
+Systematic multi-dimension check. Runs all other command lenses in sequence and produces a structured report. Use when you need a full picture before starting work. Output: dimension-by-dimension audit with specific findings.
+
+#### typeset
+Typography repair. Evaluates and fixes:
+- Font family selection (avoid default Inter/Roboto/Arial without rationale)
+- Type scale (use modular scale, not arbitrary pixel sizes)
+- Weight contrast (body vs. heading vs. label differentiation)
+- Line-height and measure (optimal reading width 60-75 chars)
+- Letter-spacing for display vs. body contexts
+- Font pairing coherence
+
+#### colorize
+Color strategy and implementation using OKLCH. Key principles:
+- Build tinted neutrals (never pure gray — always a 5-10% hue push)
+- Use OKLCH for perceptually uniform lightness steps
+- Establish semantic color roles (primary, surface, on-surface, accent, destructive)
+- Avoid pure black backgrounds; tint with brand hue at low chroma
+- Check color relationships for harmony, not just individual values
+
+#### animate
+Motion design with purpose. Core rule — 100/300/500ms:
+- 100ms: micro-interactions, state transitions (hover, focus, active)
+- 300ms: element entrances, panel transitions, drawer opens
+- 500ms: page transitions, complex sequence animations
+Avoid: bounce/elastic easing as decoration, animation on load without user trigger, looping animations in primary content areas.
+Use: ease-out for entrances, ease-in for exits, linear for progress/loading.
+
+#### normalize
+Design system alignment. Enforces:
+- Spacing scale usage (4/8/12/16/24/32/48/64 or 4pt grid)
+- Border radius consistency (choose a base radius, derive multiples)
+- Shadow scale (0-3 elevation levels, not arbitrary per-component)
+- Color token usage vs. hardcoded values
+- Component variant consistency
+
+#### polish
+Pre-ship quality sweep. Runs: typeset + colorize + arrange + AI slop test + final coherence check. Output includes a ship-readiness verdict (ship / ship with minor fixes / needs work).
+
+#### clarify
+UX writing improvement. Targets:
+- Button labels: specific verbs over generic ("Save changes" not "Submit")
+- Empty states: explain what goes here + clear action to fill it
+- Error messages: say what happened + what to do (not "An error occurred")
+- Tooltips and help text: answer the user's actual question
+- Confirmation dialogs: describe the consequence, not the action
+
+#### arrange
+Layout and spatial design. Fixes:
+- Visual hierarchy via size, weight, and position
+- Negative space: increase breathing room between unrelated groups
+- Alignment: establish a clear grid baseline
+- Proximity: group related elements, separate unrelated ones
+- Visual rhythm: consistent incremental spacing within components
+
+#### adapt
+Responsive and cross-device adaptation:
+- Mobile-first breakpoint strategy
+- Touch target sizing (minimum 44x44px)
+- Content reflow for narrow viewports
+- Progressive disclosure for complex interfaces on mobile
+- Pointer vs. touch interaction mode awareness
+
+## AI Slop Test
+
+The AI Slop Test is a critical checkpoint embedded in every `audit` and `polish` command. It must also be run manually on any design output before declaring it complete.
+
+**The question**: Would someone immediately identify this as AI-generated?
+
+### Patterns to Flag as AI Slop
+
+**Typography slop**
+- Inter, Roboto, or Arial as the default font with no intentional reason stated
+- All text the same weight except headings
+- Line-height exactly 1.5 applied universally regardless of font size
+
+**Color slop**
+- Pure black (`#000000` or `#0d0d0d`) or pure gray (`#f5f5f5`, `#e5e5e5`) backgrounds without tinting
+- One brand color on an otherwise completely neutral palette
+- Blue-purple or coral-orange gradients with no contextual rationale
+
+**Layout slop**
+- Centered-everything layout that avoids making spatial decisions
+- Identical card components with same border-radius, same shadow, and same padding stacked vertically
+- Hero section: gradient blob behind centered heading + subheading + two buttons
+
+**Motion slop**
+- Bounce or elastic easing used as "delight" with no functional purpose
+- Every element animates on page load with staggered delays
+- Hover states that scale to 1.05 on every interactive element
+
+**Copy slop**
+- Empty states: "[Icon] No [items] yet. [Create button]"
+- Error messages: "Something went wrong. Please try again."
+- Buttons: "Submit", "Confirm", "OK"
+- Tooltips: restate the label they're attached to
+
+### Slop Test Verdict
+
+After running the test, assign one of:
+- **Clean**: No slop patterns detected
+- **Mild slop**: 1-2 patterns present, easy to fix
+- **Heavy slop**: 3+ patterns, requires deliberate design work before ship
+
+## Role Separation
+
+This skill operates in the aesthetic/creative layer. It does not replace technical compliance tooling.
+
+| Design Aspect | impeccable-design (this skill) | web-design-guidelines |
+|---------------|-------------------------------|----------------------|
+| Typography | Font selection, pairing, type scale, expressive hierarchy | Minimum font sizes (16px body), contrast ratios |
+| Color | Palette building, OKLCH, tinted neutrals, emotional resonance | WCAG 2.1 AA/AAA contrast compliance |
+| Motion | Purposeful animation, easing curves, timing strategy, felt quality | prefers-reduced-motion compliance, no-animation-on-load |
+| Layout | Visual rhythm, spatial design, negative space, hierarchy | Accessibility, semantic HTML structure, ARIA landmarks |
+| Copy | Tone, clarity, specificity, label quality | (no overlap) |
+
+**When both apply**: Run `impeccable-design` for aesthetic quality, then `web-design-guidelines` for compliance. They are complementary, not competing.
+
+## Reference Guides
+
+- `guides/impeccable-design/typography.md` — type scale construction, font pairing strategy, hierarchy patterns
+- `guides/impeccable-design/color-and-contrast.md` — OKLCH primer, tinted neutral construction, palette strategy
+- `guides/impeccable-design/motion-design.md` — 100/300/500ms rule, easing reference, purposeful vs. decorative motion
+- `guides/impeccable-design/ux-writing.md` — microcopy patterns, empty state templates, error message formulas
+
+## Execution Flow
+
+```
+1. Identify active command(s) from trigger phrase or explicit instruction
+2. Read target component/page files
+3. Consult relevant reference guides for the active command
+4. Apply changes with explicit rationale for each decision
+5. Run AI Slop Test on output
+6. Report: changes made + slop test verdict + any deferred items
+```

package/templates/.claude/skills/omcustom-auto-improve/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: omcustom:auto-improve
+description: Apply verified improvement suggestions from eval-core analysis to omcustom configuration
+scope: harness
+user-invocable: true
+effort: high
+---
+
+# /omcustom:auto-improve — Automated Improvement Workflow
+
+## Purpose
+
+Reads improvement suggestions from eval-core analysis, lets the user select which to apply, applies changes in an isolated worktree with sauron verification, and creates a PR for review.
+
+## Usage
+
+```
+/omcustom:auto-improve              # Interactive selection from pending suggestions
+```
+
+## Prerequisites
+
+- eval-core analysis data exists (run `/omcustom:improve-report` first if empty)
+- Pending improvement suggestions in `proposed` status
+
+## Workflow
+
+### Step 1: Read Suggestions
+
+1. Run `bun run packages/eval-core/src/cli/index.ts analyze --format json --save` via Bash
+2. Parse JSON output for improvement suggestions
+3. If no suggestions: display "No improvement suggestions available" and exit
+
+### Step 2: Display & Select
+
+Display numbered list:
+```
+[Auto-Improve] Available suggestions:
+  1. [HIGH] agent:lang-golang-expert — Escalate model sonnet→opus (3 failures in 5 uses)
+  2. [MED]  routing:dev-lead-routing — Add Flutter keyword mapping (2 routing misses)
+  3. [LOW]  skill:systematic-debugging — Add timeout guard (1 timeout in 10 uses)
+
+Select items: [1,2,3] / "all" / "cancel"
+```
+
+**Self-reference filter**: Exclude items where targetName matches:
+- `omcustom-auto-improve`, `auto-improve`
+- `pipeline-guards`, `evaluator-optimizer`
+- Any item targeting this skill itself
+
+### Step 3: Approve (State Transition)
+
+For each selected item:
+1. Call eval-core API: transition `proposed` → `approved`
+2. Display: `[Approved] {N} items selected for application`
+
+### Step 4: Worktree Isolation
+
+- Use `EnterWorktree` tool with name `auto-improve-{YYYYMMDD}`
+- Creates isolated branch from HEAD
+
+### Step 5: Apply Changes
+
+Map each approved item to the appropriate subagent by `targetType`:
+
+| targetType | Agent | Action |
+|------------|-------|--------|
+| agent | mgr-creator | Modify agent frontmatter/body |
+| skill | Matching domain expert | Revise skill SKILL.md |
+| routing | general-purpose | Update routing patterns |
+| model-escalation | general-purpose | Update model field in agent frontmatter |
+
+Spawn agents in parallel (max 4 per R009). Each agent receives:
+- Action description and evidence data
+- Target file path
+- Specific modification instructions
+
+### Step 6: Verification
+
+1. Delegate to mgr-sauron: full R017 verification
+2. If **PASS**: proceed to Step 7
+3. If **FAIL**: display failures, offer options:
+   - `fix` → re-apply with sauron feedback (max 2 cycles)
+   - `reject` → transition all to `rejected`, ExitWorktree(remove)
+   - `manual` → keep worktree for user inspection
+
+### Step 7: PR & Finalize
+
+1. Delegate to mgr-gitnerd: commit + create PR
+   - Title: `chore(auto-improve): apply {N} improvement suggestions`
+   - Body: table of applied items with evidence
+2. Transition all items to `applied` with `appliedAt` timestamp and PR URL
+3. `ExitWorktree(action: "keep")` — keep branch for PR
+4. Display PR URL to user
+
+## Safety Guards
+
+| Guard | Implementation |
+|-------|---------------|
+| Self-reference prevention | Blocklist filter in Step 2 |
+| User approval gate | Step 2 interactive selection |
+| Worktree isolation | Step 4 EnterWorktree |
+| Sauron verification | Step 6 mandatory pass |
+| PR-based merge | Step 7 — no direct push to develop |
+| Max items per run | 20 default, 50 hard cap |
+| Max fix cycles | 2 retries before rejection |
+| Rollback | `git revert` via mgr-gitnerd post-merge |
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| No suggestions available | Display message, exit |
+| User cancels selection | Exit, no state changes |
+| Sauron verification fails 2x | Reject all, cleanup worktree |
+| Agent application error | Mark individual item as rejected, continue others |
+| EnterWorktree fails | Report error, exit |
+
+## Display Format
+
+```
+[Auto-Improve] Starting improvement workflow
+├── Suggestions: {N} available ({high}H/{medium}M/{low}L confidence)
+├── Self-reference filtered: {count} items excluded
+└── Select items to apply: [1,2,3] or "all" or "cancel"
+
+[Auto-Improve] Applying {N} improvements in worktree
+├── Worktree: auto-improve-{date}
+├── Agents: {count} parallel
+└── Pipeline guards: max 20 items, 2 retry cycles
+
+[Auto-Improve] Verification
+├── Sauron: {PASS|FAIL}
+├── PR: #{number} created
+└── Status: {N} items → applied
+```

package/templates/.claude/skills/pipeline-guards/SKILL.md

@@ -22,6 +22,7 @@ Defines mandatory safety constraints for all pipeline, workflow, and iterative e
 | Timeout per pipeline | 900s | 1800s | worker-reviewer-pipeline |
 | Max retry count | 2 | 3 | Failure retry strategies |
 | Max PR improvement items | 20 | 50 | pr-auto-improve |
+| Max auto-improve items | 20 | 50 | omcustom-auto-improve |
 
 ## Enforcement
 
@@ -152,6 +153,7 @@ Guard warnings appear inline:
 | dag-orchestration | Node count and timeout limits |
 | worker-reviewer-pipeline | Iteration and pipeline timeout limits |
 | pr-auto-improve | Improvement item count limits |
+| omcustom-auto-improve | Auto-improve item count limits |
 | stuck-recovery | Guard triggers feed into stuck detection |
 | model-escalation | Repeated failures trigger escalation advisory |
 

package/templates/.claude/skills/secretary-routing/SKILL.md

@@ -50,10 +50,16 @@ git      → mgr-gitnerd
 verify   → mgr-sauron
 spec     → mgr-claude-code-bible
 memory   → sys-memory-keeper
-todo     → sys-naggy
-batch    → multiple (parallel)
+todo            → sys-naggy
+improve-report  → omcustom-improve-report (skill invocation)
+auto-improve    → omcustom-auto-improve (skill invocation)
+batch           → multiple (parallel)
 ```
 
+**improve-report keywords**: "improve-report", "improvement", "개선", "개선 리포트", "improve" → invoke `omcustom-improve-report` skill (read-only, no agent delegation needed)
+
+**auto-improve keywords**: "auto-improve", "자동 개선", "개선 적용", "apply improvements", "improvement suggestions" → invoke `omcustom-auto-improve` skill (worktree isolation, sauron verification, PR creation)
+
 ### Ontology-RAG Enrichment (R019)
 
 If `get_agent_for_task` MCP tool is available, call it with the original query and inject `suggested_skills` into the agent prompt. Skip silently on failure.

package/templates/CLAUDE.md

@@ -101,6 +101,7 @@ oh-my-customcode로 구동됩니다.
 | `/omcustom:update-external` | 외부 소스에서 에이전트 업데이트 |
 | `/omcustom:audit-agents` | 에이전트 의존성 감사 |
 | `/omcustom:fix-refs` | 깨진 참조 수정 |
+| `/omcustom:auto-improve` | 개선 사항 자동 적용 워크플로우 |
 | `/omcustom:improve-report` | eval-core 기반 개선 현황 리포트 |
 | `/omcustom-takeover` | 기존 에이전트/스킬에서 canonical spec 추출 |
 | `/adversarial-review` | 공격자 관점 보안 코드 리뷰 |
@@ -136,12 +137,12 @@ oh-my-customcode로 구동됩니다.
 project/
 +-- CLAUDE.md                    # 진입점
 +-- .claude/
-|   +-- agents/                  # 서브에이전트 정의 (45 파일)
-|   +-- skills/                  # 스킬 (91 디렉토리)
+|   +-- agents/                  # 서브에이전트 정의 (46 파일)
+|   +-- skills/                  # 스킬 (94 디렉토리)
 |   +-- rules/                   # 전역 규칙 (R000-R021)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
-+-- guides/                      # 레퍼런스 문서 (30 토픽)
++-- guides/                      # 레퍼런스 문서 (31 토픽)
 ```
 
 ## 오케스트레이션

package/templates/guides/impeccable-design/color-and-contrast.md

@@ -0,0 +1,278 @@
+# Color and Contrast
+
+> Reference: Impeccable Design Language — https://github.com/pbakaus/impeccable (Apache 2.0)
+
+---
+
+## OKLCH: The Preferred Color Model
+
+OKLCH (Oklab Lightness, Chroma, Hue) is a perceptually uniform color space. Unlike HSL, equal numeric changes in OKLCH produce equal perceived differences — making it the right tool for generating accessible, harmonious palettes programmatically.
+
+### Structure
+
+```
+oklch(lightness% chroma hue)
+```
+
+| Channel | Range | Description |
+|---------|-------|-------------|
+| `lightness` | 0%–100% | Perceived brightness |
+| `chroma` | 0–0.4 (approx) | Color saturation/vividness |
+| `hue` | 0–360 | Color angle (red=25, yellow=90, green=145, cyan=200, blue=250, purple=310) |
+
+### Why not HSL?
+
+HSL's lightness channel is not perceptually uniform. A blue at `hsl(250, 70%, 50%)` and a yellow at `hsl(60, 70%, 50%)` have the same numeric lightness but very different perceived brightness. This makes HSL palettes that "look right" on the screen require constant manual tuning.
+
+OKLCH fixes this: a blue at `oklch(50% 0.15 250)` and a yellow at `oklch(50% 0.15 90)` appear equally bright.
+
+### Browser support
+
+OKLCH is supported in all modern browsers (Chrome 111+, Firefox 113+, Safari 15.4+). For legacy support, provide an HSL fallback:
+
+```css
+color: hsl(250, 60%, 40%); /* fallback */
+color: oklch(40% 0.15 250); /* modern */
+```
+
+---
+
+## Chroma Constraints
+
+### Reduce chroma near white and black extremes
+
+At very high or very low lightness values, maximum chroma cannot be rendered — the color clips to the display gamut. Reduce chroma as lightness approaches 0% or 100%:
+
+| Lightness range | Max chroma (approx) |
+|-----------------|---------------------|
+| 10%–20% | 0.04–0.08 |
+| 20%–40% | 0.08–0.20 |
+| 40%–60% | 0.15–0.35 |
+| 60%–80% | 0.10–0.25 |
+| 80%–95% | 0.03–0.10 |
+
+Check rendered output with [OKLCH.com](https://oklch.com/) — the gamut boundary is shown visually.
+
+---
+
+## Neutrals: Tinted, Not Pure Gray
+
+Pure grays (chroma 0) appear cold and disconnected from the UI's color palette. Tinting neutrals with a low-chroma version of the brand hue creates cohesion.
+
+### Formula
+
+Use the brand hue with chroma 0.01–0.02 for neutrals:
+
+```css
+:root {
+  /* Brand hue: 250 (blue) */
+  --neutral-900: oklch(12% 0.01 250);
+  --neutral-800: oklch(20% 0.01 250);
+  --neutral-700: oklch(30% 0.01 250);
+  --neutral-600: oklch(40% 0.01 250);
+  --neutral-500: oklch(50% 0.01 250);
+  --neutral-400: oklch(60% 0.01 250);
+  --neutral-300: oklch(72% 0.01 250);
+  --neutral-200: oklch(84% 0.01 250);
+  --neutral-100: oklch(93% 0.01 250);
+  --neutral-50:  oklch(97% 0.01 250);
+}
+```
+
+### Temperature
+
+| Hue angle | Temperature | Effect |
+|-----------|-------------|--------|
+| ~60° | Warm | Approachable, editorial |
+| ~250° | Cool | Technical, precise, professional |
+
+Warm neutrals (cream, off-white) suit consumer and lifestyle products. Cool neutrals suit developer tools, dashboards, and data products.
+
+---
+
+## Palette Architecture
+
+### Components
+
+| Component | Count | Purpose |
+|-----------|-------|---------|
+| Primary | 1 color, 3–5 shades | Brand identity, CTAs, interactive elements |
+| Neutral | 9–11 shades | Backgrounds, borders, text |
+| Semantic | 4 colors (success, warning, danger, info), 2–3 shades each | State communication |
+| Surface | 2–3 variants | Background layering (base, raised, overlay) |
+
+### Primary palette (5 shades)
+
+```css
+:root {
+  --primary-50:  oklch(95% 0.05 250);  /* tint, hover backgrounds */
+  --primary-200: oklch(80% 0.10 250);  /* light states */
+  --primary-500: oklch(55% 0.20 250);  /* primary action */
+  --primary-700: oklch(38% 0.18 250);  /* pressed, dark variant */
+  --primary-900: oklch(22% 0.12 250);  /* text on light bg */
+}
+```
+
+### Semantic palette
+
+```css
+:root {
+  /* Success */
+  --success-light: oklch(92% 0.06 145);
+  --success:       oklch(50% 0.18 145);
+  --success-dark:  oklch(35% 0.15 145);
+
+  /* Warning */
+  --warning-light: oklch(93% 0.08 85);
+  --warning:       oklch(65% 0.20 85);
+  --warning-dark:  oklch(45% 0.18 85);
+
+  /* Danger */
+  --danger-light:  oklch(93% 0.06 25);
+  --danger:        oklch(50% 0.20 25);
+  --danger-dark:   oklch(35% 0.18 25);
+
+  /* Info */
+  --info-light:    oklch(93% 0.05 230);
+  --info:          oklch(52% 0.18 230);
+  --info-dark:     oklch(38% 0.16 230);
+}
+```
+
+---
+
+## The 60-30-10 Rule
+
+Visual weight should be distributed to create hierarchy without chaos:
+
+| Proportion | Role | Example |
+|------------|------|---------|
+| 60% | Dominant (neutral backgrounds) | Page background, card surfaces |
+| 30% | Secondary (supporting) | Sidebar, navigation, secondary panels |
+| 10% | Accent (brand, CTAs) | Buttons, links, highlights, icons |
+
+Violating this ratio — for example, a 40% brand-color background — overwhelms the interface and makes it harder to identify interactive elements.
+
+---
+
+## WCAG Contrast Requirements
+
+Contrast ratio is calculated between foreground and background luminance. Use a contrast checker to verify all text/background combinations.
+
+### Minimum ratios
+
+| Element | WCAG AA | WCAG AAA |
+|---------|---------|----------|
+| Body text (< 18px / < 14px bold) | 4.5:1 | 7:1 |
+| Large text (≥ 18px / ≥ 14px bold) | 3:1 | 4.5:1 |
+| UI components (borders, icons, input outlines) | 3:1 | 4.5:1 |
+
+### Practical targets
+
+- Body text: aim for 7:1 (AAA) — the difference in effort is minimal and accessibility is significantly better
+- Large headings: 4.5:1 minimum
+- Placeholder text: WCAG requires 4.5:1; placeholders are not exempt despite their decorative role
+- Disabled elements: WCAG exempts disabled controls from contrast requirements, but aim for 3:1 as a courtesy
+
+### Anti-patterns
+
+| Anti-pattern | Problem | Fix |
+|--------------|---------|-----|
+| Light gray text on white | Classic failure — looks designed, fails AA | Use `oklch(45% 0.01 250)` on white for safe gray |
+| Gray text on colored background | Double unpredictability — two variables affecting contrast | Test with a contrast checker, not by eye |
+| Red on green | Colorblind failure (deuteranopia/protanopia) | Add pattern or icon; do not rely on color alone |
+| Blue on red | Chromatic aberration causes vibration | Add lightness contrast; avoid hue-only contrast |
+| Yellow on white | Low contrast despite perceived brightness | Yellow on white fails AA unless very dark yellow |
+| Thin text over images | Impossible to guarantee; background varies | Add text shadow, overlay panel, or blur backdrop |
+
+### Testing tools
+
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- Chrome DevTools: Elements panel → Accessibility → Contrast
+- Firefox DevTools: Accessibility panel
+- Polypane: Built-in contrast checking across all breakpoints
+
+---
+
+## No Pure Gray or Black
+
+Pure grays (`oklch(N% 0 0)` or `#808080`) read as cold and disconnected. Tinted grays integrate into the palette.
+
+### Rule: chroma 0.005–0.01 minimum
+
+```css
+/* WRONG: pure gray */
+color: oklch(50% 0 0);
+
+/* CORRECT: tinted neutral */
+color: oklch(50% 0.01 250);
+```
+
+### No pure black
+
+`#000000` or `oklch(0% 0 0)` is rarely appropriate. High contrast without tint creates harshness. Instead:
+
+```css
+/* WRONG */
+--text-primary: #000000;
+
+/* CORRECT: near-black with subtle tint */
+--text-primary: oklch(12% 0.01 250);
+```
+
+---
+
+## Dark Mode
+
+Dark mode is NOT a color inversion. Inversion breaks contrast relationships and produces garish results. Instead, dark mode requires thoughtfully redesigned color relationships.
+
+### Principles
+
+**Lighter surfaces indicate depth.** In light mode, shadows indicate elevation. In dark mode, lighter backgrounds indicate elevation:
+
+| Elevation | Light mode | Dark mode |
+|-----------|-----------|-----------|
+| Page background | Lightest | Darkest |
+| Card | +shadow | Slightly lighter |
+| Modal/overlay | +deeper shadow | Lighter still |
+| Tooltip | Darkest shadow | Lightest surface |
+
+**Slightly desaturated accents.** Saturated colors are harder to look at on dark backgrounds for extended periods. Reduce chroma by 0.02–0.04:
+
+```css
+@media (prefers-color-scheme: dark) {
+  --primary-500: oklch(62% 0.16 250); /* was 0.20 in light mode */
+}
+```
+
+**Dark gray, never pure black.** Use 12–18% lightness for the base background:
+
+```css
+@media (prefers-color-scheme: dark) {
+  --surface-base:    oklch(14% 0.01 250); /* main background */
+  --surface-raised:  oklch(18% 0.01 250); /* cards */
+  --surface-overlay: oklch(22% 0.01 250); /* modals */
+}
+```
+
+**Redefine semantic tokens, do not invert them.** Semantic tokens exist precisely for this purpose:
+
+```css
+:root {
+  --text-body:    oklch(25% 0.01 250);
+  --text-muted:   oklch(50% 0.01 250);
+  --bg-base:      oklch(98% 0.01 250);
+}
+
+@media (prefers-color-scheme: dark) {
+  --text-body:    oklch(90% 0.01 250);
+  --text-muted:   oklch(65% 0.01 250);
+  --bg-base:      oklch(14% 0.01 250);
+}
+```
+
+### Dark mode testing
+
+- DevTools: Rendering panel → Emulate CSS media feature prefers-color-scheme
+- Test WCAG contrast ratios in dark mode independently — they differ from light mode
+- Test with vision emulation filters (protanopia, deuteranopia, achromatopsia) in DevTools

package/templates/guides/impeccable-design/index.yaml

@@ -0,0 +1,12 @@
+name: impeccable-design
+description: AI design language reference — typography, color, motion, and UX writing for production-grade UI
+source:
+  type: external
+  origin: github
+  url: https://github.com/pbakaus/impeccable
+  license: Apache-2.0
+documents:
+  - typography.md
+  - color-and-contrast.md
+  - motion-design.md
+  - ux-writing.md