@gobing-ai/spur 0.3.78 → 0.3.81

package/plugins/sp/skills/taste-refactoring-tests/references/research-basis.md

@@ -0,0 +1,47 @@
+# Research and Industry-Practice Basis
+
+This skill is synthesized from established testing practice rather than one source document.
+
+## Core traditions reflected
+
+### Behavior-oriented unit testing
+Tests should focus on observable behavior and stable contracts rather than mirroring internal implementation structure. This reduces brittleness and makes refactoring safer.
+
+### Test pyramid / test portfolio thinking
+Confidence should be distributed across test levels. Unit tests are best for fast local decision logic and invariants; integration, contract, and end-to-end tests should cover concerns that inherently require real boundaries.
+
+### Mutation testing
+Mutation testing evaluates whether tests detect injected faults. It is especially useful for exposing weak assertions and green suites that execute code without proving behavior.
+
+Representative tools include PIT (JVM), Stryker (JavaScript/.NET and others), mutmut/cosmic-ray (Python), and language-specific equivalents.
+
+### Property-based testing
+Property-based testing (e.g. QuickCheck-family approaches) is useful when correctness is expressed more naturally as invariants over broad input spaces than as a few hand-picked examples.
+
+### FIRST-style test qualities
+Fast, isolated/independent, repeatable, self-validating, and timely tests remain useful heuristics, but this skill adds a stronger emphasis on fault sensitivity and delivery risk.
+
+### Testing Trophy / modern test portfolio practice
+The right test level depends on the behavior. Do not maximize unit-test count at the expense of realistic boundary confidence.
+
+### Regression testing from escaped defects
+Production bugs should become durable regression protections whenever a stable, meaningful automated check can be created.
+
+## Concepts deliberately rejected as primary quality measures
+- raw test count,
+- 100% line coverage,
+- permanently green CI,
+- high mock verification density,
+- snapshot volume,
+- number of assertions.
+
+These metrics can be inputs, but none proves that a suite detects meaningful regressions.
+
+## Central quality thesis
+A trustworthy suite must demonstrate **sensitivity to wrong behavior**. The strongest practical evidence is a combination of:
+- well-chosen behavior assertions,
+- negative and boundary tests,
+- bug reproductions,
+- representative fault injection or mutation testing,
+- low flakiness,
+- resilience to behavior-preserving refactors.

package/plugins/sp/skills/taste-refactoring-tests/references/test-refactoring-playbook.md

