frontend-quality-guardrails-cn

Frontend quality gate rules

Overview

Use this skill as the quality gate rules for frontend implementation and review, covering overly long text, overflow, line wrapping, truncation, alignment, spacing, responsiveness, component states, accessibility, internationalization, visual details, project code review, browser screenshot verification, and common UI styling pitfalls.

Treat all UI as if it will encounter imperfect content. By default, assume that labels, names, URLs, IDs, prices, translated text, user input, error messages, table cells, badges, breadcrumbs, tabs, and button copy may all be longer than the design mockup.

Prefer small, local CSS/layout fixes; do not rewrite the overall structure for a local issue. Unless the user explicitly requests a redesign, preserve the existing design system, component APIs, design tokens, spacing scale, and framework conventions.

When to use

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

• Overly long text, URLs, IDs, translated copy, form errors, labels, table cells, cards, tabs, breadcrumbs, or badges may overflow.
• The task involves 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 the UI, fix overflow, improve alignment, review frontend code, verify browser screenshots, or avoid frontend styling pitfalls.

Do not use

Do not use this skill as the primary guide in the following scenarios:

• Tasks without a visible UI, such as backend, CLI, database, or infrastructure.
• Full brand design, illustration, logo design, or image generation.
• Pixel-perfect reproduction from screenshots when a more specialized image-to-code or design reproduction skill is already available.
• Specialized accessibility audits that require a formal WCAG score or compliance report.

Usage instructions

Use the following process as a quality gate layer on top of the project's existing frontend standards. For simple changes, use only the core checklist; for deeper development, review, or acceptance, read the files in "Deep Reference" as needed.

Workflow

1. First check the existing UI conventions:

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

2. Identify text risk surfaces:

   • Usernames, organization names, file names, paths, slugs, UUIDs, hashes, tokens, URLs, emails, phone numbers.
   • Headings, card titles, table cells, navigation items, tabs, breadcrumbs, filters, chips, badges, tooltips, toasts, dialogs.
   • Form labels, placeholders, help text, validation errors, empty states, loading copy.
   • Translated copy and mixed Chinese-English content.

3. Clarify the expected behavior of each text container:

   • Wrap: content can display on multiple lines without breaking the layout.
   • Line clamp: content is visually limited to a number of lines, but the full value is accessible elsewhere.
   • Truncate: shorten with an ellipsis in compact, repetitive UI.
   • Scroll: content such as code, logs, tables, or panels intentionally scrolls.
   • Adaptive: the layout changes with the content, but has stable minimum/maximum constraints.

4. Implement the minimal and robust fix:

   • Add min-width: 0 or min-height: 0。
   • Add explicit max-width、overflow-wrap、text-overflow、line-clamp or scrolling behavior where necessary.
   • Only adjust the parent layout when the parent container is the source of the overflow.

5. Verify with extreme content and viewports:

   • Test narrow-screen phones, tablets, desktops, and wide-screen desktops.
   • Test extra-long unbroken strings, long natural language, mixed Chinese and English, URLs, empty values, and dense lists.
   • When feasible, use browser screenshots or DOM inspection to verify visual changes.

In-depth reference

Read these reference files when more complete coverage is needed:

• code-review-checklist.md: Use before editing or reviewing React, Vue, Svelte, HTML/CSS, component libraries, stateful UI, forms, tables, or existing project code.
• visual-standards.md: Use when creating, redesigning, polishing, or reviewing visual style, density, hierarchy, color, rounded corners, shadows, typography, and interaction states.
• browser-verification.md: Use after completing visible UI changes, or when debugging layout, overflow, or responsive issues, for browser automation, screenshots, console, and viewport inspection.

Text overflow rules

Prefer wrapping for content that users must read directly:

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

Truncate only when the 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 a single-line ellipsis, and show the full text on mouse hover and keyboard focus through the project's existing Tooltip/title pattern. Do not rely only on clipping to "protect the layout"; users must still be able to view the full value.

Card summaries, search results, and explanatory text can use multi-line clamping:

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

Logs, code, long tables, and raw technical values are suitable for scrolling:

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

Avoid these pitfalls:

• Do not rely only on overflow: hidden to solve the problem; it hides bugs and makes content inaccessible.
• Do not put white-space: nowrap on a container that may receive translated copy.
• Do not use word-break: break-allby default for readable body text; for long unbroken tokens, prefer overflow-wrap: anywhere。
• Do not truncate form errors, critical warnings, prices, dates, or dangerous action copy.
• Do not expect ellipsis to work without a constrained width and block/inline-block/flex behavior.
• When using line clamping, consider keyboard focus, screen readers, and the path to accessing the full content.

Flex and Grid pitfalls

Flex/grid children containing text usually need to be checked for min-width: 0：

.row {
  display: flex;
}

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

For columns containing long content in CSS Grid, prefer minmax(0, 1fr)：

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

Prevent layout jitter:

