@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/impeccable/reference/brand.md

@@ -0,0 +1,104 @@
+# Brand register
+
+When design IS the product: brand sites, landing pages, marketing surfaces, campaign pages, portfolios, long-form content, about pages. The deliverable is the design itself — a visitor's impression is the thing being made.
+
+The register spans every genre. A tech brand (Stripe, Linear, Vercel). A luxury brand (a hotel, a fashion house). A consumer product (a restaurant, a travel site, a CPG packaging page). A creative studio, an agency portfolio, a band's album page. They all share the stance — *communicate, not transact* — and diverge wildly in aesthetic. Don't collapse them into a single look.
+
+## The brand slop test
+
+If someone could look at this and say "AI made that" without hesitation, it's failed. The bar is distinctiveness — a visitor should ask "how was this made?", not "which AI made this?"
+
+Brand isn't a neutral register. AI-generated landing pages have flooded the internet, and average is no longer findable. Restraint without intent now reads as mediocre, not refined. Brand surfaces need a POV, a specific audience, a willingness to risk strangeness. Go big or go home.
+
+**The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register.
+
+## Typography
+
+### Font selection procedure
+
+Every project. Never skip.
+
+1. Read the brief. Write three concrete brand-voice words — not "modern" or "elegant," but "warm and mechanical and opinionated" or "calm and clinical and careful." Physical-object words.
+2. List the three fonts you'd reach for by reflex. If any appear in the reflex-reject list below, reject them — they are training-data defaults and they create monoculture.
+3. Browse a real catalog (Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim, Velvetyne) with the three words in mind. Find the font for the brand as a *physical object* — a museum caption, a 1970s terminal manual, a fabric label, a cheap-newsprint children's book, a concert poster, a receipt from a mid-century diner. Reject the first thing that "looks designy."
+4. Cross-check. "Elegant" is not necessarily serif. "Technical" is not necessarily sans. "Warm" is not Fraunces. If the final pick lines up with the original reflex, start over.
+
+### Reflex-reject list
+
+Training-data defaults. Ban list — look further:
+
+Fraunces · Newsreader · Lora · Crimson · Crimson Pro · Crimson Text · Playfair Display · Cormorant · Cormorant Garamond · Syne · IBM Plex Mono · IBM Plex Sans · IBM Plex Serif · Space Mono · Space Grotesk · Inter · DM Sans · DM Serif Display · DM Serif Text · Outfit · Plus Jakarta Sans · Instrument Sans · Instrument Serif
+
+### Pairing and voice
+
+Distinctive + refined is the goal — the specific shape depends on the brand:
+
+- **Editorial / long-form / luxury**: display serif + sans body (a magazine shape).
+- **Tech / dev tools / fintech**: one committed sans, usually; custom-tight tracking, strong weight contrast inside a single family.
+- **Consumer / food / travel**: warmer pairings, often a humanist sans plus a script or display serif.
+- **Creative studios / agencies**: rule-breaking welcome — mono-only, or display-only, or custom-drawn type as voice.
+
+Two families minimum is the rule *only* when the voice needs it. A single well-chosen family with committed weight/size contrast is stronger than a timid display+body pair.
+
+Vary across projects. If the last brief was a serif-display landing page, this one isn't.
+
+### Scale
+
+Modular scale, fluid `clamp()` for headings, ≥1.25 ratio between steps. Flat scales (1.1× apart) read as uncommitted.
+
+Light text on dark backgrounds: add 0.05–0.1 to line-height. Light type reads as lighter weight and needs more breathing room.
+
+## Color
+
+Brand surfaces have permission for Committed, Full palette, and Drenched strategies. Use them. A single saturated color spread across a hero is not excess — it's voice. A beige-and-muted-slate landing page ignores the register.
+
+- Name a real reference before picking a strategy. "Klim Type Foundry #ff4500 orange drench", "Stripe purple-on-white restraint", "Liquid Death acid-green full palette", "Mailchimp yellow full palette", "Condé Nast Traveler muted navy restraint", "Vercel pure black monochrome". Unnamed ambition becomes beige.
+- Palette IS voice. A calm brand and a restless brand should not share palette mechanics.
+- When the strategy is Committed or Drenched, the color is load-bearing. Don't hedge with neutrals around the edges — commit.
+- Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not.
+
+## Layout
+
+- Asymmetric compositions are one option. Break the grid intentionally for emphasis.
+- Fluid spacing with `clamp()` that breathes on larger viewports. Vary for rhythm — generous separations, tight groupings.
+- Alternative: a strict, visible grid as the voice (brutalist / Swiss / tech-spec aesthetics). Either asymmetric or rigorously-gridded can be "designed" — the failure mode is splitting the difference into a generic centered stack.
+- Don't default to centering everything. Left-aligned with asymmetric layouts feels more designed; a strict grid reads as confident structure. A centered-stack hero with icon-title-subtitle cards reads as template.
+- When cards ARE the right affordance, use `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` — breakpoint-free responsiveness.
+
+## Imagery
+
+Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo.
+
+**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse.
+
+- **For greenfield work without local assets, use stock imagery** — Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `<div>` placeholders.
+- **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel".
+- **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one.
+- **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish".
+
+Tech / dev-tool brands are the exception where zero imagery can be correct — a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on.
+
+## Motion
+
+- One well-orchestrated page-load with staggered reveals beats scattered micro-interactions — when the brand invites it. Tech-minimal brands often skip entrance motion entirely; the restraint is the voice.
+- For collapsing/expanding sections, transition `grid-template-rows` rather than `height`.
+
+## Brand bans (on top of the shared absolute bans)
+
+- Monospace as lazy shorthand for "technical / developer." If the brand isn't technical, mono reads as costume.
+- Large rounded-corner icons above every heading. Screams template.
+- Single-family pages that picked the family by reflex, not voice. (A single family chosen deliberately is fine.)
+- All-caps body copy. Reserve caps for short labels and headings.
+- Timid palettes and average layouts. Safe = invisible.
+- Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs.
+- Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic.
+
+## Brand permissions
+
+Brand can afford things product can't. Take them.
+
+- Ambitious first-load motion. Reveals, scroll-triggered transitions, typographic choreography.
+- Single-purpose viewports. One dominant idea per fold, long scroll, deliberate pacing.
+- Typographic risk. Enormous display type, unexpected italic cuts, mixed cases, hand-drawn headlines, a single oversize word as a hero.
+- Unexpected color strategies. Palette IS voice — a calm brand and a restless brand should not share palette mechanics.
+- Art direction per section. Different sections can have different visual worlds if the narrative demands it. Consistency of voice beats consistency of treatment.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/impeccable/reference/clarify.md

