@bastani/atomic 0.5.11-0 → 0.5.12-0

package/.agents/skills/advanced-evaluation/scripts/evaluation_example.py

@@ -0,0 +1,392 @@
+"""Advanced Evaluation Example
+
+Use when: building LLM-as-judge evaluation pipelines, comparing model outputs
+with position-bias mitigation, or generating domain-specific scoring rubrics.
+
+This module demonstrates the three core evaluation patterns from the
+advanced-evaluation skill: direct scoring, pairwise comparison with position
+swapping, and rubric generation. All functions use pseudocode-style examples
+that work across Python environments without specific dependencies.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "direct_scoring_example",
+    "pairwise_comparison_example",
+    "rubric_generation_example",
+]
+
+
+# =============================================================================
+# DIRECT SCORING EXAMPLE
+# =============================================================================
+
+
+def direct_scoring_example() -> dict[str, Any]:
+    """Rate a single response against defined criteria using direct scoring.
+
+    Use when: evaluating objective criteria like factual accuracy, instruction
+    following, or toxicity where a clear ground truth or rubric exists.
+
+    Returns:
+        Dictionary containing per-criterion scores, evidence, justifications,
+        and a weighted summary.
+    """
+
+    # Input
+    prompt: str = "Explain quantum entanglement to a high school student"
+    response: str = (
+        "Quantum entanglement is like having two magical coins that are connected. "
+        "When you flip one and it lands on heads, the other instantly shows tails, "
+        'no matter how far apart they are. Scientists call this "spooky action at a distance."'
+    )
+
+    criteria: list[dict[str, Any]] = [
+        {"name": "Accuracy", "description": "Scientific correctness", "weight": 0.4},
+        {"name": "Clarity", "description": "Understandable for audience", "weight": 0.3},
+        {"name": "Engagement", "description": "Interesting and memorable", "weight": 0.3},
+    ]
+
+    # System prompt for the evaluator
+    system_prompt: str = (
+        "You are an expert evaluator. Assess the response against each criterion.\n\n"
+        "For each criterion:\n"
+        "1. Find specific evidence in the response\n"
+        "2. Score according to the rubric (1-5 scale)\n"
+        "3. Justify your score with evidence\n"
+        "4. Suggest one specific improvement\n\n"
+        "Be objective and consistent. Base scores on explicit evidence."
+    )
+
+    # User prompt structure
+    user_prompt: str = f"""## Original Prompt
+{prompt}
+
+## Response to Evaluate
+{response}
+
+## Criteria
+1. **Accuracy** (weight: 0.4): Scientific correctness
+2. **Clarity** (weight: 0.3): Understandable for audience
+3. **Engagement** (weight: 0.3): Interesting and memorable
+
+## Output Format
+Respond with valid JSON:
+{{
+  "scores": [
+    {{
+      "criterion": "Accuracy",
+      "score": 4,
+      "evidence": ["quote or observation"],
+      "justification": "why this score",
+      "improvement": "specific suggestion"
+    }}
+  ],
+  "summary": {{
+    "assessment": "overall quality summary",
+    "strengths": ["strength 1"],
+    "weaknesses": ["weakness 1"]
+  }}
+}}"""
+
+    # Expected output structure
+    expected_output: dict[str, Any] = {
+        "scores": [
+            {
+                "criterion": "Accuracy",
+                "score": 4,
+                "evidence": ["Correctly uses analogy", "Mentions spooky action at a distance"],
+                "justification": "Core concept is correct, analogy is appropriate",
+                "improvement": "Could mention it's a quantum mechanical phenomenon",
+            },
+            {
+                "criterion": "Clarity",
+                "score": 5,
+                "evidence": ["Simple coin analogy", "No jargon"],
+                "justification": "Appropriate for high school level",
+                "improvement": "None needed",
+            },
+            {
+                "criterion": "Engagement",
+                "score": 4,
+                "evidence": ["Magical coins", "Spooky action quote"],
+                "justification": "Memorable imagery and Einstein quote",
+                "improvement": "Could add a real-world application",
+            },
+        ],
+        "summary": {
+            "assessment": "Good explanation suitable for the target audience",
+            "strengths": ["Clear analogy", "Age-appropriate language"],
+            "weaknesses": ["Could be more comprehensive"],
+        },
+    }
+
+    # Calculate weighted score
+    total_weight: float = sum(c["weight"] for c in criteria)
+    weighted_score: float = sum(
+        s["score"] * next(c["weight"] for c in criteria if c["name"] == s["criterion"])
+        for s in expected_output["scores"]
+    ) / total_weight
+
+    print(f"Weighted Score: {weighted_score:.2f}/5")
+    return expected_output
+
+
+# =============================================================================
+# PAIRWISE COMPARISON WITH POSITION BIAS MITIGATION
+# =============================================================================
+
+
+def pairwise_comparison_example() -> dict[str, Any]:
+    """Compare two responses with position-swapped bias mitigation.
+
+    Use when: evaluating subjective preferences like tone, style, or
+    persuasiveness where pairwise comparison achieves higher human-judge
+    agreement than direct scoring.
+
+    Returns:
+        Dictionary containing the winner, confidence score, and whether
+        position consistency was achieved across both passes.
+    """
+
+    prompt: str = "Explain machine learning to a beginner"
+
+    response_a: str = (
+        "Machine learning is a subset of artificial intelligence that enables "
+        "systems to learn and improve from experience without being explicitly "
+        "programmed. It uses statistical techniques to give computers the ability "
+        "to identify patterns in data."
+    )
+
+    response_b: str = (
+        "Imagine teaching a dog a new trick. You show the dog what to do, give "
+        "treats when it's right, and eventually it learns. Machine learning works "
+        "similarly - we show computers lots of examples, tell them when they're "
+        "right, and they learn to recognize patterns on their own."
+    )
+
+    criteria: list[str] = ["clarity", "accessibility", "accuracy"]
+
+    # System prompt emphasizing bias awareness
+    system_prompt: str = (
+        "You are an expert evaluator comparing two AI responses.\n\n"
+        "CRITICAL INSTRUCTIONS:\n"
+        "- Do NOT prefer responses because they are longer\n"
+        "- Do NOT prefer responses based on position (first vs second)\n"
+        "- Focus ONLY on quality according to the specified criteria\n"
+        "- Ties are acceptable when responses are genuinely equivalent"
+    )
+
+    # Build evaluation prompt for a given ordering
+    def evaluate_pass(
+        first_response: str,
+        second_response: str,
+        first_label: str,
+        second_label: str,
+    ) -> str:
+        """Build evaluation prompt for one pass of position-swapped comparison.
+
+        Use when: constructing the prompt for a single evaluation pass before
+        swapping response positions for bias mitigation.
+        """
+        return f"""## Original Prompt
+{prompt}
+
+## Response {first_label}
+{first_response}
+
+## Response {second_label}
+{second_response}
+
+## Comparison Criteria
+{', '.join(criteria)}
+
+## Output Format
+{{
+  "comparison": [
+    {{"criterion": "clarity", "winner": "A|B|TIE", "reasoning": "..."}}
+  ],
+  "result": {{
+    "winner": "A|B|TIE",
+    "confidence": 0.0-1.0,
+    "reasoning": "overall reasoning"
+  }}
+}}"""
+
+    # Position bias mitigation protocol
+    print("Pass 1: A in first position")
+    pass1_result: dict[str, Any] = {"winner": "B", "confidence": 0.8}
+
+    print("Pass 2: B in first position (swapped)")
+    pass2_result: dict[str, Any] = {"winner": "A", "confidence": 0.75}  # A because B was first
+
+    # Map pass2 result back (swap labels)
+    def map_winner(winner: str) -> str:
+        """Map winner label after position swap."""
+        return {"A": "B", "B": "A", "TIE": "TIE"}[winner]
+
+    pass2_mapped: str = map_winner(pass2_result["winner"])
+    print(f"Pass 2 mapped winner: {pass2_mapped}")
+
+    # Check consistency
+    consistent: bool = pass1_result["winner"] == pass2_mapped
+
+    final_result: dict[str, Any]
+    if consistent:
+        final_result = {
+            "winner": pass1_result["winner"],
+            "confidence": (pass1_result["confidence"] + pass2_result["confidence"]) / 2,
+            "position_consistent": True,
+        }
+    else:
+        final_result = {
+            "winner": "TIE",
+            "confidence": 0.5,
+            "position_consistent": False,
+            "bias_detected": True,
+        }
+
+    print(f"\nFinal Result: {final_result}")
+    return final_result
+
+
+# =============================================================================
+# RUBRIC GENERATION
+# =============================================================================
+
+
+def rubric_generation_example() -> dict[str, Any]:
+    """Generate a domain-specific scoring rubric for consistent evaluation.
+
+    Use when: establishing evaluation standards for a new criterion, reducing
+    scoring variance (rubrics cut variance by 40-60%), or onboarding new
+    evaluators to an existing evaluation pipeline.
+
+    Returns:
+        Dictionary containing score levels, characteristics, examples,
+        scoring guidelines, and edge case handling.
+    """
+
+    criterion_name: str = "Code Readability"
+    criterion_description: str = "How easy the code is to understand and maintain"
+    domain: str = "software engineering"
+    scale: str = "1-5"
+    strictness: str = "balanced"
+
+    system_prompt: str = (
+        f"You are an expert in creating evaluation rubrics.\n"
+        f"Create clear, actionable rubrics with distinct boundaries between levels.\n\n"
+        f"Strictness: {strictness}\n"
+        f"- lenient: Lower bar for passing scores\n"
+        f"- balanced: Fair, typical expectations\n"
+        f"- strict: High standards, critical evaluation"
+    )
+
+    user_prompt: str = f"""Create a scoring rubric for:
+
+**Criterion**: {criterion_name}
+**Description**: {criterion_description}
+**Scale**: {scale}
+**Domain**: {domain}
+
+Generate:
+1. Clear descriptions for each score level
+2. Specific characteristics that define each level
+3. Brief example text for each level
+4. General scoring guidelines
+5. Edge cases with guidance"""
+
+    # Expected rubric structure
+    rubric: dict[str, Any] = {
+        "criterion": criterion_name,
+        "scale": {"min": 1, "max": 5},
+        "levels": [
+            {
+                "score": 1,
+                "label": "Poor",
+                "description": "Code is difficult to understand without significant effort",
+                "characteristics": [
+                    "No meaningful variable or function names",
+                    "No comments or documentation",
+                    "Deeply nested or convoluted logic",
+                ],
+                "example": "def f(x): return x[0]*x[1]+x[2]",
+            },
+            {
+                "score": 3,
+                "label": "Adequate",
+                "description": "Code is understandable with some effort",
+                "characteristics": [
+                    "Most variables have meaningful names",
+                    "Basic comments for complex sections",
+                    "Logic is followable but could be cleaner",
+                ],
+                "example": (
+                    "def calc_total(items): # calculate sum\n"
+                    "    total = 0\n"
+                    "    for i in items: total += i\n"
+                    "    return total"
+                ),
+            },
+            {
+                "score": 5,
+                "label": "Excellent",
+                "description": "Code is immediately clear and maintainable",
+                "characteristics": [
+                    "All names are descriptive and consistent",
+                    "Comprehensive documentation",
+                    "Clean, modular structure",
+                ],
+                "example": (
+                    "def calculate_total_price(items: List[Item]) -> Decimal:\n"
+                    "    '''Calculate the total price of all items.'''\n"
+                    "    return sum(item.price for item in items)"
+                ),
+            },
+        ],
+        "scoring_guidelines": [
+            "Focus on readability, not cleverness",
+            "Consider the intended audience (team skill level)",
+            "Consistency matters more than style preference",
+        ],
+        "edge_cases": [
+            {
+                "situation": "Code uses domain-specific abbreviations",
+                "guidance": "Score based on readability for domain experts, not general audience",
+            },
+            {
+                "situation": "Code is auto-generated",
+                "guidance": "Apply same standards but note in evaluation",
+            },
+        ],
+    }
+
+    print("Generated Rubric:")
+    for level in rubric["levels"]:
+        print(f"  {level['score']}: {level['label']} - {level['description']}")
+
+    return rubric
+
+
+# =============================================================================
+# MAIN
+# =============================================================================
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("DIRECT SCORING EXAMPLE")
+    print("=" * 60)
+    direct_scoring_example()
+
+    print("\n" + "=" * 60)
+    print("PAIRWISE COMPARISON EXAMPLE")
+    print("=" * 60)
+    pairwise_comparison_example()
+
+    print("\n" + "=" * 60)
+    print("RUBRIC GENERATION EXAMPLE")
+    print("=" * 60)
+    rubric_generation_example()

package/.agents/skills/animate/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: animate
+description: Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive.
+version: 2.1.1
+user-invocable: true
+argument-hint: "[target]"
+---
+
+Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
+
+## MANDATORY PREPARATION
+
+Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: performance constraints.
+
+---
+
+## Assess Animation Opportunities
+
+Analyze where motion would improve the experience:
+
+1. **Identify static areas**:
+   - **Missing feedback**: Actions without visual acknowledgment (button clicks, form submission, etc.)
+   - **Jarring transitions**: Instant state changes that feel abrupt (show/hide, page loads, route changes)
+   - **Unclear relationships**: Spatial or hierarchical relationships that aren't obvious
+   - **Lack of delight**: Functional but joyless interactions
+   - **Missed guidance**: Opportunities to direct attention or explain behavior
+
+2. **Understand the context**:
+   - What's the personality? (Playful vs serious, energetic vs calm)
+   - What's the performance budget? (Mobile-first? Complex page?)
+   - Who's the audience? (Motion-sensitive users? Power users who want speed?)
+   - What matters most? (One hero animation vs many micro-interactions?)
+
+If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+
+**CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them.
+
+## Plan Animation Strategy
+
+Create a purposeful animation plan:
+
+- **Hero moment**: What's the ONE signature animation? (Page load? Hero section? Key interaction?)
+- **Feedback layer**: Which interactions need acknowledgment?
+- **Transition layer**: Which state changes need smoothing?
+- **Delight layer**: Where can we surprise and delight?
+
+**IMPORTANT**: One well-orchestrated experience beats scattered animations everywhere. Focus on high-impact moments.
+
+## Implement Animations
+
+Add motion systematically across these categories:
+
+### Entrance Animations
+- **Page load choreography**: Stagger element reveals (100-150ms delays), fade + slide combinations
+- **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects)
+- **Content reveals**: Scroll-triggered animations using intersection observer
+- **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management
+
+### Micro-interactions
+- **Button feedback**:
+  - Hover: Subtle scale (1.02-1.05), color shift, shadow increase
+  - Click: Quick scale down then up (0.95 → 1), ripple effect
+  - Loading: Spinner or pulse state
+- **Form interactions**:
+  - Input focus: Border color transition, slight scale or glow
+  - Validation: Shake on error, check mark on success, smooth color transitions
+- **Toggle switches**: Smooth slide + color transition (200-300ms)
+- **Checkboxes/radio**: Check mark animation, ripple effect
+- **Like/favorite**: Scale + rotation, particle effects, color transition
+
+### State Transitions
+- **Show/hide**: Fade + slide (not instant), appropriate timing (200-300ms)
+- **Expand/collapse**: Height transition with overflow handling, icon rotation
+- **Loading states**: Skeleton screen fades, spinner animations, progress bars
+- **Success/error**: Color transitions, icon animations, gentle scale pulse
+- **Enable/disable**: Opacity transitions, cursor changes
+
+### Navigation & Flow
+- **Page transitions**: Crossfade between routes, shared element transitions
+- **Tab switching**: Slide indicator, content fade/slide
+- **Carousel/slider**: Smooth transforms, snap points, momentum
+- **Scroll effects**: Parallax layers, sticky headers with state changes, scroll progress indicators
+
+### Feedback & Guidance
+- **Hover hints**: Tooltip fade-ins, cursor changes, element highlights
+- **Drag & drop**: Lift effect (shadow + scale), drop zone highlights, smooth repositioning
+- **Copy/paste**: Brief highlight flash on paste, "copied" confirmation
+- **Focus flow**: Highlight path through form or workflow
+
+### Delight Moments
+- **Empty states**: Subtle floating animations on illustrations
+- **Completed actions**: Confetti, check mark flourish, success celebrations
+- **Easter eggs**: Hidden interactions for discovery
+- **Contextual animation**: Weather effects, time-of-day themes, seasonal touches
+
+## Technical Implementation
+
+Use appropriate techniques for each animation:
+
+### Timing & Easing
+
+**Durations by purpose:**
+- **100-150ms**: Instant feedback (button press, toggle)
+- **200-300ms**: State changes (hover, menu open)
+- **300-500ms**: Layout changes (accordion, modal)
+- **500-800ms**: Entrance animations (page load)
+
+**Easing curves (use these, not CSS defaults):**
+```css
+/* Recommended - natural deceleration */
+--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth, refined */
+--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);   /* Slightly snappier */
+--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);     /* Confident, decisive */
+
+/* AVOID - feel dated and tacky */
+/* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
+/* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */
+```
+
+**Exit animations are faster than entrances.** Use ~75% of enter duration.
+
+### CSS Animations
+```css
+/* Prefer for simple, declarative animations */
+- transitions for state changes
+- @keyframes for complex sequences
+- transform + opacity only (GPU-accelerated)
+```
+
+### JavaScript Animation
+```javascript
+/* Use for complex, interactive animations */
+- Web Animations API for programmatic control
+- Framer Motion for React
+- GSAP for complex sequences
+```
+
+### Performance
+- **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties
+- **will-change**: Add sparingly for known expensive animations
+- **Reduce paint**: Minimize repaints, use `contain` where appropriate
+- **Monitor FPS**: Ensure 60fps on target devices
+
+### Accessibility
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+**NEVER**:
+- Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
+- Animate layout properties (width, height, top, left)—use transform instead
+- Use durations over 500ms for feedback—it feels laggy
+- Animate without purpose—every animation needs a reason
+- Ignore `prefers-reduced-motion`—this is an accessibility violation
+- Animate everything—animation fatigue makes interfaces feel exhausting
+- Block interaction during animations unless intentional
+
+## Verify Quality
+
+Test animations thoroughly:
+
+- **Smooth at 60fps**: No jank on target devices
+- **Feels natural**: Easing curves feel organic, not robotic
+- **Appropriate timing**: Not too fast (jarring) or too slow (laggy)
+- **Reduced motion works**: Animations disabled or simplified appropriately
+- **Doesn't block**: Users can interact during/after animations
+- **Adds value**: Makes interface clearer or more delightful
+
+Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right.

package/.agents/skills/arrange/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: arrange
+description: Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition.
+user-invocable: true
+argument-hint: "[target]"
+---
+
+Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions.
+
+## MANDATORY PREPARATION
+
+Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first.
+
+---
+
+## Assess Current Layout
+
+Analyze what's weak about the current spatial design:
+
+1. **Spacing**:
+   - Is spacing consistent or arbitrary? (Random padding/margin values)
+   - Is all spacing the same? (Equal padding everywhere = no rhythm)
+   - Are related elements grouped tightly, with generous space between groups?
+
+2. **Visual hierarchy**:
+   - Apply the squint test: blur your (metaphorical) eyes — can you still identify the most important element, second most important, and clear groupings?
+   - Is hierarchy achieved effectively? (Space and weight alone can be enough — but is the current approach working?)
+   - Does whitespace guide the eye to what matters?
+
+3. **Grid & structure**:
+   - Is there a clear underlying structure, or does the layout feel random?
+   - Are identical card grids used everywhere? (Icon + heading + text, repeated endlessly)
+   - Is everything centered? (Left-aligned with asymmetric layouts feels more designed, but not a hard and fast rule)
+
+4. **Rhythm & variety**:
+   - Does the layout have visual rhythm? (Alternating tight/generous spacing)
+   - Is every section structured the same way? (Monotonous repetition)
+   - Are there intentional moments of surprise or emphasis?
+
+5. **Density**:
+   - Is the layout too cramped? (Not enough breathing room)
+   - Is the layout too sparse? (Excessive whitespace without purpose)
+   - Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air)
+
+**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material — use it with intention.
+
+## Plan Layout Improvements
+
+Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries.
+
+Create a systematic plan:
+
+- **Spacing system**: Use a consistent scale — whether that's a framework's built-in scale (e.g., Tailwind), rem-based tokens, or a custom system. The specific values matter less than consistency.
+- **Hierarchy strategy**: How will space communicate importance?
+- **Layout approach**: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts.
+- **Rhythm**: Where should spacing be tight vs generous?
+
+## Improve Layout Systematically
+
+### Establish a Spacing System
+
+- Use a consistent spacing scale — framework scales (Tailwind, etc.), rem-based tokens, or a custom scale all work. What matters is that values come from a defined set, not arbitrary numbers.
+- Name tokens semantically if using custom properties: `--space-xs` through `--space-xl`, not `--spacing-8`
+- Use `gap` for sibling spacing instead of margins — eliminates margin collapse hacks
+- Apply `clamp()` for fluid spacing that breathes on larger screens
+
+### Create Visual Rhythm
+
+- **Tight grouping** for related elements (8-12px between siblings)
+- **Generous separation** between distinct sections (48-96px)
+- **Varied spacing** within sections — not every row needs the same gap
+- **Asymmetric compositions** — break the predictable centered-content pattern when it makes sense
+
+### Choose the Right Layout Tool
+
+- **Use Flexbox for 1D layouts**: Rows of items, nav bars, button groups, card contents, most component internals. Flex is simpler and more appropriate for the majority of layout tasks.
+- **Use Grid for 2D layouts**: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control.
+- **Don't default to Grid** when Flexbox with `flex-wrap` would be simpler and more flexible.
+- Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints.
+- Use named grid areas (`grid-template-areas`) for complex page layouts — redefine at breakpoints.
+
+### Break Card Grid Monotony
+
+- Don't default to card grids for everything — spacing and alignment create visual grouping naturally
+- Use cards only when content is truly distinct and actionable — never nest cards inside cards
+- Vary card sizes, span columns, or mix cards with non-card content to break repetition
+
+### Strengthen Visual Hierarchy
+
+- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough — generous whitespace around an element draws the eye. Some of the most sophisticated designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
+- Be aware of reading flow — in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
+- Create clear content groupings through proximity and separation.
+
+### Manage Depth & Elevation
+
+- Create a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip)
+- Build a consistent shadow scale (sm → md → lg → xl) — shadows should be subtle
+- Use elevation to reinforce hierarchy, not as decoration
+
+### Optical Adjustments
+
+- If an icon looks visually off-center despite being geometrically centered, nudge it — but only if you're confident it actually looks wrong. Don't adjust speculatively.
+
+**NEVER**:
+- Use arbitrary spacing values outside your scale
+- Make all spacing equal — variety creates hierarchy
+- Wrap everything in cards — not everything needs a container
+- Nest cards inside cards — use spacing and dividers for hierarchy within
+- Use identical card grids everywhere (icon + heading + text, repeated)
+- Center everything — left-aligned with asymmetry feels more designed
+- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work — but it should display actual data, not decorative numbers.
+- Default to CSS Grid when Flexbox would be simpler — use the simplest tool for the job
+- Use arbitrary z-index values (999, 9999) — build a semantic scale
+
+## Verify Layout Improvements
+
+- **Squint test**: Can you identify primary, secondary, and groupings with blurred vision?
+- **Rhythm**: Does the page have a satisfying beat of tight and generous spacing?
+- **Hierarchy**: Is the most important content obvious within 2 seconds?
+- **Breathing room**: Does the layout feel comfortable, not cramped or wasteful?
+- **Consistency**: Is the spacing system applied uniformly?
+- **Responsiveness**: Does the layout adapt gracefully across screen sizes?
+
+Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.