Frontend UI Standards

Frontend UI Standards

Purpose

Use this skill to turn UI work into systematic frontend implementation. The goal is not pixel tweaking. The goal is to preserve a design system in code so future changes stay predictable, reusable, and visually consistent.

This skill is framework-agnostic. Translate the rules to the local stack:

• SwiftUI: design tokens as enums/static constants, reusable Views, semantic metrics.
• React/Web: CSS variables, design-token modules, component props/variants.
• React Native/Flutter: theme objects, shared components, semantic dimensions.

When To Use

Use this skill before touching UI when the task involves:

• Building or changing a visible screen, component, layout, or interaction.
• Translating Figma, SVG, screenshots, or visual specs into code.
• Fixing visual bugs: misalignment, truncation, inconsistent spacing, wrong font, wrong button size, unsafe-area issues.
• Creating or changing buttons, cards, chips, tabs, nav bars, sheets, dialogs, lists, progress indicators, input fields, or reading surfaces.
• Reviewing frontend code for production readiness or design consistency.
• Refactoring duplicated UI or scattered hardcoded values.

Do not use it for pure backend, data model, prompt, or infrastructure work unless the change affects user-facing UI.

Core Principle

UI code has three layers:

1. Design tokens: global primitives and semantic values such as color, type, spacing, radius, elevation, safe-area offsets, content width.
2. Component metrics: component-specific structure such as chip height, icon size, internal padding, card header spacing, button variants.
3. Screen layout metrics: page-specific composition such as hero card position, section gaps, repeated row alignment, decorative asset placement.

View code should describe structure and state. It should not hide raw design math in the body.

Implementation Workflow

1. Inspect Existing Patterns

   • Search for the closest existing component and screen before adding new UI.
   • Identify the local design token files, theme files, component libraries, and layout helpers.
   • Check if the same visual element already appears elsewhere.

2. Classify Every Visual Value

   • Global and reusable: put it in design tokens.
   • Component-specific: put it in a component metrics object/enum.
   • Screen-specific but repeated within that screen: put it in screen layout metrics.
   • One-off decorative positioning: keep it isolated in named screen metrics, not inline in the view body.

3. Build From Reuse

   • Prefer extending an existing component variant over creating a new component.
   • If two places use the same visual role, they should share the same component or metrics.
   • If a new component repeats soon after, extract it immediately.

4. Encode Layout Relationships

   • Prefer derived values over duplicated numbers.
   • Example: authorChipWidth = rowWidth - sourceChipWidth - rowGap, not three unrelated widths.
   • Align related elements by sharing a container, grid, layout guide, or named metric.
   • Do not fix alignment by locally nudging one element unless the offset is a named decorative exception.

5. Verify Similar Surfaces

   • After fixing one button/card/header, search for the same label, component, asset, or pattern.
   • Update the shared component when possible.
   • If a one-off remains, document why through a clear metric name or short comment.

6. Build And Visually Sanity Check

   • Run the relevant build/typecheck.
   • For mobile UI, install or run in simulator/device when the user is actively validating visuals.
   • Check truncation, safe areas, touch targets, dynamic text risk, and navigation/back behavior.

Token And Metrics Rules

Prefer semantic names over visual coordinates:

• Good: primaryActionWidth, screenHorizontalInset, cardVerticalSpacing, metadataRowWidth, sourceChipWidth.
• Bad: width: 271, padding(.leading, 12), offset(y: 37) repeated inside view bodies.

Allowed numeric values:

• Numeric values are allowed inside token or metrics definitions.
• Numeric values are allowed for one-off asset geometry if they are grouped in a named metrics section.
• Numeric values are allowed when using a platform API that requires a literal and the value is not part of visual design.

Avoid:

• Scattered raw hex colors.
• Inline font sizes when a type scale exists.
• Inline spacing that should come from a spacing scale.
• Multiple local versions of the same button, chip, top bar, card, or bottom CTA.
• Fixing a shared component issue at only one call site.

Component Reuse Rules

Before creating UI, ask:

• Is this a new visual role or a variant of an existing role?
• Does an existing component already define the interaction, size, shadow, radius, or typography?
• Will this appear on another screen?
• Should this be a component prop/variant instead of a new file?

Create component variants for:

• Same structure, different color or state.
• Same button shape with different text/icon.
• Same card shell with different content.
• Same chip with different label/icon.

Create a new component only when:

• The structure, behavior, or layout role is meaningfully different.
• Extending the old component would make it unclear or fragile.