absolute-ui

name	absolute-ui
version	0.5.0
description	Build polished, intentional UIs with concrete CSS/Tailwind values — typography, color, layout, spacing, dark mode, accessibility, animations, components. Encodes specific, opinionated rules with exact values, not vague advice. Covers buttons, cards, forms, tables, navigation, dashboards, landing pages, onboarding, and more. Triggers on "absolute ui", "design a UI", "style this component", "make this less like AI slop", "fix the spacing/typography/color", "dark mode", "design a pricing page", "make this look better".
category	workflow
tags	["workflow","ui","design","css","tailwind","accessibility","typography"]
platforms	["claude-code","gemini-cli","openai-codex","mcp"]
user-invocable	true
argument-hint	[target]
license	MIT
maintainers	[{"github":"maddhruv"}]

Start your first response with the 🧢 emoji.

Absolute UI

A comprehensive design system knowledge base for building UIs that feel crafted by a senior designer, not generated by a prompt. This skill encodes specific, opinionated rules - exact spacing values, proven color ratios, real typography scales, and battle-tested component patterns. Every recommendation is actionable with concrete CSS/Tailwind values, not vague advice like "make it clean."

The difference between AI slop and a polished UI comes down to constraint and restraint - fewer colors used with intention, consistent spacing from a scale, typography that creates hierarchy without screaming, and micro-interactions that feel responsive without being distracting.

---

When to use this skill

Trigger this skill when the user:

• Asks to build or style a UI component (button, card, form, table, nav)
• Needs help with layout, spacing, or grid decisions
• Wants to implement dark mode or theme switching
• Asks about typography, font choices, or text styling
• Needs accessible and WCAG-compliant designs
• Wants landing page, onboarding, or conversion-focused layouts
• Asks about animations, transitions, or micro-interactions
• Needs help with responsive design or mobile navigation
• Wants feedback patterns (toasts, tooltips, loading states)
• Asks to make something "look better" or "more professional"

Do NOT trigger this skill for:

• Backend logic, API design, or database schema questions
• Brand identity or logo design (this is implementation, not branding)

---

Read config first

Before writing any markup or CSS, read cached config: if .absolute.config.json or ~/.absolute/config.json exists (from /absolute init), resolve the effective config (project file → global projects["<cwd>"] → global defaults) and adopt conventions.ui:

• framework — generate for the project's framework (react/vue/svelte), not a default.
• styling — use the project's system (tailwind / css-modules / styled-components / vanilla) instead of assuming Tailwind.
• iconLibrary — pull icons from the project's library (principle 7 mandates real icons); don't introduce a different one.
• componentLib — build on the existing component library (shadcn/mui/chakra) when set.
• tokensPath — read existing design tokens from this file and extend them, don't invent a parallel scale.

Detect from package.json deps only for whatever config doesn't supply; with no config, soft-suggest init and detect on the fly.

---

Design thinking

Before writing CSS, commit to an aesthetic direction. The #1 cause of generic-looking UIs is starting with code instead of intent.

1. Start from user intent, not structure - Don't begin with headers, footers, or layout scaffolding. Ask: "What is the user trying to do?" If they're searching for accommodations, a search bar is the natural starting point. Only expand UI as user intent expands. For many pages, the core is a heading, an input, and a button - that's all you needed.
2. Choose a tone - Pick one that fits the context: brutalist, editorial, retro-futuristic, organic, luxury, playful, industrial, art deco, soft/pastel, minimalist-sharp. These are starting points - blend and invent your own. See references/style-catalog.md for 25 concrete options.
3. Define what's memorable - What's the one visual choice someone will remember? An unusual color, dramatic typography, a bold layout break, atmospheric texture?
4. Creativity is connecting, not inventing - Study top-tier existing designs in your domain. Gather 3-5 inspirations, note what you like about each, then combine those elements in your own way. Step away before designing - new ideas emerge when you return.
5. Vary between projects - Every design should feel different. If your last 3 outputs used the same fonts, colors, and layout patterns, you're producing slop.

---

Key principles

1. Use a spacing scale, never arbitrary values - Pick a base unit (4px or 8px) and only use multiples: 4, 8, 12, 16, 24, 32, 48, 64, 96. Tailwind's default scale does this. Random padding like 13px or 27px is the #1 tell of amateur UI.