@@ -0,0 +1,174 @@
+> **Additional context needed**: audience technical level and users' mental state in context.
+
+Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
+
+
+---
+
+## Assess Current Copy
+
+Identify what makes the text unclear or ineffective:
+
+1. **Find clarity problems**:
+   - **Jargon**: Technical terms users won't understand
+   - **Ambiguity**: Multiple interpretations possible
+   - **Passive voice**: "Your file has been uploaded" vs "We uploaded your file"
+   - **Length**: Too wordy or too terse
+   - **Assumptions**: Assuming user knowledge they don't have
+   - **Missing context**: Users don't know what to do or why
+   - **Tone mismatch**: Too formal, too casual, or inappropriate for situation
+
+2. **Understand the context**:
+   - Who's the audience? (Technical? General? First-time users?)
+   - What's the user's mental state? (Stressed during error? Confident during success?)
+   - What's the action? (What do we want users to do?)
+   - What's the constraint? (Character limits? Space limitations?)
+
+**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.
+
+## Plan Copy Improvements
+
+Create a strategy for clearer communication:
+
+- **Primary message**: What's the ONE thing users need to know?
+- **Action needed**: What should users do next (if anything)?
+- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)
+- **Constraints**: Length limits, brand voice, localization considerations
+
+**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.
+
+## Improve Copy Systematically
+
+Refine text across these common areas:
+
+### Error Messages
+**Bad**: "Error 403: Forbidden"
+**Good**: "You don't have permission to view this page. Contact your admin for access."
+
+**Bad**: "Invalid input"
+**Good**: "Email addresses need an @ symbol. Try: name@example.com"
+
+**Principles**:
+- Explain what went wrong in plain language
+- Suggest how to fix it
+- Don't blame the user
+- Include examples when helpful
+- Link to help/support if applicable
+
+### Form Labels & Instructions
+**Bad**: "DOB (MM/DD/YYYY)"
+**Good**: "Date of birth" (with placeholder showing format)
+
+**Bad**: "Enter value here"
+**Good**: "Your email address" or "Company name"
+
+**Principles**:
+- Use clear, specific labels (not generic placeholders)
+- Show format expectations with examples
+- Explain why you're asking (when not obvious)
+- Put instructions before the field, not after
+- Keep required field indicators clear
+
+### Button & CTA Text
+**Bad**: "Click here" | "Submit" | "OK"
+**Good**: "Create account" | "Save changes" | "Got it, thanks"
+
+**Principles**:
+- Describe the action specifically
+- Use active voice (verb + noun)
+- Match user's mental model
+- Be specific ("Save" is better than "OK")
+
+### Help Text & Tooltips
+**Bad**: "This is the username field"
+**Good**: "Choose a username. You can change this later in Settings."
+
+**Principles**:
+- Add value (don't just repeat the label)
+- Answer the implicit question ("What is this?" or "Why do you need this?")
+- Keep it brief but complete
+- Link to detailed docs if needed
+
+### Empty States
+**Bad**: "No items"
+**Good**: "No projects yet. Create your first project to get started."
+
+**Principles**:
+- Explain why it's empty (if not obvious)
+- Show next action clearly
+- Make it welcoming, not dead-end
+
+### Success Messages
+**Bad**: "Success"
+**Good**: "Settings saved! Your changes will take effect immediately."
+
+**Principles**:
+- Confirm what happened
+- Explain what happens next (if relevant)
+- Be brief but complete
+- Match the user's emotional moment (celebrate big wins)
+
+### Loading States
+**Bad**: "Loading..." (for 30+ seconds)
+**Good**: "Analyzing your data... this usually takes 30-60 seconds"
+
+**Principles**:
+- Set expectations (how long?)
+- Explain what's happening (when it's not obvious)
+- Show progress when possible
+- Offer escape hatch if appropriate ("Cancel")
+
+### Confirmation Dialogs
+**Bad**: "Are you sure?"
+**Good**: "Delete 'Project Alpha'? This can't be undone."
+
+**Principles**:
+- State the specific action
+- Explain consequences (especially for destructive actions)
+- Use clear button labels ("Delete project" not "Yes")
+- Don't overuse confirmations (only for risky actions)
+
+### Navigation & Wayfinding
+**Bad**: Generic labels like "Items" | "Things" | "Stuff"
+**Good**: Specific labels like "Your projects" | "Team members" | "Settings"
+
+**Principles**:
+- Be specific and descriptive
+- Use language users understand (not internal jargon)
+- Make hierarchy clear
+- Consider information scent (breadcrumbs, current location)
+
+## Apply Clarity Principles
+
+Every piece of copy should follow these rules:
+
+1. **Be specific**: "Enter email" not "Enter value"
+2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity)
+3. **Be active**: "Save changes" not "Changes will be saved"
+4. **Be human**: "Oops, something went wrong" not "System error encountered"
+5. **Be helpful**: Tell users what to do, not just what happened
+6. **Be consistent**: Use same terms throughout (don't vary for variety)
+
+**NEVER**:
+- Use jargon without explanation
+- Blame users ("You made an error" → "This field is required")
+- Be vague ("Something went wrong" without explanation)
+- Use passive voice unnecessarily
+- Write overly long explanations (be concise)
+- Use humor for errors (be empathetic instead)
+- Assume technical knowledge
+- Vary terminology (pick one term and stick with it)
+- Repeat information (headers restating intros, redundant explanations)
+- Use placeholders as the only labels (they disappear when users type)
+
+## Verify Improvements
+
+Test that copy improvements work:
+
+- **Comprehension**: Can users understand without context?
+- **Actionability**: Do users know what to do next?
+- **Brevity**: Is it as short as possible while remaining clear?
+- **Consistency**: Does it match terminology elsewhere?
+- **Tone**: Is it appropriate for the situation?
+
+Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/impeccable/reference/cognitive-load.md

@@ -0,0 +1,106 @@
+# Cognitive Load Assessment
+
+Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload.
+
+---
+
+## Three Types of Cognitive Load
+
+### Intrinsic Load — The Task Itself
+Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it.
+
+**Manage it by**:
+- Breaking complex tasks into discrete steps
+- Providing scaffolding (templates, defaults, examples)
+- Progressive disclosure — show what's needed now, hide the rest
+- Grouping related decisions together
+
+### Extraneous Load — Bad Design
+Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste.
+
+**Common sources**:
+- Confusing navigation that requires mental mapping
+- Unclear labels that force users to guess meaning
+- Visual clutter competing for attention
+- Inconsistent patterns that prevent learning
+- Unnecessary steps between user intent and result
+
+### Germane Load — Learning Effort
+Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery.
+
+**Support it by**:
+- Progressive disclosure that reveals complexity gradually
+- Consistent patterns that reward learning
+- Feedback that confirms correct understanding
+- Onboarding that teaches through action, not walls of text
+
+---
+
+## Cognitive Load Checklist
+
+Evaluate the interface against these 8 items:
+
+- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements?
+- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)?
+- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)?
+- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen?
+- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next?
+- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)?
+- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one?
+- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it?
+
+**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed).
+
+---
+
+## The Working Memory Rule
+
+**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001).
+
+At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider:
+- **≤4 items**: Within working memory limits — manageable
+- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure
+- **8+ items**: Overloaded — users will skip, misclick, or abandon
+
+**Practical applications**:
+- Navigation menus: ≤5 top-level items (group the rest under clear categories)
+- Form sections: ≤4 fields visible per group before a visual break
+- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu
+- Dashboard widgets: ≤4 key metrics visible without scrolling
+- Pricing tiers: ≤3 options (more causes analysis paralysis)
+
+---
+
+## Common Cognitive Load Violations
+
+### 1. The Wall of Options
+**Problem**: Presenting 10+ choices at once with no hierarchy.
+**Fix**: Group into categories, highlight recommended, use progressive disclosure.
+
+### 2. The Memory Bridge
+**Problem**: User must remember info from step 1 to complete step 3.
+**Fix**: Keep relevant context visible, or repeat it where it's needed.
+
+### 3. The Hidden Navigation
+**Problem**: User must build a mental map of where things are.
+**Fix**: Always show current location (breadcrumbs, active states, progress indicators).
+
+### 4. The Jargon Barrier
+**Problem**: Technical or domain language forces translation effort.
+**Fix**: Use plain language. If domain terms are unavoidable, define them inline.
+
+### 5. The Visual Noise Floor
+**Problem**: Every element has the same visual weight — nothing stands out.
+**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted.
+
+### 6. The Inconsistent Pattern
+**Problem**: Similar actions work differently in different places.
+**Fix**: Standardize interaction patterns. Same type of action = same type of UI.
+
+### 7. The Multi-Task Demand
+**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating).
+**Fix**: Sequence the steps. Let the user do one thing at a time.
+
+### 8. The Context Switch
+**Problem**: User must jump between screens/tabs/modals to gather info for a single decision.
+**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/impeccable/reference/color-and-contrast.md

@@ -0,0 +1,105 @@
+# Color & Contrast
+
+## Color Spaces: Use OKLCH
+
+**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.
+
+The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness — but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish.
+
+The hue you pick is a brand decision and should not come from a default. Do not reach for blue (hue 250) or warm orange (hue 60) by reflex — those are the dominant AI-design defaults, not the right answer for any specific brand.
+
+## Building Functional Palettes
+
+### Tinted Neutrals
+
+**Pure gray is dead.** A neutral with zero chroma feels lifeless next to a colored brand. Add a tiny chroma value (0.005-0.015) to all your neutrals, hued toward whatever your brand color is. The chroma is small enough not to read as "tinted" consciously, but it creates subconscious cohesion between brand color and UI surfaces.
+
+The hue you tint toward should come from THIS project's brand, not from a "warm = friendly, cool = tech" formula. If your brand color is teal, your neutrals lean toward teal. If your brand color is amber, they lean toward amber. The point is cohesion with the SPECIFIC brand, not a stock palette.
+
+**Avoid** the trap of always tinting toward warm orange or always tinting toward cool blue. Those are the two laziest defaults and they create their own monoculture across projects.
+
+### Palette Structure
+
+A complete system needs:
+
+| Role | Purpose | Example |
+|------|---------|---------|
+| **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades |
+| **Neutral** | Text, backgrounds, borders | 9-11 shade scale |
+| **Semantic** | Success, error, warning, info | 4 colors, 2-3 shades each |
+| **Surface** | Cards, modals, overlays | 2-3 elevation levels |
+
+**Skip secondary/tertiary unless you need them.** Most apps work fine with one accent color. Adding more creates decision fatigue and visual noise.
+
+### The 60-30-10 Rule (Applied Correctly)
+
+This rule is about **visual weight**, not pixel count:
+
+- **60%**: Neutral backgrounds, white space, base surfaces
+- **30%**: Secondary colors—text, borders, inactive states
+- **10%**: Accent—CTAs, highlights, focus states
+
+The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power.
+
+## Contrast & Accessibility
+
+### WCAG Requirements
+
+| Content Type | AA Minimum | AAA Target |
+|--------------|------------|------------|
+| Body text | 4.5:1 | 7:1 |
+| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 |
+| UI components, icons | 3:1 | 4.5:1 |
+| Non-essential decorations | None | None |
+
+**The gotcha**: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere? Usually fails WCAG.
+
+### Dangerous Color Combinations
+
+These commonly fail contrast or cause readability issues:
+
+- Light gray text on white (the #1 accessibility fail)
+- **Gray text on any colored background**—gray looks washed out and dead on color. Use a darker shade of the background color, or transparency
+- Red text on green background (or vice versa)—8% of men can't distinguish these
+- Blue text on red background (vibrates visually)
+- Yellow text on white (almost always fails)
+- Thin light text on images (unpredictable contrast)
+
+### Never Use Pure Gray or Pure Black
+
+Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature—real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.)
+
+### Testing
+
+Don't trust your eyes. Use tools:
+
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- Browser DevTools → Rendering → Emulate vision deficiencies
+- [Polypane](https://polypane.app/) for real-time testing
+
+## Theming: Light & Dark Mode
+
+### Dark Mode Is Not Inverted Light Mode
+
+You can't just swap colors. Dark mode requires different design decisions:
+
+| Light Mode | Dark Mode |
+|------------|-----------|
+| Shadows for depth | Lighter surfaces for depth (no shadows) |
+| Dark text on light | Light text on dark (reduce font weight) |
+| Vibrant accents | Desaturate accents slightly |
+| White backgrounds | Never pure black—use dark gray (oklch 12-18%) |
+
+In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project — do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light.
+
+### Token Hierarchy
+
+Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer—primitives stay the same.
+
+## Alpha Is A Design Smell
+
+Heavy use of transparency (rgba, hsla) usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency. Define explicit overlay colors for each context instead. Exception: focus rings and interactive states where see-through is needed.
+
+---
+
+**Avoid**: Relying on color alone to convey information. Creating palettes without clear roles for each color. Using pure black (#000) for large areas. Skipping color blindness testing (8% of men affected).

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/impeccable/reference/colorize.md

@@ -0,0 +1,154 @@
+> **Additional context needed**: existing brand colors.
+
+Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality.
+
+---
+
+## Register
+
+Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule — that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it.
+
+Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators — not decoration. Every color has a consistent meaning across every screen.
+
+---
+
+## Assess Color Opportunity
+
+Analyze the current state and identify opportunities:
+
+1. **Understand current state**:
+   - **Color absence**: Pure grayscale? Limited neutrals? One timid accent?
+   - **Missed opportunities**: Where could color add meaning, hierarchy, or delight?
+   - **Context**: What's appropriate for this domain and audience?
+   - **Brand**: Are there existing brand colors we should use?
+
+2. **Identify where color adds value**:
+   - **Semantic meaning**: Success (green), error (red), warning (yellow/orange), info (blue)
+   - **Hierarchy**: Drawing attention to important elements
+   - **Categorization**: Different sections, types, or states
+   - **Emotional tone**: Warmth, energy, trust, creativity
+   - **Wayfinding**: Helping users navigate and understand structure
+   - **Delight**: Moments of visual interest and personality
+
+If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+
+**CRITICAL**: More color ≠ better. Strategic color beats rainbow vomit every time. Every color should have a purpose.
+
+## Plan Color Strategy
+
+Create a purposeful color introduction plan:
+
+- **Color palette**: What colors match the brand/context? (Choose 2-4 colors max beyond neutrals)
+- **Dominant color**: Which color owns 60% of colored elements?
+- **Accent colors**: Which colors provide contrast and highlights? (30% and 10%)
+- **Application strategy**: Where does each color appear and why?
+
+**IMPORTANT**: Color should enhance hierarchy and meaning, not create chaos. Less is more when it matters more.
+
+## Introduce Color Strategically
+
+Add color systematically across these dimensions:
+
+### Semantic Color
+- **State indicators**:
+  - Success: Green tones (emerald, forest, mint)
+  - Error: Red/pink tones (rose, crimson, coral)
+  - Warning: Orange/amber tones
+  - Info: Blue tones (sky, ocean, indigo)
+  - Neutral: Gray/slate for inactive states
+
+- **Status badges**: Colored backgrounds or borders for states (active, pending, completed, etc.)
+- **Progress indicators**: Colored bars, rings, or charts showing completion or health
+
+### Accent Color Application
+- **Primary actions**: Color the most important buttons/CTAs
+- **Links**: Add color to clickable text (maintain accessibility)
+- **Icons**: Colorize key icons for recognition and personality
+- **Headers/titles**: Add color to section headers or key labels
+- **Hover states**: Introduce color on interaction
+
+### Background & Surfaces
+- **Tinted backgrounds**: Replace pure gray (`#f5f5f5`) with warm neutrals (`oklch(97% 0.01 60)`) or cool tints (`oklch(97% 0.01 250)`)
+- **Colored sections**: Use subtle background colors to separate areas
+- **Gradient backgrounds**: Add depth with subtle, intentional gradients (not generic purple-blue)
+- **Cards & surfaces**: Tint cards or surfaces slightly for warmth
+
+**Use OKLCH for color**: It's perceptually uniform, meaning equal steps in lightness *look* equal. Great for generating harmonious scales.
+
+### Data Visualization
+- **Charts & graphs**: Use color to encode categories or values
+- **Heatmaps**: Color intensity shows density or importance
+- **Comparison**: Color coding for different datasets or timeframes
+
+### Borders & Accents
+- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`)
+- **Underlines**: Color underlines for emphasis or active states
+- **Dividers**: Subtle colored dividers instead of gray lines
+- **Focus rings**: Colored focus indicators matching brand
+- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe
+
+**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe.
+
+### Typography Color
+- **Colored headings**: Use brand colors for section headings (maintain contrast)
+- **Highlight text**: Color for emphasis or categories
+- **Labels & tags**: Small colored labels for metadata or categories
+
+### Decorative Elements
+- **Illustrations**: Add colored illustrations or icons
+- **Shapes**: Geometric shapes in brand colors as background elements
+- **Gradients**: Colorful gradient overlays or mesh backgrounds
+- **Blobs/organic shapes**: Soft colored shapes for visual interest
+
+## Balance & Refinement
+
+Ensure color addition improves rather than overwhelms:
+
+### Maintain Hierarchy
+- **Dominant color** (60%): Primary brand color or most used accent
+- **Secondary color** (30%): Supporting color for variety
+- **Accent color** (10%): High contrast for key moments
+- **Neutrals** (remaining): Gray/black/white for structure
+
+### Accessibility
+- **Contrast ratios**: Ensure WCAG compliance (4.5:1 for text, 3:1 for UI components)
+- **Don't rely on color alone**: Use icons, labels, or patterns alongside color
+- **Test for color blindness**: Verify red/green combinations work for all users
+
+### Cohesion
+- **Consistent palette**: Use colors from defined palette, not arbitrary choices
+- **Systematic application**: Same color meanings throughout (green always = success)
+- **Temperature consistency**: Warm palette stays warm, cool stays cool
+
+**NEVER**:
+- Use every color in the rainbow (choose 2-4 colors beyond neutrals)
+- Apply color randomly without semantic meaning
+- Put gray text on colored backgrounds—it looks washed out; use a darker shade of the background color or transparency instead
+- Use pure gray for neutrals—add subtle color tint (warm or cool) for sophistication
+- Use pure black (`#000`) or pure white (`#fff`) for large areas
+- Violate WCAG contrast requirements
+- Use color as the only indicator (accessibility issue)
+- Make everything colorful (defeats the purpose)
+- Default to purple-blue gradients (AI slop aesthetic)
+
+## Verify Color Addition
+
+Test that colorization improves the experience:
+
+- **Better hierarchy**: Does color guide attention appropriately?
+- **Clearer meaning**: Does color help users understand states/categories?
+- **More engaging**: Does the interface feel warmer and more inviting?
+- **Still accessible**: Do all color combinations meet WCAG standards?
+- **Not overwhelming**: Is color balanced and purposeful?
+
+Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional.
+
+## Live-mode signature params
+
+When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)` — typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage.
+
+```json
+{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"}
+```
+
+Layer 1-2 variant-specific params on top: palette selection (`steps` with named options), temperature warmth, or tint vs. true color. See `reference/live.md` for the full params contract.