• Give avatars, icons, buttons, table columns, and thumbnails stable dimensions.
• Use flex: none or an equivalent for icons and fixed controls.
• For repeated horizontal/vertical rhythm, prefer gap。
• Avoid overflow caused by percentage widths combined with padding.
• If the project has no global setting, add box-sizing: border-box。
• For nested flex/grid panels that need internal scrolling, check min-height: 0。

Alignment and spacing

Align by visual role, not by incidental DOM order:

• Labels/values in forms, detail panels, tables, and cards should be aligned consistently.
• For icons and text, use inline-flex、align-items: center and stable gap。
• Icon-only buttons stay square and centered.
• Icon + text controls should be visually baseline-balanced, avoiding the icon floating above the text.
• Use the project's existing spacing scale; do not invent one-off margins at will.
• Maintain vertical rhythm between headings, body text, controls, and section boundaries.
• Do not center-align long paragraphs, tables, form labels, or high-density business interfaces.
• Only right-align numbers when it facilitates comparison across columns.
• Prefer tabular figures for metrics, prices, timers, and numeric columns.

Recommended:

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

Typography

Keep typography readable and stable:

• Do not scale font size directly with viewport width.
• Avoid negative letter-spacing unless the project's design system explicitly uses it.
• Mixed Chinese-English typesetting and CJK content need sufficient line height.
• Avoid oversized headings in compact cards, sidebars, toolbars, tables, and dialogs.
• Button copy should be short, but not hard to understand.
• Maintain semantic heading order even when visual sizes differ.
• Do not overuse font weight; hierarchy should also come from font size, spacing, color, and layout.
• Test translation expansion; German, Russian, Vietnamese, Chinese, Japanese, and Korean will challenge width and height in different ways.

Suggested starting points:

• Body text line height about 1.45 to 1.7, adjusted by density.
• UI label line height about 1.2 to 1.4。
• For high-density tables, ensure readability first, then pursue row count.

Responsive layout

Design for real breakpoints, not just one desktop width:

• When feasible, check 320px、375px、768px、1024px、1280px and one widescreen size.
• Avoid fixed widths that exceed small screens.
• Use max-width: 100%。
• Ensure sticky headers, sidebars, bottom bars, and floating controls do not obscure content.
• Only scroll horizontally when naturally required, such as for large tables, timelines, code, or comparison matrices.
• On mobile, tap targets should be as close as possible to 44px in height/width, unless the project explicitly adopts a high-density specification.
• Mobile browser address bars affect viewport height; use svh、dvh or a fallback supported by the project when necessary.

Mobile:

• Forms and filter bars should stack when horizontal density is fragile.
• Primary actions should be reachable and not obscure input.
• Dialogs should adapt to viewport height and let the body scroll internally.
• Do not rely on hover-only interactions.

Component-specific checks

Buttons and controls

• Text spans inside flexible buttons must handle overflow.
• Loading and idle states should keep the same size.
• Danger, disabled, focus, hover, pressed, and selected states should be distinguishable.
• Do not remove the focus outline unless replacing it with an accessible focus style.
• When an icon library is available, prefer icons for familiar tool operations and provide accessible labels or tooltips.

Forms

• Keep visible labels whenever possible; placeholders are not labels.
• Validation errors should wrap and stay close to the field.
• Avoid large layout shifts when errors appear.
• Long options in select, radio, checkbox, and combobox must explicitly wrap or truncate.
• Cover autofill, disabled, readonly, required, invalid, loading, and success states.
• Input text should not be so small that it affects readability.

Tables and data grids

• Define a clear strategy for each column: fixed width, flexible width, wrapping, truncation, or horizontal scrolling.
• Important identifiers must be readable; if truncated, provide a copy or full-value access path.
• Right-align numbers, left-align text.
• Sticky headers/columns must not create clipping or z-index issues.
• Test empty, single-row, multi-row, loading, error, and filtered states.
• Unless the product pattern already has it, do not stuff complex cards into every table cell.

Cards and lists

• Repeated items have a stable structure, and action positions are consistent.
• You can limit summary lines, but do not arbitrarily limit key titles unless the full title can be seen on hover/focus/detail.
• Badges should not push the main content out of view.
• Hover/focus styles should not change the card size.
• Avoid cards inside cards unless the design system explicitly uses it.

Navigation, tabs, and breadcrumbs

• Test long route names and translated labels.
• Use overflow menus, scrollable tabs, wrappable breadcrumbs, or intentional truncation as needed.
• When labels are truncated, the active state must still be visible.
• Keep keyboard navigation usable.

Modals, drawers, overlays, tooltips

• Header/footer are stable, and body content scrolls.
• Popovers should not be clipped by viewport edges.
• Do not put key information only in a hover tooltip.
• Dialogs must handle long titles, long errors, and complex forms.
• Escape, outside click, focus trap, and focus return after close follow the component library pattern.

Images, avatars, and media