2. Limit your palette to 1 primary + 1 neutral + 1 accent - More colors = more chaos. Use 5-7 shades of your primary (50-900), a full neutral gray scale, and one accent for destructive/success states. Never more than 3 hues on a single screen.

3. Create hierarchy through contrast, not decoration - Size, weight, color, and spacing create hierarchy. You should never need borders, shadows, AND color differences simultaneously. One or two signals per level of hierarchy. Key insight: to emphasize something, often deemphasize competing elements instead of making the target louder.

4. Every interactive element needs 4 states - Default, hover, active/pressed, and disabled. If you skip any state, the UI feels broken. Focus states are mandatory for accessibility.

5. Whitespace is a feature, not wasted space - Generous padding makes UIs feel premium. Cramped UIs feel cheap. Workflow: start with too much spacing, view the design as a whole, then reduce until it feels right. Users scan the entire UI before focusing on details - space that feels excessive when you're zoomed into one element looks correct at page level.

6. Consistency within, personality across - Within a project, use the same border-radius, shadow scale, and transition timing everywhere. But each project should have its own distinct personality - different fonts, colors, and spatial feel. Consistency without character is how AI slop is made.

7. Use real icons, never emojis - Unicode emojis (e.g. ✅, ⚡, 🔥, 📊) render inconsistently across operating systems and browsers, cannot be styled with CSS (no size, color, or stroke control), break visual consistency, and hurt accessibility. Always use a proper icon library - Lucide React (recommended), React Icons, Heroicons, Phosphor, or Font Awesome. Icons from these libraries are SVG-based, styleable, consistent, and accessible.

8. Backgrounds need atmosphere - Flat solid-color backgrounds (#fff, #f9fafb) are the default of every AI-generated UI. Use subtle gradient meshes, noise/grain overlays, geometric patterns, or tinted surfaces to create depth. Texture should be felt, not seen - if you notice it consciously, it's too much.

---

Core concepts

The 8px grid - All spacing, sizing, and layout decisions snap to an 8px grid. Component heights: 32px (small), 40px (medium), 48px (large). Padding: 8px, 12px, 16px, 24px. Gaps: 8px, 16px, 24px, 32px. This single rule eliminates 80% of "why does this look wrong" problems.

Visual weight - Every element has visual weight determined by size, color darkness, border thickness, and shadow. A page should have one clear heavyweight (the CTA or primary content), with everything else progressively lighter. Squint at your page - if nothing stands out, your hierarchy is flat.

The 60-30-10 rule - 60% dominant color (background/neutral), 30% secondary (cards, sections), 10% accent (CTAs, active states). This ratio works for any color scheme and prevents the "everything is colorful" trap.

Optical alignment - Mathematical center doesn't always look centered. Text in buttons needs 1-2px more padding on top visually. Icons next to text need optical adjustment. Always trust your eyes over the inspector.

Progressive disclosure - Don't show everything at once. Start with the essential action, reveal complexity on demand. This applies to forms (multi-step > one long form), settings (basic > advanced), and navigation (primary > secondary > tertiary).

Gestalt: similarity and proximity - The brain processes the whole before the parts. Use consistent shape, size, and color to signal "these belong together" (similarity). Use spacing to group related elements and separate unrelated ones (proximity). If the design isn't scannable within seconds, the gestalt is broken.

Depth for character - Use shadows to replace solid borders, subtle gradients to replace flat fills, and cards to elevate bland elements. The closer something feels to the user (higher elevation), the more attention it attracts. One accent gradient or colored shadow can add excitement without complexity.

Context overrides tags - Not all H1s should be the same size. An H3 might be larger than an H2 in a different context. HTML tags define semantics; visual hierarchy depends on what the user needs to see first in that specific layout.

---

Common tasks

Style a button hierarchy

Every app needs 3 button levels: primary (filled), secondary (outlined), and ghost (text-only). Never use more than one primary button per visual section.

/* Primary - solid fill, high contrast */
.btn-primary {
  background: var(--color-primary-600);
  color: white;
  padding: 10px 20px;
  border-radius: 8px;
  font-weight: 500;
  font-size: 14px;
  border: none;
  transition: background 150ms ease, transform 100ms ease;
}
.btn-primary:hover { background: var(--color-primary-700); }
.btn-primary:active { transform: scale(0.98); }

/* Secondary - outlined */
.btn-secondary {
  background: transparent;
  color: var(--color-primary-600);
  padding: 10px 20px;
  border: 1.5px solid var(--color-primary-200);
  border-radius: 8px;
  font-weight: 500;
  font-size: 14px;
  transition: border-color 150ms ease, background 150ms ease;
}
.btn-secondary:hover {
  border-color: var(--color-primary-400);
  background: var(--color-primary-50);
}

/* Ghost - text only */
.btn-ghost {
  background: transparent;
  color: var(--color-gray-600);
  padding: 10px 20px;
  border: none;
  border-radius: 8px;
  font-weight: 500;
  font-size: 14px;
}
.btn-ghost:hover { background: var(--color-gray-100); }

Button height should be 36px (sm), 40px (md), or 48px (lg). Never smaller than 36px for touch targets.

Set up a type scale

Use a modular scale with ratio 1.25 (major third). Base size: 16px.

:root {
  --text-xs: 0.75rem;    /* 12px - captions, labels */
  --text-sm: 0.875rem;   /* 14px - secondary text, metadata */
  --text-base: 1rem;     /* 16px - body text */
  --text-lg: 1.125rem;   /* 18px - lead paragraphs */
  --text-xl: 1.25rem;    /* 20px - card titles */
  --text-2xl: 1.5rem;    /* 24px - section headings */
  --text-3xl: 1.875rem;  /* 30px - page titles */
  --text-4xl: 2.25rem;   /* 36px - hero subheading */
  --text-5xl: 3rem;      /* 48px - hero heading */

  --leading-tight: 1.25;  /* headings */
  --leading-normal: 1.5;  /* body text */
  --leading-relaxed: 1.75; /* small text, captions */
}

Limit to 2 font families max. Pair a distinctive display font with a refined body font - avoid defaulting to Inter, Roboto, or Space Grotesk. See references/typography.md for aesthetic-specific pairings.

Build a responsive layout with CSS Grid

/* Content-first responsive grid - no media queries needed */
.grid-auto {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(100%, 320px), 1fr));
  gap: 24px;
}