@@ -0,0 +1,222 @@
+# Test Refactoring Playbook
+
+## 1. What “good” means
+A unit test is valuable when it has four properties:
+
+1. **Regression sensitivity** — plausible defects cause it to fail.
+2. **Behavior relevance** — the failure corresponds to behavior that matters.
+3. **Diagnostic clarity** — the failure tells engineers what contract broke.
+4. **Maintenance efficiency** — harmless internal refactors do not constantly break it.
+
+A useful mental model is:
+
+`Test Value ≈ (Risk Protected × Fault Sensitivity × Diagnostic Value) / (Maintenance Cost + Flakiness + Runtime Cost)`
+
+This is a reasoning aid, not a numeric scoring formula.
+
+## 2. The Always-Pass illusion
+A suite can stay green while quality degrades when tests:
+- execute code without proving outcomes,
+- assert only happy paths,
+- configure mocks to guarantee the expected answer,
+- duplicate the implementation in expectations,
+- test framework behavior instead of domain behavior,
+- ignore negative effects,
+- swallow exceptions,
+- are skipped or quarantined indefinitely,
+- use snapshots nobody reviews,
+- optimize for coverage rather than defect detection.
+
+The antidote is to ask: **what plausible bug would this test catch?**
+
+If the answer is unclear, the test is a refactoring candidate.
+
+## 3. Start from risks, not files
+Map tests to risks such as:
+- authorization bypass,
+- incorrect financial calculation,
+- invalid state transition,
+- duplicate processing,
+- stale or corrupt persistence,
+- wrong serialization,
+- input validation gaps,
+- rounding/time-zone boundaries,
+- unexpected side effects,
+- historical production defects.
+
+Review the highest-risk areas first.
+
+## 4. Weak assertion patterns
+
+### “Does not throw” only
+Sometimes valid for idempotent/no-op behavior, but usually incomplete. Add the expected resulting state or side effect.
+
+### `not null`
+Often proves only allocation. Assert the semantic value.
+
+### `isTrue`
+Can hide what actually matters. Prefer domain-specific assertions.
+
+### count only
+`count == 1` may still accept the wrong item. Assert identity/content when relevant.
+
+### status only
+For protocol-facing units, status without body/error semantics may miss serious regressions.
+
+### mock call only
+A collaborator being called is rarely the user-visible outcome. Assert state/result unless the interaction itself is contractual.
+
+## 5. Mutation mindset
+Mutation testing asks whether tests detect small deliberate faults.
+
+Representative mutants:
+- `>` to `>=`,
+- true to false,
+- remove branch,
+- remove side effect,
+- return null/default,
+- change constant,
+- skip validation,
+- negate authorization result.
+
+A surviving mutant in critical logic is strong evidence of missing or weak tests.
+
+Do not optimize blindly for a mutation score. Some mutants are equivalent or low-risk. Use survivors to drive judgment.
+
+## 6. Refactoring mock-heavy tests
+
+### Smell
+A test contains more mock setup and `verify` calls than domain assertions.
+
+### Questions
+- Is the unit boundary too large?
+- Are we testing orchestration instead of behavior?
+- Can a fake preserve useful state and enable clearer assertions?
+- Is call order actually contractual?
+
+### Preferred move
+Move pure decision logic into a focused unit, test it directly, and leave wiring/protocol coordination to a smaller number of integration/contract tests.
+
+## 7. Boundary-value coverage
+For ordered numeric/date/count domains, cover equivalence classes around boundaries:
+- just below,
+- exactly at,
+- just above.
+
+For collections:
+- empty,
+- one,
+- many,
+- duplicates where relevant.
+
+For nullable/optional values:
+- absent,
+- present valid,
+- present invalid.
+
+For time:
+- clock control,
+- timezone transitions,
+- expiry boundary,
+- leap/day rollover only when domain-relevant.
+
+## 8. Negative-path testing
+Critical negative tests often provide more confidence than another happy path.
+
+Examples:
+- unauthorized actor is rejected and state is unchanged,
+- invalid input does not persist,
+- failed payment does not fulfill order,
+- duplicate message does not duplicate side effects,
+- timeout maps to retriable error rather than success,
+- missing required field returns a meaningful rejection.
+
+## 9. Property-based testing
+Use when examples are insufficient and invariants are stable.
+
+Candidate properties:
+- serialize then deserialize preserves meaning,
+- normalized output is idempotent,
+- sorting is ordered and permutation-preserving,
+- money allocation preserves total,
+- state transitions never reach illegal states,
+- parser never crashes for arbitrary bytes/strings within a defined domain.
+
+Keep generated counterexamples reproducible by recording seeds or framework-provided replay data.
+
+## 10. Snapshot/golden tests
+Snapshots can help for stable, reviewable structures but become dangerous when:
+- snapshots are huge,
+- updates are rubber-stamped,
+- irrelevant formatting dominates diffs,
+- assertions are replaced entirely by snapshot acceptance.
+
+Prefer targeted semantic assertions for critical fields. Keep snapshots small and intentional.
+
+## 11. Test fixtures
+A fixture should reduce noise, not hide causality.
+
+Good fixture design:
+- safe defaults,
+- test overrides important values explicitly,
+- minimal global state,
+- readable builders,
+- no hidden network/database work,
+- deterministic identifiers and clocks where useful.
+
+Avoid “mystery guests”: fixtures whose invisible defaults determine the outcome.
+
+## 12. Flaky tests
+Investigate categories:
+- clock/time dependence,
+- randomness,
+- race/synchronization,
+- leaked shared state,
+- test ordering,
+- environment/locale,
+- external I/O,
+- resource exhaustion,
+- eventual consistency.
+
+A retry can hide the symptom while preserving the defect. Track root cause.
+
+## 13. When unit tests are the wrong level
+Move confidence upward when behavior depends essentially on:
+- database transaction semantics,
+- serialization framework configuration,
+- network protocol details,
+- schema compatibility,
+- distributed coordination,
+- real dependency behavior.
+
+Keep unit tests for decision logic and local invariants; add integration/contract tests for the real boundary.
+
+## 14. Bug-driven strengthening
+For every escaped defect:
+1. Write the smallest reproducer.
+2. Prove it fails before the fix.
+3. Fix production code.
+4. Prove it passes.
+5. Check whether the defect reveals a wider missing property.
+6. Add the smallest additional protection needed.
+
+## 15. Test deletion safety
+Before deleting a test, answer:
+- What unique behavior does it protect?
+- Is another test stronger and equivalent?
+- Is the behavior obsolete?
+- Does the test encode a bug regression?
+- Is there hidden setup that exercises a real side effect?
+
+Delete only when protection is absent, duplicated, or obsolete.
+
+## 16. Review economics
+Prioritize test work by:
+- business impact of failure,
+- likelihood of change,
+- code complexity,
+- historical defects,
+- ease of fault detection elsewhere,
+- test maintenance cost.
+
+Do not spend a day perfecting trivial tests while critical rules remain weakly protected.

