syahiidkamil/super-ui-ux-design
Complete UI/UX design capability — a wiki-style knowledge map of design theory (UX laws, Nielsen heuristics, usability, visual hierarchy, typography, contrast/WCAG, design systems, aesthetics-vs-conversion) fused with a hands-on execution playbook for building distinctive, production-grade frontend interfaces. Use when designing or building any UI (websites, landing pages, dashboards, components, apps), reviewing or critiquing UI/UX, diagnosing why a design doesn't convert, or styling/beautifying web interfaces. Grounds every visual decision in UX principles and avoids generic AI aesthetics.
npx skills add https://github.com/syahiidkamil/Software-Engineer-AI-Agent-Atlas --skill super-ui-ux-design
> A wiki-style knowledge map. Each section is a node. Follow the links, build the schema in your head, then go break it against real users.
>
> Format notes: Internal links like Visual Hierarchy jump between nodes. Mermaid blocks render in Obsidian, GitHub, Notion, and most modern markdown viewers.
Start here. Everything below hangs off this tree.
mindmap
root((DESIGN))
Problem Solving
Define the problem
Constraints
Trade-offs
Iteration
UX["UX (Experience)"]
Research
Information Architecture
Interaction Design
Usability
Mental Models
UX Laws & Heuristics
UI["UI (Interface)"]
Visual Hierarchy
Layout & Grids
Typography
Color & Contrast
Components
Design Systems
Tokens
Components
Patterns
Documentation
Business Layer
Conversion
Retention
Trust & Credibility
Aesthetics vs Performance
Learning Layer
Constructivism
Schemata
Mental Models
Jakob's Law
Definition: Design is the intentional shaping of something (a product, a screen, a service, a process) to achieve a purpose under constraints.
The keyword is *intentional*. Decoration happens to look nice. Design exists to *do* something.
Herbert Simon, in *The Sciences of the Artificial*, framed it roughly as: anyone who devises a course of action to change an existing situation into a preferred one is designing. By that definition, a doctor writing a treatment plan is designing. So is an engineer, a teacher, and yes, the person arranging buttons on a checkout page.
So... is design about problem solving?
Yes, with one important nuance.
Design *is* problem solving, but it's a specific flavor of it. Most design problems are what theorists call wicked problems (Rittel & Webber, 1973):
This is why design is iterative by nature. You don't "solve" a checkout flow the way you solve a math equation. You propose, test, learn, and revise.
flowchart LR
A[Existing Situation] -->|"Understand the problem"| B[Problem Definition]
B -->|"Generate options"| C[Proposed Solution]
C -->|"Test with reality"| D{Did it work?}
D -->|"No / Partially"| B
D -->|"Yes"| E[Preferred Situation]
E -.->|"World changes, new problems"| A
> ⚠️ The nuance: "Design = problem solving" is true but incomplete. Design also involves *problem finding* (framing what's actually wrong) and *meaning making* (why should anyone care?). A perfectly solved wrong problem is still a failure.
See also: The Double Diamond, Wicked problems vs puzzles
You asked about Constructivism and schemata. Both matter twice here: once for *how you learn design*, and once for *how your users experience your design*.
Definition: Knowledge isn't transferred into your head like a file copy. You *construct* it by connecting new information to what you already know. Key figures: Jean Piaget (cognitive constructivism), Lev Vygotsky (social constructivism).
Piaget's two core mechanisms:
| Mechanism | What happens | Design-learning example |
|---|---|---|
| Assimilation | New info fits into an existing schema | "Oh, a design token is just a variable. I know variables." |
| Accommodation | New info breaks the schema, forcing you to rebuild it | "Wait, beautiful design *lowered* conversion? My schema 'pretty = good' is wrong." |
Definition: A schema (plural: *schemata*) is an organized mental framework: a cluster of related concepts, expectations, and patterns. The term comes from Piaget and from Frederic Bartlett's memory research (1932).
A wiki is basically a schema made visible. Nodes, links, hierarchy. That's why this document is wiki-shaped: the format mirrors the cognitive structure you're trying to build.
Here is the punchline. In UX, a user's schema is called a mental model, and it's one of the most powerful forces in interface design.
flowchart TD
A["Schema Theory<br/>(Piaget, Bartlett)"] --> B["Mental Models<br/>(how users THINK a system works)"]
B --> C["Jakob's Law<br/>'Users spend most of their time on OTHER sites'"]
C --> D["Design implication:<br/>Match conventions unless you have<br/>a very good reason not to"]
B --> E["Norman's Gulf of Execution<br/>(user can't figure out HOW to act)"]
B --> F["Norman's Gulf of Evaluation<br/>(user can't tell WHAT happened)"]
E --> G[Confusion, abandonment]
F --> G
When your interface matches the user's schema, it feels "intuitive." When it violates the schema, the user must *accommodate* (rebuild their mental model), and accommodation costs effort. Users mostly refuse to pay that cost. They just leave.
> 💡 Rule of thumb: "Intuitive" is not a property of your design. It's a property of the *match between your design and the user's existing schemata.*
See also: UX Laws, Why ugly sites convert
UX (User Experience): The *entire* journey: how someone discovers, learns, uses, struggles with, and feels about a product. UX includes things you never see on screen: loading speed, support emails, the pricing page, the cancellation flow.
UI (User Interface): The concrete surface a person touches: screens, buttons, typography, colors, spacing, motion.
A classic way to relate them:
flowchart TB
subgraph UX["UX — the whole experience"]
direction TB
R[Research & Strategy] --> IA[Information Architecture]
IA --> IXD[Interaction Design]
IXD --> UI_node
subgraph UI_node["UI — the visible surface"]
V[Visual Design]
T[Typography]
C[Color & Contrast]
CO[Components]
end
IXD --> U[Usability Testing]
U --> R
end
Common metaphor: UX is the architecture and structural engineering of a house; UI is the interior finishing. A gorgeous interior in a house with no plumbing is still a bad house. (And yes, the metaphor leaks: in practice UI decisions feed back into UX. The layers talk to each other.)
| | UX | UI |
|---|---|---|
| Core question | Does this solve the right problem, smoothly? | Is this clear, legible, and pleasant to operate? |
| Artifacts | Personas, journey maps, flows, wireframes, test reports | Mockups, design systems, components, prototypes |
| Measured by | Task success, time on task, retention, NPS, support tickets | Legibility, scannability, error rate per screen, accessibility |
| Fails like | "I don't understand what this app is for" | "I can't read this gray text on white" |
See also: Usability, Visual Hierarchy
You asked directly: *what is the principle of UX?* There isn't one principle; there are a few canonical frameworks. Learn these three and you've covered most of the field's foundations.
10. Help and documentation
> 💡 Memorize #6. "Recognition rather than recall" explains half of all good UI decisions: show options instead of making users remember them. It's schema theory in action: recognition only requires *activating* an existing schema; recall requires *reconstructing* one.
Borrowed from Maslow. You cannot skip levels. Delight built on broken functionality is lipstick on a 404.
flowchart BT
A["1. FUNCTIONAL<br/>It works. No crashes, no dead ends."] --> B["2. RELIABLE<br/>It works consistently, every time."]
B --> C["3. USABLE<br/>It works without a manual."]
C --> D["4. CONVENIENT<br/>It fits into my life and habits."]
D --> E["5. PLEASURABLE<br/>It feels good. I'd recommend it."]
E --> F["6. MEANINGFUL<br/>It matters to my identity or values."]
See also: Usability, Aesthetics vs Conversion
These are the empirical regularities of human-computer interaction. Treat them like physics for interfaces. (Reference: lawsofux.com)
| Law | Statement | Practical move |
|---|---|---|
| Jakob's Law | Users spend most of their time on *other* products, so they expect yours to work the same way | Follow conventions for nav, carts, forms. Innovate on value, not on where the logout button lives |
| Hick's Law | Decision time grows with the number and complexity of choices | Cut options. One primary CTA per screen. Progressive disclosure for the rest |
| Fitts's Law | Time to hit a target depends on its distance and size | Make tap targets big (44×44px+) and put frequent actions within thumb reach |
| Miller's Law | Working memory holds about 7±2 chunks | Chunk phone numbers, group form fields, break long flows into steps |
| Tesler's Law | Every system has irreducible complexity; someone must absorb it | Absorb complexity in the design, not in the user. Smart defaults > 12 settings |
| Aesthetic–Usability Effect | People perceive attractive designs as *more usable*, even when they aren't | Beauty buys forgiveness for small flaws. It also masks real flaws in testing. Double-edged 🔪 |
| Von Restorff Effect | The item that differs from the rest gets remembered | Make the primary action visually distinct. Only one thing can be distinct |
| Peak–End Rule | Experiences are judged by their peak moment and their ending | Polish the success state and the offboarding, not just the funnel entrance |
| Doherty Threshold | Keep system response under ~400ms to hold attention | Performance IS UX. Use skeletons and optimistic UI when you can't be fast |
| Goal-Gradient Effect | Motivation increases as people near a goal | Show progress bars; pre-fill the first step ("2 of 5 complete") |
flowchart LR
subgraph Perception
VR[Von Restorff]
AU[Aesthetic-Usability]
end
subgraph Cognition
H[Hick's Law]
M[Miller's Law]
J[Jakob's Law]
end
subgraph Motor["Motor / Time"]
F[Fitts's Law]
D[Doherty Threshold]
end
subgraph Memory["Memory / Emotion"]
P[Peak-End Rule]
G[Goal-Gradient]
end
Perception --> X((User<br/>Behavior))
Cognition --> X
Motor --> X
Memory --> X
Definition (ISO 9241-11): The extent to which a product can be used by specified users to achieve specified goals with effectiveness, efficiency, and satisfaction in a specified context of use.
Break that down:
Nielsen adds two more attributes worth tracking: learnability (how fast can a first-timer get it?) and memorability (after a month away, do they still remember how?).
A checklist for whether an experience is actually complete:
> Useful · Usable · Desirable · Findable · Accessible · Credible · Valuable
Notice that *desirable* (aesthetics) is one cell out of seven. This becomes important in Node 8.
flowchart LR
A[Define tasks] --> B[Recruit ~5 users]
B --> C[Observe & measure]
C --> D[Prioritize issues]
D --> E[Fix design]
E --> A
See also: Nielsen's Heuristics, The Design Process
You named these specifically, so here's each one as its own sub-node.
Definition: The deliberate ordering of elements so the eye lands on things in the sequence *you* intend.
Hierarchy is built from a small set of levers:
| Lever | How it signals importance |
|---|---|
| Size | Bigger = more important. The H1 should be unmistakable |
| Weight | Bold pulls the eye before regular text does |
| Color & contrast | High-contrast elements come forward; muted ones recede |
| Position | Top-left start (in LTR languages); F-pattern and Z-pattern scanning |
| Whitespace | Isolation = emphasis. Space around an element is a spotlight |
| Imagery | Faces and photos beat text for first attention. Eye-gaze in photos steers attention |
> 🧪 The squint test: Blur your eyes at the screen. Whatever still stands out is your real hierarchy. If everything stands out, nothing does. If the decorative blob outshines your CTA, you've found a conversion leak.
Proximity · Similarity · Continuity · Closure · Figure/Ground · Common Region · Common Fate
These are pre-attentive: the user's brain applies them before conscious thought. You don't get to opt out, so use them on purpose.
Definition: The luminance ratio between foreground and background, from 1:1 (invisible) to 21:1 (black on white).
The WCAG 2.x standards you should know cold:
| Content | AA (the practical legal/industry bar) | AAA (stricter) |
|---|---|---|
| Normal body text | 4.5:1 | 7:1 |
| Large text (≥24px, or ≥18.66px bold) | 3:1 | 4.5:1 |
| UI components & meaningful graphics (icons, input borders, focus rings) | 3:1 | — |
Why care beyond compliance:
Tools: WebAIM Contrast Checker, Stark, the contrast inspector built into Chrome DevTools.
See also: Design Systems, Aesthetics vs Conversion
Definition: A single source of truth that packages design decisions into reusable parts: tokens, components, patterns, and the documentation explaining when to use which.
flowchart TD
A["DESIGN TOKENS<br/>(atoms of decision)<br/>color.primary = #0F62FE<br/>space.md = 16px<br/>radius.sm = 4px"] --> B["COMPONENTS<br/>Button, Input, Card, Modal<br/>(built FROM tokens)"]
B --> C["PATTERNS<br/>Login flow, checkout, empty states,<br/>error handling<br/>(built FROM components)"]
C --> D["PRODUCTS<br/>Actual screens users touch"]
E["PRINCIPLES & DOCS<br/>voice, accessibility rules,<br/>do's and don'ts"] -.governs.-> A
E -.governs.-> B
E -.governs.-> C
color.text.danger) over raw values (red-500) so themes and dark mode don't require rewritesprimary/secondary/ghost), which are forbiddenFamous public systems worth studying: Material Design (Google), Human Interface Guidelines (Apple), Carbon (IBM), Polaris (Shopify), Atlassian Design System.
See also: Typography, Nielsen heuristic #4: Consistency
This is the contradiction you noticed, and it's real. Beautiful designs sometimes convert worse. Ugly designs sometimes convert and retain brilliantly. Craigslist, Hacker News, Wikipedia, and Berkshire Hathaway's website are all famously plain and famously sticky. Plenty of award-winning redesigns have tanked revenue.
The paradox dissolves once you separate what aesthetics actually does from what conversion actually requires.
| Failure mode | What's happening |
|---|---|
| Beauty without clarity | The visitor can't answer "what is this and why should I care?" in ~5 seconds. Gorgeous hero image, vague headline, dead funnel |
| Misdirected hierarchy | The most visually dominant element is decorative, so attention never reaches the CTA. Failed squint test |
| Aesthetic-Usability Effect masking flaws | In testing, users *rate* pretty designs as usable while still failing tasks. Your test scores lied to you |
| Performance cost | Heavy animation, video backgrounds, custom fonts → slow load. Every second of delay costs conversions. Doherty Threshold violated |
| Schema violation | The "creative" navigation breaks Jakob's Law. Users must accommodate, and they won't |
| Form over friction | Minimalist aesthetics hid the trust signals, prices, or shipping info people needed to feel safe buying |
| Wrong audience | Designers design for designers. Dribbble taste ≠ what a 52-year-old procurement manager finds credible |
Aesthetics is a *multiplier on a working system*, not a substitute for one. Refer back to the UX Hierarchy of Needs: pleasurable sits on top of functional, reliable, usable, and convenient. And per the Honeycomb, desirable is one cell of seven.
Conversion specifically depends on, in rough order of leverage:
flowchart TD
A[Low conversion / retention] --> B{Can users state what the<br/>product does in 5 seconds?}
B -->|No| B1[CLARITY problem<br/>Rewrite the headline & hero.<br/>Aesthetics can't fix this]
B -->|Yes| C{Does the page load fast?<br/>under ~3s, ideally under 1s}
C -->|No| C1[PERFORMANCE problem<br/>Cut weight before adding beauty]
C -->|Yes| D{Squint test: is the CTA<br/>the most prominent element?}
D -->|No| D1[HIERARCHY problem<br/>Demote decoration, promote action]
D -->|Yes| E{Can users complete the<br/>core task in usability tests?}
E -->|No| E1[USABILITY problem<br/>Watch 5 users. Fix what they trip on]
E -->|Yes| F{Do they trust you?<br/>reviews, pricing, security, brand}
F -->|No| F1[CREDIBILITY problem<br/>Add proof, not polish]
F -->|Yes| G{Does the offer match<br/>what they actually want?}
G -->|No| G1[PRODUCT/MESSAGE FIT problem<br/>No design fixes a wrong offer]
G -->|Yes| H[NOW invest in aesthetics.<br/>It will multiply a working system]
> 💡 Takeaway: When beautiful designs fail, beauty usually isn't the culprit. Something below it on the hierarchy is broken, and the beauty either hid the break or actively caused it (slow load, buried CTA, violated schema).
See also: Aesthetic-Usability Effect, Mental models
Two canonical models. Both encode the same idea: alternate between expanding options and committing to choices.
flowchart LR
subgraph D1["Diamond 1: Design the RIGHT thing"]
A[Discover<br/>research, interviews,<br/>analytics] --> B[Define<br/>problem statement,<br/>'How might we...']
end
subgraph D2["Diamond 2: Design the thing RIGHT"]
C[Develop<br/>ideate, sketch,<br/>prototype] --> D[Deliver<br/>test, refine,<br/>ship, measure]
end
B --> C
D -.learnings.-> A
Empathize → Define → Ideate → Prototype → Test, looping freely. Same DNA, more emphasis on user empathy at the front.
> ⚠️ The diagrams look linear. Real projects loop constantly. Testing in Deliver routinely reveals you defined the wrong problem, sending you back to Discover. That's not failure; that's the process working.
Since knowledge is built, not copied, here's a sequence designed for assimilation (each step hooks onto the previous schema):
| Term | One-liner |
|---|---|
| Affordance | What an object's form lets you do |
| CTA | Call to action; the thing you want clicked |
| Heuristic evaluation | Expert review against Nielsen's 10 |
| Information architecture | How content is organized, labeled, and navigated |
| Mental model | The user's schema of how a system works |
| Progressive disclosure | Reveal complexity only when needed |
| SUS | System Usability Scale; 10-question usability score |
| Token | A named, reusable design decision |
| WCAG | Web Content Accessibility Guidelines |
| Wireframe | Low-fidelity structural sketch of a screen |
*End of schemata. Now go violate it knowingly instead of accidentally.* 🛠️
Everything above is the map — the *why* behind every design decision. What follows is the territory: the working procedure for actually producing an interface, with the schemata loaded in your head while you build. The two halves form one loop: the schemata tells you which rules exist and what breaking them costs; the playbook tells you how to build something distinctive without breaking the rules that matter.
Read the playbook through the lens of the nodes above:
With that frame set, here is the playbook.
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.
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
Before any aesthetic choices, use deductive reasoning to derive the right design from the context:
Derive the design from the problem, don't impose a style onto it.
LLMs are next-token predictors optimized via backpropagation. This creates a natural bias toward the most statistically probable (generic) output. To counter this:
Present the chosen direction to the user briefly before implementing. This ensures every design is intentionally de-biased.
LLMs have deepest mastery over raw web fundamentals. Use this to your advantage:
This prevents framework abstractions from flattening creative choices.
Adopt the mindset of a senior UI/UX Designer — someone who both solves usability problems and crafts visually beautiful, creative interfaces. Evaluate the output through that expert lens:
Focus on:
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
IMPORTANT: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
Take syahiidkamil/super-ui-ux-design from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.