USP
This collection provides a comprehensive, opinionated set of UI skills, offering concrete, code-level suggestions to prevent common pitfalls and enforce design engineering best practices across various aspects of front-end development.
Use cases
- 01Enforcing UI design consistency
- 02Auditing and fixing accessibility issues
- 03Optimizing animation performance
- 04Managing SEO and social media metadata
- 05Reviewing UI code for best practices
Detected files (4)
skills/baseline-ui/SKILL.mdskillShow content (3531 bytes)
--- name: baseline-ui description: Validates animation durations, enforces typography scale, checks component accessibility, and prevents layout anti-patterns in Tailwind CSS projects. Use when building UI components, reviewing CSS utilities, styling React views, or enforcing design consistency. --- # Baseline UI Enforces an opinionated UI baseline to prevent AI-generated interface slop. ## How to use - `/baseline-ui` Apply these constraints to any UI work in this conversation. - `/baseline-ui <file>` Review the file against all constraints below and output: - violations (quote the exact line/snippet) - why it matters (1 short sentence) - a concrete fix (code-level suggestion) ## Stack - MUST use Tailwind CSS defaults unless custom values already exist or are explicitly requested - MUST use `motion/react` (formerly `framer-motion`) when JavaScript animation is required - SHOULD use `tw-animate-css` for entrance and micro-animations in Tailwind CSS - MUST use `cn` utility (`clsx` + `tailwind-merge`) for class logic ## Components - MUST use accessible component primitives for anything with keyboard or focus behavior (`Base UI`, `React Aria`, `Radix`) - MUST use the project’s existing component primitives first - NEVER mix primitive systems within the same interaction surface - SHOULD prefer [`Base UI`](https://base-ui.com/react/components) for new primitives if compatible with the stack - MUST add an `aria-label` to icon-only buttons - NEVER rebuild keyboard or focus behavior by hand unless explicitly requested ## Interaction - MUST use an `AlertDialog` for destructive or irreversible actions - SHOULD use structural skeletons for loading states - NEVER use `h-screen`, use `h-dvh` - MUST respect `safe-area-inset` for fixed elements - MUST show errors next to where the action happens - NEVER block paste in `input` or `textarea` elements ## Animation - NEVER add animation unless it is explicitly requested - MUST animate only compositor props (`transform`, `opacity`) - NEVER animate layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`) - SHOULD avoid animating paint properties (`background`, `color`) except for small, local UI (text, icons) - SHOULD use `ease-out` on entrance - NEVER exceed `200ms` for interaction feedback - MUST pause looping animations when off-screen - SHOULD respect `prefers-reduced-motion` - NEVER introduce custom easing curves unless explicitly requested - SHOULD avoid animating large images or full-screen surfaces ## Typography - MUST use `text-balance` for headings and `text-pretty` for body/paragraphs - MUST use `tabular-nums` for data - SHOULD use `truncate` or `line-clamp` for dense UI - NEVER modify `letter-spacing` (`tracking-*`) unless explicitly requested ## Layout - MUST use a fixed `z-index` scale (no arbitrary `z-*`) - SHOULD use `size-*` for square elements instead of `w-*` + `h-*` ## Performance - NEVER animate large `blur()` or `backdrop-filter` surfaces - NEVER apply `will-change` outside an active animation - NEVER use `useEffect` for anything that can be expressed as render logic ## Design - NEVER use gradients unless explicitly requested - NEVER use purple or multicolor gradients - NEVER use glow effects as primary affordances - SHOULD use Tailwind CSS default shadow scale unless explicitly requested - MUST give empty states one clear next action - SHOULD limit accent color usage to one per view - SHOULD use existing theme or Tailwind CSS color tokens before introducing new onesskills/fixing-accessibility/SKILL.mdskillShow content (4718 bytes)
--- name: fixing-accessibility description: Audit and fix HTML accessibility issues including ARIA labels, keyboard navigation, focus management, color contrast, and form errors. Use when adding interactive controls, forms, dialogs, or reviewing WCAG compliance. --- # fixing-accessibility Fix accessibility issues. ## how to use - `/fixing-accessibility` Apply these constraints to any UI work in this conversation. - `/fixing-accessibility <file>` Review the file against all rules below and report: - violations (quote the exact line or snippet) - why it matters (one short sentence) - a concrete fix (code-level suggestion) Do not rewrite large parts of the UI. Prefer minimal, targeted fixes. ## when to apply Reference these guidelines when: - adding or changing buttons, links, inputs, menus, dialogs, tabs, dropdowns - building forms, validation, error states, helper text - implementing keyboard shortcuts or custom interactions - working on focus states, focus trapping, or modal behavior - rendering icon-only controls - adding hover-only interactions or hidden content ## rule categories by priority | priority | category | impact | |----------|----------|--------| | 1 | accessible names | critical | | 2 | keyboard access | critical | | 3 | focus and dialogs | critical | | 4 | semantics | high | | 5 | forms and errors | high | | 6 | announcements | medium-high | | 7 | contrast and states | medium | | 8 | media and motion | low-medium | | 9 | tool boundaries | critical | ## quick reference ### 1. accessible names (critical) - every interactive control must have an accessible name - icon-only buttons must have aria-label or aria-labelledby - every input, select, and textarea must be labeled - links must have meaningful text (no “click here”) - decorative icons must be aria-hidden ### 2. keyboard access (critical) - do not use div or span as buttons without full keyboard support - all interactive elements must be reachable by Tab - focus must be visible for keyboard users - do not use tabindex greater than 0 - Escape must close dialogs or overlays when applicable ### 3. focus and dialogs (critical) - modals must trap focus while open - restore focus to the trigger on close - set initial focus inside dialogs - opening a dialog should not scroll the page unexpectedly ### 4. semantics (high) - prefer native elements (button, a, input) over role-based hacks - if a role is used, required aria attributes must be present - lists must use ul or ol with li - do not skip heading levels - tables must use th for headers when applicable ### 5. forms and errors (high) - errors must be linked to fields using aria-describedby - required fields must be announced - invalid fields must set aria-invalid - helper text must be associated with inputs - disabled submit actions must explain why ### 6. announcements (medium-high) - critical form errors should use aria-live - loading states should use aria-busy or status text - toasts must not be the only way to convey critical information - expandable controls must use aria-expanded and aria-controls ### 7. contrast and states (medium) - ensure sufficient contrast for text and icons - hover-only interactions must have keyboard equivalents - disabled states must not rely on color alone - do not remove focus outlines without a visible replacement ### 8. media and motion (low-medium) - images must have correct alt text (meaningful or empty) - videos with speech should provide captions when relevant - respect prefers-reduced-motion for non-essential motion - avoid autoplaying media with sound ### 9. tool boundaries (critical) - prefer minimal changes, do not refactor unrelated code - do not add aria when native semantics already solve the problem - do not migrate UI libraries unless requested ## common fixes ```html <!-- icon-only button: add aria-label --> <!-- before --> <button><svg>...</svg></button> <!-- after --> <button aria-label="Close"><svg aria-hidden="true">...</svg></button> <!-- div as button: use native element --> <!-- before --> <div onclick="save()">Save</div> <!-- after --> <button onclick="save()">Save</button> <!-- form error: link with aria-describedby --> <!-- before --> <input id="email" /> <span>Invalid email</span> <!-- after --> <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">Invalid email</span> ``` ## review guidance - fix critical issues first (names, keyboard, focus, tool boundaries) - prefer native HTML before adding aria - quote the exact snippet, state the failure, propose a small fix - for complex widgets (menu, dialog, combobox), prefer established accessible primitives over custom behaviorskills/fixing-metadata/SKILL.mdskillShow content (4439 bytes)
--- name: fixing-metadata description: > Audit and fix HTML metadata including page titles, meta descriptions, canonical URLs, Open Graph tags, Twitter cards, favicons, JSON-LD structured data, and robots directives. Use when adding SEO metadata, fixing social share previews, reviewing Open Graph tags, setting up canonical URLs, or shipping new pages that need correct meta tags. version: 1.0.1 license: MIT --- ## Workflow 1. Identify pages with missing or incorrect metadata (titles, descriptions, canonical, OG tags) 2. Audit against the priority rules below — fix critical issues (duplicates, indexing) first 3. Ensure title, description, canonical, and og:url all agree with each other 4. Verify social cards render correctly on a real URL, not localhost 5. Keep diffs minimal and scoped to metadata only — do not refactor unrelated code ## when to apply Reference these guidelines when: - adding or changing page titles, descriptions, canonical, robots - implementing Open Graph or Twitter card metadata - setting favicons, app icons, manifest, theme-color - building shared SEO components or layout metadata defaults - adding structured data (JSON-LD) - changing locale, alternate languages, or canonical routing - shipping new pages, marketing pages, or shareable links ## rule categories by priority | priority | category | impact | |----------|----------|--------| | 1 | correctness and duplication | critical | | 2 | title and description | high | | 3 | canonical and indexing | high | | 4 | social cards | high | | 5 | icons and manifest | medium | | 6 | structured data | medium | | 7 | locale and alternates | low-medium | | 8 | tool boundaries | critical | ## quick reference ### 1. correctness and duplication (critical) - define metadata in one place per page, avoid competing systems - do not emit duplicate title, description, canonical, or robots tags - metadata must be deterministic, no random or unstable values - escape and sanitize any user-generated or dynamic strings - every page must have safe defaults for title and description ### 2. title and description (high) - every page must have a title - use a consistent title format across the site - keep titles short and readable, avoid stuffing - shareable or searchable pages should have a meta description - descriptions must be plain text, no markdown or quote spam ### 3. canonical and indexing (high) - canonical must point to the preferred URL for the page - use noindex only for private, duplicate, or non-public pages - robots meta must match actual access intent - previews or staging pages should be noindex by default when possible - paginated pages must have correct canonical behavior ### 4. social cards (high) - shareable pages must set Open Graph title, description, and image - Open Graph and Twitter images must use absolute URLs - prefer correct image dimensions and stable aspect ratios - og:url must match the canonical URL - use a sensible og:type, usually website or article - set twitter:card appropriately, summary_large_image by default ### 5. icons and manifest (medium) - include at least one favicon that works across browsers - include apple-touch-icon when relevant - manifest must be valid and referenced when used - set theme-color intentionally to avoid mismatched UI chrome - icon paths should be stable and cacheable ### 6. structured data (medium) - do not add JSON-LD unless it clearly maps to real page content - JSON-LD must be valid and reflect what is actually rendered - do not invent ratings, reviews, prices, or organization details - prefer one structured data block per page unless required ### 7. locale and alternates (low-medium) - set the html lang attribute correctly - set og:locale when localization exists - add hreflang alternates only when pages truly exist - localized pages must canonicalize correctly per locale ### 8. tool boundaries (critical) - prefer minimal changes, do not refactor unrelated code - do not migrate frameworks or SEO libraries unless requested - follow the project's existing metadata pattern (Next.js metadata API, react-helmet, manual head, etc.) ## review guidance - fix critical issues first (duplicates, canonical, indexing) - ensure title, description, canonical, and og:url agree - verify social cards on a real URL, not localhost - prefer stable, boring metadata over clever or dynamic - keep diffs minimal and scoped to metadata onlyskills/fixing-motion-performance/SKILL.mdskillShow content (5565 bytes)
--- name: fixing-motion-performance description: Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance. --- # fixing-motion-performance Fix animation performance issues. ## how to use - `/fixing-motion-performance` Apply these constraints to any UI animation work in this conversation. - `/fixing-motion-performance <file>` Review the file against all rules below and report: - violations (quote the exact line or snippet) - why it matters (one short sentence) - a concrete fix (code-level suggestion) Do not migrate animation libraries unless explicitly requested. Apply rules within the existing stack. ## when to apply Reference these guidelines when: - adding or changing UI animations (CSS, WAAPI, Motion, rAF, GSAP) - refactoring janky interactions or transitions - implementing scroll-linked motion or reveal-on-scroll - animating layout, filters, masks, gradients, or CSS variables - reviewing components that use will-change, transforms, or measurement ## rendering steps glossary - composite: transform, opacity - paint: color, borders, gradients, masks, images, filters - layout: size, position, flow, grid, flex ## rule categories by priority | priority | category | impact | |----------|----------|--------| | 1 | never patterns | critical | | 2 | choose the mechanism | critical | | 3 | measurement | high | | 4 | scroll | high | | 5 | paint | medium-high | | 6 | layers | medium | | 7 | blur and filters | medium | | 8 | view transitions | low | | 9 | tool boundaries | critical | ## quick reference ### 1. never patterns (critical) - do not interleave layout reads and writes in the same frame - do not animate layout continuously on large or meaningful surfaces - do not drive animation from scrollTop, scrollY, or scroll events - no requestAnimationFrame loops without a stop condition - do not mix multiple animation systems that each measure or mutate layout ### 2. choose the mechanism (critical) - default to transform and opacity for motion - use JS-driven animation only when interaction requires it - paint or layout animation is acceptable only on small, isolated surfaces - one-shot effects are acceptable more often than continuous motion - prefer downgrading technique over removing motion entirely ### 3. measurement (high) - measure once, then animate via transform or opacity - batch all DOM reads before writes - do not read layout repeatedly during an animation - prefer FLIP-style transitions for layout-like effects - prefer approaches that batch measurement and writes ### 4. scroll (high) - prefer Scroll or View Timelines for scroll-linked motion when available - use IntersectionObserver for visibility and pausing - do not poll scroll position for animation - pause or stop animations when off-screen - scroll-linked motion must not trigger continuous layout or paint on large surfaces ### 5. paint (medium-high) - paint-triggering animation is allowed only on small, isolated elements - do not animate paint-heavy properties on large containers - do not animate CSS variables for transform, opacity, or position - do not animate inherited CSS variables - scope animated CSS variables locally and avoid inheritance ### 6. layers (medium) - compositor motion requires layer promotion, never assume it - use will-change temporarily and surgically - avoid many or large promoted layers - validate layer behavior with tooling when performance matters ### 7. blur and filters (medium) - keep blur animation small (<=8px) - use blur only for short, one-time effects - never animate blur continuously - never animate blur on large surfaces - prefer opacity and translate before blur ### 8. view transitions (low) - use view transitions only for navigation-level changes - avoid view transitions for interaction-heavy UI - avoid view transitions when interruption or cancellation is required - treat size changes as potentially layout-triggering ### 9. tool boundaries (critical) - do not migrate or rewrite animation libraries unless explicitly requested - apply these rules within the existing animation system - never partially migrate APIs or mix styles within the same component ## common fixes ```css /* layout thrashing: animate transform instead of width */ /* before */ .panel { transition: width 0.3s; } /* after */ .panel { transition: transform 0.3s; } /* scroll-linked: use scroll-timeline instead of JS */ /* before */ window.addEventListener('scroll', () => el.style.opacity = scrollY / 500) /* after */ .reveal { animation: fade-in linear; animation-timeline: view(); } ``` ```js // measurement: batch reads before writes (FLIP) // before — layout thrash el.style.left = el.getBoundingClientRect().left + 10 + 'px'; // after — measure once, animate via transform const first = el.getBoundingClientRect(); el.classList.add('moved'); const last = el.getBoundingClientRect(); el.style.transform = `translateX(${first.left - last.left}px)`; requestAnimationFrame(() => { el.style.transition = 'transform 0.3s'; el.style.transform = ''; }); ``` ## review guidance - enforce critical rules first (never patterns, tool boundaries) - choose the least expensive rendering work that matches the intent - for any non-default choice, state the constraint that justifies it (surface size, duration, or interaction requirement) - when reviewing, prefer actionable notes and concrete alternatives over theory
