ss-review

UI Design Review

Registry-first artifact boundary

When .styleseed/project.json and .styleseed/artifacts/index.json exist, resolve the requested artifact ID first, then read only .styleseed/bundles/<artifact-id>.md and .styleseed/manifests/<artifact-id>.json. Never fall back to the global legacy bundle for a registry project. Legacy projects may use .styleseed/effective-rules.md only when no registry exists.

If either registry file exists, require both files and valid artifact configuration. Use only the selected artifact's bundle and manifest; an incomplete registry is not a legacy project. Only when neither registry file exists, read .styleseed/effective-rules.md and .styleseed/manifest.json. If the selected bundle is missing or stale, report the missing evidence; do not regenerate it during a review-only request or claim verified compliance. Review task fitness and grammar coherence before framework conventions. For non-web artifacts, replace React/Tailwind-only checks with the active adapter's render/export checks.

Review scope

Review and recommend; do not edit implementation or project configuration. A request to fix findings authorizes a separate implementation step with the appropriate editing tools, not an expansion of this read-only skill. Honor a narrower user request. Cite the selected contract for each violation; distinguish core failures, contract drift, optional suggestions, and missing evidence. Library conventions below apply only when the project uses those conventions.

When NOT to use

• For accessibility-only issues → use /ss-a11y
• For Nielsen UX heuristics → use /ss-audit
• For a quick automated check → use /ss-lint
• For non-UI code (data fetching, business rules)

Review the file: $ARGUMENTS

Checklist

1. Design Token and Recipe Compliance

• [ ] No hardcoded hex colors (use semantic tokens: text-foreground, bg-brand, etc.)
• [ ] No hardcoded px spacing in Tailwind (use p-6 not p-[24px])
• [ ] Pattern geometry/elevation uses the selected recipe or explicit semantic variables
• [ ] No hardcoded universal rounded-2xl + shadow + mx-6 language across unrelated recipes

2. Component Conventions

• [ ] Uses data-slot attribute
• [ ] Uses cn() for className merging
• [ ] Props typed with React.ComponentProps<>
• [ ] Supports className prop override
• [ ] Named export (not default export for components)
• [ ] No wrapper components that only add a className

3. Accessibility (a11y)

• [ ] Touch targets >= 44x44px on touch surfaces; pointer-first desktop controls may be

36–40px when the adapter and approved component contract support them

• [ ] focus-visible styles on all interactive elements
• [ ] Proper aria-* attributes where needed
• [ ] Color contrast meets WCAG AA (4.5:1 for text, 3:1 for large text)
• [ ] Animations respect prefers-reduced-motion
• [ ] Images have alt text
• [ ] Form inputs have associated labels

4. Surface Best Practices

• [ ] No horizontal overflow
• [ ] Touch-friendly spacing between interactive elements
• [ ] Mobile safe area insets handled when the adapter requires them
• [ ] Desktop density/type and non-web canvas/export rules follow the selected adapter
• [ ] Text remains readable at the adapter's viewing distance and supported zoom
• [ ] Scrollable containers have -webkit-overflow-scrolling: touch

5. Performance

• [ ] No unnecessary re-renders (stable references, memoization where needed)
• [ ] Images are lazy-loaded
• [ ] Heavy components are code-split

6. Typography

• [ ] Uses the locked type family and recipe-fit type roles
• [ ] Size, weight, leading, and tracking follow the compiled type roles and approved tokens
• [ ] Display, heading, body, and caption roles remain distinct at the target surface size
• [ ] Language, script, wrapping, and zoom do not cause clipping or impair reading
• [ ] Handbook type examples are defaults, not grounds to replace an approved type scale

7. Spacing Consistency

• [ ] Spacing uses one maintained token scale and the selected recipe's major rhythm
• [ ] Off-scale values have an optical, canvas, or platform reason
• [ ] Uses size-* shorthand instead of w-* h-*
• [ ] Uses ms-*/me-* instead of ml-*/mr-* (logical properties)
• [ ] Motion transitions use design tokens (duration-[var(--duration-fast)])

8. Coherence (VISUAL-CRAFT.md §C0 — the "one choice per axis" laws)

The biggest reason a UI reads as "AI-generated" isn't ugly parts — it's mixed parts. Check for one deliberate system of roles, not identical values on every component.

• [ ] Recipe-bound radius scale — surfaces, controls, compact choices, and nested elements

follow their approved roles. For example, calm-consumer permits 12–20px outer surfaces and pill controls for true compact choices. Flag unexplained drift, not that valid pairing.

• [ ] One identifiable primary action plus only the selected grammar's stable semantic,

categorical, or brand roles — no competing decorative emphasis hues.

• [ ] No emoji as UI icons (🚗🧺⭐ as list/nav/status/category markers) — they inject many uncontrolled hues; use one line-icon set in currentColor.
• [ ] Status and category colors have stable roles under the selected grammar and palette;

severity remains distinguishable, and a normal state does not compete with urgent states

• [ ] No uncontracted decorative hues — additional colors need a documented semantic,

categorical, editorial, or brand role

• [ ] One shadow language — same light direction, same scale/tint; not some black + some tinted, some up-lit + some down-lit.
• [ ] One icon family / fill mode / stroke weight across the file.
• [ ] Nested contours — use the recipe's nested-radius relationship; for concentric rounded

rectangles, max(0, outer − padding) is a useful default, not a rule for every shape

• [ ] Consistent control heights — buttons, inputs, selects share a height set (e.g. 40px).
• [ ] Errors/states never rely on color alone (icon + text too).

Output Format

Provide:

1. Score: Pass / Needs Improvement / Fail
2. Issues: List each violation with file:line reference
3. Fixes: Concrete code changes for each issue