ralphctl-frontend-ui-engineering

Frontend UI Engineering

Adapted from addyosmani/agent-skills — "Frontend UI Engineering" (MIT). Adapted for ralphctl's harness contract.

Build interfaces that look like a design-aware engineer made them for this product: the project's own design system, every state handled, usable from a keyboard and a screen reader. The specifics differ by stack — a component framework, server-rendered templates, a native toolkit — so learn this project's before writing any UI.

When this applies

• Execute — whenever the task builds or changes something a user sees or operates. When reviewing a UI change, use the self-check below as the lens: a missing state or an inaccessible control is a finding, not a nit.

Discover the UI stack first

Find the component library, the theme or token file (colour, spacing, type, radius), the existing components that already solve part of the task, and how the project tests UI (component tests, accessibility checks, visual or browser tests). Reuse a house component before writing a new one.

Components

• One job per component. A component that fetches, transforms, and renders is three things.
• Composition over configuration. A growing list of layout and variant flags signals a component that should accept children or slots instead.
• Data apart from presentation. A container loads data and decides which state to show; a presentational piece renders what it is given. The presentational piece is then trivial to test.
• The simplest state that works. Local state first; lift it only when siblings share it; a shared context for read-mostly app-wide values; the URL for shareable view state (filters, pagination); the project's server-data layer for remote data; a global store only for complex client state many places share. Use the mechanisms the project already has.

Follow the design system

• Use the project's tokens for colour, spacing, type, and radius — never a raw value off the scale.
• Keep the type hierarchy: heading levels in order, heading styles only on headings.
• Use realistic content when building, not placeholder text — real lengths reveal wrapping and overflow.
• Avoid the generic generated look: a default accent palette on everything, decorative gradients, maximal rounding, uniform oversized padding, stock card grids, stacked shadows. Each one ignores the product's real hierarchy; the project's system already decided these.