Frontend Quality Guardrails

Frontend Quality Guardrails

Core Rule

Treat every UI as hostile to perfect content. Assume labels, names, URLs, IDs, prices, translated strings, user input, errors, table cells, badges, breadcrumbs, tabs, and button text can be longer than the mockup.

Prefer small, local CSS/layout fixes over broad rewrites. Preserve the existing design system, component API, tokens, spacing scale, and framework conventions unless the user asks for a redesign.

When to Use

Use this skill when building, modifying, or reviewing frontend UI where layout quality matters, especially:

• Long text, URLs, IDs, translated strings, form errors, labels, table cells, cards, tabs, breadcrumbs, or badges may overflow.
• The task touches HTML, CSS, React, Vue, Svelte, Next.js, Tailwind, shadcn/ui, Ant Design, forms, tables, dashboards, modals, drawers, navigation, or responsive layouts.
• The user asks to polish UI, fix overflow, improve alignment, review frontend code, validate browser screenshots, or avoid frontend style pitfalls.

Do not use

Do not use this skill as the primary guide for:

• Backend-only, CLI-only, database-only, or infrastructure tasks with no visible UI.
• Full brand identity creation, illustration, logo design, or image generation.
• Pixel-perfect implementation from a provided screenshot when a dedicated image-to-code or design reproduction skill is available.
• Accessibility audits that require formal WCAG scoring beyond implementation-level guardrails.

Instructions

Apply the workflow below as a guardrail layer on top of the project's existing frontend conventions. For simple changes, use the core checklist only. For deeper work, load the relevant reference file from the Deep References section.

Workflow

1. Inspect the existing UI conventions before editing:

• Identify the framework, styling system, component library, breakpoints, typography scale, spacing tokens, and icon library.
• Reuse existing components and utility classes.
• Do not introduce a new design system for a localized fix.

2. Identify text risk surfaces:

• User names, organization names, file names, paths, slugs, UUIDs, hashes, tokens, URLs, emails, phone numbers.
• Headings, card titles, table cells, nav items, tabs, breadcrumbs, filters, chips, badges, tooltips, toasts, dialogs.
• Form labels, placeholders, help text, validation errors, empty states, loading text.
• Translated strings and CJK/Latin mixed content.

3. Define the intended behavior for each text container:

• Wrap: content can take multiple lines without breaking layout.
• Clamp: content is visually limited but full value is available elsewhere.
• Truncate: content is shortened with ellipsis for compact repeated UI.
• Scroll: content is intentionally scrollable, usually code, logs, tables, or panels.
• Resize: layout adapts to content, but within stable min/max bounds.

4. Implement the smallest robust fix:

• Add missing min-width: 0 or min-height: 0 in flex/grid children.
• Add explicit max-width, overflow-wrap, text-overflow, line-clamp, or scroll behavior where needed.
• Avoid changing parent layout unless the parent is the source of the overflow.

5. Verify with adversarial content and viewports:

• Test narrow mobile, tablet, desktop, and wide desktop.
• Test long unbroken strings, long natural language, CJK text, mixed CJK/English, URLs, empty values, and dense lists.
• Use browser screenshots or DOM inspection for visual changes when feasible.

Deep References

Load these reference files when the task needs deeper coverage:

• code-review-checklist.md: use before editing or reviewing React, Vue, Svelte, HTML/CSS, component-library usage, stateful UI, forms, tables, or existing project code.
• visual-standards.md: use when creating, redesigning, polishing, or critiquing visual style, density, hierarchy, color, radius, shadow, typography, and interaction states.
• browser-verification.md: use after visible UI changes, before final response, or when debugging layout/overflow/responsive issues with browser automation, screenshots, console logs, and viewport checks.

Text Overflow Rules

Use wrapping when users must read the content inline:

.wrap-text {
  overflow-wrap: anywhere;
  word-break: normal;
  hyphens: auto;
}

Use truncation only when space is intentionally compact and the full value is still accessible:

.truncate-one-line {
  min-width: 0;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

For compact names or titles in repeated UI, prefer one-line ellipsis with full text available on hover and keyboard focus through the project's Tooltip/title pattern. Do not only "protect layout" by clipping text; the user must still be able to inspect the complete value.

Use multi-line clamping for cards, summaries, and search results:

.clamp-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

Use scroll for logs, code, long tables, and raw technical values:

.scroll-panel {
  min-width: 0;
  min-height: 0;
  overflow: auto;
}

Avoid these traps:

• Do not rely on overflow: hidden alone; it hides bugs and can make content inaccessible.
• Do not apply white-space: nowrap to containers that may receive translated text.
• Do not use word-break: break-all as the default for readable prose; use overflow-wrap: anywhere for long unbroken tokens.
• Do not truncate form errors, critical warnings, prices, dates, or destructive action labels.
• Do not place ellipsis on inline elements without a constrained width and block/inline-block/flex behavior.
• Do not clamp text without considering keyboard focus, screen readers, and access to full content.

Flex And Grid Pitfalls

Always check min-width: 0 for flex/grid children that contain text:

.row {
  display: flex;
}

.row__content {
  min-width: 0;
  flex: 1;
}

Use minmax(0, 1fr) in CSS Grid when columns contain long content:

.grid {
  display: grid;
  grid-template-columns: minmax(0, 1fr) auto;
}

Guard against layout shifts:

• Give avatars, icons, buttons, table columns, and thumbnails stable dimensions.
• Use flex: none for icons and fixed controls next to flexible text.
• Use gap rather than margin hacks for repeated horizontal/vertical rhythm.
• Avoid percentage widths that combine with padding and cause overflow.
• Set box-sizing: border-box if the project does not already do it globally.
• Use min-height: 0 on nested flex/grid panels that need internal scrolling.

Alignment And Spacing

Align by visual role, not by accidental DOM order:

• Align labels and values consistently within forms, detail panels, tables, and cards.
• Align icons with text using inline-flex, align-items: center, and a stable gap.
• Keep icon-only buttons square and centered.
• Keep mixed icon/text controls baseline-balanced; avoid icons floating above text.
• Use the project spacing scale; do not invent one-off margins unless necessary.
• Preserve vertical rhythm between headings, body text, controls, and section boundaries.
• Do not center-align long paragraphs, tables, form labels, or dense operational UI.
• Use right alignment only for numeric values that users compare in columns.
• Use tabular numbers for metrics, prices, timers, and aligned numeric columns when available.

Prefer:

.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 0.5rem;
}

Typography

Keep type readable and stable:

• Do not scale font size directly with viewport width.
• Avoid negative letter spacing unless the existing design system explicitly uses it.
• Use sufficient line-height for CJK and mixed-language text.
• Avoid oversized headings inside compact cards, sidebars, toolbars, tables, and modals.
• Keep button labels short but do not make them cryptic.
• Use semantic heading order even when visual size differs.
• Use font weights sparingly; hierarchy should also come from size, spacing, color, and layout.
• Test text expansion from localization; English to German, Russian, Vietnamese, Chinese, Japanese, and Korean can stress width/height differently.

Recommended starting points:

• Body text: line-height around 1.45 to 1.7, depending on density.
• UI labels: line-height around 1.2 to 1.4.
• Dense tables: maintain legibility before optimizing for row count.

Responsive Layout

Design for real breakpoints, not only one desktop width:

• Check 320px, 375px, 768px, 1024px, 1280px, and one wide desktop size when feasible.
• Avoid fixed widths that exceed small screens.
• Use max-width: 100% for media and text containers.
• Ensure sticky headers, sidebars, bottom bars, and floating controls do not cover content.
• Use horizontal scrolling only for content that naturally needs it, such as large tables, timelines, code, or comparison matrices.
• Keep tap targets at least roughly 44px high/wide on mobile unless the app's dense UI standard intentionally differs.
• Ensure viewport units account for mobile browser chrome; prefer modern units like svh, dvh, or project-supported fallbacks when relevant.