/* Holy grail layout */
.page-layout {
  display: grid;
  grid-template-columns: minmax(240px, 1fr) minmax(0, 3fr) minmax(200px, 1fr);
  gap: 32px;
  max-width: 1280px;
  margin: 0 auto;
  padding: 0 24px;
}

/* Stack on mobile */
@media (max-width: 768px) {
  .page-layout {
    grid-template-columns: 1fr;
  }
}

Max content width: 1280px for apps, 720px for reading content. Never let text lines exceed 75 characters.

Implement dark mode properly

:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f9fafb;
  --bg-tertiary: #f3f4f6;
  --text-primary: #111827;
  --text-secondary: #6b7280;
  --border: #e5e7eb;
  --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg-primary: #0f172a;
    --bg-secondary: #1e293b;
    --bg-tertiary: #334155;
    --text-primary: #f1f5f9;
    --text-secondary: #94a3b8;
    --border: #334155;
    --shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
  }
}

Never just invert colors. Dark mode backgrounds should be dark blue-gray (#0f172a, #1e293b), not pure black. Reduce white text to #f1f5f9 (not #ffffff) to prevent eye strain. Shadows need higher opacity in dark mode.

Add a toast notification system

.toast {
  position: fixed;
  bottom: 24px;
  right: 24px;
  padding: 12px 20px;
  border-radius: 8px;
  font-size: 14px;
  font-weight: 500;
  display: flex;
  align-items: center;
  gap: 8px;
  animation: slide-up 200ms ease-out;
  z-index: 50;
}

.toast-success { background: #ecfdf5; color: #065f46; border: 1px solid #a7f3d0; }
.toast-error { background: #fef2f2; color: #991b1b; border: 1px solid #fecaca; }
.toast-info { background: #eff6ff; color: #1e40af; border: 1px solid #bfdbfe; }

@keyframes slide-up {
  from { transform: translateY(16px); opacity: 0; }
  to { transform: translateY(0); opacity: 1; }
}

Auto-dismiss success toasts after 3-5s. Error toasts should persist until dismissed. Stack multiple toasts with 8px gap. Max 3 visible at once.

Create a data table

.table {
  width: 100%;
  border-collapse: collapse;
  font-size: 14px;
}

.table th {
  text-align: left;
  padding: 12px 16px;
  font-weight: 500;
  font-size: 12px;
  text-transform: uppercase;
  letter-spacing: 0.05em;
  color: var(--text-secondary);
  border-bottom: 2px solid var(--border);
}

.table td {
  padding: 12px 16px;
  border-bottom: 1px solid var(--border);
  color: var(--text-primary);
}

.table tr:hover td {
  background: var(--bg-secondary);
}

Right-align numbers. Left-align text. Don't stripe rows AND add hover - pick one. Fixed headers for tables taller than the viewport. Add horizontal scroll wrapper for mobile, never let tables overflow.

---

Anti-patterns / common mistakes

Mistake	Why it's wrong	What to do instead
Using pure black (#000) on white (#fff)	Too harsh, causes eye strain, looks unnatural	Use #111827 on #fff or #f1f5f9 on #0f172a
Different border-radius on every component	Destroys visual consistency, looks auto-generated	Pick one radius (8px) and use it everywhere
Shadows on everything	Visual noise, no hierarchy, feels heavy	Reserve shadows for elevated elements (modals, dropdowns, cards)
Rainbow of colors	No hierarchy, overwhelming, unprofessional	Max 3 hues: primary, neutral, accent. 60-30-10 rule
Tiny click targets on mobile	Fails WCAG, frustrates users, increases errors	Minimum 44x44px touch targets (48px preferred)
Animating everything	Distracting, feels gimmicky, hurts performance	Only animate what changes state. 150-300ms transitions max
Centering everything	Kills readability, looks like a PowerPoint slide	Left-align body text. Center only hero headlines and CTAs
Inconsistent spacing	Most obvious tell of unpolished UI	Use a 4/8px spacing scale. Same gap everywhere for same context
Using emojis as icons	Render differently across OS/browsers, cannot be styled, break visual consistency, poor a11y	Use a real icon library: Lucide React, React Icons, Heroicons, Phosphor, or Font Awesome
Generic font stack (Inter, Roboto, Arial)	Screams "AI generated this", zero personality	Choose fonts that match an aesthetic direction. See references/typography.md
Purple/indigo gradient on white	The #1 AI-generated color cliche	Pick context-specific brand colors. Finance: navy+gold. Creative: coral+teal
Predictable symmetric layouts everywhere	Every section is centered 3-column grid, looks templated	Use asymmetry, overlapping elements, and grid-breaking for marketing pages
Flat solid-color backgrounds	No atmosphere, no depth, feels like a wireframe	Add gradient meshes, subtle grain, or geometric patterns. See references/atmosphere-and-texture.md
Multi-hue gradients (blue+green, etc.)	Clashing colors, looks amateur	If using gradients, stick to lighter/darker shades of the SAME hue. Or just use a flat color
Redundant UI elements	Arrows that duplicate swipe, borders on already-differentiated elements	Remove anything that doesn't add function. Each element must earn its place
AI-repeated KPIs / metrics	Same stats shown 2-3 times on one page	Show each metric once, in the most relevant location
Every action as a visible button	Cards with 4+ exposed buttons, overwhelming	Collapse secondary actions into a triple-dot context menu
Gradient profile circles with initials	Screams "AI placeholder", never seen in production apps	Use real avatar upload with initials as fallback (flat bg, no gradient)
Sparse create forms as full pages	AI gives a form 3 fields but an entire page of space	Use a modal for simple forms, collapse advanced options by default
Landing pages with only text + icons	No visual proof the product exists, feels like a template	Use real product screenshots (skewed, shadowed) instead of generic icons

---

Gotchas

1. CSS custom properties in dark mode require explicit overrides at the right scope - Setting --bg-primary on :root works, but if a component is inside a portal or shadow DOM, it may not inherit the theme variables. Always test theme switching in modals, dropdowns, and third-party widget wrappers.

2. Tailwind's purge/content config missing component paths causes production CSS to be empty - In a monorepo or when UI components live outside the src/ directory, Tailwind will strip their classes from the production bundle. Every path that contains Tailwind classes must be listed in content in tailwind.config.js.

3. transform: scale() on buttons clips focus rings and overflow shadows - Using scale(0.98) on :active is a common polish trick, but if the button has box-shadow for a focus ring, the shadow gets clipped by the parent's overflow. Use outline-offset instead of box-shadow for focus indicators on transformed elements.

4. min-height: 100vh breaks on mobile Safari - Mobile browsers include the browser chrome in 100vh, causing content to be cut off below the fold. Use min-height: 100dvh (dynamic viewport height) for full-screen layouts on mobile. Add a 100vh fallback for older browsers.

5. Grid auto-fill vs auto-fit produces visually different results on sparse grids - auto-fill creates empty columns to fill the row; auto-fit collapses them so items stretch. Using auto-fill when you expect items to fill the width produces a grid that stops at the last item with empty whitespace. Use auto-fit for responsive grids that should expand to fill.

6. Design for real content, not perfect content - What happens when a title is 3x longer than expected? When an icon sits on a bright image? When a username has 40 characters? Truncate long text with text-overflow: ellipsis, add contrast backgrounds behind icons on images, and test with real-world data, not lorem ipsum. Edge cases are where amateur UIs break.

---

References

For detailed guidance on specific UI topics, read the relevant file from the references/ folder:

• references/buttons-and-icons.md - Button hierarchy, icon sizing, icon-text pairing, states
• references/color-and-theming.md - Color theory, palette generation, dark/light mode, semantic tokens
• references/visual-hierarchy.md - F/Z patterns, focal points, emphasis techniques, whitespace
• references/grids-spacing-and-layout.md - Grid systems, spacing scales, max-widths, layout patterns
• references/onboarding.md - First-run experience, progressive disclosure, empty states, tutorials
• references/tables.md - Data tables, sorting, pagination, responsive tables, number formatting
• references/typography.md - Type scales, font pairing, line height, measure, vertical rhythm
• references/accessibility.md - WCAG 2.2, ARIA patterns, keyboard nav, screen readers, contrast
• references/performance.md - Core Web Vitals, image optimization, font loading, lazy loading
• references/responsiveness-and-mobile-nav.md - Breakpoints, mobile-first, touch targets, navigation
• references/landing-pages.md - Hero sections, CTAs, social proof, conversion patterns, fold
• references/shadows-and-borders.md - Elevation scale, border usage, card design, dividers
• references/feedback-and-status.md - Toasts, tooltips, modals, loading states, empty states, errors
• references/micro-animations.md - Motion principles, transitions, hover effects, scroll animations
• references/forms-and-inputs.md - Text inputs, selects, checkboxes, radios, toggles, file upload, validation
• references/navigation.md - Sidebars, tabs, breadcrumbs, command palettes, mega menus, pagination
• references/dashboards.md - KPI cards, chart containers, filter bars, dashboard grids, real-time updates
• references/images-and-media.md - Avatars, galleries, carousels, video, aspect ratios, placeholders
• references/cards-and-lists.md - Card variants, list views, infinite scroll, virtualization, skeletons
• references/microcopy-and-ux-writing.md - Button labels, error messages, empty states, confirmation copy
• references/scroll-patterns.md - Sticky elements, scroll-snap, infinite scroll, scrollbar styling
• references/design-tokens.md - Token naming, CSS custom properties, theme architecture, multi-brand
• references/atmosphere-and-texture.md - Gradient meshes, noise/grain, glassmorphism, geometric patterns, depth effects
• references/style-catalog.md - 25 UI styles (glassmorphism, brutalism, aurora, etc.) with effects, best-for, quick-pick table
• references/product-type-guide.md - 35 product types mapped to style, colors, fonts, and landing patterns
• references/palette-recipes.md - 4 production-ready OKLCH palettes (SaaS, e-commerce, editorial, fintech), color-mix(), hue reference
• references/animation-libraries.md - Framer Motion, GSAP, spring physics, easing library, performance rules

Only load a references file if the current task requires it - they are long and will consume context.

---

Pre-delivery checklist

Before shipping any UI, verify:

• Visual: Consistent spacing scale, single border-radius value, max 3 color hues, 4-5 text sizes only
• Interaction: All interactive elements have hover/active/focus states, 44px+ touch targets on mobile
• Dark mode: No pure black, sufficient contrast, shadows adjusted, images dimmed
• Layout: Content max-width enforced, mobile-first responsive, safe-area padding on mobile
• Accessibility: 4.5:1 contrast, focus-visible rings, semantic HTML, ARIA where needed, keyboard navigable
• Personality: Fonts match aesthetic direction (not generic defaults), colors fit the product context
• States: Every screen has empty, loading, success, and error states - not just the happy path
• Flow: Each screen answers "how did the user get here?" and "what do they need next?"

---

Companion commands

Sibling commands in this skill pair well with ui:

• /absolute work — plan and build the feature this UI belongs to.
• /absolute simplify — clean up the component diff before committing.
• /absolute docs — document the components or design system.

Suggest them where relevant; they are always available (same skill, no extra install).