/ui-design

UI Design Guidelines

Use when designing or building new UI, or when a workflow tells you to load design guidance before editing UI code.

Load Contract

• Before writing UI code, scan the index below and load the rule files supported by concrete elements in the request or target UI. Do not load unrelated component rules as generic inspiration.
• Three mappings are not obvious from a filename, so treat them as direct hits rather than inspiration: a hero section loads heading-group rules, an individual page section loads landing-page rules, and a dashboard card or list item loads surface rules.
• Load reference modules only when the request needs that material.

General Design Principles

• Every layout must adapt from mobile to desktop via responsive breakpoint classes; see Responsive Design for detailed rules.

Rule Files

Follow these when designing or building UI:

• Avatars: profile photos, user thumbnails, people images in testimonials, team sections, comments, anywhere a person's face appears
• Badges: tags, pills, status indicators, labels, chips, with or without icons
• Border Radius: rounding corners on cards, containers, buttons, images, screenshots, and nested elements with concentric radii
• Buttons: primary/secondary buttons, CTAs, icon buttons, destructive/danger actions, touch targets
• Colors: brand colors, accent colors, palette selection, default color choices
• Copywriting: punctuation, periods, headings, taglines, subtitles, descriptions, list items
• Custom Fonts: loading custom fonts via <link> or @import url(), registering in @theme with --font-*, font-feature-settings, font-variation-settings
• Dark Mode: dark theme styling, contrast ratios, colored panels, card backgrounds, shadow removal, decorative elements, heading colors, dark-mode image handoff, inline/external SVG dark-mode handling
• Description Lists: <dl>/<dt>/<dd> styling, term/detail contrast and font-weight hierarchy
• Dashboards: dashboard layouts, stat grids, KPI cards, metric cards, admin panels, analytics views, key statistics, charts, summary data
• Feature Lists: feature grids, feature sections, benefit lists, multiple features with titles and descriptions
• Flexbox Layout: flex containers, flex children, min-w-0 shrinking, shrink-0 on icons/images/SVGs, fluid vs fixed layouts, sidebar + content patterns, flex-1 or flexible sizing
• Footers: page footers, footer logos, footer links, social media icons, site-wide bottom navigation
• Form Controls: inputs, selects, checkboxes, radio buttons, login/sign-up/checkout forms, search bars, newsletter sign-up fields, input + button combos
• General: general markup rules (class placement on block vs inline elements, redundant display classes, role="list") and Tailwind CSS authoring rules (utility preferences, spacing conventions, arbitrary value syntax, variant patterns, deprecated utilities) across all components
• Headers: site headers, navigation bars, navbars, top bars, logos, mobile menus, hamburger menus
• Heading Groups: headline, subheadline, optional eyebrow at the top of marketing and landing page sections (hero, features, team, pricing, CTA); not blog posts, articles, or editorial content
• Icons: SVG icons, icon sizing, alignment with text, Heroicons, filled vs stroked icons, inline list icons like checkmarks
• Images: photos, thumbnails, screenshots, app UI mockups, image borders/outlines
• Landing Pages: full-page consistency for buttons, fonts, containers, border radius, column gaps, layout alignment, responsive constraints across all sections
• Login Pages: login, sign-in, sign-up, and authentication page backgrounds and layout
• Logo Clouds: logo grids, client logo rows, partner logos, trust bars, brand-logo collections
• Materials: translucent chrome, backdrop-filter layers, material weight as hierarchy, vibrancy text legibility, scroll edge effects, grain against banding, reduced-transparency fallbacks
• Navigation: sidebar nav, header nav, mobile nav menus, tabs, tab bars, vertical menus, active/selected states, current-page indicators
• Pagination: page number links, previous/next buttons, paged navigation controls
• Placeholder Content: dummy logos, placeholder avatars, app screenshots, wallpapers, and the assets API for generating realistic placeholder content
• Prose Content: styling raw HTML from markdown, CMS, or database content where Tailwind classes can't be applied to individual elements; replaces @tailwindcss/typography with a custom .prose class
• Pricing Cards: pricing tiers, pricing tables, plan cards, emphasized/popular plan styling, button alignment across columns
• Responsive Design: responsive breakpoints, container queries, @container placement, mobile-to-desktop layout adaptation
• SVG: inline SVG elements, xmlns attributes, SVG color styling (fill, stroke, currentColor), SVG markup conventions in HTML/JSX
• Section Layout: left-aligned vs centered section layouts, content width constraints, aligning containers across stacked page sections, spacing rhythm and grouping, sizing a panel to its task, single ownership of shared chrome
• Shadows: box shadows on cards, modals, popovers, dropdowns, elevated elements, including border-pairing rules
• Surfaces: cards, wells, borders, dividers, and white space as surface treatments; when to use cards vs subtle dividers vs recessed backgrounds vs no separation; applies to stat grids, dashboard metrics, list items, sidebars, any content grouping decision
• Tables: data tables, comparison tables, table headings, row dividers, table containers
• Team Sections: team grids, team member cards, staff listings, about-us sections, people galleries with photos and bios
• Testimonials: customer quotes, reviews, social proof sections, testimonial cards, hanging punctuation, attribution layout
• Typography: font weights, line heights, text sizes, heading styles, max-width constraints, text-pretty/text-balance, tracking, eyebrow text, when to omit a label, link styling in dense UI

Reference Modules

Load these only when the request needs the reference:

• Assets API: placeholder asset URLs, query parameters, examples for marks, avatars, logos, screenshots, wallpapers
• Font Recommendations: optional font suggestions when the user wants help choosing a font or wants to try different fonts across design variations; includes sourcing notes, feature settings, and per-font tips

Design Conflicts

When a rule says ⚠️ ask-user, the user's input conflicts with a guideline. Don't silently override or follow it. Instead:

1. Use the AskUserQuestion tool to flag the conflict.
2. Explain what the guideline recommends and why the input doesn't fit.
3. Offer a concrete alternative (e.g. a rewritten version of their copy, a different layout).
4. Wait for the user to choose before proceeding.

Never skip this, even when it feels minor: the user should always be aware when their input bumps up against a design rule.