For mobile:

• Stack forms and filter bars when horizontal density becomes brittle.
• Let primary actions remain reachable without covering inputs.
• Make modals fit within viewport height with internal scrolling.
• Avoid hover-only affordances.

Component-Specific Checks

Buttons And Controls

• Prevent label overflow with min-width: 0 on text spans inside flexible buttons.
• Keep loading states the same size as idle states.
• Keep destructive, disabled, focus, hover, pressed, and selected states visually distinct.
• Do not hide focus outlines unless replacing them with accessible focus styles.
• Use icons for familiar tool actions when an icon library exists, with accessible labels or tooltips.

Forms

• Keep labels visible when possible; placeholders are not labels.
• Let validation errors wrap and remain close to the field.
• Avoid layout jump when errors appear; reserve space only if the project pattern supports it.
• Ensure long option labels in selects, radio groups, checkboxes, and comboboxes wrap or truncate intentionally.
• Support autofill, disabled, readonly, required, invalid, loading, and success states.
• Do not make input text smaller than surrounding UI in a way that harms readability.

Tables And Data Grids

• Decide per column: fixed width, flexible width, wrap, truncate, or horizontal scroll.
• Keep important identifiers readable; if truncated, provide copy or full-value access.
• Align numbers right and text left.
• Use sticky headers/columns only when they do not create clipping or z-index issues.
• Test empty, one-row, many-row, loading, error, and filtered states.
• Avoid putting complex cards inside every table cell unless the product pattern already does it.

Cards And Lists

• Give repeated items stable structure and consistent action placement.
• Clamp summaries, not critical titles, unless full titles are available on hover/focus/detail.
• Keep badges from pushing primary content out of view.
• Ensure hover/focus styles do not resize cards.
• Avoid nested cards unless the design system explicitly uses them.

Navigation, Tabs, And Breadcrumbs

• Test long route names and translated labels.
• Use overflow menus, scrollable tab lists, wrapping breadcrumbs, or truncation intentionally.
• Keep the active state visible when labels truncate.
• Ensure keyboard navigation remains usable.

Modals, Drawers, Popovers, Tooltips

• Keep headers and footers stable while body content scrolls.
• Prevent popovers from clipping against viewport edges.
• Do not put critical content only in hover tooltips.
• Let dialogs handle long titles, long errors, and dense forms.
• Ensure escape, outside click, focus trap, and return focus behavior match the library pattern.

Images, Avatars, And Media

• Set explicit aspect ratios or dimensions to prevent layout shifts.
• Use object-fit deliberately.
• Provide alt text for meaningful images and empty alt for decorative images.
• Test missing, slow, broken, and very large images.
• Do not crop product/person/content images so aggressively that users cannot inspect them.

CSS And Styling Pitfalls

Avoid fragile CSS:

• Do not fix overflow by adding random z-index, position: absolute, or negative margins.
• Do not use height: 100vh for app shells without accounting for mobile viewport behavior.
• Do not set overflow: hidden on high-level layout containers unless clipping is intentional.
• Do not use global selectors that alter unrelated components.
• Do not introduce color, radius, shadow, or spacing values outside existing tokens without reason.
• Do not make text unreadable by relying on low contrast placeholder, muted, disabled, or secondary colors.
• Do not put important content behind transparent overlays or decorative layers.
• Do not let hover borders change element size; use transparent borders or shadows.
• Do not animate layout properties when transform/opacity can achieve the same effect.

Prefer robust CSS primitives:

• box-sizing: border-box
• min-width: 0
• min-height: 0
• max-width: 100%
• overflow-wrap: anywhere
• text-wrap: balance only for headings where supported and not required for correctness
• contain, content-visibility, or virtualization only when performance need is real

Tailwind Notes

Use Tailwind utilities intentionally:

• Add min-w-0 to flex/grid text children.
• Use truncate only with a constrained width.
• Use break-words for readable wrapping and break-all only for technical tokens when acceptable.
• Use line-clamp-* for summaries when the plugin/support exists.
• Use overflow-x-auto around wide tables, not on the whole page.
• Use shrink-0 for icons/avatars and flex-1 min-w-0 for text.
• Avoid long arbitrary-value chains when a token or existing component class exists.

Common patterns:

<div className="flex min-w-0 items-center gap-2">
  <Icon className="size-4 shrink-0" aria-hidden="true" />
  <span className="min-w-0 truncate">Very long label</span>
</div>

<div className="grid grid-cols-[minmax(0,1fr)_auto] items-center gap-3">
  <p className="min-w-0 break-words">Long readable content</p>
  <button className="shrink-0">Action</button>
</div>

Component Library Notes

When using a component library:

• Read the local wrapper component before changing usage.
• Prefer library-supported props for size, status, disabled, placement, overflow, and accessibility.
• Do not override internals with brittle selectors unless there is no public API.
• For Ant Design, check Table column width, ellipsis, scroll.x, Tooltip, Form.Item help text, Select option rendering, and Typography.Text ellipsis behavior.
• For shadcn/ui, preserve Radix accessibility behavior and component composition; fix layout with wrapper classes before rewriting primitives.
• For MUI/Chakra/Headless UI, prefer documented slot props, style props, or composition points.

Accessibility And Semantics

Keep UI usable beyond the happy path:

• Preserve visible focus and logical tab order.
• Use semantic elements for buttons, links, headings, lists, tables, forms, and landmarks.
• Provide accessible names for icon-only controls.
• Do not rely on color alone for errors, warnings, active states, or status.
• Ensure truncated content has an accessible path to the full value when the full value matters.
• Ensure tooltips are reachable or nonessential.
• Respect reduced motion for large or repeated animations.
• Keep contrast sufficient for normal, muted, disabled, hover, selected, and error text.

Internationalization And Content Variability

Plan for text expansion and writing differences:

• Avoid hard-coded pixel heights for text containers that may translate.
• Do not concatenate translated fragments when grammar may differ.
• Check pluralization and variable interpolation.
• Avoid layout assumptions based on English word boundaries.
• Ensure CJK text, RTL text, diacritics, emoji, and long numbers do not break the layout.
• Use dir, logical CSS properties, or library RTL support when the app supports RTL.

Visual Polish Checks

Before finishing a UI change, scan for:

• Text overlapping icons, badges, images, inputs, or adjacent sections.
• Content clipped by rounded corners, sticky bars, drawers, or hidden overflow.
• Cards or rows changing size on hover.
• Inconsistent icon sizes or stroke weights.
• Mismatched border radius within the same component group.
• Shadows or borders that make nested surfaces look accidental.
• Uneven spacing between repeated items.
• Empty states that look like broken loading states.
• Loading skeletons that do not match final layout dimensions.
• Disabled states with insufficient contrast or unclear affordance.
• Toasts, dropdowns, menus, and popovers hidden behind headers or modals.

Required Test Content

When practical, verify with these strings:

This is a normal sentence that should wrap naturally without breaking the layout.
SuperLongUnbrokenOrganizationNameWithNoSpacesAndManyCharacters1234567890
https://example.com/a/very/long/path/with/query?search=frontend-layout-overflow-and-wrapping
UserLocaleLongTextWithoutSpacesMixedWithAsciiABCDEFGHIJKLMN1234567890
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Also test:

• Empty string
• Single character
• Very long translated label
• Long number or currency value
• Long validation error
• Multiple badges or tags
• Missing image/avatar
• Loading and error states

Verification Checklist

Do not mark the task complete until these are true for the changed surface:

