Design and build beautiful, accessible graphical interfaces — web, desktop (Electron/Tauri), and native (iOS/macOS/Android). Use for visual hierarchy and layout, color and theming (light/dark, semantic tokens, WCAG contrast), typography systems, motion and micro-interactions, accessibility, component systems and design tokens, responsive/adaptive layout, and platform-native idioms. The GUI counterpart to beautiful-cli-design. NOT for terminal/CLI output (use beautiful-cli-design) or API/data schemas.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Design and build beautiful, accessible graphical interfaces — web, desktop (Electron/Tauri), and native (iOS/macOS/Android). Use for visual hierarchy and layout, color and theming (light/dark, semantic tokens, WCAG contrast), typography systems, motion and micro-interactions, accessibility, component systems and design tokens, responsive/adaptive layout, and platform-native idioms. The GUI counterpart to beautiful-cli-design. NOT for terminal/CLI output (use beautiful-cli-design) or API/data schemas.
license
Apache-2.0
allowed-tools
Read,Write,Edit,Bash,Grep,Glob
metadata
{"category":"Design & UX","tags":["gui","design-system","accessibility","design-tokens","typography","color","motion","layout","native-ui"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"gpui-rust-console","reason":"pd-console's panes need this skill's hierarchy/token/accessibility rules translated into gpui's render-agnostic Block/Tone system."},{"skill":"rust-gpui-motion","reason":"This skill's motion rules (duration/easing tokens, transform/opacity-only, prefers-reduced-motion) hand off to gpui's compositor-friendly primitives once the target is native Rust."},{"skill":"gpui-shaders","reason":"Shader-driven per-pixel effects still answer to this skill's hierarchy/color/motion rules — a shader is the escape hatch, not a substitute for the token/layout system."},{"skill":"web-design-expert","reason":"Brand identity, palette, and typography direction sit upstream of this skill's execution rules for tokens, layout, and accessibility."},{"skill":"color-contrast-auditor","reason":"Computes the exact WCAG contrast ratios this skill's audit requires; run it on the palette before locking tokens."}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}
Beautiful GUI Design
Treat the screen as a designed surface, not a dump of controls: hierarchy, color, type, motion, and accessibility are load-bearing, and every choice must survive light/dark mode, small and large viewports, keyboard and screen-reader use, and the conventions of the platform it ships on.
When to Use
Designing or reviewing a web app, marketing page, dashboard, or settings/onboarding flow.
Building a desktop GUI (Electron/Tauri) or a native app (SwiftUI/AppKit, Jetpack Compose, WinUI).
Establishing a design system: semantic color tokens, a type scale, spacing, elevation, component states.
Adding light/dark themes, fixing contrast/accessibility failures, or making a layout responsive.
Choosing a component approach (headless primitives vs. styled kit) or a design-to-code tool.
NOT for
Terminal/CLI output, TUIs, prompts, or ANSI rendering. Use beautiful-cli-design.
API response schemas, wire formats, or machine-only output contracts.
Backend architecture, data modeling, or non-visual logic.
Brand strategy / copywriting (this is the visual + interaction layer).
Decision Points
flowchart TD
A[GUI design task] --> B{Output target?}
B -->|Web| C{Component adapts to its container or the page?}
C -->|Its container| C1[Container queries + fluid type]
C -->|The page| C2[Mobile-first breakpoints]
B -->|Desktop Electron/Tauri| D[Web tech, but adopt the host OS idioms]
B -->|Native iOS/macOS| E[SwiftUI + SF Symbols + Apple HIG]
B -->|Native Android| F[Compose + Material 3 + Material icons]
C1 --> G{Need ship-fast or full control?}
C2 --> G
D --> G
G -->|Ship fast| H[Styled kit: shadcn/ui on Radix]
G -->|Full control / cross-platform looks| I[Headless primitives: Radix/Headless UI + own styling]
H --> J[Layer the system: tokens -> components -> a11y -> motion]
I --> J
E --> J
F --> J
Route first:
Tokens before components, components before screens. A screen built on ad-hoc values can't be themed or kept consistent. Build the three-tier token model (primitive → semantic → component) first. See references/06-component-systems-tokens-and-platform-idioms.md.
Headless primitives (Radix/Headless UI) when you need full visual control or different looks per platform; styled kits (shadcn/ui) when you want 80% shipped with accessibility already handled. Never hand-roll an interactive control without the ARIA/keyboard logic a primitive gives you.
Container queries when a component appears at multiple widths (sidebar vs. grid); breakpoints for page-level layout.
Native means native. A web look shipped on iOS/Android reads as a web app. Adopt the platform's icons, spacing, type, and controls.
Visual System Rules
Spacing is a system, not vibes. Use an 8pt grid (4pt for micro-adjustments). One base per project. references/01.
Hierarchy needs contrast, not just color. Distinguish tiers by ≥1.5–2× size plus weight/position — never color alone. references/01.
Color is semantic tokens, never raw hex in components. Build a perceptually-uniform (OKLCH) ramp; derive light/dark and every state from it. references/02.
Type: rem not px, a modular scale, body ≥ 14px (0.875rem). 45–75ch measure, role-based line-height. Honor OS Dynamic Type; never lock zoom. references/03.
Motion is communication, not decoration. 100–300ms, ease-out to enter / ease-in to exit, animate only transform/opacity, always honor prefers-reduced-motion. references/04.
Accessibility is a design input, not a retrofit. Semantic HTML/native controls first, visible focus always, 4.5:1 body contrast, 44/48pt touch targets, keyboard + screen-reader passes. references/05.
Icons are an icon system (SF Symbols / Lucide / Heroicons), never emoji. Emoji as UI icons reads as cheap and renders inconsistently.
Failure Modes
Anti-Pattern: "Rainbow Vomit"
Symptom: Many unrelated colors; states (hover/error/focus) are indistinguishable from intent (primary/info).
Detection rule: Count unique colors in a 400×400px screenshot — more than ~8 is a smell.
Fix: One primary + one accent + semantic status colors; derive hover/active/disabled by lightness offset. references/02.
Anti-Pattern: "Invisible in Light Mode" (or Dark)
Symptom: Looks fine in one theme, unreadable in the other (light text on light, low-contrast accents).
Detection rule: Hardcoded theme colors; contrast checker reports < 4.5:1 (text) or < 3:1 (UI) in either mode. scripts/gui_design_audit.mjs flags low-text-contrast (critical) when textContrastMinRatio < 4.5, and missing-light-dark (high) when lightAndDark is false.
Fix: Semantic tokens with real light AND dark values (not an inversion); verify both with a contrast tool. references/02.
Anti-Pattern: "Tiny Type / Locked Zoom"
Symptom: Body/caption text below 14px; user-scalable=no or maximum-scale<2; ignores OS text size.
Detection rule: Grep for font-size: 0.[0-7]…, Tailwind text-xs on prose, user-scalable=no. scripts/gui_design_audit.mjs flags tiny-body-font (critical) when minBodyFontPx < 14.
Fix: rem-based scale, ≥14px body, honor Dynamic Type, never disable zoom. references/03, references/05.
Anti-Pattern: "Decorative Motion / Layout Thrash"
Symptom: Animations on width/height/top/left, parallax, >300ms repeated transitions; janky on mobile.
Detection rule: DevTools Performance shows tall Layout/Recalc bars during animation; no prefers-reduced-motion path.
Fix: Animate transform/opacity only; tokenize durations/easing; honor reduced-motion. references/04.
Anti-Pattern: "Web Look on Native"
Symptom: Material ripples on iOS, 4pt corners and emoji icons, centered controls that fight the HIG.
Detection rule: Side-by-side with a first-party app (Settings, Messages) — corners/spacing/icons/controls differ.
Fix: Use the platform's primitives, icon set, spacing, and type. references/06.
Anti-Pattern: "Magic Numbers in Components"
Symptom: padding: 13px, one-off hex, hand-picked hover colors scattered through component files.
Detection rule: Grep components for numeric literals and #[0-9a-f]{6} — every hit is un-tokenized. scripts/gui_design_audit.mjs flags no-semantic-tokens (critical) when semanticTokensUsed is false, and ad-hoc-spacing (high) when spacingScale is "ad-hoc".
Fix: Three-tier tokens; components reference semantic tokens only. references/06.
Anti-Pattern: "Stateless / Inaccessible Controls"
Symptom: A control with only default + click; no focus ring, no disabled/loading/error, <div>-as-button.
Detection rule: Tab through the UI — focus vanishes; render the control in all states — most are missing. scripts/gui_design_audit.mjs flags no-interactive-states (critical) when interactiveStatesDefined is false.
Fix: Full state machine (default/hover/active/focus/disabled/loading) on a semantic element or headless primitive. references/05, references/06.
Anti-Pattern: "Cramped Touch Targets"
Symptom: Buttons/icons sized to their visual glyph (e.g. a 20×20px icon button) with no invisible hit-area padding; taps miss or double-fire on mobile.
Detection rule: Rendered hit area (including padding) measures below 44×44pt (iOS) / 48dp (Android) / the 24px WCAG 2.5.8 floor, with tight surrounding spacing. scripts/gui_design_audit.mjs flags touch-target-below-minimum (high) when touchTargetMinPx < 44.
Fix: Pad the interactive element — not just the glyph — to at least the platform minimum, and space adjacent targets so they don't crowd. references/05.
Anti-Pattern: "Design-by-Committee Type System"
Symptom: Every screen introduces a new font weight or one-off size; the type scale has ballooned past a handful of steps and reads inconsistent.
Detection rule: More than ~3 font weights or more than ~8 distinct font sizes in the shipped system. scripts/gui_design_audit.mjs flags too-many-font-weights (medium) when fontWeightsCount > 3, and too-many-font-sizes (medium) when fontSizesCount > 8.
Fix: Collapse to a modular scale (~6–8 sizes) and 2–3 weights (regular/medium/bold); every new size must justify itself against the scale. references/03.
Why it works: a semantic <button> (keyboard + SR for free), tokens that flip cleanly for dark mode, every state defined, contrast guaranteed by token design, motion that respects the user. The same tokens render natively via SF Symbols/SwiftUI on iOS and Compose on Android (references/06).
Quality Gates
Spacing on an 8pt system; one base; no magic numbers in components.
Hierarchy reads when squinting — focal point obvious via size/weight/position, not color alone.
Color is semantic tokens; light AND dark both designed and contrast-verified (4.5:1 text, 3:1 UI).
Type in rem, body ≥14px, modular scale, 45–75ch measure; OS text-size honored; zoom never locked.
Every interactive element has default/hover/active/focus-visible/disabled (+ loading where async).
Keyboard pass: full operability, visible focus on every stop, modals trap + restore focus.
Screen-reader pass: semantic elements/labels; ARIA only where needed and correct.
Icons from an icon system (SF Symbols/Lucide/Heroicons), never emoji-as-icon.
Native builds use native idioms (controls, icons, spacing, type) — no web look shipped on native.
Tokens flow to all targets from one source (web CSS vars, iOS Swift, Android Kotlin).
Deterministic Audit
Once a design is measurable as data — one spec per surface, per schemas/gui-spec.schema.json — run it through scripts/gui_design_audit.mjs to check it against the Quality Gates above before calling the work done:
auditGuiDesign(spec) returns { pass, score, findings, recommendations }, flagging low text contrast, missing light/dark, a too-small body font, an un-tokenized (raw hex/px) system, ad-hoc spacing off the 8pt/4pt grid, too many font weights/sizes, undersized touch targets, and interactive elements missing their full state machine. It audits the measured spec, not the rendered UI — the Keyboard pass, Screen-reader pass, and "built and run" checks above still have to happen by hand.
Fork Guidance
Fork when the work has distinct lanes owned by different actors:
Keep final visual-language decisions in the parent so one actor owns coherence.
Reference Map
references/01-visual-hierarchy-layout-spacing.md — Gestalt, the 8pt/4pt system, layout grids and safe areas, focal point, density vs. whitespace, elevation, layout archetypes.
references/02-color-and-theming.md — semantic tokens, OKLCH ramps, light/dark done right, WCAG contrast math, state colors, data-viz vs. chrome, theming architecture.
references/04-motion-and-microinteractions.md — duration/easing tokens, spring vs. tween, purposeful motion, the compositor budget, honest progress, reduced-motion.
Machine-checkable governance layer, for turning a design brief into an auditable spec:
schemas/gui-spec.schema.json — the JSON shape of a GUI design spec (contrast, type, tokens, spacing, targets, states).
scripts/gui_design_audit.mjs — auditGuiDesign(spec), a deterministic check of a spec against the Quality Gates above.
examples/sample-input.json — a complete, passing GUI spec.
examples/expected-output.md — a failing spec audited, then the fix walkthrough to a passing one.
templates/output-template.md — a fill-in template for the visual-design-system-and-layout deliverable.
agents/openai.yaml — a subagent descriptor for delegated GUI design work.
Layout QA gate (mechanical — run before shipping)
Before calling any rendered page, artifact, dashboard, deck, or component done,
run the mechanical overflow/collision checker. It renders the page headlessly and
flags text-vs-text collisions, clipped/ellipsis-truncated elements, text escaping
its container, and horizontal page scroll — the visual defects a screenshot hides
and that only appear at a specific width or in one theme.
Resolve layout-overflow-guard from the active skill catalog before running it.
The command below shows the standard Claude install path; use the path reported
by your harness. If the skill is absent, install or sync it instead of skipping
this gate.
You do not need to read check_layout.py — invoke it with the Bash tool and
act on its report and exit code (non-zero = a defect). The script's source never
enters your context; only its findings do. Drive it to zero violations across
every width and both themes before you ship. Full detail: the
layout-overflow-guard skill.
Skill Bundle Index
Every file in this skill, and when to open it. Auto-generated; run scripts/index_references.py --fix.
README.md — Beautiful GUI Design — Treat the screen as a designed surface, not a dump of controls: hierarchy, color, type, motion, and accessibility are load-bearing, and ever
examples/expected-output.md — Example Output: Beautiful GUI Design — Scenario: the "Before" button from SKILL.md's Worked Example, generalized to a whole screen — hardcoded hex, magic padding, no dark theme,
references/01-visual-hierarchy-layout-spacing.md — Visual Hierarchy, Layout & Spacing — **Visual hierarchy is the art of making some elements more prominent than others through spatial relationships, sizing, color, and alignment
references/02-color-and-theming.md — Color & Theming: Semantic Tokens, Accessible Contrast, and Multimode Systems — Raw hex colors in components are the root of evil.
references/04-motion-and-microinteractions.md — Motion & Micro-Interactions Reference — Motion is communication—feedback on state, guidance through hierarchy, reassurance during waits, and affordance signaling on interactive ele
references/06-component-systems-tokens-and-platform-idioms.md — Component Systems, Design Tokens & Platform-Native Idioms — A professional design system bridges the gap between tokens (semantic units of visual design), components (reusable building blocks
