ui-craft

# UI Craft

Create an intentional interface, not merely valid frontend code. Make the page fit its product, help the user act, and hold up under real browser inspection.

## Establish the design brief

Before editing, identify:

- the user and the situation in which they reach this interface;
- the primary job, decision, or action the interface must support;
- the information that must be noticed first, second, and later;
- the dominant behavior: scan, operate, enter, compare, learn, or explore;
- the important default, loading, empty, error, success, disabled, and permission states;
- the target viewports, input methods, accessibility needs, and engineering constraints.

Ask a small number of focused questions only when a missing answer would materially change the result. Otherwise proceed with conservative assumptions and preserve the user's scope.

## Read the existing visual language

Inspect the rendered page and the source that actually defines it. Read relevant:

- routes and page composition;
- layout shells and navigation;
- theme, token, and global style files;
- nearby components and their variants;
- typography, icons, imagery, and other assets;
- copy conventions and product terminology;
- responsive rules and existing breakpoints.

Treat the repository as the source of truth. Reuse its components and tokens before adding new ones. Do not introduce a parallel palette, spacing scale, radius family, shadow language, or component pattern for one screen.

Preserve the established product language unless the request explicitly calls for a redesign. If the current interface is inconsistent, improve the requested surface without casually rewriting unrelated global styles.

## Choose the composition before decoration

Let the dominant user behavior determine the page structure:

- For scanning or monitoring, favor density, stable alignment, glanceable status, and clear exceptions.
- For operating or managing, favor selection state, nearby actions, feedback, and efficient repeated work.
- For entering or configuring, favor grouping, progressive disclosure, validation, and a clear completion path.
- For comparing, align equivalent information and make differences easy to inspect.
- For learning or deciding, build a paced narrative with one clear idea or action at a time.
- For exploring, make search, filters, results, preview, and wayfinding the primary composition.

Do not give every product surface a marketing hero. Do not default to a centered heading followed by three equal cards. Choose what should dominate, what should support it, and what should recede.

Form a one-sentence visual thesis before implementation. State the intended hierarchy, density, and tone, for example: “A compact operational surface where exceptions lead, controls stay close to data, and color is reserved for state.” Use the thesis to reject choices that do not belong.

## Build a coherent visual system

Use a small number of deliberate decisions consistently.

When no established system exists, define the smallest useful set of local tokens for color, type, spacing, shape, and depth before styling individual components. Keep the system proportional to the deliverable.

### Hierarchy and layout

- Establish hierarchy with scale, position, spacing, alignment, weight, and contrast before adding containers.
- Use whitespace to group and separate information, not simply to make the page airy.
- Align related content to a shared grid.
- Vary emphasis according to importance; avoid making every section, card, and action equally loud.
- Keep the primary action easy to find without turning every control into a primary button.
- Prefer content-driven dimensions over fragile fixed heights and viewport assumptions.

### Typography

- Reuse the product type system when one exists.
- Choose a compact type scale with clear roles for display, heading, body, label, metadata, and numeric content.
- Use weight and size intentionally; do not rely on low-contrast gray text for the entire hierarchy.
- Keep line length, line height, wrapping, and truncation readable at each viewport.
- Use monospace only for content that benefits from it.

### Color, shape, and depth

- Reuse semantic color tokens and verify important text and controls have sufficient contrast.
- Reserve saturated color for meaning, focus, or a small number of high-value accents.
- Use borders, surfaces, shadows, and elevation as one system; do not mix unrelated treatments.
- Keep radii consistent with the product and appropriate to component size.
- Avoid wrapping every group in a rounded card when spacing or a divider would communicate structure better.

### Imagery, icons, and motion

- Use supplied assets and the existing icon system when available.
- Add icons only when they improve recognition or scanning; do not use decorative icon badges as filler.
- Use motion to explain continuity, state change, or feedback.
- Keep motion brief and interruptible, and respect `prefers-reduced-motion`.
- Do not invent elaborate illustrations, fake screenshots, or stock imagery to fill an unresolved composition.

## Keep content honest

Use real provided content or realistic structure that does not invent product claims.

- Do not add fake metrics, testimonials, customers, integrations, or strategic claims.
- Do not add generic feature sections merely to fill space.
- Use specific labels and actions instead of vague words such as “Optimize,” “Insights,” or “Transform.”
- Preserve domain terminology from the product.
- Mark unavoidable placeholder copy clearly when it could be mistaken for final content.

## Implement the real interface

- Work in the repository's actual framework, component architecture, package manager, and styling approach.
- Implement the requested deliverable in runnable form. In an existing product, modify the actual route or component; create a standalone artifact only when the user requests one.
- Keep semantics meaningful and controls keyboard-acce