• No horizontal page overflow unless intentionally required.
• No text overlaps adjacent UI.
• Long text wraps, clamps, truncates, or scrolls according to the intended behavior.
• Full critical content remains accessible.
• Flex/grid children with text have appropriate min-width: 0 or min-height: 0.
• Mobile and desktop layouts remain usable.
• Loading, empty, error, disabled, hover, focus, selected, and dense-data states are covered when relevant.
• The change follows existing design tokens and component patterns.
• The UI is verified visually when a browser or screenshot workflow is available.

Response Pattern

When reporting work done with this skill:

• Mention the specific overflow/layout risks addressed.
• Mention the verification performed.
• Call out any remaining UI risk, untested viewport, or state that could not be checked.

Browser Verification Workflow

Use this reference after visible frontend changes or when debugging overflow, responsive behavior, visual regressions, or interaction states.

Contents

• When To Verify In Browser
• Setup
• Viewports
• Adversarial Content
• Screenshot Pass
• DOM And Console Checks
• Interaction Checks
• Automated Assertions When Useful
• Verification Report

When To Verify In Browser

Verify with a browser when any change affects:

• Layout, spacing, typography, colors, borders, shadows, or responsive behavior.
• Text rendering, truncation, wrapping, tables, cards, forms, navigation, or modals.
• Dropdowns, tooltips, popovers, drawers, dialogs, sticky elements, or portals.
• Loading, error, empty, disabled, hover, focus, selected, expanded, or collapsed states.
• Canvas, SVG, charts, images, video, maps, or animation.

Setup

1. Start the project using the existing package manager and dev script. 2. Prefer the repo's documented local URL. If the port is busy, use the next available port only if the framework supports it. 3. Open the page in the in-app browser or available browser automation tool. 4. Watch terminal output, browser console, and network errors. 5. Keep the dev server running only while needed for verification.

Viewports

Check the changed surface at practical sizes:

• 320x700: smallest common mobile stress case.
• 375x812: common mobile.
• 768x1024: tablet.
• 1024x768: small desktop or tablet landscape.
• 1280x800: common laptop.
• 1440x900 or wider: desktop spacing.

Use fewer viewports only for very small changes, but always include at least one narrow and one desktop viewport for layout work.

Adversarial Content

Inject or create test data when possible:

• Long unbroken token.
• Long normal sentence.
• URL with query string.
• Mixed Chinese and English.
• Long translated button/label.
• Many tags/badges.
• Empty value.
• Missing image/avatar.
• Long validation error.
• Large table row count or many list items.

If live data cannot be changed safely, use devtools DOM editing, local mock data, storybook stories, fixtures, or temporary test-only data. Remove temporary data before finishing.

Screenshot Pass

For each important viewport:

1. Capture a screenshot of the whole changed surface. 2. Inspect for horizontal overflow, clipped text, overlap, accidental scrollbars, layout shifts, and poor alignment. 3. Compare key states if the change affects interaction. 4. Zoom mentally: titles, labels, values, buttons, and errors should remain readable without guessing.

Look specifically at:

• Page edges for content extending beyond viewport.
• Flex rows containing title + metadata + actions.
• Table wrappers and sticky columns.
• Modal headers/footers and body scroll.
• Dropdown/popover position against viewport edges.
• Text baselines next to icons.
• Loading skeleton dimensions versus final content.

DOM And Console Checks

Use DOM inspection when screenshots are ambiguous:

• Check computed width, min-width, overflow, white-space, text-overflow, word-break, and overflow-wrap.
• Check whether the overflowing node or its parent needs min-width: 0.
• Check portal root and z-index when overlays render incorrectly.
• Check accessible names for icon-only controls.
• Check console errors and warnings.
• Check network failures that cause broken loading/error states.

Interaction Checks

Exercise real workflows:

• Type long input values.
• Trigger validation errors.
• Open and close dropdowns, popovers, drawers, and modals.
• Hover and keyboard-focus controls.
• Select tabs and filters.
• Sort and scroll tables.
• Resize the viewport while the component is open.
• Submit forms in loading and error cases.

Automated Assertions When Useful

