frontend-design-guardrails

Files (1)

• SKILL.md

SKILL.md (first lines)

# Frontend Design Guardrails

## Goal

Build usable interfaces that match the target repository's existing UI system and can be verified reliably.

## Reference Principles

- Ant Design baseline: optimize for natural interaction, certainty, meaningful task progress, and systems that can grow without visual drift.
- Design patterns beat freestyle UI: prefer established page patterns, reusable components, tokens, layout rules, copy conventions, feedback patterns, and data-entry/data-display patterns.
- Design-system packets beat vague style adjectives: record the minimum explicit tokens and component decisions needed to make the result repeatable.
- Preview culture matters: make the result inspectable through browser evidence, screenshots, or a clear static fallback.

## Rules

- Prefer the repository's existing component library, theme tokens, layout primitives, icon set, routing, and state patterns.
- If the repository uses Ant Design, Ant Design Pro, Pro Components, or compatible tokens, use their components and interaction patterns first; only build custom controls when the library cannot express the workflow.
- For operational tools, favor dense, calm, scannable layouts over marketing-style hero sections.
- Use semantic controls: buttons for commands, inputs for text, selects/menus for option sets, tabs for views, toggles for binary settings.
- Provide loading, empty, error, disabled, success, and partial states when the workflow needs them.
- Avoid magic pixel offsets, absolute-positioned main layouts, clipped text, overlapping controls, and layout shifts.
- Ensure controls have stable accessible labels or text so browser tests can locate them.
- For mobile and desktop, verify that text fits and primary actions remain reachable.
- Do not invent metrics, testimonials, brand claims, screenshots, or business data. Use real data, labelled placeholders, or explicit empty states.
- Avoid generic AI-looking UI: ungrounded purple gradients, decorative blob backgrounds, arbitrary glass cards, over-rounded nested cards, lorem ipsum, and icon-only controls without accessible names.

## Before Implementation

Freeze:

- target user and workflow
- existing UI library/patterns
- page structure
- critical states
- responsive breakpoints
- validation method
- brand source or visual direction
- data density and hierarchy
- accessibility-critical labels and keyboard path

## Design System Packet

For non-trivial UI work, generate a small design-system packet before coding, inspired by UI UX Pro Max and Open Design's active-design-system workflow:

- `product_type`
- `surface`
- `audience`
- `style_direction`
- `brand_source`
- `color_tokens`
- `typography`
- `spacing`
- `components`
- `data_density`
- `states`
- `accessibility_rules`
- `test_plan`
- `anti_patterns`

Store this in the task plan or component notes only when useful; do not create a persistent design-system folder unless the user or spec asks for it.

If the visual direction is underspecified, propose 2-3 concrete directions with tradeoffs before coding. For implementation tasks with an existing product style, derive the packet from current code and screenshots rather than replacing the product identity.

## Craft Review

Before delivery, self-review the UI across five dimensions:

- hierarchy: primary action, data priority, and scan path are clear
- consistency: spacing, typography, components, and feedback match the system
- function: core workflow works with realistic loading/error/empty data
- accessibility: labels, contrast, keyboard path, and focus states are adequate
- implementation: no layout shifts, clipped text, console errors, or endpoint leaks

## Before Completion

Run or request a browser/visual check through `web-experience-audit`, or state why runtime verification is unavailable and provide static fallback evidence.

From funky-eyes/best-copilot, Apache-2.0.

More from funky-eyes/best-copilot