Create distinctive, production-grade frontend interfaces with strong hierarchy, thoughtful systems, and polished implementation that avoid generic AI aesthetics. Use when the user wants to build or redesign web pages, flows, components, or full app surfaces, or when another better-web-ui skill needs

This skill guides creation of distinctive, production grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. Refactoring UI Operating Model Use this decision order before reaching for effects: 1. Start with a feature, not a shell : Design the specific user task first. Navigation, chrome, and decorative structure should follow the needs of the feature, not the other way around. 2. Establish hierarchy in grayscale : First make the interface clear using spacing, size, weight, contrast, and grouping. If it doesn't work in grayscale, color won't save it. 3. Define systems before details : Use constrained scales for spacing, type, color, radius, and elevation. Limit choices to reduce decision fatigue and make the result feel intentional. 4. Choose personality through concrete levers : Express tone through font choice, color temperature, border radius, and language — not random effects. 5. Polish last : Add color, depth, decoration, motion, and finishing touches only after hierarchy and systems are already working. CRITICAL : Hierarchy beats decoration. Systems beat one off tweaking. Restraint beats trend chasing. Context Gathering Protocol Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. Required context — every design skill needs at minimum: Target audience : Who uses this product and in what context? Use cases : What jobs are they trying to get done? Brand personality/tone : How should the interface feel? Individual skills may require additional context — check the skill's preparation section for specifics. CRITICAL : You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. Gathering order: 1. Check current instructions (instant) : If your loaded instructions already contain a Design Context section, proceed immediately. 2. Check .better web ui.md (fast) : If not in instructions, read .better web ui.md from the project root. If it exists and contains the required context, proceed. 3. Check legacy context files (fallback) : If .better web ui.md does not exist yet, read .better ui.md and then .impeccable.md from the project root. If either exists and contains the required context, proceed, but prefer migrating to .better web ui.md when possible. 4. Run setup (REQUIRED) : If neither source has context, you MUST run $setup NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. Framework & Library Guidance This skill library is intentionally framework agnostic and library agnostic. When implementation details matter, follow this precedence: 1. Detect and match the existing project stack first 2. Respect explicit user choices for new projects second 3. Use the default matrix only when the project is new and unspecified The full precedence order, framework default matrix, problem shorthand, and caveats live in [framework defaults](reference/framework defaults.md). Use that reference whenever you need to decide styling, component libraries, form architecture, table architecture, or virtualization defaults. When the project uses a specific frontend framework or meta framework, consult [framework official docs](reference/framework official docs.md) before making framework specific implementation decisions. For Next.js specifically, if the project includes bundled version matched docs at node modules/next/dist/docs/ , read the relevant local Next.js doc there before coding. Treat those bundled docs as the source of truth for the installed version instead of relying on stale memory. When React based fallback defaults are relevant, use [component and block strategy](reference/component and block strategy.md) to decide when to compose from shadcn/ui primitives, when blocks are an appropriate accelerator, and how to avoid shipping generic library output unchanged. Use [react shadcn accelerators](reference/react shadcn accelerators.md) when the request maps to a curated community component such as theme controls, consent, text motion, testimonial patterns, wheel pickers, or slide actions. When the project does not have a mature component library and you need to build or refine primitives from scratch, use [component anatomy](reference/component anatomy.md) for practical anatomy guidance on custom components such as buttons, cards, checkboxes, dropdowns, tabs, textareas, toasts, toggles, tooltips, accordions, avatars, badges, borders, breadcrumbs, iconography, lists, and submit actions. The more focused component pattern references in this folder — such as accordion, breadcrumb, carousel, slider, date input, date time picker, navigation menu, feature comparison, configurator, and complex table guidance — follow the same default. They are primarily for custom primitives, headless compositions, or plain HTML / CSS / JavaScript implementations. If a mature component library already owns the primitive well, use those references mainly to decide whether the pattern fits, how it should be composed, what defaults and states it needs, and how it should behave responsively around the library component instead of rewriting strong upstream anatomy, semantics, or accessibility behavior. Design Direction Treat design direction as a deliberate constraint system, not a vague tone adjective. Feature first : Identify the primary workflow or moment this screen must support before designing the shell around it. Purpose : What problem does this interface solve? Who uses it? Brand fit : What should this feel like for this specific company, product, audience, and promise? Content fit : How much copy, proof, imagery, navigation, and product detail must this layout support? Constraints : Technical requirements, performance budget, accessibility, and maintenance cost. Differentiation : What makes this memorable without making it harder to use? Follow [design directions](reference/design directions.md) when choosing or preserving a style. That reference defines the approved website directions for this library, how to choose among them, where louder styles should stay selective, and which styles this library should not generate. Use these rules by default: Existing project first : if the project already has a visual system, preserve its typography, palette, spacing rhythm, surface language, and interaction tone unless the user explicitly asks for a rebrand or larger style shift. Broad new project requests choose from approved directions : if the user asks for a new landing page, marketing page, or several distinct directions without naming a style, select from the approved design directions based on the product idea and brand fit instead of inventing random vibe labels. Choose structure before effects : establish one primary structural direction first, then optionally add one supporting surface, typographic, motion, or expressive modifier. Keep core flows clearer than the shell : even when the marketing layer is more expressive, forms, tables, settings, auth, pricing comparisons, and error states should usually stay closer to minimalist, Swiss, flat, or similarly clarity first behavior. Never default to retro / cyber / synthwave / terminal aesthetics : do not volunteer those directions from broad prompts in this library. Apply a little pessimism up front: design the smallest useful version first do not imply functionality that is not ready to exist use rough exploration to make decisions quickly, then build the real thing early and iterate in short cycles lock typography, spacing, hierarchy, and CTA structure before layering on heavier style treatments Use [design process](reference/design process.md) when the request is still fuzzy, when layout and flow decisions need to be clarified before polish, or when you need a cleaner progression from wireframe to styleguide to prototype. Use [design principles](reference/design principles.md) when the team needs clearer shared defaults, stronger product values, or a more durable decision making point of view that explains both what to do and what to avoid. Use [ux strategy](reference/ux strategy.md) when the work needs clearer user segment focus, priorities, high value UX actions, feasibility framing, or risk aware alignment with product and business goals before screen level execution. Use [audience sensitive design](reference/audience sensitive design.md) when the audience itself changes the UX — for example when designing for Gen Z, children, parents, older adults, or any audience with distinct device habits, trust patterns, or accessibility needs. CRITICAL : Choose a clear conceptual direction and execute it with precision. Intentionality beats intensity. Typography, spacing, hierarchy, and content structure should still work even if decorative effects are temporarily removed. Then implement working code that is: Production grade and functional Visually striking and memorable Cohesive with a clear aesthetic point of view Meticulously refined in every detail Frontend Aesthetics Guidelines Typography → Consult [typography reference](reference/typography.md) for scales, pairing, loading strategies, and font selection heuristics. Use [text hierarchy and readability](reference/text hierarchy and readability.md) for line length, line height, baseline alignment, label/value treatment, link emphasis, numeric alignment, and semantic vs visual hierarchy. Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. DO : Use a constrained, hand crafted type scale; use modular ratios as inspiration, not as a prison DO : Build hierarchy with weight, color, and spacing — not size alone DO : Align mixed font sizes by their baseline when they appear on the same line DO : Tighten headlines carefully and add letter spacing to all caps text when readability benefits DO : When a hero or display headline wraps to multiple lines, reduce the size before crushing the leading; keep enough line height and block padding that ascenders and descenders never clip DON'T : Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults DON'T : Use monospace typography as lazy shorthand for "technical/developer" vibes DON'T : Use em based type scales for nested UI — they drift off system fast DON'T : Center long form text; center works for short statements, not dense reading DON'T : Put large icons with rounded corners above every heading—they rarely add value and make sites look templated Color & Theme → Consult [color reference](reference/color and contrast.md) for OKLCH, palettes, and dark mode. Use [colorblindness UX](reference/colorblindness ux.md) when semantic states, charts, active states, or category colors must remain distinguishable under color vision deficiencies. Use [color ramp workflow](reference/color ramp workflow.md) when building or repairing ramps. Use [semantic color](reference/semantic color.md) when color is carrying status, alerts, or meaning. Use [data visualization](reference/data visualization.md) when presenting data through charts, graphs, or plots. Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly distributed palettes. DO : Start in grayscale, then layer color on top of an already clear hierarchy DO : Use modern CSS color functions (oklch, color mix, light dark) for perceptually uniform, maintainable palettes DO : Define shades up front — greys need a real scale, primary and accent colors need multiple usable stops DO : Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion DO : Prefer dark text on light tint

frontend-design