For Playwright or similar tools, prefer simple checks:

• Assert no document-level horizontal overflow:

document.documentElement.scrollWidth <= document.documentElement.clientWidth

• Assert target text container dimensions are within parent bounds.
• Assert key controls are visible and enabled/disabled as expected.
• Assert screenshots for critical responsive surfaces when the project already supports visual testing.

Avoid brittle pixel-perfect tests unless the project already has visual regression infrastructure.

Verification Report

In the final response, mention:

• Viewports checked.
• Main states checked.
• Browser/console errors found or absence of relevant errors.
• Any state or viewport not verified and why.

Do not claim visual verification if only code inspection was performed.

Frontend Code Review Checklist

Use this reference before modifying or reviewing project UI code. Keep the review surgical: flag concrete defects, fix only the changed surface, and preserve existing patterns.

Contents

• Review Order
• React And Next.js
• Vue And Nuxt
• Svelte
• HTML And CSS
• Data And Content
• Forms
• Tables And Dense Data
• Component Libraries
• State And Interaction
• Performance Risks
• Review Findings Format

Review Order

1. Identify the changed user-facing surface. 2. Find the component boundaries, wrappers, design-system primitives, data shape, and CSS source. 3. Trace every dynamic text value into the DOM. 4. Check layout constraints from parent to child, especially flex/grid containers. 5. Check all meaningful states: loading, empty, error, disabled, readonly, focus, hover, selected, expanded, collapsed, and permission-limited. 6. Verify with adversarial text and at least one narrow viewport when feasible.

React And Next.js

• Check whether text-bearing children inside flex or grid have min-w-0, flex-1, shrink-0, or equivalent classes in the right places.
• Keep truncation on the text node, not on a high-level row that also contains buttons or badges.
• Avoid unstable layout caused by conditional rendering that inserts/removes wrappers; prefer stable slots where loading/error states share dimensions.
• Do not use array index keys for reorderable, filterable, or dynamic lists.
• Ensure client/server component boundaries in Next.js do not force unnecessary client rendering just for styling.
• Avoid hydration mismatches from browser-only values, dates, random IDs, and viewport-dependent rendering.
• Keep aria-label, title, tooltip content, and visible labels consistent when truncating.
• Ensure useEffect is not used for simple derived display values.
• Keep memoization local and justified; do not add useMemo/useCallback to hide inefficient structure unless measurable.
• Check that Suspense, skeletons, and loading states preserve final layout dimensions.

Vue And Nuxt

• Check v-if/v-show choices: v-if can remove layout and focus targets; v-show preserves DOM and dimensions.
• Verify :key stability in v-for.
• Keep computed display strings in computed, not repeated inline template expressions when they affect multiple UI locations.
• Ensure scoped CSS does not rely on brittle deep selectors unless component-library APIs are unavailable.
• Check slots with long content; parent components must constrain slot layout.
• Avoid fixed-height containers around translated labels and validation text.
• Ensure SSR/client-only logic does not cause layout shifts in Nuxt.

Svelte

