gracefullight/pkgs / .agents/skills/oma-design
oma-design
UnverifiedDefine or review a visual system, DESIGN.md, or redesign direction. Use for typography, layout, color, motion, and interaction design decisions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.1 KB |
| examples/design-context-example.md | markdown | 2.3 KB |
| examples/landing-page-prompt.md | markdown | 4.8 KB |
| reference/accessibility.md | markdown | 4.4 KB |
| reference/color-and-contrast.md | markdown | 3.7 KB |
| reference/component-patterns.md | markdown | 5.7 KB |
| reference/motion-design.md | markdown | 7.9 KB |
| reference/responsive-design.md | markdown | 3.6 KB |
| reference/shader-and-3d.md | markdown | 5.0 KB |
| reference/spatial-design.md | markdown | 2.8 KB |
| reference/typography.md | markdown | 2.6 KB |
| reference/visual-hierarchy.md | markdown | 9.6 KB |
| resources/anti-patterns.md | markdown | 8.4 KB |
| resources/asset-strategy.md | markdown | 3.0 KB |
| resources/checklist.md | markdown | 5.6 KB |
| resources/design-md-spec.md | markdown | 8.3 KB |
| resources/design-tokens.md | markdown | 3.9 KB |
| resources/error-playbook.md | markdown | 3.9 KB |
| resources/execution-protocol.md | markdown | 14.5 KB |
| resources/getdesign-fetcher.md | markdown | 13.2 KB |
| resources/prompt-enhancement.md | markdown | 9.2 KB |
| resources/redesign-protocol.md | markdown | 3.7 KB |
| resources/stitch-integration.md | markdown | 3.8 KB |
resources/error-playbook.md
View on GitHub# Design Error Playbook
## Contrast Failure
**Symptom**: Text hard to read, WCAG contrast check fails.
**Fix**:
1. Check contrast ratio with browser DevTools or axe
2. For dark themes: use warm off-white (#f5f0eb) instead of pure white (#fff)
3. Increase text opacity (text-white/60 → text-white/80)
4. Darken or lighten background to increase contrast
5. For colored backgrounds: use dark text or add a dark overlay
**Prevention**: Always define text colors relative to backgrounds in DESIGN.md.
---
## AI Slop Detected
**Symptom**: Design looks generic, fails the "AI made this" test.
**Fix**:
1. Check anti-patterns.md to identify which patterns triggered
2. Replace purple gradients with brand-derived colors
3. Add texture (noise/grain) instead of plain gradients
4. Vary layout patterns across sections (not all card grids)
5. Inject project-specific design context from .design-context.md
6. Replace Inter/Geist with system fonts or project-specific fonts
7. Remove gratuitous glassmorphism; reserve for 1-2 accent elements
**Prevention**: Use relevant existing context; perform discovery when a new design decision requires it.
---
## Responsive Breakage
**Symptom**: Horizontal scroll, overlapping elements, tiny touch targets on mobile.
**Fix**:
1. Check at 375px viewport width (iPhone SE)
2. Stack columns: grid-cols-1 on mobile, grid-cols-2+ on md/lg
3. Increase touch targets to min 44x44pt (min-h-[44px] min-w-[44px])
4. Use clamp() for fluid typography instead of fixed sizes
5. Hide decorative elements on mobile if they cause overflow
6. Switch from side-by-side to stacked layout on mobile
7. Check for fixed-width elements: replace px values with percentages or max-w
**Prevention**: Always start with mobile layout, enhance upward.
---
## Animation Jank
**Symptom**: Janky scrolling, low FPS, dropped frames, laggy interactions.
**Fix**:
1. Only animate `transform` and `opacity`; never width, height, top, left
2. Reduce concurrent animations to max 2-3 visible simultaneously
3. Pause off-screen Canvas/WebGL with Intersection Observer
4. Add `will-change: transform` sparingly and remove after animation completes
5. Reduce particle count on mobile (50-75% fewer)
6. Provide static fallback for prefers-reduced-motion
7. Reduce canvas resolution: `renderer.setPixelRatio(Math.min(devicePixelRatio, 2))`
**Prevention**: Test on actual mobile devices, not just browser responsive mode.
---
## Stitch MCP Connection Failure
**Symptom**: MCP tools not responding, authentication errors.
**Fix**:
1. Run `npx @_davideast/stitch-mcp doctor --verbose`
2. Check API key validity or OAuth token expiry
3. Verify API is enabled: `gcloud beta services mcp enable stitch.googleapis.com`
4. For OAuth: re-authenticate with `npx @_davideast/stitch-mcp init`
5. For API key: verify STITCH_API_KEY environment variable is set
**Fallback**: Proceed without Stitch; all workflow phases work standalone.
---
## Design System Inconsistency
**Symptom**: Colors, spacing, or typography don't match DESIGN.md.
**Fix**:
1. Re-read DESIGN.md and compare against generated code
2. Search for hardcoded hex values: `grep -r "#[0-9a-fA-F]\{6\}" src/`
3. Replace hardcoded values with CSS custom properties or Tailwind theme tokens
4. Check for arbitrary Tailwind values (e.g., `text-[13px]`); replace with scale values
5. Verify spacing uses 8px grid multiples only
**Prevention**: Generate CSS custom properties from DESIGN.md before writing component code.
---
## Theme Switching Issues
**Symptom**: Elements look wrong in dark/light mode, missing tokens.
**Fix**:
1. Verify all color tokens have both :root and .dark variants
2. Check for hardcoded colors that bypass the theme system
3. Ensure borders use alpha transparency (border-white/10) not gray hex values
4. Test both themes end-to-end; toggle and check every section
5. Add system preference detection: prefers-color-scheme media query
**Prevention**: Define complete light and dark token sets in DESIGN.md before implementing.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |