@pzy560117/codex-harness 0.1.2 → 0.1.4

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

@@ -1,114 +0,0 @@
-# Responsive Design
-
-## Mobile-First: Write It Right
-
-Start with base styles for mobile, use `min-width` queries to layer complexity. Desktop-first (`max-width`) means mobile loads unnecessary styles first.
-
-## Breakpoints: Content-Driven
-
-Don't chase device sizes—let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use `clamp()` for fluid values without breakpoints.
-
-## Detect Input Method, Not Just Screen Size
-
-**Screen size doesn't tell you input method.** A laptop with touchscreen, a tablet with keyboard—use pointer and hover queries:
-
-```css
-/* Fine pointer (mouse, trackpad) */
-@media (pointer: fine) {
-  .button { padding: 8px 16px; }
-}
-
-/* Coarse pointer (touch, stylus) */
-@media (pointer: coarse) {
-  .button { padding: 12px 20px; }  /* Larger touch target */
-}
-
-/* Device supports hover */
-@media (hover: hover) {
-  .card:hover { transform: translateY(-2px); }
-}
-
-/* Device doesn't support hover (touch) */
-@media (hover: none) {
-  .card { /* No hover state - use active instead */ }
-}
-```
-
-**Critical**: Don't rely on hover for functionality. Touch users can't hover.
-
-## Safe Areas: Handle the Notch
-
-Modern phones have notches, rounded corners, and home indicators. Use `env()`:
-
-```css
-body {
-  padding-top: env(safe-area-inset-top);
-  padding-bottom: env(safe-area-inset-bottom);
-  padding-left: env(safe-area-inset-left);
-  padding-right: env(safe-area-inset-right);
-}
-
-/* With fallback */
-.footer {
-  padding-bottom: max(1rem, env(safe-area-inset-bottom));
-}
-```
-
-**Enable viewport-fit** in your meta tag:
-```html
-<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
-```
-
-## Responsive Images: Get It Right
-
-### srcset with Width Descriptors
-
-```html
-<img
-  src="hero-800.jpg"
-  srcset="
-    hero-400.jpg 400w,
-    hero-800.jpg 800w,
-    hero-1200.jpg 1200w
-  "
-  sizes="(max-width: 768px) 100vw, 50vw"
-  alt="Hero image"
->
-```
-
-**How it works**:
-- `srcset` lists available images with their actual widths (`w` descriptors)
-- `sizes` tells the browser how wide the image will display
-- Browser picks the best file based on viewport width AND device pixel ratio
-
-### Picture Element for Art Direction
-
-When you need different crops/compositions (not just resolutions):
-
-```html
-<picture>
-  <source media="(min-width: 768px)" srcset="wide.jpg">
-  <source media="(max-width: 767px)" srcset="tall.jpg">
-  <img src="fallback.jpg" alt="...">
-</picture>
-```
-
-## Layout Adaptation Patterns
-
-**Navigation**: Three stages—hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. **Tables**: Transform to cards on mobile using `display: block` and `data-label` attributes. **Progressive disclosure**: Use `<details>/<summary>` for content that can collapse on mobile.
-
-## Testing: Don't Trust DevTools Alone
-
-DevTools device emulation is useful for layout but misses:
-
-- Actual touch interactions
-- Real CPU/memory constraints
-- Network latency patterns
-- Font rendering differences
-- Browser chrome/keyboard appearances
-
-**Test on at least**: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you'll never see on simulators.
-
----
-
-**Avoid**: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.

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

@@ -1,136 +0,0 @@
-Shape the UX and UI for a feature before any code is written. This command produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork.
-
-**Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good.
-
-**Output**: A design brief that can be handed off to $impeccable craft, or directly to $impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output.
-
-## Philosophy
-
-Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This command inverts that: understand deeply first, so implementation is precise.
-
-## Phase 1: Discovery Interview
-
-**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later.
-
-Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer.
-
-### Purpose & Context
-- What is this feature for? What problem does it solve?
-- Who specifically will use it? (Not "users"; be specific: role, context, frequency)
-- What does success look like? How will you know this feature is working?
-- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?)
-
-### Content & Data
-- What content or data does this feature display or collect?
-- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items)
-- What are the edge cases? (Empty state, error state, first-time use, power user)
-- Is any content dynamic? What changes and how often?
-
-### Design Direction
-
-Force a visual decision on three fronts. Skip anything PRODUCT.md or DESIGN.md already answers; ask only what's missing.
-
-- **Color strategy for this surface.** Pick one: Restrained / Committed / Full palette / Drenched. Can override the project default if the surface earns it (e.g. a drenched hero inside an otherwise Restrained product).
-- **Theme via scene sentence.** Write one sentence of physical context for this surface — who uses it, where, under what ambient light, in what mood. The sentence forces dark vs light. If it doesn't, add detail until it does.
-- **Two or three named anchor references.** Specific products, brands, objects — not adjectives like "modern" or "clean."
-
-### Scope
-
-Always ask. Sketch quality and shipped quality are different outputs; don't guess between them.
-
-- **Fidelity.** Sketch / mid-fi / high-fi / production-ready?
-- **Breadth.** One screen / a flow / a whole surface?
-- **Interactivity.** Static visual / interactive prototype / shipped-quality component?
-- **Time intent.** Quick exploration, or polish until it ships?
-
-Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — carry them through the design brief only.
-
-### Constraints
-- Are there technical constraints? (Framework, performance budget, browser support)
-- Are there content constraints? (Localization, dynamic text length, user-generated content)
-- Mobile/responsive requirements?
-- Accessibility requirements beyond WCAG AA?
-
-### Anti-Goals
-- What should this NOT be? What would be a wrong direction?
-- What's the biggest risk of getting this wrong?
-
-## Phase 1.5: Visual Direction Probe (Capability-Gated)
-
-After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true:
-
-- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief.
-- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning.
-- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this.
-
-When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief.
-
-### What to generate
-
-Generate **2 to 4** distinct direction probes based on the discovery answers, especially:
-
-- Color strategy
-- Theme scene sentence
-- Named anchor references
-- Scope and fidelity
-
-The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks.
-
-### How to use the probes
-
-- Treat them as **direction tests**, not final designs.
-- Use them to pressure-test whether the brief is pointing at the right lane.
-- Ask the user which direction feels closest, what feels off, and what should carry forward.
-- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief.
-
-### Important limits
-
-- Do **not** skip discovery because image generation is available.
-- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior.
-- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice.
-
-If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief.
-
-## Phase 2: Design Brief
-
-After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete.
-
-### Brief Structure
-
-**1. Feature Summary** (2-3 sentences)
-What this is, who it's for, what it needs to accomplish.
-
-**2. Primary User Action**
-The single most important thing a user should do or understand here.
-
-**3. Design Direction**
-Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides.
-
-If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it.
-
-**4. Scope**
-Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief.
-
-**5. Layout Strategy**
-High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS.
-
-**6. Key States**
-List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel.
-
-**7. Interaction Model**
-How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion?
-
-**8. Content Requirements**
-What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges.
-
-**9. Recommended References**
-Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features).
-
-**10. Open Questions**
-Anything unresolved that the implementer should resolve during build.
-
----
-
-ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions.
-
-Once confirmed, the brief is complete. The user can now hand it to $impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use $impeccable craft instead, which runs this command internally.)

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

@@ -1,100 +0,0 @@
-# Spatial Design
-
-## Spacing Systems
-
-### Use 4pt Base, Not 8pt
-
-8pt systems are too coarse—you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
-
-### Name Tokens Semantically
-
-Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing—it eliminates margin collapse and cleanup hacks.
-
-## Grid Systems
-
-### The Self-Adjusting Grid
-
-Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints. Columns are at least 280px, as many as fit per row, leftovers stretch. For complex layouts, use named grid areas (`grid-template-areas`) and redefine them at breakpoints.
-
-## Visual Hierarchy
-
-### The Squint Test
-
-Blur your eyes (or screenshot and blur). Can you still identify:
-- The most important element?
-- The second most important?
-- Clear groupings?
-
-If everything looks the same weight blurred, you have a hierarchy problem.
-
-### Hierarchy Through Multiple Dimensions
-
-Don't rely on size alone. Combine:
-
-| Tool | Strong Hierarchy | Weak Hierarchy |
-|------|------------------|----------------|
-| **Size** | 3:1 ratio or more | <2:1 ratio |
-| **Weight** | Bold vs Regular | Medium vs Regular |
-| **Color** | High contrast | Similar tones |
-| **Position** | Top/left (primary) | Bottom/right |
-| **Space** | Surrounded by white space | Crowded |
-
-**The best hierarchy uses 2-3 dimensions at once**: A heading that's larger, bolder, AND has more space above it.
-
-### Cards Are Not Required
-
-Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when content is truly distinct and actionable, items need visual comparison in a grid, or content needs clear interaction boundaries. **Never nest cards inside cards**—use spacing, typography, and subtle dividers for hierarchy within a card.
-
-## Container Queries
-
-Viewport queries are for page layouts. **Container queries are for components**:
-
-```css
-.card-container {
-  container-type: inline-size;
-}
-
-.card {
-  display: grid;
-  gap: var(--space-md);
-}
-
-/* Card layout changes based on its container, not viewport */
-@container (min-width: 400px) {
-  .card {
-    grid-template-columns: 120px 1fr;
-  }
-}
-```
-
-**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands—automatically, without viewport hacks.
-
-## Optical Adjustments
-
-Text at `margin-left: 0` looks indented due to letterform whitespace—use negative margin (`-0.05em`) to optically align. Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction.
-
-### Touch Targets vs Visual Size
-
-Buttons can look small but need large touch targets (44px minimum). Use padding or pseudo-elements:
-
-```css
-.icon-button {
-  width: 24px;  /* Visual size */
-  height: 24px;
-  position: relative;
-}
-
-.icon-button::before {
-  content: '';
-  position: absolute;
-  inset: -10px;  /* Expand tap target to 44px */
-}
-```
-
-## Depth & Elevation
-
-Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers. For shadows, create a consistent elevation scale (sm → md → lg → xl). **Key insight**: Shadows should be subtle—if you can clearly see it, it's probably too strong.
-
----
-
-**Avoid**: Arbitrary spacing values outside your scale. Making all spacing equal (variety creates hierarchy). Creating hierarchy through size alone - combine size, weight, color, and space.