• Set explicit width and height or aspect-ratio to avoid layout shift.
• Intentionally use object-fit。
• Provide alt for meaningful images, and use empty alt for decorative images.
• Test missing, slow-loading, broken, and oversized images.
• Do not over-crop product, people, or content images in a way that affects user recognition.

CSS and styling pitfalls

Avoid fragile CSS:

• Do not use random z-index、position: absolute or negative margin to fix overflow.
• Do not blindly use height: 100vhfor the app shell; consider the mobile viewport.
• Do not arbitrarily overflow: hidden。
• Do not use global selectors that affect unrelated components.
• Do not introduce colors, radii, shadows, or spacing values outside the tokens without reason.
• Do not let placeholder, muted, disabled, or secondary colors have such low contrast that they are unreadable.
• Do not place important content behind transparent overlays or decorative layers.
• Hover borders should not change the element size.
• For animations that can use transform/opacity, do not animate layout properties.

Robust foundational attributes:

• box-sizing: border-box
• min-width: 0
• min-height: 0
• max-width: 100%
• overflow-wrap: anywhere
• text-wrap: balance used only for heading enhancement, not as a correctness dependency
• contain、content-visibility or virtual lists only when there is a real performance need

Tailwind notes

• Add min-w-0。
• truncate Must be paired with a constrained width.
• Readable text takes priority break-words, and only use break-all。
• Use line-clamp-* to handle summaries when supported.
• Use overflow-x-autoon the outer layer of large tables; do not let the entire page scroll horizontally.
• Use shrink-0for icons/avatars, and use flex-1 min-w-0。
• for text. When tokens or existing component classes are available, avoid piling up very long arbitrary values.

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

• Read the wrapper components in the project before making changes.
• Prefer using the component library's public props to control size, state, disabled, position, overflow, and accessibility.
• Unless there is no public API, do not override internal implementations with fragile selectors.
• For Ant Design, focus on checking Table column widths,ellipsis、scroll.x、Tooltip、Form.Item help、Select option rendering.Typography.Text ellipsis。
• For shadcn/ui, preserve Radix's accessible behavior and composition patterns, and prefer fixing layout through wrapper classes.
• For MUI/Chakra/Headless UI, prefer the documented slot props, style props, or composition points.

Accessibility and semantics

• Preserve visible focus and a reasonable tab order.
• Use semantic elements for buttons, links, headings, lists, tables, forms, and landmarks.
• Provide accessible names for icon-only controls.
• Do not convey errors, warnings, active states, and status through color alone.
• When important content is truncated, there must be a way to access the full value.
• Tooltips must be reachable or must not carry critical information.
• Respect reduced motion for large-scale or repeated animations.
• Normal, muted, disabled, hover, selected, and error text must all have sufficient contrast.

Internationalization and content changes

• Avoid hard-coded pixel heights for text containers that may be translated.
• Do not concatenate translation fragments; grammatical order may differ.
• Check plurals and variable interpolation.
• Do not assume English word boundaries.
• Ensure CJK, RTL, diacritics, emoji, and long numbers do not break the layout.
• When supporting RTL, use dir, logical CSS properties, or the component library's RTL capabilities.

Visual detail check

Before completing UI changes, scan for:

• Whether text covers icons, badges, images, input fields, or adjacent blocks.
• Whether content is clipped by rounded corners, sticky bars, drawers, or hidden overflow.
• Whether cards or rows change size on hover.
• Whether icon sizes and strokes are inconsistent.
• Whether border radii are inconsistent within the same component group.
• Whether shadows or borders make nested hierarchy look accidental.
• Whether spacing between repeated items is uneven.
• Whether empty states look like broken loading.
• Whether skeletons match the final layout dimensions.
• Whether disabled states have insufficient contrast or unclear meaning.
• Whether toasts, dropdowns, menus, or popovers are obscured by the header or modal.

Must-test content

When feasible, use these strings to verify:

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
张三李四王五赵六前端页面超长文本混排ABCDEFGHIJKLMN1234567890
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Also test:

• Empty string
• Single character
• Extra-long translated labels
• Long numbers or currency values
• Long validation errors
• Multiple badges/tags
• Missing images/avatars
• Loading and error states

Acceptance checklist

Do not mark as complete before these conditions are met:

• The page has no horizontal overflow unless intentionally designed.
• Text does not overlap adjacent UI.
• Long text wraps, clamps, truncates, or scrolls as expected.
• Key complete content remains accessible.
• Flex/grid children containing text have appropriate min-width: 0 or min-height: 0。
• Mobile and desktop layouts are usable.
• Cover loading, empty, error, disabled, hover, focus, selected, and dense data states when relevant.
• Changes follow existing design tokens and component patterns.
• Complete visual verification when a browser or screenshot workflow is available.

Response format

When using this skill to complete a task:

• Explain which specific overflow/layout risks were addressed.
• Explain what verification was done.
• Explain which UI risks, viewports, or states have not yet been checked.