package/plugins/sp/skills/taste-refactoring-ui/README.md

@@ -0,0 +1,12 @@
+# taste-refactoring-ui
+
+A reusable agent skill distilled from the uploaded *Refactoring UI* PDF for day-to-day product UI design and refactoring.
+
+## Files
+- `SKILL.md` — primary agent instructions and workflow.
+- `references/refactoring-ui-playbook.md` — chapter-by-chapter operational reference.
+- `checklists/daily-ui-review.md` — short daily design QA checklist.
+- `examples/review-template.md` — reusable critique/output template.
+
+## Suggested usage
+Attach or install this directory as an agent skill and invoke `taste-refactoring-ui` whenever designing, reviewing, or refactoring UI. For screenshot critiques, provide the screenshot. For code refactors, provide the relevant component(s) and existing design-system constraints.

package/plugins/sp/skills/taste-refactoring-ui/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: taste-refactoring-ui
+description: Design, review, and refactor UI hierarchy, layout, typography, spacing, color, and interactions.
+---
+
+# taste-refactoring-ui
+
+## Purpose
+
+Act as a product UI design critic and refactoring partner. Improve interfaces by making the important thing obvious, reducing arbitrary design decisions, and turning visual taste into repeatable systems.
+
+Use this skill when the user asks to:
+- design or redesign a screen, flow, component, dashboard, landing page, or application UI;
+- critique a screenshot, mockup, or frontend implementation;
+- make UI feel cleaner, more polished, more premium, more professional, or more coherent;
+- establish or refine spacing, sizing, type, color, radius, or shadow tokens;
+- fix visual hierarchy, density, readability, color contrast, or component inconsistency;
+- perform a final “taste” pass before shipping.
+
+This skill is intentionally practical. Prefer concrete changes over abstract design commentary.
+
+## Core operating principles
+
+1. **Start from the feature, not the shell.** Understand the primary user task and the minimum controls/content needed for that task before deciding navigation, sidebars, page chrome, or decorative structure.
+2. **Delay detail until structure works.** Solve composition, grouping, hierarchy, spacing, and content order before spending time on color, icons, shadows, or fine styling.
+3. **Design the smallest useful thing.** Do not invent future functionality or over-design edge cases before the working feature demands them.
+4. **Choose a personality deliberately.** Typography, color, radius, imagery, and language should express a coherent character instead of being individually “nice.”
+5. **Constrain choices.** Prefer a small design system over one-off values. Reuse scales and tokens so each decision is made once.
+6. **Hierarchy before decoration.** Make primary, secondary, and tertiary content visibly different. When everything asks for attention, nothing wins.
+7. **Use spacing as structure.** Group related things by proximity and separate unrelated things clearly. Avoid ambiguous gaps.
+8. **Typography is interface architecture.** Use a restrained type scale, readable line lengths, appropriate line-height, sensible alignment, and purposeful weight/contrast.
+9. **Color is a system, not a picker.** Define usable shade ramps, semantic roles, and contrast behavior. Never rely on color alone to carry meaning.
+10. **Depth should communicate structure.** Shadows, borders, overlap, and highlights should explain elevation or grouping rather than decorate indiscriminately.
+11. **Images need intentional treatment.** Preserve legibility, use imagery at suitable sizes, and defend layouts against unpredictable user-uploaded content.
+12. **Finish with restraint.** Improve defaults, empty states, backgrounds, accents, and borders only after the fundamentals are solid.
+
+## Default workflow
+
+### 1. Frame the job
+
+Before touching styling, identify:
+- the screen’s primary user goal;
+- the most important action or information;
+- the secondary actions/information;
+- the actual content and states that must exist now;
+- the constraints already present in the product or codebase.
+
+If the user provides code or an existing design system, preserve its useful primitives unless they are the source of inconsistency.
+
+### 2. Build or audit in passes
+
+Always review in this order unless the user asks for a narrower scope:
+
+**Pass A — Function and content**
+- Is the feature itself clear?
+- Is anything present that does not help the current task?
+- Are “nice-to-have” controls or future features distracting from the shippable core?
+- Can the interface be understood without decorative styling?
+
+**Pass B — Hierarchy**
+- Rank every visible element as primary, secondary, tertiary, or structural.
+- Strengthen the top priority before adding more visual effects.
+- Prefer de-emphasizing competitors over endlessly emphasizing the primary item.
+- Use size, weight, contrast, placement, and spacing together; do not use font size alone.
+
+**Pass C — Layout and spacing**
+- Start slightly more spacious than feels necessary, then tighten deliberately.
+- Group related elements with smaller internal gaps and larger external gaps.
+- Avoid filling available width merely because it exists.
+- Let different regions use the width that best serves their content; do not force every region onto the same grid.
+- Use explicit spacing/sizing values from a scale rather than arbitrary percentages or tiny one-off adjustments.
+
+**Pass D — Typography**
+- Use a restrictive type scale.
+- Use a neutral, legible UI face for dense interface text unless personality requires otherwise.
+- Keep paragraphs and long-form text to a comfortable line length; do not stretch them across wide containers.
+- Align text to baselines when mixed with icons or adjacent labels instead of visually centering everything.
+- Use more line-height for smaller text and less for larger display text.
+- Do not color every link by default; rely on context and interaction cues where appropriate.
+- Prefer left alignment for most reading-heavy text; center only short, self-contained blocks.
+- Tighten letter spacing for large headlines only when the typeface benefits from it.
+
+**Pass E — Color**
+- Think in hue/saturation/lightness relationships rather than isolated hex values.
+- Define a useful family of shades before improvising new ones.
+- Keep saturated colors lively across light/dark variants; do not change only lightness if it makes shades muddy.
+- Tint neutrals slightly when it supports the design personality.
+- Verify accessible contrast, but solve contrast with hierarchy and color construction rather than making every element maximal contrast.
+- Pair color with text, iconography, shape, or position for status and meaning.
+
+**Pass F — Depth and surfaces**
+- Assume a consistent light source.
+- Use highlights on top-facing edges and shadows beneath elements only when they help communicate form.
+- Map shadow size/blur to elevation: tight/subtle for low elevation, broader/softer for higher elevation.
+- When useful, combine a small sharp shadow with a larger soft shadow to simulate contact plus ambient shadow.
+- Use overlap to create layering when it clarifies relationships.
+- Do not chase photorealism; depth should remain quiet and functional.
+
+**Pass G — Images and media**
+- Prefer strong source imagery over trying to rescue weak imagery with effects.
+- Ensure text over images has stable contrast using overlays, lowered image contrast, controlled colorization, or a subtle text glow/shadow where appropriate.
+- Do not enlarge small icons merely because vectors allow it; use artwork designed for the intended size or place small icons inside a larger supporting shape.
+- Do not shrink detailed screenshots until text becomes illegible; crop, use a smaller-layout capture, or simplify the screenshot.
+- Put user-uploaded images inside predictable frames, crop safely, and avoid depending on unknown image colors for text readability.
+
+**Pass H — Finishing touches**
+- Upgrade browser/default-looking controls only when it improves cohesion.
+- Use accent borders sparingly to inject color without overwhelming the surface.
+- Use subtle background decoration to support personality or section separation.
+- Design empty states as real product states, not blank leftovers.
+- Remove unnecessary borders; prefer spacing, background shifts, and shadows when they communicate structure better.
+- Break out of repetitive card grids when a different composition better serves the content.
+
+### 3. Systematize the decisions
+
+Whenever a UI decision repeats, turn it into a token, component rule, or documented pattern.
+
+At minimum, look for systems covering:
+- font sizes;
+- font weights;
+- line heights;
+- text colors;
+- brand and semantic color shades;
+- spacing and padding;
+- widths and heights;
+- border radius;
+- border widths;
+- shadows/elevation;
+- opacity;
+- icon sizes.
+
+A useful scale has perceptible jumps. Avoid scales where adjacent large values differ so little that they create fake precision.
+
+When choosing among tokens, compare neighboring options instead of micro-tuning. Pick a plausible value, compare one step smaller and one step larger, eliminate obvious misses, and repeat only when necessary.
+
+## Practical heuristics
+
+### Hierarchy
+- Aim for roughly three text-emphasis levels: strong primary, quieter secondary, very quiet tertiary.
+- Two primary text weights are usually enough: normal/medium for body content and semibold/bold for emphasis.
+- Avoid weights below 400 for small UI text unless the typeface is specifically designed for it.
+- On colored surfaces, do not simply switch secondary text to generic grey or low-opacity white. Choose a lower-contrast color related to the surface so it stays intentional rather than washed out.
+- Labels should not dominate values. Remove obvious labels, combine label + value into natural language, or de-emphasize labels when the value is what users scan for.
+- In specification-heavy interfaces where users scan for the field name, labels may deserve more emphasis than values.
+
+### Spacing
+- Prefer a non-linear spacing scale with small, meaningful jumps at the low end and larger jumps at the high end.
+- Internal spacing should be smaller than spacing between groups.
+- If a form label could visually belong to two fields, the vertical rhythm is wrong.
+- Dense interfaces are allowed, but density should be an explicit product decision rather than the default consequence of insufficient spacing.
+
+### Sizing and width
+- Avoid percentage-based sizing for elements whose content needs stable visual emphasis.
+- Do not make everything fluid simply because the viewport is fluid.
+- Cap text and content regions where readability benefits from a narrower measure.
+- Let sidebars, cards, forms, and content columns use independent widths when the content justifies it.
+
+### Personality
+Use a small set of coordinated decisions:
+- **formal/serious:** restrained color, squarer corners, conservative typography, direct language;
+- **neutral/productive:** neutral sans serif, moderate radius, practical color system, concise language;
+- **friendly/playful:** warmer/brighter color, rounder forms, softer shapes, friendlier copy;
+- **premium/elegant:** disciplined whitespace, restrained palette, refined type pairing, deliberate imagery.
+
+Do not mimic a direct competitor so closely that the product loses its own identity.
+
+## Refactoring protocol for existing UI
+
+When reviewing an existing screen, return findings in priority order rather than by visual location.
+
+Use this severity model:
+- **P0 — Task failure:** user cannot understand, complete, or trust the primary task.
+- **P1 — Hierarchy/structure:** the right content exists but attention, grouping, or order is wrong.
+- **P2 — System inconsistency:** arbitrary spacing, typography, color, radius, or shadow values undermine cohesion.
+- **P3 — Polish:** image treatment, micro-alignment, accents, empty states, background details, etc.
+
+For every issue, provide:
+1. **Observation** — what is visibly wrong.
+2. **Why it matters** — effect on comprehension, hierarchy, readability, or perceived quality.
+3. **Refactor** — precise change to make.
+4. **System rule** — reusable token/component rule if the issue can recur.
+
+Do not merely say “add whitespace,” “improve hierarchy,” or “make it cleaner.” Specify where and how.
+
+## Implementation mode
+
+When the user asks for code changes:
+- infer the existing design system before inventing a new one;
+- preserve component semantics and accessibility;
+- consolidate repeated magic numbers into tokens/constants/classes;
+- prefer a small coherent token set over exact reproduction of scattered values;
+- keep responsive behavior intentional rather than universally fluid;
+- implement states: default, hover/focus, active/selected, disabled, empty, loading, error, and overflow where relevant;
+- protect media containers from extreme aspect ratios and unknown user content;
+- remove redundant borders and shadows before adding new decoration.
+
+When code is provided, explain only the design decisions that materially affect the result. Deliver working edits, not a lecture.
+
+## Screenshot / mockup critique mode
+
+When an image is provided, inspect in this sequence:
+1. What do the eyes land on first?
+2. Is that the intended primary thing?
+3. Which items compete unnecessarily?
+4. Are related items visually grouped?
+5. Are gaps unambiguous?
+6. Is text readable and appropriately ranked?
+7. Are colors systematic and accessible?
+8. Are borders/shadows doing useful structural work?
+9. Are images helping or harming clarity?
+10. What can be removed?
+
+Return the smallest set of high-leverage changes first. If useful, describe a “before → after” layout in concrete terms.
+
+## New-screen design mode
+
+When designing from scratch:
+1. Define the feature in one sentence.
+2. List the minimum content and controls.
+3. Sketch the content order in plain text.
+4. Establish hierarchy in grayscale.
+5. Apply spacing and sizing tokens.
+6. Apply typography tokens.
+7. Add color system and states.
+8. Add depth/images only where they support the design.
+9. Add finishing touches.
+10. Test edge cases only after the core version is coherent and shippable.
+
+## Output contract
+
+Unless the user requests another format, answer with:
+
+### Diagnosis
+A concise statement of the main design problem and the intended visual direction.
+
+### Highest-impact changes
+A prioritized set of concrete refactors, usually 3–8 items.
+
+### System decisions
+Tokens/rules that should become reusable.
+
+### Implementation notes
+Exact component/layout/styling guidance or code-oriented instructions.
+
+### Final quality gate
+A short pass/fail checklist for hierarchy, spacing, typography, color, states, and polish.
+
+## Quality gate
+
+Before finalizing any UI recommendation, confirm:
+- [ ] The primary task is obvious.
+- [ ] The primary action/information wins the hierarchy.
+- [ ] Secondary and tertiary content are visibly quieter.
+- [ ] Related elements are grouped by spacing.
+- [ ] No major width exists only to “fill the screen.”
+- [ ] Typography uses a deliberate scale and readable line length.
+- [ ] Text weight, size, and contrast work together.
+- [ ] Colors come from a coherent shade/semantic system.
+- [ ] Meaning is never communicated by color alone.
+- [ ] Borders, shadows, and radii are consistent and purposeful.
+- [ ] Images/media preserve legibility and intended scale.
+- [ ] Empty/loading/error/disabled/overflow states are considered.
+- [ ] Repeated choices have been converted into reusable rules or tokens.
+- [ ] Decorative polish has not been used to hide structural problems.
+
+## Anti-patterns to reject
+
+- Starting with navigation or application chrome before understanding the feature.
+- Designing every feature and edge case before implementation teaches you anything.
+- Solving hierarchy only by making titles huge and support text tiny.
+- Giving every data point a same-weight `label: value` presentation.
+- Using arbitrary pixel values for every component.
+- Using a purely linear spacing scale that encourages meaningless micro-differences.
+- Stretching text and forms to fill the viewport.
+- Making all layout regions obey one rigid grid when their content has different needs.
+- Using generic grey or transparent white text on colored backgrounds.
+- Picking colors one at a time without shade/semantic relationships.
+- Using color as the sole signal for status.
+- Using shadows everywhere because they “look premium.”
+- Scaling icons/screenshots far beyond their intended visual size.
+- Letting unpredictable user images control text contrast.
+- Wrapping every section in a bordered card.
+- Treating empty states as blank space.
+
+## Reference files
+
+For deeper reasoning and daily use, read:
+- `references/refactoring-ui-playbook.md` — chapter-by-chapter distilled guidance.
+- `checklists/daily-ui-review.md` — fast audit and ship checklist.
+- `examples/review-template.md` — reusable UI critique response structure.

