diff --git a/.codespellrc b/.codespellrc index 97fcd0893..e7d76690a 100644 --- a/.codespellrc +++ b/.codespellrc @@ -54,7 +54,9 @@ # CAF - Microsoft Cloud Adoption Framework acronym -ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,Vertexes,nin,FO,CAF +# ratatui - Rust crate for terminal UI + +ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,Vertexes,nin,FO,CAF,ratatui # Skip certain files and directories diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index ca2e819e7..4058d026d 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -765,6 +765,12 @@ "description": "Comprehensive collection of prompts, instructions, and resources for building declarative agents and API plugins using TypeSpec for Microsoft 365 Copilot extensibility.", "version": "1.0.0" }, + { + "name": "vibe-coding", + "source": "vibe-coding", + "description": "Discipline plugin for vibe-driven development — turns mood, feel, and outcome-shaped requests into shippable code without drift, hallucinated APIs, or silent scope creep. Bundles a vibe-lock entry skill with companion skills for visual design, shorthand translation, and plain-English explanation.", + "version": "0.1.0" + }, { "name": "whatidid", "description": "Turn your Copilot sessions into proof of impact — research-grounded HTML reports with effort estimation, skills analysis, and ROI metrics from local session logs.", diff --git a/docs/README.plugins.md b/docs/README.plugins.md index cd2e48029..f9eaf0f39 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -91,3 +91,4 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | [testing-automation](../plugins/testing-automation/README.md) | Comprehensive collection for writing tests, test automation, and test-driven development including unit tests, integration tests, and end-to-end testing strategies. | 9 items | testing, tdd, automation, unit-tests, integration, playwright, jest, nunit | | [typescript-mcp-development](../plugins/typescript-mcp-development/README.md) | Complete toolkit for building Model Context Protocol (MCP) servers in TypeScript/Node.js using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 2 items | typescript, mcp, model-context-protocol, nodejs, server-development | | [typespec-m365-copilot](../plugins/typespec-m365-copilot/README.md) | Comprehensive collection of prompts, instructions, and resources for building declarative agents and API plugins using TypeSpec for Microsoft 365 Copilot extensibility. | 3 items | typespec, m365-copilot, declarative-agents, api-plugins, agent-development, microsoft-365 | +| [vibe-coding](../plugins/vibe-coding/README.md) | Discipline plugin for vibe-driven development — turns mood, feel, and outcome-shaped requests into shippable code without drift, hallucinated APIs, or silent scope creep. Bundles a vibe-lock entry skill with companion skills for visual design, shorthand translation, and plain-English explanation. | 4 items | vibe-coding, prototyping, intent-driven, natural-language-to-code, design, shorthand, pseudo-code, beginner-friendly | diff --git a/docs/README.skills.md b/docs/README.skills.md index 10907e4e9..ef601d8e0 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -180,6 +180,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [github-issues](../skills/github-issues/SKILL.md)
`gh skills install github/awesome-copilot github-issues` | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task. | `references/dependencies.md`
`references/images.md`
`references/issue-fields.md`
`references/issue-types.md`
`references/projects.md`
`references/search.md`
`references/sub-issues.md`
`references/templates.md` | | [github-release](../skills/github-release/SKILL.md)
`gh skills install github/awesome-copilot github-release` | Guides IA through releasing a new version of a GitHub library end-to-end. Handles SemVer versioning and Keep a Changelog formatting automatically. | `references/commit-classification.md`
`references/semver-rules.md` | | [go-mcp-server-generator](../skills/go-mcp-server-generator/SKILL.md)
`gh skills install github/awesome-copilot go-mcp-server-generator` | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. | None | +| [graphic-designer](../skills/graphic-designer/SKILL.md)
`gh skills install github/awesome-copilot graphic-designer` | Expert visual design guidance for UI and UX of GUI apps and websites. Use when asked to design, critique, or improve interface visuals, color palettes, typography, layout grids, design tokens, component states, micro-interactions, or accessibility of screens. Covers visual hierarchy, Gestalt principles, Laws of UX (Fitts, Hick, aesthetic-usability), the 60-30-10 color rule, bento grids, glassmorphism, dopamine palettes, WCAG contrast, motion easing, and 2026 trends like tactile maximalism and adaptive UI. | `references/accessibility.md`
`references/design-systems.md`
`references/principles.md`
`references/trends-2026.md` | | [gsap-framer-scroll-animation](../skills/gsap-framer-scroll-animation/SKILL.md)
`gh skills install github/awesome-copilot gsap-framer-scroll-animation` | Use this skill whenever the user wants to build scroll animations, scroll effects, parallax, scroll-triggered reveals, pinned sections, horizontal scroll, text animations, or any motion tied to scroll position — in vanilla JS, React, or Next.js. Covers GSAP ScrollTrigger (pinning, scrubbing, snapping, timelines, horizontal scroll, ScrollSmoother, matchMedia) and Framer Motion / Motion v12 (useScroll, useTransform, useSpring, whileInView, variants). Use this skill even if the user just says "animate on scroll", "fade in as I scroll", "make it scroll like Apple", "parallax effect", "sticky section", "scroll progress bar", or "entrance animation". Also triggers for Copilot prompt patterns for GSAP or Framer Motion code generation. Pairs with the premium-frontend-ui skill for creative philosophy and design-level polish. | `references/framer.md`
`references/gsap.md` | | [gtm-0-to-1-launch](../skills/gtm-0-to-1-launch/SKILL.md)
`gh skills install github/awesome-copilot gtm-0-to-1-launch` | Launch new products from idea to first customers. Use when launching products, finding early adopters, building launch week playbooks, diagnosing why adoption stalls, or learning that press coverage does not equal growth. Includes the three-layer diagnosis, the 2-week experiment cycle, and the launch that got 50K impressions and 12 signups. | None | | [gtm-ai-gtm](../skills/gtm-ai-gtm/SKILL.md)
`gh skills install github/awesome-copilot gtm-ai-gtm` | Go-to-market strategy for AI products. Use when positioning AI products, handling "who is responsible when it breaks" objections, pricing variable-cost AI, choosing between copilot/agent/teammate framing, or selling autonomous tools into enterprises. | None | @@ -355,6 +356,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [update-markdown-file-index](../skills/update-markdown-file-index/SKILL.md)
`gh skills install github/awesome-copilot update-markdown-file-index` | Update a markdown file section with an index/table of files from a specified folder. | None | | [update-specification](../skills/update-specification/SKILL.md)
`gh skills install github/awesome-copilot update-specification` | Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code. | None | | [vardoger-analyze](../skills/vardoger-analyze/SKILL.md)
`gh skills install github/awesome-copilot vardoger-analyze` | Use when the user asks to personalize the GitHub Copilot CLI assistant, adapt Copilot to their style, use vardoger, or analyze their Copilot CLI conversation history. Reads the local session directory at `~/.copilot/session-state/`, extracts recurring preferences and conventions, and writes a fenced personalization block into `~/.copilot/copilot-instructions.md`. Runs entirely on the user's machine via the local `vardoger` CLI (`pipx install vardoger`); no network calls and no uploads. Triggers: 'personalize my copilot', 'analyze my copilot history', 'tailor copilot to me', 'run vardoger', 'update my copilot instructions from history', 'make copilot learn my style'. | None | +| [vibe-coder](../skills/vibe-coder/SKILL.md)
`gh skills install github/awesome-copilot vibe-coder` | Discipline skill for vibe-driven development — turns mood, feel, and outcome-shaped requests into shippable code without the usual drift, hallucinated APIs, and silent scope creep. Use when a collaborator describes software by feel rather than spec ("make it feel snappy", "vibe-code a dashboard", "like Linear but cozy", "build me something that does X, you figure out the rest"), when a prototype is being built from a vibe instead of a ticket, or when the request mixes aesthetic intent with vague behavior. Enforces a four-line Vibe Lock before any code is generated, names the specific failure modes of vibe coding, and gives concrete patterns for translating a vibe into a runnable slice. Keywords: vibe coding, vibe code, build me, make it feel, aesthetic, mood, taste, prototype, scaffold from idea, natural-language to code, intent-driven, ambient spec, Karpathy. | None | | [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-commands` | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None | | [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-localization` | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None | | [web-design-reviewer](../skills/web-design-reviewer/SKILL.md)
`gh skills install github/awesome-copilot web-design-reviewer` | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`
`references/visual-checklist.md` | diff --git a/plugins/vibe-coding/.github/plugin/plugin.json b/plugins/vibe-coding/.github/plugin/plugin.json new file mode 100644 index 000000000..1c41f1709 --- /dev/null +++ b/plugins/vibe-coding/.github/plugin/plugin.json @@ -0,0 +1,28 @@ +{ + "name": "vibe-coding", + "description": "Discipline plugin for vibe-driven development — turns mood, feel, and outcome-shaped requests into shippable code without drift, hallucinated APIs, or silent scope creep. Bundles a vibe-lock entry skill with companion skills for visual design, shorthand translation, and plain-English explanation.", + "version": "0.1.0", + "keywords": [ + "vibe-coding", + "prototyping", + "intent-driven", + "natural-language-to-code", + "design", + "shorthand", + "pseudo-code", + "beginner-friendly" + ], + "author": { + "name": "Awesome Copilot Community" + }, + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "agents": [], + "commands": [], + "skills": [ + "./skills/graphic-designer/", + "./skills/noob-mode/", + "./skills/quasi-coder/", + "./skills/vibe-coder/" + ] +} diff --git a/plugins/vibe-coding/README.md b/plugins/vibe-coding/README.md new file mode 100644 index 000000000..faf64b91d --- /dev/null +++ b/plugins/vibe-coding/README.md @@ -0,0 +1,93 @@ +# vibe-coding + +Discipline plugin for vibe-driven development. Turns mood, feel, and outcome-shaped requests — "make it feel snappy", "vibe-code a dashboard", "like Linear but cozy", "build me something that does X, you figure out the rest" — into shippable code without the usual drift, hallucinated APIs, and silent scope creep. + +The plugin is intentionally small. It does one thing: it keeps vibe coding honest from the first prompt to the first runnable slice. + +## What's Included + +| Component | Type | Role | +|---|---|---| +| [`vibe-coder`](../../skills/vibe-coder/) | Skill (entry) | Captures the vibe as a four-line Vibe Lock, enforces the runnable-slice rhythm, names the failure modes | +| [`graphic-designer`](../../skills/graphic-designer/) | Skill | Translates `Feel` into palette, type, layout, motion, and accessibility decisions | +| [`quasi-coder`](../../skills/quasi-coder/) | Skill | Translates shorthand, pseudo-code, and mixed-language fragments into idiomatic code in the locked stack | +| [`noob-mode`](../../skills/noob-mode/) | Skill (middleware) | Plain-English layer for non-technical collaborators — see [How `noob-mode` Fits In](#how-noob-mode-fits-in) | + +## Typical Flow + +1. **Collaborator sends a vibey request.** `vibe-coder` writes the four-line Vibe Lock and waits for "lock it". +2. **Once locked**, `vibe-coder` decides what to dispatch: + - UI taste work → `graphic-designer` + - Shorthand, `()=>` fragments, mixed-language code, or stack-selection → `quasi-coder` + - Everything else → handled by `vibe-coder` itself +3. **First runnable slice ships.** No styling pass, no second feature. +4. **Re-confirm the Vibe Lock** before slice two. + +## How `noob-mode` Fits In + +`noob-mode` is wired in as a middleware skill, not a parallel one. It activates based on the collaborator's apparent technical fluency, not the request's content. + +- **~50% confidence the writer is not fluent in computer science, programming, or related topics:** Ease into `noob-mode`. Mirror its plain-English phrasing without naming it. Drop jargon where a short phrase would do. Keep the four-line Vibe Lock — non-technical collaborators benefit from it more than anyone — but explain each field in one sentence the first time. +- **Blatantly obvious the writer has no technical background:** Respond fully per the `noob-mode` skill. Use it as a collaborator that sits between this plugin and the writer — every output from `vibe-coder`, `graphic-designer`, or `quasi-coder` is paraphrased through `noob-mode` before it reaches the writer. Approval prompts, error messages, and technical output get color-coded risk indicators per the skill's spec. +- **Writer is clearly technical:** Do not engage `noob-mode`. Plain output. + +Signals that raise the noob-mode probability: + +- Use of vague verbs for technical actions ("make it go", "hook it up") +- Confusion between adjacent concepts (file vs. folder, function vs. variable, repo vs. branch) +- Requests phrased as outcomes with no mechanism ("I want a website that does this") +- Apologetic framing about not understanding code +- Asking what an error message means + +Signals that lower it: + +- Naming languages, frameworks, or packages correctly +- Reading or modifying code in the prompt +- Using domain terms (PR, diff, stash, async, type) accurately + +## Installation + +In this repository, the plugin is laid out per the awesome-copilot spec: + +``` +plugins/vibe-coding/ +└── .github/plugin/plugin.json +skills/ +├── vibe-coder/ +├── graphic-designer/ +├── quasi-coder/ +└── noob-mode/ +``` + +## When to Invoke This Plugin + +`vibe-coding` is not meant to load automatically. Reach for it deliberately, in the moments when you want an AI agent to carry the parts of building software you do not want to carry yourself — picking the stack, naming the look and feel, translating a rough idea into working code, deciding what "done enough" means for the first slice. + +Summon it by opening a request with the vibe in plain language ("vibe-code me a…", "make it feel like…", "build something that does X") or by naming `vibe-coder` directly. The plugin then takes over the discipline pieces — locking the vibe, choosing the right skill, shipping one runnable slice at a time — so you can stay focused on the outcome instead of the mechanics. + +## When to Use This Plugin + +- Describe software by feel rather than spec +- Compare to existing products ("like Linear but warmer") +- Skip the stack decision and want a recommendation +- Mix UI taste and code in the same ask +- Paste shorthand, `()=>` markers, or pseudo-code without a target language +- Prototype heavily and need discipline rather than ceremony + +Do not install it for teams that already work from formal specs, ADRs, or strict design tokens — those teams have the discipline built in elsewhere. + +## What This Plugin Adds Beyond a Frontier Model + +Each component is targeted at a specific failure mode a frontier model exhibits when handed a vibe: + +| Failure mode | Component that addresses it | +|---|---| +| Silently rewrites the goal mid-generation | `vibe-coder` — Vibe Lock checkpoint | +| Ships a 500-line file when one runnable slice would do | `vibe-coder` — runnable-slice rule | +| Produces a UI that contradicts the stated feel | `graphic-designer` — derives palette/type/motion from `Feel` | +| Translates shorthand into broken polyglot code | `quasi-coder` — idiomatic single-target translation | +| Speaks fluent jargon to a non-technical user | `noob-mode` — middleware paraphrase | + +## License + +MIT. See the awesome-copilot repository for full license terms. diff --git a/skills/graphic-designer/SKILL.md b/skills/graphic-designer/SKILL.md new file mode 100644 index 000000000..6b1c19d58 --- /dev/null +++ b/skills/graphic-designer/SKILL.md @@ -0,0 +1,127 @@ +--- +name: graphic-designer +description: 'Expert visual design guidance for UI and UX of GUI apps and websites. Use when asked to design, critique, or improve interface visuals, color palettes, typography, layout grids, design tokens, component states, micro-interactions, or accessibility of screens. Covers visual hierarchy, Gestalt principles, Laws of UX (Fitts, Hick, aesthetic-usability), the 60-30-10 color rule, bento grids, glassmorphism, dopamine palettes, WCAG contrast, motion easing, and 2026 trends like tactile maximalism and adaptive UI.' +--- + +# Graphic Designer + +Apply professional UI/UX visual design judgment to mockups, components, screens, and full interfaces. Translate vague aesthetic requests ("make it pop", "looks dated", "feels cluttered") into concrete, defensible design decisions grounded in perception research and current platform conventions. + +## When to Use This Skill + +- Designing or reviewing screens, components, landing pages, dashboards, or mobile app UI +- Picking color palettes, type scales, spacing, or grid systems +- Defining design tokens or component variants for a design system +- Improving visual hierarchy, scannability, or conversion on an existing layout +- Adding or auditing micro-interactions, state transitions, and motion +- Making a UI accessible (WCAG contrast, neurodivergent-friendly patterns, dynamic type) +- Modernizing a "flat 2018" interface against current 2026 expectations + +## Core Decision Framework + +Every visual decision should answer three questions in order: + +1. **Where does the eye land first?** — primary action must win the contrast/size/position battle. Run a 5-second squint test; if the CTA disappears at 30% opacity, hierarchy is broken. +2. **What does the user need to perceive as related?** — apply Gestalt proximity and similarity *before* adding borders, dividers, or boxes. Whitespace groups more cleanly than lines. +3. **What can be hidden until needed?** — progressive disclosure beats density. Every visible element pays rent in cognitive load. + +## Visual System Defaults + +Use these as starting points, then deviate with reason: + +| System | Default | Notes | +|---|---|---| +| Color ratio | **60-30-10** (dominant / secondary / accent) | Accent is reserved for primary CTAs and critical state | +| Type scale | 1.250 (major third) or 1.333 (perfect fourth) | Tighter scales feel editorial; wider scales feel marketing | +| Base unit | 4px or 8px spacing grid | Every padding/margin is a multiple — no `padding: 13px` | +| Body text | 16px minimum on web, 17pt on iOS, 14sp on Android | Below 16px on web fails most accessibility audits | +| Line length | 45–75 characters | Long-form prose; UI labels can be shorter | +| Line height | 1.4–1.6 for body, 1.1–1.25 for display | Tight headings, generous body | +| Corner radius | One scale (e.g., 4 / 8 / 16 / full) | Mixing arbitrary radii ages a UI fast | +| Elevation | 3–5 shadow tiers max | Use them semantically (resting / raised / overlay / modal) | + +## Color & Contrast + +- **WCAG minimums**: 4.5:1 for body text, 3:1 for large text (≥18pt or 14pt bold) and UI components. AAA is 7:1 / 4.5:1. Glass/blur backgrounds usually fail — test against worst-case content behind them. +- **Dopamine palettes** (saturated neons, Y2K) need a desaturated 60% dominant to remain usable; pure saturation everywhere reads as a children's toy. +- **Dark mode is not "invert"** — pure white text on pure black causes halation. Use `#E6E6E6` on `#121212` style off-blacks. +- **Never encode information by hue alone.** Pair color with icon, label, or shape (red error + ⚠ + "Error:"). +- State colors live on a separate axis from brand: success/warning/error/info should survive a brand refresh. + +## Typography + +- **Two families maximum.** One display, one text. A third for monospace if the product shows code or numerics that need alignment. +- **Optical sizing matters at scale.** Display weights at body size look bloated; text weights at hero size look weak. Use variable fonts with optical-size axes (`opsz`) when available. +- **Numerals**: tabular figures (`font-variant-numeric: tabular-nums`) for tables, dashboards, and any column of numbers. Proportional figures everywhere else. +- **Kinetic / oversized type** is the dominant 2026 hero pattern, but it eats accessibility if it animates without a `prefers-reduced-motion` fallback. + +## Layout Patterns Worth Knowing + +- **Bento grid** — modular tiles of varying sizes; ideal for feature showcases, dashboards, and portfolios. Each tile must be self-contained (one idea, one CTA). +- **F-pattern** for text-heavy pages; **Z-pattern** for sparse landing pages. Place primary CTA at the terminus of the expected scan path. +- **Asymmetric / broken-grid** is back in 2026 marketing UI, but production app UI still rewards strict grids. +- **Scroll-driven storytelling** is the default long-form pattern; budget for IntersectionObserver-based reveals, not scroll-jacking. + +## Motion & Micro-interactions + +- **Durations**: 100–200ms for state changes (hover, press), 200–400ms for transitions (open/close), 400–800ms only for narrative reveals. Anything over 800ms feels broken. +- **Easing**: `cubic-bezier(0.4, 0, 0.2, 1)` (Material "standard") is a safe default. Linear easing should only appear on indeterminate spinners. +- **Always respect `prefers-reduced-motion`** — replace transforms with opacity fades, never remove feedback entirely. +- Every interactive element needs four visual states minimum: rest, hover, active/pressed, focus-visible. Disabled is a fifth when applicable. +- **Tactile maximalism** ("squishy UI") — buttons that compress 2–4% on press with a brief overshoot on release. Reads as premium on touch devices, gimmicky if every element does it. + +## Design Tokens & Systems + +- Tokens are tiered: **primitive** (`color-blue-500`) → **semantic** (`color-action-primary`) → **component** (`button-primary-bg`). Components reference semantic, never primitive. +- Spacing, radius, elevation, motion duration, and z-index all deserve token sets — not just color and type. +- **One source of truth** between design tool and code. Hand-off without sync drift means using Style Dictionary, Tokens Studio, or platform-native variables — not screenshots. + +## Accessibility (Non-Negotiable Floor) + +- Contrast ratios per WCAG 2.2 AA (above). +- Hit targets ≥44×44 pt (iOS) / 48×48 dp (Android) / 24×24 CSS px minimum on web with adequate spacing. +- Focus indicators must be visible against every background they cross — a 2px ring in brand color often fails on brand-colored sections; use a contrasting outline + offset. +- Support OS-level dynamic type up to 200%. Test that no text clips, truncates without affordance, or breaks layout. +- **Neurodivergent-friendly defaults**: avoid auto-playing motion, allow disabling parallax, keep cognitive load chunked, never rely on time-limited interactions without a pause control. + +## 2026 Trend Cheat Sheet + +Apply selectively — trendy ≠ correct for every product. + +- **Tactile maximalism** — glossy, clay, jelly textures with realistic depth. Strong for consumer/creative tools, wrong for finance/enterprise. +- **Dopamine + Y2K palettes** — saturated neons, chrome, gradients. Balance with desaturated dominant per 60-30-10. +- **Glassmorphism (refined)** — translucent surfaces with backdrop-blur. Always verify text contrast against the *worst-case* content behind the glass. +- **Bento grids** — feature showcases, settings screens, dashboards. +- **Adaptive / "vibe" UI** — theme shifts by mood, time, or focus state. Requires a deterministic fallback theme. +- **Controlled imperfection** — hand-drawn marks, collage textures, scribbles. Reads human; do not mix with hyper-precise grids unless deliberately contrasted. +- **Multimodal affordances** — even click/tap apps should expose voice and keyboard paths; design icons that work across input methods. + +## Gotchas + +- **Never** ship a glass/blur surface without testing text contrast against the darkest *and* brightest content that can scroll behind it. Designers reliably forget the bright case. +- **Never** apply Y2K saturation across an entire palette — keep one accent saturated and desaturate the rest, or the UI becomes illegible. +- **Never** specify pixel values without a token. `margin-top: 13px` is the canary for a design system in collapse. +- **Never** rely on hover for critical information or actions — touch users have no hover, and keyboard users need focus parity. +- **Never** animate `width`/`height`/`top`/`left` for transitions — animate `transform` and `opacity` to stay on the compositor thread. +- **Never** use placeholder text as the only label. It vanishes on focus and fails screen readers. +- The **aesthetic-usability effect** is real but cuts both ways: a beautiful UI hides usability flaws *during testing*, then surfaces them as churn. Test with real tasks, not first impressions. +- Trendy ≠ timeless. Default the long-lived parts of a system (type scale, spacing, accessibility) to conservative choices, and confine trends to surface treatments that can be swapped. + +## Troubleshooting + +| Symptom | Likely Cause | Fix | +|---|---|---| +| "Feels cluttered" | Weak hierarchy, no whitespace, equal-weight elements competing | Demote secondary elements, increase spacing, raise contrast on the one primary action | +| "Looks dated" | Tight radii + flat fills + 2018 sans-serif + heavy borders | Soften radii to one scale, replace borders with spacing or subtle elevation, refresh type | +| "Feels cheap" | Inconsistent spacing, mixed corner radii, low-quality imagery, default OS shadows | Enforce spacing scale, unify radii, audit photography/iconography, design custom shadows | +| "CTA gets lost" | Accent color used everywhere; CTA blends in | Reserve accent for CTA only; demote other accent uses to secondary palette | +| "Brand doesn't pop" | Brand color used as background everywhere, not as accent | Move brand to accent role; pick a neutral dominant | +| "Inaccessible per audit" | Insufficient contrast, missing focus rings, hover-only affordances | Run automated audit (axe), then manual keyboard + screen reader pass | +| "Animations feel janky" | Animating layout properties or running on main thread | Switch to `transform`/`opacity`; throttle non-essential motion; respect `prefers-reduced-motion` | + +## References + +- [Principles deep-dive](./references/principles.md) — visual hierarchy, Gestalt, Laws of UX +- [Design systems & tokens](./references/design-systems.md) — tiered tokens, variants, hand-off +- [Accessibility checklist](./references/accessibility.md) — WCAG 2.2 AA practical pass +- [2026 trends with caveats](./references/trends-2026.md) — when to adopt, when to skip diff --git a/skills/graphic-designer/references/accessibility.md b/skills/graphic-designer/references/accessibility.md new file mode 100644 index 000000000..3b2667d00 --- /dev/null +++ b/skills/graphic-designer/references/accessibility.md @@ -0,0 +1,67 @@ +# Accessibility Checklist (WCAG 2.2 AA, Practical) + +A pragmatic pass. Automated audits catch ~30% of issues; the rest needs manual review. + +## Color & Contrast + +- Body text against background: **≥ 4.5:1**. +- Large text (≥ 18pt or 14pt bold / ~24px or 19px bold): **≥ 3:1**. +- UI components and graphical objects (icons, form borders, focus rings): **≥ 3:1** against adjacent colors. +- **Test glass/blur surfaces against the worst-case content** that can scroll behind. Bright photos defeat dark text on glass even when the glass blur is heavy. +- Never encode information by color alone — pair with text, icon, or pattern. + +## Text & Type + +- Minimum body size: 16px on web, 17pt iOS, 14sp Android. +- Support OS dynamic type up to **200% zoom** with no clipping, horizontal scroll, or overlap. +- Line height ≥ 1.5 for body prose. Paragraph spacing ≥ 1.5× line height. Letter spacing ≥ 0.12× and word spacing ≥ 0.16× must remain visually acceptable when user-adjusted. +- No text in images for content. SVG with text or live HTML, always. + +## Interactive Elements + +- Hit target minimums: **24×24 CSS px** (WCAG 2.2 AA), with sufficient surrounding space. Practical floors: **44×44 pt** iOS, **48×48 dp** Android. +- **Focus indicator** must be visible against every background it crosses. A 2px brand-colored ring on a brand-colored section is invisible — add offset and contrasting outline. +- All hover states have a focus equivalent. All click handlers work via Enter/Space (or arrow keys, where appropriate). +- Drag-only interactions must have a non-drag fallback (WCAG 2.2 SC 2.5.7). +- Don't trap focus except in modals; always provide an escape (Esc key + close button + clicking the scrim). + +## Forms + +- Every input has a visible label. Placeholder is not a label. +- Errors are programmatically associated with their field (`aria-describedby`) and explain how to fix, not just what went wrong. +- Required fields marked with both text and a symbol; never asterisk-only. +- Autocomplete attributes on common fields (name, email, address, payment). +- Don't validate on blur of the first field before the user has finished typing the rest. + +## Motion & Animation + +- Respect `prefers-reduced-motion: reduce`. Replace motion with opacity fades or no transition; do not remove feedback entirely. +- No flashing content above 3Hz (seizure risk). +- Auto-playing motion longer than 5 seconds must be pausable. +- Parallax and scroll-jacking are accessibility hazards; provide an off switch or skip them. + +## Structure & Semantics + +- Heading hierarchy is meaningful and sequential (`h1` once, then `h2`, then `h3`; no skipping for size). +- Landmarks (`
`, `
`, `