| name | better-interface |
| description | Build, improve, and review product interfaces as one system across accessibility, layout, UX writing, typography, color, and UI polish. Use when implementing or auditing web UI, components, screens, flows, forms, responsive behavior, interaction states, design-system details, or when the user asks for better-interface, a holistic UI review, accessibility, layout, copy, type, color, icons, surfaces, or motion polish. Supports targeted, quick, full, and implementation modes. |
Better Interface
Treat the interface as one system. Preserve the product's conventions, load only the domain references the task needs, and prioritize user impact over cosmetic novelty.
Resolve the mode
Infer mode from the request and state the resolved scope when reviewing.
| Mode | Use when | Coverage |
|---|
targeted | One component or one domain is in scope | Load only the owning domain and relevant detailed references |
quick | The user requests a fast holistic review | Inspect the primary path across all six domains; report at most 5 HIGH or MEDIUM findings |
full | The user requests a complete or holistic review | Inspect the requested flow across all six domains and relevant loading, empty, error, narrow-width, keyboard, and appearance states; report at most 15 findings |
implementation | The user asks to build, fix, or improve the interface | Load relevant domains, make the requested changes, and verify them; do not force a review report |
Use full when the user explicitly requests a holistic review without naming a mode. Otherwise infer targeted or implementation from the task. Narrow an unreviewably large scope to the highest-traffic complete flow and disclose the boundary.
Apply the authority order
Resolve conflicts in this order:
- Follow the user's explicit requirements and supported product constraints.
- Meet applicable accessibility, platform, and interoperability requirements.
- Preserve the project's component library, design tokens, styling system, density, and interaction language.
- Apply domain heuristics when evidence supports them.
- Use house-style recipes only when the project has no established answer.
Treat exact aesthetic values in the UI-polish references—animation scale, blur, bounce, radius, shadow, and outline recipes—as starting presets, not universal laws. Requirements may be unconditional; taste must remain contextual. Verify current standards and browser support before making compliance or compatibility claims.
Follow the workflow
- Resolve scope and intent. Identify the screen, flow, component, repository boundary, and whether the user wants review or implementation.
- Recon the project. Identify framework, styling system, component library, tokens, supported viewports and browsers, localization conventions, and relevant preview or test commands.
- Load references. Read every domain overview required by the mode, then read only the detailed files relevant to actual evidence. For a holistic review, read all six overviews.
- Inspect the artifact. Read source for code claims. Inspect the rendered interface for visual or runtime claims. Traverse relevant states and user paths.
- Assign ownership. Report one root cause once under its owning domain; mention secondary effects in the rationale.
- Act within intent. Keep reviews read-only. For implementation requests, make the scoped changes using the project's existing conventions.
- Verify. Run safe, relevant checks and report observed results. Mark unperformed checks
Not verified; never turn a verification gap into a finding.
Route domain knowledge
All reference files are directly reachable from this entry point. Do not load every detailed file by default.
| Domain | Owns | Read |
|---|
| Accessibility | Semantic HTML, keyboard and focus behavior, accessible names, forms, assistive technology, reduced motion, zoom, and accessibility requirements | Start with accessibility.md. Read focus and keyboard, semantics and ARIA, forms, screen readers, hit areas, or motion and zoom when relevant. |
| Layout | Grouping, alignment, spacing, responsive structure, reading order, logical properties, clipping, and spatial RTL behavior | Start with layout.md. Read grouping and alignment or spacing and adaptivity when relevant. |
| Writing | Source wording, terminology, voice, tone, labels, errors, settings, and empty-state copy | Read writing.md. |
| Typography | Visual text rendering, type systems, font behavior, wrapping, punctuation, truncation, and text-level bidi behavior | Start with typography.md. Read choosing fonts, variable fonts and OpenType, spacing and sizing, wrapping and punctuation, details and accessibility, or the CSS cheat sheet when relevant. |
| Colors | Color notation, semantic tokens, palette construction, gamut, appearance variants, rendered-pair contrast measurement, and color remediation | Start with colors.md. Read conversion, palette generation, contrast, gamut and Tailwind, or color usage when relevant. |
|
When concerns cross domains, use this ownership map:
- Accessibility determines whether contrast is required and classifies impact; Colors measures and remediates the rendered pair.
- Accessibility owns semantic heading structure; Typography owns its visual rendering.
- Layout owns logical properties and spatial mirroring; Typography owns language metadata, punctuation, and mixed-direction text.
- Typography owns truncation mechanics; Layout owns available room and expansion affordances; Writing owns source copy.
- Accessibility owns reduced-motion requirements; UI polish owns optional animation recipes.
Require evidence
- Cite
path/to/file:line for source findings. For artifacts without source, cite the exact screen and component.
- Show the current implementation and an actionable replacement.
- Do not infer runtime behavior from source alone when browser behavior decides the result.
- Do not infer a code defect from appearance alone when computed styles, DOM, or state are required.
- Consolidate repeated instances caused by one token or shared component into one finding and list all confirmed locations.
- Prefer shared-component and token fixes over leaf-level patches.
- Do not pad a review to reach its finding cap.
Measure colors deterministically
Use the bundled script rather than estimating conversions, sRGB gamut, or WCAG 2 contrast:
python3 <skill-root>/scripts/color_tools.py convert '#3b82f6'
python3 <skill-root>/scripts/color_tools.py contrast '#111827' '#ffffff'
python3 <skill-root>/scripts/color_tools.py gamut 'oklch(0.7 0.35 150)'
python3 <skill-root>/scripts/color_tools.py clamp 'oklch(0.7 0.35 150)'
Do not invent APCA values. Report APCA only when a deterministic APCA calculator was actually run, and include polarity, font size, and weight context. Use WCAG 2 thresholds for WCAG 2 conformance claims. Preserve the project's established tokens and notation unless color-system migration is explicitly in scope.
Review output
Use this format only for review modes. For implementation mode, summarize changes and verification instead.
Scope and Coverage
State the mode, exact scope, stack, styling conventions, reviewed states, and any boundary. For quick and full, include all six domains:
| Domain | Evidence inspected | Result |
|---|
| Accessibility | Files, components, states, or checks | Findings count, Clear, or Not reviewed with reason |
Findings
Order one consolidated table by severity, then reach and leverage:
| # | Severity | Domain | Location | Before | After | Why |
|---|
| 1 | HIGH | Accessibility | src/Dialog.tsx:42 | <button><XIcon /></button> | Add an accessible name and hide the decorative icon | The icon-only control has no accessible name |
Use the shared severity scale:
HIGH: blocks a task, misleads the user, hides content or controls, creates data-loss risk, or causes a repeated systemic accessibility failure.MEDIUM: meaningfully harms comprehension, efficiency, adaptability, or consistency.LOW: isolated polish with limited task impact; include only in full or targeted mode.
If there are no findings, omit the table and state No actionable interface findings.
Considered but Rejected
Include this section only when real borderline candidates were inspected and deliberately rejected because evidence was insufficient, the project convention was intentional, or the change would add complexity without user benefit. Never invent filler.
Verification
List each exact command or interaction and its observed result. Separate passed checks from Not verified checks.
Verdict
End a review with exactly one:
Block when one or more HIGH findings remain.Needs changes when only MEDIUM or LOW findings remain.Approve when no actionable findings remain and the claimed coverage was verified.
Implementation output
Lead with the completed outcome. Name the important files or components changed, list relevant verification and observed results, and disclose anything still unverified. Do not reproduce the review template unless the user also requested a review.
