contextos-agents 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/AGENTS.md +421 -0
- package/.agents/adapters/aider/export.js +137 -0
- package/.agents/adapters/claude/export.js +55 -0
- package/.agents/adapters/copilot/export.js +107 -0
- package/.agents/adapters/cursor/export.js +210 -0
- package/.agents/adapters/gemini/export.js +115 -0
- package/.agents/adapters/shared.js +119 -0
- package/.agents/adapters/zed/export.js +111 -0
- package/.agents/core/profiles/backend.yaml +47 -0
- package/.agents/core/profiles/enterprise.yaml +46 -0
- package/.agents/core/profiles/frontend.yaml +46 -0
- package/.agents/core/profiles/hackathon.yaml +45 -0
- package/.agents/core/profiles/mvp.yaml +43 -0
- package/.agents/core/profiles/startup.yaml +48 -0
- package/.agents/core/skills/adapters/EXAMPLES.md +19 -0
- package/.agents/core/skills/adapters/SKILL.md +105 -0
- package/.agents/core/skills/adapters/TROUBLESHOOTING.md +7 -0
- package/.agents/core/skills/adapters/VALIDATION.json +12 -0
- package/.agents/core/skills/adapters/skill.yaml +10 -0
- package/.agents/core/skills/architecture-diagrams/SKILL.md +108 -0
- package/.agents/core/skills/architecture-diagrams/VALIDATION.json +12 -0
- package/.agents/core/skills/architecture-diagrams/skill.yaml +8 -0
- package/.agents/core/skills/brutalist-design/SKILL.md +150 -0
- package/.agents/core/skills/brutalist-design/VALIDATION.json +12 -0
- package/.agents/core/skills/brutalist-design/skill.yaml +8 -0
- package/.agents/core/skills/context-manager/EXAMPLES.md +19 -0
- package/.agents/core/skills/context-manager/SKILL.md +126 -0
- package/.agents/core/skills/context-manager/TROUBLESHOOTING.md +7 -0
- package/.agents/core/skills/context-manager/VALIDATION.json +12 -0
- package/.agents/core/skills/context-manager/skill.yaml +10 -0
- package/.agents/core/skills/context-os/EXAMPLES.md +21 -0
- package/.agents/core/skills/context-os/SKILL.md +169 -0
- package/.agents/core/skills/context-os/TROUBLESHOOTING.md +7 -0
- package/.agents/core/skills/context-os/VALIDATION.json +12 -0
- package/.agents/core/skills/context-os/packs.yaml +59 -0
- package/.agents/core/skills/context-os/references/context-rules.md +68 -0
- package/.agents/core/skills/context-os/references/pipeline.md +119 -0
- package/.agents/core/skills/context-os/references/project-graph.md +103 -0
- package/.agents/core/skills/context-os/rules.yaml +135 -0
- package/.agents/core/skills/context-os/skill.yaml +10 -0
- package/.agents/core/skills/database/EXAMPLES.md +74 -0
- package/.agents/core/skills/database/SKILL.md +101 -0
- package/.agents/core/skills/database/TROUBLESHOOTING.md +18 -0
- package/.agents/core/skills/database/VALIDATION.json +11 -0
- package/.agents/core/skills/database/skill.yaml +25 -0
- package/.agents/core/skills/ddd/EXAMPLES.md +42 -0
- package/.agents/core/skills/ddd/SKILL.md +247 -0
- package/.agents/core/skills/ddd/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/ddd/VALIDATION.json +12 -0
- package/.agents/core/skills/ddd/ddd.md +178 -0
- package/.agents/core/skills/ddd/skill.yaml +10 -0
- package/.agents/core/skills/decisions/EXAMPLES.md +35 -0
- package/.agents/core/skills/decisions/SKILL.md +90 -0
- package/.agents/core/skills/decisions/TROUBLESHOOTING.md +13 -0
- package/.agents/core/skills/decisions/VALIDATION.json +12 -0
- package/.agents/core/skills/decisions/skill.yaml +10 -0
- package/.agents/core/skills/docker/EXAMPLES.md +56 -0
- package/.agents/core/skills/docker/SKILL.md +63 -0
- package/.agents/core/skills/docker/TROUBLESHOOTING.md +18 -0
- package/.agents/core/skills/docker/VALIDATION.json +11 -0
- package/.agents/core/skills/docker/skill.yaml +23 -0
- package/.agents/core/skills/engineering-workflow/EXAMPLES.md +57 -0
- package/.agents/core/skills/engineering-workflow/SKILL.md +343 -0
- package/.agents/core/skills/engineering-workflow/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/engineering-workflow/VALIDATION.json +12 -0
- package/.agents/core/skills/engineering-workflow/skill.yaml +13 -0
- package/.agents/core/skills/fastapi/EXAMPLES.md +36 -0
- package/.agents/core/skills/fastapi/SKILL.md +148 -0
- package/.agents/core/skills/fastapi/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/fastapi/VALIDATION.json +12 -0
- package/.agents/core/skills/fastapi/fastapi.md +112 -0
- package/.agents/core/skills/fastapi/skill.yaml +10 -0
- package/.agents/core/skills/gemini-precision/SKILL.md +169 -0
- package/.agents/core/skills/gemini-precision/VALIDATION.json +12 -0
- package/.agents/core/skills/gemini-precision/skill.yaml +9 -0
- package/.agents/core/skills/generators/EXAMPLES.md +19 -0
- package/.agents/core/skills/generators/SKILL.md +112 -0
- package/.agents/core/skills/generators/TROUBLESHOOTING.md +7 -0
- package/.agents/core/skills/generators/VALIDATION.json +12 -0
- package/.agents/core/skills/generators/skill.yaml +10 -0
- package/.agents/core/skills/generators/templates/API.md +77 -0
- package/.agents/core/skills/generators/templates/ARCHITECTURE.md +70 -0
- package/.agents/core/skills/generators/templates/DATABASE.md +42 -0
- package/.agents/core/skills/generators/templates/DECISION.md +46 -0
- package/.agents/core/skills/generators/templates/PRD.md +67 -0
- package/.agents/core/skills/generators/templates/PROJECT_GRAPH.md +56 -0
- package/.agents/core/skills/generators/templates/ROADMAP.md +51 -0
- package/.agents/core/skills/generators/templates/TASKS.md +43 -0
- package/.agents/core/skills/generators/templates/UI.md +73 -0
- package/.agents/core/skills/graphify/EXAMPLES.md +73 -0
- package/.agents/core/skills/graphify/SKILL.md +130 -0
- package/.agents/core/skills/graphify/VALIDATION.json +12 -0
- package/.agents/core/skills/graphify/skill.yaml +13 -0
- package/.agents/core/skills/gstack-roles/EXAMPLES.md +23 -0
- package/.agents/core/skills/gstack-roles/SKILL.md +152 -0
- package/.agents/core/skills/gstack-roles/TROUBLESHOOTING.md +13 -0
- package/.agents/core/skills/gstack-roles/VALIDATION.json +12 -0
- package/.agents/core/skills/gstack-roles/skill.yaml +12 -0
- package/.agents/core/skills/impeccable-design/EXAMPLES.md +26 -0
- package/.agents/core/skills/impeccable-design/SKILL.md +201 -0
- package/.agents/core/skills/impeccable-design/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/impeccable-design/VALIDATION.json +12 -0
- package/.agents/core/skills/impeccable-design/skill.yaml +14 -0
- package/.agents/core/skills/interview-me/SKILL.md +97 -0
- package/.agents/core/skills/interview-me/VALIDATION.json +12 -0
- package/.agents/core/skills/interview-me/skill.yaml +8 -0
- package/.agents/core/skills/microservices/EXAMPLES.md +38 -0
- package/.agents/core/skills/microservices/SKILL.md +164 -0
- package/.agents/core/skills/microservices/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/microservices/VALIDATION.json +12 -0
- package/.agents/core/skills/microservices/microservices.md +119 -0
- package/.agents/core/skills/microservices/skill.yaml +10 -0
- package/.agents/core/skills/minimalist-design/SKILL.md +113 -0
- package/.agents/core/skills/minimalist-design/VALIDATION.json +12 -0
- package/.agents/core/skills/minimalist-design/skill.yaml +8 -0
- package/.agents/core/skills/nestjs/EXAMPLES.md +40 -0
- package/.agents/core/skills/nestjs/SKILL.md +139 -0
- package/.agents/core/skills/nestjs/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/nestjs/VALIDATION.json +12 -0
- package/.agents/core/skills/nestjs/nestjs.md +103 -0
- package/.agents/core/skills/nestjs/skill.yaml +10 -0
- package/.agents/core/skills/nextjs/EXAMPLES.md +40 -0
- package/.agents/core/skills/nextjs/SKILL.md +163 -0
- package/.agents/core/skills/nextjs/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/nextjs/VALIDATION.json +12 -0
- package/.agents/core/skills/nextjs/nextjs.md +67 -0
- package/.agents/core/skills/nextjs/skill.yaml +10 -0
- package/.agents/core/skills/node/EXAMPLES.md +80 -0
- package/.agents/core/skills/node/SKILL.md +128 -0
- package/.agents/core/skills/node/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/node/VALIDATION.json +12 -0
- package/.agents/core/skills/node/node.md +87 -0
- package/.agents/core/skills/node/skill.yaml +10 -0
- package/.agents/core/skills/performance/EXAMPLES.md +30 -0
- package/.agents/core/skills/performance/SKILL.md +75 -0
- package/.agents/core/skills/performance/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/performance/VALIDATION.json +12 -0
- package/.agents/core/skills/performance/performance.md +52 -0
- package/.agents/core/skills/performance/skill.yaml +10 -0
- package/.agents/core/skills/ponytail-mindset/EXAMPLES.md +45 -0
- package/.agents/core/skills/ponytail-mindset/SKILL.md +193 -0
- package/.agents/core/skills/ponytail-mindset/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/ponytail-mindset/VALIDATION.json +12 -0
- package/.agents/core/skills/ponytail-mindset/skill.yaml +14 -0
- package/.agents/core/skills/react/EXAMPLES.md +79 -0
- package/.agents/core/skills/react/SKILL.md +132 -0
- package/.agents/core/skills/react/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/react/VALIDATION.json +12 -0
- package/.agents/core/skills/react/react.md +93 -0
- package/.agents/core/skills/react/skill.yaml +10 -0
- package/.agents/core/skills/react-best-practices/SKILL.md +155 -0
- package/.agents/core/skills/react-best-practices/VALIDATION.json +12 -0
- package/.agents/core/skills/react-best-practices/skill.yaml +10 -0
- package/.agents/core/skills/redesign-audit/SKILL.md +117 -0
- package/.agents/core/skills/redesign-audit/VALIDATION.json +12 -0
- package/.agents/core/skills/redesign-audit/skill.yaml +8 -0
- package/.agents/core/skills/security/EXAMPLES.md +64 -0
- package/.agents/core/skills/security/SKILL.md +158 -0
- package/.agents/core/skills/security/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/security/VALIDATION.json +12 -0
- package/.agents/core/skills/security/security.md +106 -0
- package/.agents/core/skills/security/skill.yaml +10 -0
- package/.agents/core/skills/soft-design/SKILL.md +108 -0
- package/.agents/core/skills/soft-design/VALIDATION.json +12 -0
- package/.agents/core/skills/soft-design/skill.yaml +8 -0
- package/.agents/core/skills/state-management/EXAMPLES.md +56 -0
- package/.agents/core/skills/state-management/SKILL.md +48 -0
- package/.agents/core/skills/state-management/TROUBLESHOOTING.md +18 -0
- package/.agents/core/skills/state-management/VALIDATION.json +11 -0
- package/.agents/core/skills/state-management/skill.yaml +22 -0
- package/.agents/core/skills/subagent-orchestrator/SKILL.md +100 -0
- package/.agents/core/skills/subagent-orchestrator/VALIDATION.json +12 -0
- package/.agents/core/skills/subagent-orchestrator/skill.yaml +8 -0
- package/.agents/core/skills/system-design/EXAMPLES.md +75 -0
- package/.agents/core/skills/system-design/SKILL.md +419 -0
- package/.agents/core/skills/system-design/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/system-design/VALIDATION.json +12 -0
- package/.agents/core/skills/system-design/skill.yaml +13 -0
- package/.agents/core/skills/system-design/system-design.md +112 -0
- package/.agents/core/skills/testing/EXAMPLES.md +71 -0
- package/.agents/core/skills/testing/SKILL.md +70 -0
- package/.agents/core/skills/testing/TROUBLESHOOTING.md +18 -0
- package/.agents/core/skills/testing/VALIDATION.json +11 -0
- package/.agents/core/skills/testing/skill.yaml +26 -0
- package/.agents/core/skills/typescript/EXAMPLES.md +64 -0
- package/.agents/core/skills/typescript/SKILL.md +112 -0
- package/.agents/core/skills/typescript/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/typescript/VALIDATION.json +12 -0
- package/.agents/core/skills/typescript/skill.yaml +10 -0
- package/.agents/core/skills/typescript/typescript.md +71 -0
- package/.agents/core/skills/ui-design/EXAMPLES.md +21 -0
- package/.agents/core/skills/ui-design/SKILL.md +124 -0
- package/.agents/core/skills/ui-design/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/ui-design/VALIDATION.json +12 -0
- package/.agents/core/skills/ui-design/skill.yaml +10 -0
- package/.agents/core/skills/ui-design/ui.md +88 -0
- package/.agents/core/skills/ui-ux-pro/EXAMPLES.md +62 -0
- package/.agents/core/skills/ui-ux-pro/SKILL.md +375 -0
- package/.agents/core/skills/ui-ux-pro/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/ui-ux-pro/VALIDATION.json +12 -0
- package/.agents/core/skills/ui-ux-pro/skill.yaml +13 -0
- package/.agents/core/skills/ux-design/EXAMPLES.md +36 -0
- package/.agents/core/skills/ux-design/SKILL.md +116 -0
- package/.agents/core/skills/ux-design/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/ux-design/VALIDATION.json +12 -0
- package/.agents/core/skills/ux-design/skill.yaml +10 -0
- package/.agents/core/skills/ux-design/ux.md +80 -0
- package/.agents/core/skills/vercel-optimize/SKILL.md +83 -0
- package/.agents/core/skills/vercel-optimize/VALIDATION.json +12 -0
- package/.agents/core/skills/vercel-optimize/skill.yaml +10 -0
- package/.agents/core/skills/web-accessibility/EXAMPLES.md +39 -0
- package/.agents/core/skills/web-accessibility/SKILL.md +170 -0
- package/.agents/core/skills/web-accessibility/TROUBLESHOOTING.md +19 -0
- package/.agents/core/skills/web-accessibility/VALIDATION.json +12 -0
- package/.agents/core/skills/web-accessibility/accessibility.md +63 -0
- package/.agents/core/skills/web-accessibility/skill.yaml +10 -0
- package/.agents/ctx.js +370 -0
- package/.agents/generated/claude/skills/adapters/SKILL.md +126 -0
- package/.agents/generated/claude/skills/architecture-diagrams/SKILL.md +101 -0
- package/.agents/generated/claude/skills/brutalist-design/SKILL.md +145 -0
- package/.agents/generated/claude/skills/context-manager/SKILL.md +147 -0
- package/.agents/generated/claude/skills/context-os/SKILL.md +191 -0
- package/.agents/generated/claude/skills/database/SKILL.md +191 -0
- package/.agents/generated/claude/skills/ddd/SKILL.md +305 -0
- package/.agents/generated/claude/skills/decisions/SKILL.md +134 -0
- package/.agents/generated/claude/skills/docker/SKILL.md +135 -0
- package/.agents/generated/claude/skills/engineering-workflow/SKILL.md +414 -0
- package/.agents/generated/claude/skills/fastapi/SKILL.md +200 -0
- package/.agents/generated/claude/skills/gemini-precision/SKILL.md +161 -0
- package/.agents/generated/claude/skills/generators/SKILL.md +133 -0
- package/.agents/generated/claude/skills/graphify/SKILL.md +198 -0
- package/.agents/generated/claude/skills/gstack-roles/SKILL.md +184 -0
- package/.agents/generated/claude/skills/impeccable-design/SKILL.md +241 -0
- package/.agents/generated/claude/skills/interview-me/SKILL.md +90 -0
- package/.agents/generated/claude/skills/microservices/SKILL.md +218 -0
- package/.agents/generated/claude/skills/minimalist-design/SKILL.md +108 -0
- package/.agents/generated/claude/skills/nestjs/SKILL.md +195 -0
- package/.agents/generated/claude/skills/nextjs/SKILL.md +219 -0
- package/.agents/generated/claude/skills/node/SKILL.md +224 -0
- package/.agents/generated/claude/skills/performance/SKILL.md +121 -0
- package/.agents/generated/claude/skills/ponytail-mindset/SKILL.md +252 -0
- package/.agents/generated/claude/skills/react/SKILL.md +227 -0
- package/.agents/generated/claude/skills/react-best-practices/SKILL.md +146 -0
- package/.agents/generated/claude/skills/redesign-audit/SKILL.md +112 -0
- package/.agents/generated/claude/skills/security/SKILL.md +237 -0
- package/.agents/generated/claude/skills/soft-design/SKILL.md +103 -0
- package/.agents/generated/claude/skills/state-management/SKILL.md +120 -0
- package/.agents/generated/claude/skills/subagent-orchestrator/SKILL.md +93 -0
- package/.agents/generated/claude/skills/system-design/SKILL.md +507 -0
- package/.agents/generated/claude/skills/testing/SKILL.md +157 -0
- package/.agents/generated/claude/skills/typescript/SKILL.md +192 -0
- package/.agents/generated/claude/skills/ui-design/SKILL.md +161 -0
- package/.agents/generated/claude/skills/ui-ux-pro/SKILL.md +451 -0
- package/.agents/generated/claude/skills/ux-design/SKILL.md +168 -0
- package/.agents/generated/claude/skills/vercel-optimize/SKILL.md +76 -0
- package/.agents/generated/claude/skills/web-accessibility/SKILL.md +225 -0
- package/.agents/generated/gemini/skills/adapters/SKILL.md +135 -0
- package/.agents/generated/gemini/skills/architecture-diagrams/SKILL.md +107 -0
- package/.agents/generated/gemini/skills/brutalist-design/SKILL.md +151 -0
- package/.agents/generated/gemini/skills/context-manager/SKILL.md +156 -0
- package/.agents/generated/gemini/skills/context-os/SKILL.md +200 -0
- package/.agents/generated/gemini/skills/database/SKILL.md +200 -0
- package/.agents/generated/gemini/skills/ddd/SKILL.md +314 -0
- package/.agents/generated/gemini/skills/decisions/SKILL.md +143 -0
- package/.agents/generated/gemini/skills/docker/SKILL.md +144 -0
- package/.agents/generated/gemini/skills/engineering-workflow/SKILL.md +423 -0
- package/.agents/generated/gemini/skills/fastapi/SKILL.md +209 -0
- package/.agents/generated/gemini/skills/gemini-precision/SKILL.md +167 -0
- package/.agents/generated/gemini/skills/generators/SKILL.md +142 -0
- package/.agents/generated/gemini/skills/graphify/SKILL.md +205 -0
- package/.agents/generated/gemini/skills/gstack-roles/SKILL.md +193 -0
- package/.agents/generated/gemini/skills/impeccable-design/SKILL.md +250 -0
- package/.agents/generated/gemini/skills/interview-me/SKILL.md +96 -0
- package/.agents/generated/gemini/skills/microservices/SKILL.md +227 -0
- package/.agents/generated/gemini/skills/minimalist-design/SKILL.md +114 -0
- package/.agents/generated/gemini/skills/nestjs/SKILL.md +204 -0
- package/.agents/generated/gemini/skills/nextjs/SKILL.md +298 -0
- package/.agents/generated/gemini/skills/node/SKILL.md +323 -0
- package/.agents/generated/gemini/skills/performance/SKILL.md +185 -0
- package/.agents/generated/gemini/skills/ponytail-mindset/SKILL.md +261 -0
- package/.agents/generated/gemini/skills/react/SKILL.md +332 -0
- package/.agents/generated/gemini/skills/react-best-practices/SKILL.md +152 -0
- package/.agents/generated/gemini/skills/redesign-audit/SKILL.md +118 -0
- package/.agents/generated/gemini/skills/security/SKILL.md +355 -0
- package/.agents/generated/gemini/skills/soft-design/SKILL.md +109 -0
- package/.agents/generated/gemini/skills/state-management/SKILL.md +129 -0
- package/.agents/generated/gemini/skills/subagent-orchestrator/SKILL.md +99 -0
- package/.agents/generated/gemini/skills/system-design/SKILL.md +631 -0
- package/.agents/generated/gemini/skills/testing/SKILL.md +166 -0
- package/.agents/generated/gemini/skills/typescript/SKILL.md +275 -0
- package/.agents/generated/gemini/skills/ui-design/SKILL.md +170 -0
- package/.agents/generated/gemini/skills/ui-ux-pro/SKILL.md +460 -0
- package/.agents/generated/gemini/skills/ux-design/SKILL.md +177 -0
- package/.agents/generated/gemini/skills/vercel-optimize/SKILL.md +82 -0
- package/.agents/generated/gemini/skills/web-accessibility/SKILL.md +300 -0
- package/.agents/mcp/runtime.py +454 -0
- package/.agents/mcp/server.mjs +189373 -0
- package/.agents/plugins.js +574 -0
- package/.agents/profiles.js +267 -0
- package/.agents/resolver.js +336 -0
- package/.agents/skills-index.json +200 -0
- package/.agents/skills.json +6 -0
- package/.agents/validate.js +500 -0
- package/LICENSE +21 -0
- package/README.md +415 -0
- package/benchmarks/gemini-issues.js +533 -0
- package/bin/index.js +458 -0
- package/package.json +70 -0
- package/registry.json +53 -0
- package/registry.schema.json +32 -0
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: UX Design
|
|
3
|
+
description: >
|
|
4
|
+
ContextOS skill for UX Design
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# UX Design
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
User experience and interaction design standard. Enforces progressive disclosure, predictable user flows, designed empty/loading/error states, form usability, and keyboard navigation ergonomics.
|
|
12
|
+
|
|
13
|
+
## When to Use
|
|
14
|
+
|
|
15
|
+
Activate when designing complex multi-step workflows, onboarding funnels, form validation feedback, error recovery flows, and user journeys.
|
|
16
|
+
|
|
17
|
+
## Rules & Patterns
|
|
18
|
+
<!-- Source: ux.md -->
|
|
19
|
+
|
|
20
|
+
## UX Design — Best Practices
|
|
21
|
+
|
|
22
|
+
## Information Architecture
|
|
23
|
+
|
|
24
|
+
- **Mental models** — organize content the way users think, not the way your code is structured
|
|
25
|
+
- **Card sorting** — group features into logical categories
|
|
26
|
+
- **Navigation structure** — no more than 3 clicks to any page
|
|
27
|
+
- **Naming** — use user's language, not internal jargon
|
|
28
|
+
|
|
29
|
+
## User Flows
|
|
30
|
+
|
|
31
|
+
### Design every state
|
|
32
|
+
|
|
33
|
+
Every screen has 5 states. Design ALL of them:
|
|
34
|
+
|
|
35
|
+
1. **Empty state** — first visit, no data yet. Include CTA to get started
|
|
36
|
+
2. **Loading state** — skeleton screens > spinners
|
|
37
|
+
3. **Partial state** — some data, not complete
|
|
38
|
+
4. **Ideal state** — normal usage with data
|
|
39
|
+
5. **Error state** — what went wrong and how to fix it
|
|
40
|
+
|
|
41
|
+
### Reduce cognitive load
|
|
42
|
+
|
|
43
|
+
- **Progressive disclosure** — show only what's needed now
|
|
44
|
+
- **Sensible defaults** — pre-fill what you can
|
|
45
|
+
- **Inline help** — tooltips and contextual guidance
|
|
46
|
+
- **Confirmation for destructive actions** — but NOT for every action
|
|
47
|
+
|
|
48
|
+
## Forms UX
|
|
49
|
+
|
|
50
|
+
- Show progress for multi-step forms
|
|
51
|
+
- Validate inline (on blur), not on submit
|
|
52
|
+
- Show password requirements as the user types
|
|
53
|
+
- Auto-focus the first input
|
|
54
|
+
- Use appropriate input types (email, tel, date)
|
|
55
|
+
- Disable submit button only when form is submitting, never as "validation"
|
|
56
|
+
|
|
57
|
+
## Onboarding
|
|
58
|
+
|
|
59
|
+
- **Quick win** — let users see value within 30 seconds
|
|
60
|
+
- **Minimal signup** — only ask for what's absolutely needed
|
|
61
|
+
- **Progressive onboarding** — teach features as users encounter them
|
|
62
|
+
- **Skip option** — always let users skip tutorials
|
|
63
|
+
|
|
64
|
+
## Feedback
|
|
65
|
+
|
|
66
|
+
- Every action needs feedback (success, error, pending)
|
|
67
|
+
- Use toast notifications for non-blocking feedback
|
|
68
|
+
- Use inline messages for form validation
|
|
69
|
+
- Loading states should be < 300ms before showing (avoid flash)
|
|
70
|
+
- Optimistic UI for fast-perceived actions
|
|
71
|
+
|
|
72
|
+
## Mobile UX
|
|
73
|
+
|
|
74
|
+
- Touch targets: minimum 44x44px
|
|
75
|
+
- Thumb zones — place primary actions within easy reach
|
|
76
|
+
- Bottom navigation for core actions
|
|
77
|
+
- Pull-to-refresh for content lists
|
|
78
|
+
- Haptic feedback for important actions
|
|
79
|
+
|
|
80
|
+
## Psychology Principles
|
|
81
|
+
|
|
82
|
+
- **Fitts's Law** — make important targets large and close
|
|
83
|
+
- **Hick's Law** — reduce choices to reduce decision time
|
|
84
|
+
- **Jakob's Law** — users prefer familiar patterns
|
|
85
|
+
- **Peak-End Rule** — make the last interaction great
|
|
86
|
+
- **Aesthetic-Usability Effect** — beautiful things are perceived as easier to use
|
|
87
|
+
|
|
88
|
+
## Usability Heuristics (Nielsen)
|
|
89
|
+
|
|
90
|
+
1. Visibility of system status
|
|
91
|
+
2. Match between system and real world
|
|
92
|
+
3. User control and freedom (undo, escape)
|
|
93
|
+
4. Consistency and standards
|
|
94
|
+
5. Error prevention
|
|
95
|
+
6. Recognition rather than recall
|
|
96
|
+
7. Flexibility and efficiency of use
|
|
97
|
+
8. Aesthetic and minimalist design
|
|
98
|
+
9. Help users recognize and recover from errors
|
|
99
|
+
10. Help and documentation
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
## Code Examples
|
|
103
|
+
|
|
104
|
+
See `EXAMPLES.md` for detailed code examples.
|
|
105
|
+
|
|
106
|
+
## Validation Checklist
|
|
107
|
+
|
|
108
|
+
What to verify during the review phase before completing the task.
|
|
109
|
+
|
|
110
|
+
## Common Mistakes
|
|
111
|
+
|
|
112
|
+
Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
|
|
113
|
+
|
|
114
|
+
## Integration Notes
|
|
115
|
+
|
|
116
|
+
How this skill interacts with other skills.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# ux-design Troubleshooting & Common Mistakes
|
|
2
|
+
|
|
3
|
+
## 1. Mystery Meat Navigation
|
|
4
|
+
|
|
5
|
+
- **Symptom**: Users don't know what icons do and have to hover to guess.
|
|
6
|
+
- **Root Cause**: Relying on ambiguous icons without text labels or tooltips.
|
|
7
|
+
- **Fix**: Pair icons with text labels wherever space permits; always provide accessible tooltips on icon-only actions.
|
|
8
|
+
|
|
9
|
+
## 2. Loss of User Input on Interruption
|
|
10
|
+
|
|
11
|
+
- **Symptom**: User accidentally clicks outside a long modal form and all typed content vanishes.
|
|
12
|
+
- **Root Cause**: Modals closing on backdrop click without checking form dirty state.
|
|
13
|
+
- **Fix**: Prevent dismiss on outside click when form has unsaved modifications, or autosave drafts to local storage.
|
|
14
|
+
|
|
15
|
+
## 3. Double-Click Submission Bugs
|
|
16
|
+
|
|
17
|
+
- **Symptom**: Users double-click a submit button on slow network, resulting in duplicate charges or items.
|
|
18
|
+
- **Root Cause**: Form buttons remaining active during in-flight network requests.
|
|
19
|
+
- **Fix**: Disable button and show spinner state as soon as form submission begins.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# UX Design — Best Practices
|
|
2
|
+
|
|
3
|
+
## Information Architecture
|
|
4
|
+
|
|
5
|
+
- **Mental models** — organize content the way users think, not the way your code is structured
|
|
6
|
+
- **Card sorting** — group features into logical categories
|
|
7
|
+
- **Navigation structure** — no more than 3 clicks to any page
|
|
8
|
+
- **Naming** — use user's language, not internal jargon
|
|
9
|
+
|
|
10
|
+
## User Flows
|
|
11
|
+
|
|
12
|
+
### Design every state
|
|
13
|
+
|
|
14
|
+
Every screen has 5 states. Design ALL of them:
|
|
15
|
+
|
|
16
|
+
1. **Empty state** — first visit, no data yet. Include CTA to get started
|
|
17
|
+
2. **Loading state** — skeleton screens > spinners
|
|
18
|
+
3. **Partial state** — some data, not complete
|
|
19
|
+
4. **Ideal state** — normal usage with data
|
|
20
|
+
5. **Error state** — what went wrong and how to fix it
|
|
21
|
+
|
|
22
|
+
### Reduce cognitive load
|
|
23
|
+
|
|
24
|
+
- **Progressive disclosure** — show only what's needed now
|
|
25
|
+
- **Sensible defaults** — pre-fill what you can
|
|
26
|
+
- **Inline help** — tooltips and contextual guidance
|
|
27
|
+
- **Confirmation for destructive actions** — but NOT for every action
|
|
28
|
+
|
|
29
|
+
## Forms UX
|
|
30
|
+
|
|
31
|
+
- Show progress for multi-step forms
|
|
32
|
+
- Validate inline (on blur), not on submit
|
|
33
|
+
- Show password requirements as the user types
|
|
34
|
+
- Auto-focus the first input
|
|
35
|
+
- Use appropriate input types (email, tel, date)
|
|
36
|
+
- Disable submit button only when form is submitting, never as "validation"
|
|
37
|
+
|
|
38
|
+
## Onboarding
|
|
39
|
+
|
|
40
|
+
- **Quick win** — let users see value within 30 seconds
|
|
41
|
+
- **Minimal signup** — only ask for what's absolutely needed
|
|
42
|
+
- **Progressive onboarding** — teach features as users encounter them
|
|
43
|
+
- **Skip option** — always let users skip tutorials
|
|
44
|
+
|
|
45
|
+
## Feedback
|
|
46
|
+
|
|
47
|
+
- Every action needs feedback (success, error, pending)
|
|
48
|
+
- Use toast notifications for non-blocking feedback
|
|
49
|
+
- Use inline messages for form validation
|
|
50
|
+
- Loading states should be < 300ms before showing (avoid flash)
|
|
51
|
+
- Optimistic UI for fast-perceived actions
|
|
52
|
+
|
|
53
|
+
## Mobile UX
|
|
54
|
+
|
|
55
|
+
- Touch targets: minimum 44x44px
|
|
56
|
+
- Thumb zones — place primary actions within easy reach
|
|
57
|
+
- Bottom navigation for core actions
|
|
58
|
+
- Pull-to-refresh for content lists
|
|
59
|
+
- Haptic feedback for important actions
|
|
60
|
+
|
|
61
|
+
## Psychology Principles
|
|
62
|
+
|
|
63
|
+
- **Fitts's Law** — make important targets large and close
|
|
64
|
+
- **Hick's Law** — reduce choices to reduce decision time
|
|
65
|
+
- **Jakob's Law** — users prefer familiar patterns
|
|
66
|
+
- **Peak-End Rule** — make the last interaction great
|
|
67
|
+
- **Aesthetic-Usability Effect** — beautiful things are perceived as easier to use
|
|
68
|
+
|
|
69
|
+
## Usability Heuristics (Nielsen)
|
|
70
|
+
|
|
71
|
+
1. Visibility of system status
|
|
72
|
+
2. Match between system and real world
|
|
73
|
+
3. User control and freedom (undo, escape)
|
|
74
|
+
4. Consistency and standards
|
|
75
|
+
5. Error prevention
|
|
76
|
+
6. Recognition rather than recall
|
|
77
|
+
7. Flexibility and efficiency of use
|
|
78
|
+
8. Aesthetic and minimalist design
|
|
79
|
+
9. Help users recognize and recover from errors
|
|
80
|
+
10. Help and documentation
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vercel-optimize
|
|
3
|
+
description: "Use for Vercel cost and performance optimization on deployed projects, especially Next.js, SvelteKit, Nuxt, and limited Astro apps. Collect Vercel metrics, usage, project config, and code scan results first; investigate only metric-backed candidates; produce ranked recommendations grounded in verified files and version-aware Vercel/framework docs. Trigger for Vercel bill reduction, slow or expensive routes, caching opportunities, Function Invocations, Build Minutes, Fast Data Transfer, Core Web Vitals, Bot Management, Fluid compute, or cost breakdown requests."
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.2.0"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Vercel Optimize
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
Observability-first Vercel performance and cost reduction optimization skill. Evaluates deployed Next.js, SvelteKit, Nuxt, and Astro projects using production telemetry signals (`signals.json`), deterministic candidate gating, and code scanning to deliver ranked, verified architectural recommendations.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- When tasked with reducing Vercel bills, Function Invocations, Fast Data Transfer, or Build Minutes.
|
|
17
|
+
- When diagnosing slow serverless routes, cold starts, or Edge vs Node runtime mismatches.
|
|
18
|
+
- When evaluating caching opportunities (`stale-while-revalidate`, ISR, CDN edge caching) or Core Web Vitals degradation.
|
|
19
|
+
|
|
20
|
+
## Rules & Patterns
|
|
21
|
+
|
|
22
|
+
### 1. Prerequisites & Framework Support
|
|
23
|
+
|
|
24
|
+
- Vercel CLI v53+ with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api`.
|
|
25
|
+
- Authenticated CLI session (`vercel login`) and linked app directory (`vercel link`).
|
|
26
|
+
- Framework support: Next.js App Router (Full), Pages Router (Supported), SvelteKit (Supported), Nuxt (Supported), Astro (Limited).
|
|
27
|
+
- Security rule: Never put auth tokens in shell commands (`VERCEL_TOKEN=...` is banned in chat/logs).
|
|
28
|
+
|
|
29
|
+
### 2. Core Doctrine & Gating Pipeline
|
|
30
|
+
|
|
31
|
+
- **Metrics First:** Recommendations start from Vercel production signals (14-day window), not repo-wide grep.
|
|
32
|
+
- **Deterministic Gates:** `scripts/gate-investigations.mjs` selects code-scope and platform-scope candidates.
|
|
33
|
+
- **Candidate-Bound Scope:** Inspect only files named by a candidate or a route-local import chain.
|
|
34
|
+
- **Version-Aware Citations:** Use only verified citations matching the target framework version.
|
|
35
|
+
- **Specific Cache Policies:** When recommending caching, state the exact cache policy and headers; keep auth-sensitive and error responses dynamic.
|
|
36
|
+
|
|
37
|
+
### 3. Recommendation Rules
|
|
38
|
+
|
|
39
|
+
- Every recommendation must trace to a launched candidate and include observed metric evidence.
|
|
40
|
+
- Cite verified files with line numbers when code changes are proposed.
|
|
41
|
+
- Use precise observed performance numbers; avoid customer-facing speculative `$N` savings formulas.
|
|
42
|
+
- Do not recommend duration reductions for Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`).
|
|
43
|
+
|
|
44
|
+
## Code Examples
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
// [GOOD] Next.js Route Segment Config for Caching & Edge Runtime
|
|
48
|
+
export const dynamic = 'force-static';
|
|
49
|
+
export const revalidate = 3600; // Cache at Edge for 1 hour
|
|
50
|
+
|
|
51
|
+
export default async function CachedCatalogPage() {
|
|
52
|
+
const products = await getCatalogData();
|
|
53
|
+
return <CatalogGrid items={products} />;
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Running the signals collection and gate
|
|
59
|
+
node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json"
|
|
60
|
+
node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
|
|
61
|
+
node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"
|
|
62
|
+
node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Validation Checklist
|
|
66
|
+
|
|
67
|
+
- [ ] Project is properly linked with valid team/personal scope (`vercel link`).
|
|
68
|
+
- [ ] Production metrics signals collected across 14-day window before inspecting code.
|
|
69
|
+
- [ ] No secrets or tokens passed in command line arguments.
|
|
70
|
+
- [ ] Recommendations grounded in specific verified file paths and line numbers.
|
|
71
|
+
- [ ] Unsafe or auth-sensitive paths kept strictly dynamic.
|
|
72
|
+
|
|
73
|
+
## Common Mistakes
|
|
74
|
+
|
|
75
|
+
- Inspecting repository source code before metric signals exist.
|
|
76
|
+
- Hardcoding `VERCEL_TOKEN` into terminal commands or prompt logs.
|
|
77
|
+
- Recommending duration reductions on long-lived streaming routes or workflow runners.
|
|
78
|
+
- Applying static caching to user-specific or authenticated routes.
|
|
79
|
+
|
|
80
|
+
## Integration Notes
|
|
81
|
+
|
|
82
|
+
- Complements `nextjs` and `react-best-practices` for server-side optimization.
|
|
83
|
+
- Pairs with `performance` and `security` skills.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# web-accessibility Examples — Anti-patterns vs ContextOS Standard
|
|
2
|
+
|
|
3
|
+
## Example 1: Semantic Buttons vs Clickable Divs
|
|
4
|
+
|
|
5
|
+
### Anti-pattern: Clickable Div
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
// BAD: Cannot be focused with Tab, does not respond to Enter or Space, silent to screen readers
|
|
9
|
+
<div className="button" onClick={handleSubmit}>Submit</div>
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
### Best practice: ContextOS Standard (Semantic Button Element)
|
|
13
|
+
|
|
14
|
+
```tsx
|
|
15
|
+
// GOOD: Keyboard focusable, native Enter/Space handling, properly announced by assistive tech
|
|
16
|
+
<button type="button" onClick={handleSubmit} className="btn btn-primary">
|
|
17
|
+
Submit
|
|
18
|
+
</button>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Example 2: Icon-only Buttons
|
|
24
|
+
|
|
25
|
+
### Anti-pattern: Unlabelled Icon Button
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
// BAD: Screen reader announces "button", user has zero idea what it does
|
|
29
|
+
<button onClick={onClose}><XIcon /></button>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Best practice: ContextOS Standard (Accessible Label)
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
// GOOD: Explicit aria-label and hidden decorative icon
|
|
36
|
+
<button type="button" onClick={onClose} aria-label="Close modal window">
|
|
37
|
+
<XIcon aria-hidden="true" />
|
|
38
|
+
</button>
|
|
39
|
+
```
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Web Accessibility
|
|
3
|
+
description: >
|
|
4
|
+
ContextOS skill for Web Accessibility (WCAG 2.1 AA/AAA), ARIA dialog patterns, keyboard focus traps, and Web Interface Guidelines.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Web Accessibility & Interface Guidelines
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
Enforces universal accessibility compliance (WCAG 2.1 AA / AAA), rigorous semantic markup, keyboard navigability with focus traps, screen reader live regions, and Web Interface Guidelines standards.
|
|
12
|
+
|
|
13
|
+
## When to Use
|
|
14
|
+
|
|
15
|
+
Activate whenever building, styling, or reviewing user interfaces, forms, modals, menus, navigation drawers, custom interactive widgets, or media elements.
|
|
16
|
+
|
|
17
|
+
## Negative Constraints (What NOT to Do)
|
|
18
|
+
|
|
19
|
+
1. **NEVER use `outline: none` without a custom `:focus-visible` replacement**: Keyboard users must always have a distinct, high-contrast visual focus ring.
|
|
20
|
+
2. **NEVER use non-semantic elements (`<div onClick>`) for interactive triggers**: Always use native `<button>` or `<a href>`.
|
|
21
|
+
3. **NEVER create modals or dialogs without keyboard focus traps**: Focus must remain trapped inside open dialogs during Tab / Shift-Tab navigation and restore to trigger on close.
|
|
22
|
+
4. **NEVER rely exclusively on color to indicate state or errors**: Always pair colors with text labels, icons, or ARIA attributes (`aria-invalid="true"`).
|
|
23
|
+
5. **NEVER trap screen readers with missing form labels or error associations**: Every input must link to `<label htmlFor="id">` and errors via `aria-describedby`.
|
|
24
|
+
6. **NEVER play animations without honoring `prefers-reduced-motion`**: Respect user OS motion reduction preferences.
|
|
25
|
+
|
|
26
|
+
## Rules & Patterns
|
|
27
|
+
|
|
28
|
+
### 1. Focus Visible & High-Contrast Focus Rings
|
|
29
|
+
|
|
30
|
+
```css
|
|
31
|
+
button:focus-visible,
|
|
32
|
+
a:focus-visible,
|
|
33
|
+
input:focus-visible {
|
|
34
|
+
outline: 2px solid #6366f1;
|
|
35
|
+
outline-offset: 2px;
|
|
36
|
+
border-radius: 4px;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
button:focus:not(:focus-visible) {
|
|
40
|
+
outline: none;
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### 2. Accessible Modal & Focus Trap Contract
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
import React, { useEffect, useRef } from 'react';
|
|
48
|
+
import { createPortal } from 'react-dom';
|
|
49
|
+
|
|
50
|
+
interface ModalProps {
|
|
51
|
+
isOpen: boolean;
|
|
52
|
+
onClose: () => void;
|
|
53
|
+
titleId: string;
|
|
54
|
+
children: React.ReactNode;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export function AccessibleModal({ isOpen, onClose, titleId, children }: ModalProps) {
|
|
58
|
+
const dialogRef = useRef<HTMLDivElement>(null);
|
|
59
|
+
const triggerRef = useRef<HTMLElement | null>(null);
|
|
60
|
+
|
|
61
|
+
useEffect(() => {
|
|
62
|
+
if (!isOpen) return;
|
|
63
|
+
triggerRef.current = document.activeElement as HTMLElement;
|
|
64
|
+
|
|
65
|
+
const handleKeyDown = (e: KeyboardEvent) => {
|
|
66
|
+
if (e.key === 'Escape') {
|
|
67
|
+
e.preventDefault();
|
|
68
|
+
onClose();
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
if (e.key === 'Tab') {
|
|
72
|
+
const focusables = dialogRef.current?.querySelectorAll<HTMLElement>(
|
|
73
|
+
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
|
|
74
|
+
) || [];
|
|
75
|
+
if (!focusables.length) return;
|
|
76
|
+
|
|
77
|
+
const first = focusables[0];
|
|
78
|
+
const last = focusables[focusables.length - 1];
|
|
79
|
+
|
|
80
|
+
if (e.shiftKey && document.activeElement === first) {
|
|
81
|
+
e.preventDefault();
|
|
82
|
+
last.focus();
|
|
83
|
+
} else if (!e.shiftKey && document.activeElement === last) {
|
|
84
|
+
e.preventDefault();
|
|
85
|
+
first.focus();
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
};
|
|
89
|
+
|
|
90
|
+
document.addEventListener('keydown', handleKeyDown);
|
|
91
|
+
return () => {
|
|
92
|
+
document.removeEventListener('keydown', handleKeyDown);
|
|
93
|
+
triggerRef.current?.focus();
|
|
94
|
+
};
|
|
95
|
+
}, [isOpen, onClose]);
|
|
96
|
+
|
|
97
|
+
if (!isOpen) return null;
|
|
98
|
+
|
|
99
|
+
return createPortal(
|
|
100
|
+
<div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4">
|
|
101
|
+
<div
|
|
102
|
+
ref={dialogRef}
|
|
103
|
+
role="dialog"
|
|
104
|
+
aria-modal="true"
|
|
105
|
+
aria-labelledby={titleId}
|
|
106
|
+
className="w-full max-w-lg rounded-xl bg-background p-6 shadow-2xl border"
|
|
107
|
+
>
|
|
108
|
+
{children}
|
|
109
|
+
</div>
|
|
110
|
+
</div>,
|
|
111
|
+
document.body
|
|
112
|
+
);
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### 3. Accessible Forms & Error Association
|
|
117
|
+
|
|
118
|
+
```tsx
|
|
119
|
+
export function EmailInput({ error, ...props }: { error?: string } & React.InputHTMLAttributes<HTMLInputElement>) {
|
|
120
|
+
const inputId = 'user-email';
|
|
121
|
+
const errorId = 'user-email-error';
|
|
122
|
+
|
|
123
|
+
return (
|
|
124
|
+
<div className="flex flex-col gap-1.5">
|
|
125
|
+
<label htmlFor={inputId} className="text-sm font-medium">
|
|
126
|
+
Email Address <span aria-hidden="true" className="text-destructive">*</span>
|
|
127
|
+
</label>
|
|
128
|
+
<input
|
|
129
|
+
id={inputId}
|
|
130
|
+
type="email"
|
|
131
|
+
autoComplete="email"
|
|
132
|
+
required
|
|
133
|
+
aria-invalid={Boolean(error)}
|
|
134
|
+
aria-describedby={error ? errorId : undefined}
|
|
135
|
+
className="rounded-md border p-2 text-sm focus-visible:ring-2"
|
|
136
|
+
{...props}
|
|
137
|
+
/>
|
|
138
|
+
{error && (
|
|
139
|
+
<p id={errorId} role="alert" className="text-xs text-destructive">
|
|
140
|
+
{error}
|
|
141
|
+
</p>
|
|
142
|
+
)}
|
|
143
|
+
</div>
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Code Examples
|
|
149
|
+
|
|
150
|
+
See `EXAMPLES.md` for detailed dialog, menu, and form examples.
|
|
151
|
+
|
|
152
|
+
## Validation Checklist
|
|
153
|
+
|
|
154
|
+
- [ ] All interactive elements are fully operable via Keyboard (`Tab`, `Enter`, `Space`, `Escape`).
|
|
155
|
+
- [ ] Visual `:focus-visible` styling is distinct and high contrast (≥ 3:1).
|
|
156
|
+
- [ ] Modals use `role="dialog"`, `aria-modal="true"`, focus trap, and restore focus on close.
|
|
157
|
+
- [ ] Text contrast ratios satisfy WCAG AA (≥ 4.5:1 for normal text, ≥ 3:1 for large text).
|
|
158
|
+
- [ ] Forms pair inputs with `<label htmlFor>`, valid `autocomplete` tokens, and `aria-invalid`.
|
|
159
|
+
- [ ] Non-text media contains descriptive `alt` attributes or `aria-hidden="true"` for decorative icons.
|
|
160
|
+
|
|
161
|
+
## Common Mistakes
|
|
162
|
+
|
|
163
|
+
- Hiding outline focus indicators globally without `:focus-visible` fallback.
|
|
164
|
+
- Forgetting to trap focus in modal dialogs or not returning focus to trigger when modal closes.
|
|
165
|
+
- Missing `aria-expanded` attributes on disclosure buttons and dropdown toggles.
|
|
166
|
+
|
|
167
|
+
## Integration Notes
|
|
168
|
+
|
|
169
|
+
- Pairs with `ui-ux-pro` and `impeccable-design` for visual contrast and component standards.
|
|
170
|
+
- Pairs with `react` and `nextjs` for accessible dialogs and focus restoration across route transitions.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# web-accessibility Troubleshooting & Common Mistakes
|
|
2
|
+
|
|
3
|
+
## 1. Trapping Keyboard Users in Inactive Elements
|
|
4
|
+
|
|
5
|
+
- **Symptom**: Tab key moves focus into invisible elements hidden offscreen.
|
|
6
|
+
- **Root Cause**: Using display: none vs opacity: 0 or left: -9999px.
|
|
7
|
+
- **Fix**: Always apply display: none / hidden or inert attribute to elements that are currently not visible.
|
|
8
|
+
|
|
9
|
+
## 2. Color Contrast Violations
|
|
10
|
+
|
|
11
|
+
- **Symptom**: Text is unreadable for users with low vision or in bright sunlight.
|
|
12
|
+
- **Root Cause**: Contrast ratio between text and background color is below WCAG AA thresholds.
|
|
13
|
+
- **Fix**: Ensure contrast ratio is at least 4.5:1 for body text and 3:1 for large text / graphical controls.
|
|
14
|
+
|
|
15
|
+
## 3. Silent Dynamic Updates
|
|
16
|
+
|
|
17
|
+
- **Symptom**: Asynchronous error messages or notifications appear on screen without screen reader announcement.
|
|
18
|
+
- **Root Cause**: Missing ARIA live region.
|
|
19
|
+
- **Fix**: Wrap notification banners in aria-live="polite" and role="status".
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Web Accessibility — WCAG 2.1 Compliance
|
|
2
|
+
|
|
3
|
+
## Principles (POUR)
|
|
4
|
+
|
|
5
|
+
1. **Perceivable** — content can be perceived by all users
|
|
6
|
+
2. **Operable** — interface can be operated by all users
|
|
7
|
+
3. **Understandable** — content and interface are understandable
|
|
8
|
+
4. **Robust** — content works across assistive technologies
|
|
9
|
+
|
|
10
|
+
## Keyboard Navigation
|
|
11
|
+
|
|
12
|
+
- All interactive elements must be reachable with Tab
|
|
13
|
+
- Focus order must be logical (DOM order)
|
|
14
|
+
- Custom widgets need keyboard handlers (Enter, Space, Escape, Arrow keys)
|
|
15
|
+
- Visible focus indicator on all interactive elements (never `outline: none` without replacement)
|
|
16
|
+
- Skip navigation link for repeated content
|
|
17
|
+
|
|
18
|
+
## Semantic HTML
|
|
19
|
+
|
|
20
|
+
- Use `<button>` not `<div onClick>` for actions
|
|
21
|
+
- Use `<a href>` for navigation
|
|
22
|
+
- Use heading hierarchy (`<h1>` → `<h2>` → `<h3>`)
|
|
23
|
+
- Use `<nav>`, `<main>`, `<article>`, `<aside>` landmarks
|
|
24
|
+
- Use `<label>` with every form input
|
|
25
|
+
|
|
26
|
+
## ARIA (when HTML alone isn't enough)
|
|
27
|
+
|
|
28
|
+
- `aria-label` — label for screen readers when no visible text
|
|
29
|
+
- `aria-labelledby` — reference to existing visible text
|
|
30
|
+
- `aria-describedby` — additional description
|
|
31
|
+
- `aria-live="polite"` — announce dynamic changes
|
|
32
|
+
- `aria-expanded` — for collapsible sections
|
|
33
|
+
- `aria-hidden="true"` — hide decorative elements
|
|
34
|
+
|
|
35
|
+
**Rule: no ARIA is better than bad ARIA.** Use semantic HTML first.
|
|
36
|
+
|
|
37
|
+
## Color and Contrast
|
|
38
|
+
|
|
39
|
+
- Text contrast: 4.5:1 minimum (AA), 7:1 (AAA)
|
|
40
|
+
- Large text (18px+ bold, 24px+ regular): 3:1 minimum
|
|
41
|
+
- Never use color alone to convey information
|
|
42
|
+
- Test with grayscale filter
|
|
43
|
+
|
|
44
|
+
## Images
|
|
45
|
+
|
|
46
|
+
- All images need `alt` text
|
|
47
|
+
- Decorative images: `alt=""`
|
|
48
|
+
- Complex images: `aria-describedby` with longer description
|
|
49
|
+
- SVG icons: `role="img"` + `aria-label`
|
|
50
|
+
|
|
51
|
+
## Forms
|
|
52
|
+
|
|
53
|
+
- Every input needs a visible `<label>`
|
|
54
|
+
- Error messages linked with `aria-describedby`
|
|
55
|
+
- Required fields marked with `aria-required="true"`
|
|
56
|
+
- Group related fields with `<fieldset>` + `<legend>`
|
|
57
|
+
|
|
58
|
+
## Testing
|
|
59
|
+
|
|
60
|
+
- Automated: axe-core, Lighthouse accessibility audit
|
|
61
|
+
- Manual: keyboard-only navigation test
|
|
62
|
+
- Screen reader: test with NVDA (Windows), VoiceOver (Mac)
|
|
63
|
+
- Zoom: test at 200% and 400% zoom
|