• Check {#each} blocks use stable keys for dynamic lists.
• Ensure reactive declarations do not recompute expensive layout data unnecessarily.
• Keep conditional blocks from replacing focusable elements in ways that lose focus.
• Check slotted content constraints, especially card headers, table cells, and toolbar actions.

HTML And CSS

• Confirm semantic elements match behavior: button for actions, a for navigation, label for form fields, table for tabular data.
• Check that position: absolute is not used to patch normal document flow unless the UI is intentionally overlaid.
• Check stacking contexts before adding z-index; many overlay bugs come from transformed parents, opacity, filters, or positioned ancestors.
• Verify overflow: hidden does not clip focus rings, dropdowns, sticky children, or validation messages.
• Avoid fixed height for text-heavy containers; prefer min-height, content flow, or internal scroll.
• Ensure global CSS changes are scoped and do not alter unrelated components.
• Check print styles only when the surface is printable.

Data And Content

• Treat backend content as untrusted for length and formatting.
• Test empty/null/undefined values without rendering undefined, null, NaN, or broken punctuation.
• Avoid concatenating optional fields into awkward strings with dangling separators.
• Format numbers, dates, currency, and percentages consistently with existing utilities.
• Keep raw IDs, URLs, hashes, and file paths copyable when they are operationally important.
• Preserve whitespace only for logs/code/preformatted content, not ordinary labels.

Forms

• Confirm every input has a visible or accessible label.
• Keep validation messages close to the field and allow them to wrap.
• Check long labels in checkboxes, radios, switches, select options, and segmented controls.
• Preserve browser affordances: autocomplete, input type, required, disabled, readonly, invalid.
• Avoid disabled submit buttons without explaining what blocks submission.
• Ensure async submit states prevent duplicate submission without shifting layout.
• Check that errors returned from APIs do not overflow toast/dialog/form containers.

Tables And Dense Data

• Decide per column: wrap, truncate, fixed, flexible, sticky, or hidden on small screens.
• Use horizontal scroll at the table wrapper, not the whole page.
• Ensure row actions remain reachable at narrow widths.
• Keep headers aligned with cells after scroll, sticky, or virtualization changes.
• Check virtualization with variable row height if cells can wrap.
• Ensure empty/filter/no-permission states keep table frame coherent.
• Avoid hiding columns that contain required decisions unless there is a detail row or drill-in path.

Component Libraries

• Prefer project wrapper components before importing raw library primitives.
• Read existing usage nearby; match size, density, variant, tone, and placement.
• Use documented props for ellipsis, tooltip, placement, popup container, scroll, virtualized lists, and status.
• Avoid overriding generated class names or internals unless there is no supported API.
• Check portal containers for dropdowns, popovers, modals, selects, and date pickers.
• Verify overlays inside drawers/modals do not render behind their parent or outside expected clipping.

State And Interaction

• Check keyboard interaction for every click target.
• Ensure hover-only actions are also discoverable by keyboard and touch users.
• Keep optimistic UI reversible or clearly pending.
• Preserve focus after dialogs close, filters apply, tabs switch, rows expand, or async actions complete.
• Avoid layout shifts when toggling details, sorting, filtering, or validation messages.
• Confirm destructive actions use the project's confirmation pattern.

Performance Risks

• Avoid rendering huge lists without pagination, virtualization, or lazy loading.
• Avoid measuring layout repeatedly in render loops.
• Debounce expensive search/filter operations when input is large.
• Check image dimensions, lazy loading, and object fit.
• Avoid importing large icon packs or chart libraries for one small visual.
• Ensure CSS animations do not animate width, height, top, left, or expensive filters in repeated elements.

Review Findings Format

When reviewing, lead with defects:

• Severity and short title.
• File and line reference.
• Why it breaks under realistic content or viewport.
• Minimal fix direction.
• Mention missing verification or test gaps after findings.

Visual Standards

Use this reference when creating, redesigning, or polishing UI. The goal is not decoration; it is clear hierarchy, stable layout, readable content, and a product surface that feels intentional.

Contents

• Visual Hierarchy
• Density
• Color
• Typography
• Spacing
• Borders, Radius, And Shadows
• Icons
• Layout Composition
• Interaction States
• Motion
• Common Style Failures
• Finish Criteria

Visual Hierarchy

• Make the primary task visually obvious within the first viewport.
• Use one dominant heading level per surface; avoid multiple elements competing as the page title.
• Use spacing and grouping before adding borders, shadows, or background fills.
• Keep secondary metadata visually quieter than titles and actions.
• Do not use hero-scale type inside dashboards, tables, sidebars, cards, modals, or toolbars.
• Keep action hierarchy clear: primary, secondary, tertiary, destructive, disabled.

Density

• Match density to product type. SaaS/admin tools should be compact, scannable, and calm; marketing pages can breathe more.
• Avoid oversized cards for small amounts of operational data.
• Avoid large decorative whitespace that pushes key workflows below the fold.
• Keep repeated rows/cards consistent so users can scan quickly.
• Use progressive disclosure for advanced controls rather than crowding the first screen.

Color

• Use existing tokens first.
• Limit accent colors; one primary accent plus semantic colors is usually enough.
• Do not communicate status by color alone; pair with text/icon/shape.
• Check muted text contrast on real backgrounds, not only white.
• Avoid one-note palettes where every surface is a tint of the same hue.
• Keep destructive colors reserved for destructive or dangerous actions.
• Avoid gradients unless the product style already uses them or the surface is explicitly editorial/marketing.

Typography

• Keep a clear scale: page title, section title, body, metadata, caption.
• Do not use negative letter spacing.
• Do not use viewport-width-driven font sizes.
• Keep line length readable: long prose should not span the full desktop width.
• Use tabular numerals for dashboards, financial values, timers, and comparable numeric columns.
• Prefer sentence case unless the existing product style uses title case.
• Avoid all-caps labels for long strings; they become harder to scan and localize.

Spacing

• Use the project's spacing scale.
• Keep related elements close and unrelated groups farther apart.
• Align vertical edges across sections, forms, cards, and tables.
• Keep toolbar control gaps consistent.
• Avoid stacking multiple containers each with large padding; nested padding makes cramped content look accidental.
• Do not solve alignment by hand-tuned one-off margins when layout primitives can express it.

Borders, Radius, And Shadows

• Use radius consistently by component type.
• Avoid nested cards with competing borders/shadows.
• Use shadows for elevation, not decoration.
• Keep borders subtle but visible enough to define dense data regions.
• Avoid hover borders that change size; use existing border width with transparent idle color.
• Do not mix many radius values in the same control group.

Icons

• Use the project's icon library.
• Keep icon size and stroke weight consistent within a toolbar or list.
• Use aria-hidden for decorative icons and accessible labels for icon-only buttons.
• Do not replace clear text with unfamiliar icons unless tooltip/label support exists.
• Align icons optically with text, not just mathematically.

Layout Composition

• Keep page sections full-width or naturally grouped; do not put whole pages inside floating cards unless the product pattern requires it.
• Avoid cards inside cards.
• Use grids when comparing similar items; use lists/tables when scanning many records.
• Keep sidebars and filters from stealing space from primary content at small widths.
• Let important content, not decoration, occupy the largest visual area.
• Make responsive changes intentional: stack, collapse, scroll, or hide with a substitute path.

Interaction States

• Design idle, hover, active, focus, disabled, loading, selected, error, warning, success, empty, and skeleton states.
• Keep state changes from resizing the component.
• Ensure focus styles are visible against all state backgrounds.
• Ensure disabled controls still explain unavailable actions when the reason is not obvious.
• Make selected state stronger than hover state.
• Keep loading indicators close to the content/action they affect.

Motion

• Use motion to clarify cause and effect, not as decoration.
• Prefer transform and opacity.
• Keep durations short for operational UI.
• Respect reduced motion.
• Avoid animating repeated table rows or dense list items unless the product pattern demands it.

Common Style Failures

• Text too large for compact controls.
• Metadata louder than primary content.
• Too many borders plus shadows.
• Low-contrast gray text on tinted backgrounds.
• Center-aligned dense content.
• Buttons with inconsistent heights.
• Icons that shift text baseline.
• Badges that dominate titles.
• Empty states that look like errors.
• Skeletons that do not match final content.
• Cards with hover transforms that make the grid jitter.
• Dropdowns and popovers visually disconnected from their trigger.

Finish Criteria

Before finalizing visual work, confirm:

• The eye lands on the right first action/content.
• Related controls align and share dimensions.
• Text hierarchy is clear without reading every word.
• Long text has a planned behavior.
• The page still works in a dense, real-data scenario.
• No decorative choice harms readability, scanning, or accessibility.