package/plugins/sp/skills/taste-refactoring-ui/checklists/daily-ui-review.md

@@ -0,0 +1,72 @@
+# Daily UI Review Checklist
+
+Use this in 5–10 minutes before shipping or requesting review.
+
+## 1. Task clarity
+- [ ] Can a first-time user tell what this screen is for in a few seconds?
+- [ ] Is the primary action or primary information obvious?
+- [ ] Did we include only functionality we can actually support now?
+
+## 2. Hierarchy
+- [ ] Is there one clear visual entry point?
+- [ ] Are secondary and tertiary elements quieter?
+- [ ] Are we using weight/contrast/spacing, not just font size?
+- [ ] Could any label be removed or merged into the value?
+- [ ] If something important is weak, can competitors be de-emphasized instead?
+
+## 3. Spacing and layout
+- [ ] Do closer elements belong together?
+- [ ] Are group-to-group gaps visibly larger than internal gaps?
+- [ ] Are any gaps ambiguous?
+- [ ] Are we filling width without a content reason?
+- [ ] Does each region use an appropriate width instead of one forced grid?
+- [ ] Are values drawn from a spacing/sizing scale?
+
+## 4. Typography
+- [ ] Are type sizes drawn from a small scale?
+- [ ] Is body/UI text comfortably legible?
+- [ ] Is line length controlled?
+- [ ] Does line-height fit the text size?
+- [ ] Are icons/text aligned optically or by baseline where appropriate?
+- [ ] Are colored links used only when they need emphasis?
+- [ ] Is centered text limited to short blocks?
+
+## 5. Color
+- [ ] Do colors belong to defined shade ramps?
+- [ ] Are neutral colors coherent with the product personality?
+- [ ] Is contrast sufficient for reading and controls?
+- [ ] Is secondary text on colored surfaces intentionally color-matched rather than generic grey/opacity?
+- [ ] Is any status communicated by color alone?
+
+## 6. Depth and surfaces
+- [ ] Do shadows imply a consistent elevation model?
+- [ ] Are borders necessary?
+- [ ] Could spacing or surface color replace some borders?
+- [ ] Are radii consistent with the personality?
+- [ ] Is overlap used only when it improves the composition?
+
+## 7. Images
+- [ ] Are source images high enough quality?
+- [ ] Is text readable over every likely image?
+- [ ] Are icons shown near their intended visual size?
+- [ ] Are screenshots readable without squinting?
+- [ ] Are user uploads safely cropped and constrained?
+
+## 8. States
+- [ ] Empty
+- [ ] Loading
+- [ ] Error
+- [ ] Disabled
+- [ ] Hover/focus/active
+- [ ] Overflow / long text / large numbers
+- [ ] Small and large viewport behavior
+
+## 9. Polish
+- [ ] Do empty states help the user act?
+- [ ] Are accents/background decorations subordinate to content?
+- [ ] Is the UI over-carded or over-bordered?
+- [ ] Are repeated values converted to tokens/components?
+- [ ] Did we solve structural problems before adding decoration?
+
+## Final test
+Hide the brand color and decorative imagery mentally. If the screen still has strong hierarchy, clear grouping, readable typography, and coherent actions, the foundation is good.