shadow-design
Skill1 starsChanged yesterdayMITView on GitHub
Product UI/UX & Design Systems. Use when designing design tokens, UX user flows, wireframes, 9-state component contracts, or human-AI UX states. Pair with antislop-ui.
In this repository51 other files it gives its agents.
- antislop-codeSkill
- antislop-copywritingSkill
- antislop-humanSkill
- antislop-layoutmobileSkill
- antislopSkill
- antislop-uiSkill
- context7Skill
- handoffSkill
- shadow-accessibilitySkill
- shadow-apiSkill
- shadow-architectSkill
- shadow-authSkill
- shadow-bootstrapSkill
- shadow-browserSkill
- shadow-cacheSkill
- shadow-compatSkill
- shadow-concurrencySkill
- shadow-dataSkill
- shadow-dbSkill
- shadow-debugSkill
- shadow-discoverySkill
- shadow-docSkill
- shadow-domainSkill
- shadow-eaSkill
- shadow-evalSkill
- shadow-finopsSkill
- shadow-gitSkill
- shadow-grcSkill
- shadow-handoverSkill
- shadow-integrateSkill
- shadow-maintainSkill
- shadow-mobileSkill
- shadow-modernizeSkill
- shadow-monarchSkill
- shadow-observeSkill
- shadow-opsSkill
- shadow-perfSkill
- shadow-planSkill
- shadow-pmoSkill
- shadow-presalesSkill
- shadow-privacySkill
- shadow-qualitySkill
- shadow-realtimeSkill
- shadow-refactorSkill
- shadow-releaseSkill
- shadow-resilienceSkill
- shadow-searchSkill
- shadow-secSkill
- shadow-supplychainSkill
- shadow-testSkill
- shadow-uatSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use this skill before or during frontend/mobile/AI product implementation to establish an Evidence-Disciplined Product Specification, …
- Very specific: line 42
When designing or implementing any of these 15 core product flows, load the corresponding T1 reference before writing UI code:
- Distinctive: line 64
Every product/UX claim MUST be explicitly labeled:
- Very specific: line 71
Before designing or modifying UI in an existing repository, build a compact pattern inventory (pattern -> where used -> accepted behavior …
- Very specific: line 77
Never hardcode arbitrary hex colors, pixel spacings, or font sizes per page.
- Distinctive: line 114
Partial / Degraded State: When one sub-widget or non-critical service fails, render available data and isolate the retry banner to the …
- Very specific: line 127
Never display a green "Completed" or "Ready" toast on HTTP 202 Accepted when background worker indexing or settlement is still running.
- Very specific: line 137
Before signing off on any feature design (templates/FEATURE-DESIGN.md) or UX review
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Shadow Design (/shadow-design) — Product Design, User Flows, 9-State Machines & Design Systems
Use this skill before or during frontend/mobile/AI product implementation to establish an Evidence-Disciplined Product Specification, Brownfield Pattern Inventory, User Story → Flow → State Traceability, Design System Tokens, and Severity-First UX Release Gate.
Provenance & Safe Upstream Sync: Enhanced with vendored reference modules and templates from
ai-product-designer-skill-packplus 4 auditedT1_AUDITED_MARKDOWNexternal Git skill packs (ghaida/intent,jpoindexter/ux-flow-skills,phuryn/pm-skills,Owl-Listener/designer-skills), all tracked with license, commit SHA, and per-file SHA-256 checksums inUPSTREAM_PROVENANCE.json. Verify integrity or safely pull upstream GitHub updates anytime via:python shadow-quality/scripts/skill_vendor_sync.py verify shadow-design python shadow-quality/scripts/skill_vendor_sync.py check-remote-updates shadow-design python shadow-quality/scripts/skill_vendor_sync.py update-remote shadow-design
0. Foreign-Key Reference Routing (Load Only What the Task Needs)
| Design Phase / Topic | Reference File |
| Discovery, JTBD & Evidence Tagging | references/ai-product-designer-skill-pack/01-discovery-and-evidence.md |
User Stories (US-ID), Flows & Preconditions | references/ai-product-designer-skill-pack/02-story-to-flow.md |
9-State Machines, Concurrency (ETag) & 12-Domain Edge Cases | references/ai-product-designer-skill-pack/03-state-machine-and-edge-cases.md |
| Information Architecture, Navigation & Wayfinding | references/ai-product-designer-skill-pack/04-information-architecture-and-patterns.md |
| Existing Product Guardian & Token Discipline | references/ai-product-designer-skill-pack/05-existing-system-guardian.md |
| Accessibility (WCAG 2.2 AA), Mobile & Microcopy | references/ai-product-designer-skill-pack/06-accessibility-responsive-content.md |
| Privacy, RBAC, Security & Anti-Dark-Pattern Ethics | references/ai-product-designer-skill-pack/07-privacy-security-and-ethics.md |
Async (HTTP 202 != Done) & Human-AI Failure Modes | references/ai-product-designer-skill-pack/08-async-and-ai-ux.md |
| Severity-First UX Review & Release Gates | references/ai-product-designer-skill-pack/09-ux-evaluation-and-gates.md |
| Engineering Handoff, Traceability & Metrics | references/ai-product-designer-skill-pack/10-handoff-and-measurement.md |
Curated External Projects & Trust Tiers (T0–T3) | references/ai-product-designer-skill-pack/11-external-projects-and-trust.md |
Upstream Pack: Design with Intent (ghaida/intent, CC0-1.0, T1) | references/external-upstreams/ghaida-intent/README.md (skills/intent, strategize, investigate, blueprint, journey, organize, wireframe, articulate, evaluate, fortify, include, transpose, localize, measure, philosopher, storytelling, specify, present) |
Upstream Pack: UX Flow Skills (jpoindexter/ux-flow-skills, MIT, T1) | references/external-upstreams/ux-flow-skills/README.md (15 production flow blueprints + userflow dispatcher — see §0b below) |
Upstream Pack: PM Skills (phuryn/pm-skills, MIT, T1) | references/external-upstreams/pm-skills/README.md (pm-product-discovery, pm-product-strategy, pm-execution, pm-market-research, pm-data-analytics, pm-go-to-market, pm-ai-shipping) |
Upstream Pack: Designer Skills (Owl-Listener/designer-skills, MIT, T1) | references/external-upstreams/designer-skills/README.md (design-research, ux-strategy, interaction-design, ui-design, design-systems, visual-critique, prototyping-testing, design-ops, designer-toolkit) |
| Feature Design Spec Template | templates/FEATURE-DESIGN.md |
| UX Review & Release Gate Template | templates/UX-REVIEW.md |
0b. 15-Domain Battle-Tested UX Flow Routing (ux-flow-skills)
When designing or implementing any of these 15 core product flows, load the corresponding T1 reference before writing UI code:
- Onboarding & First-Run Activation:
skills/flow-onboarding/SKILL.md - Authentication, Passkeys, Magic Links, SSO & 2FA:
skills/flow-auth/SKILL.md - Empty States, Skeletons & Perceived Speed:
skills/flow-empty-states/SKILL.md - Permission Priming & Just-in-Time Prompts:
skills/flow-permissions/SKILL.md - Checkout, Cart, Express Pay & Confirmation:
skills/flow-checkout/SKILL.md - Pricing, Trials, Paywalls & Honest Cancellation:
skills/flow-paywall/SKILL.md - Settings IA, Account Management & Danger Zones:
skills/flow-settings/SKILL.md - Sharing Links, Invites & Collaboration Cues:
skills/flow-sharing/SKILL.md - Navigation (Tab Bar vs Sidebar vs Command Palette):
skills/flow-navigation/SKILL.md - App Shell (Sidebar+Main, 3-Pane, Master-Detail Collapse):
skills/flow-app-shell/SKILL.md - Enterprise Data Tables, Bulk Actions & Pagination:
skills/flow-tables/SKILL.md - Search, Faceted Filters & Zero-Results Recovery:
skills/flow-search/SKILL.md - Forms, Validation Timing, Wizards & Save-and-Resume:
skills/flow-forms/SKILL.md - Error Anatomy, Undo-over-Confirm, Offline & Work Preservation:
skills/flow-errors/SKILL.md - AI / Chat UX, Streaming, Tool-Use Display & Human-in-the-Loop:
skills/flow-ai-chat/SKILL.md
1. Evidence Discipline & Existing Product Guardian (Before Drawing Screens)
- Mandatory Evidence Classification:
Every product/UX claim MUST be explicitly labeled:
[EVIDENCE]: Grounded in real codebase routes/components, analytics, support tickets, or dated user research.[ASSUMPTION]: Plausible product hypothesis — must state risk if wrong and validation plan.[PROPOSAL]: Recommended design direction awaiting Monarch/stakeholder decision.[NEEDS VALIDATION]: Unverified usability or behavioral question.- Strict Prohibition: Never fabricate user interviews, quote fake personas as empirical evidence, or claim usability is "validated" without actual user testing.
- Existing Product Guardian (Brownfield UI Preservation):
Before designing or modifying UI in an existing repository, build a compact pattern inventory (
pattern -> where used -> accepted behavior -> defects -> recommendation). Reuse established navigation, shells, form patterns, table toolbars, modal/drawer rules, and status nomenclature unless fixing a documented usability/accessibility defect.
2. Design System Foundation (Tokens Before Components)
Never hardcode arbitrary hex colors, pixel spacings, or font sizes per page. Define semantic design tokens in a single source of truth (tailwind.config, CSS custom properties :root, or Flutter ThemeData):
- Typography Scale:
- Font families:
--font-sans(UI body),--font-display(headings),--font-mono(IDs, code, financial numbers withfont-variant-numeric: tabular-nums). - Strict hierarchy: Page Title (
h1), Section Header (h2), Card Title (h3), Body (1rem/16px— prevents iOS auto-zoom on inputs), Secondary/Caption (0.875rem/14px).
- Font families:
- Semantic Color Tokens (WCAG 2.2 AA/AAA Contrast Verified):
- Surfaces:
bg-canvas,bg-surface,bg-elevated,bg-muted. - Text:
text-primary,text-secondary,text-muted,text-on-brand. - Status:
status-success,status-warning,status-danger,status-info(always pair color with an icon, shape, or text badge — never rely on color alone).
- Surfaces:
- Spacing, Radius & Elevation Scale:
- 4px/8px spatial grid (
4, 8, 12, 16, 24, 32, 48, 64px). - Consistent border-radius and border-width across cards, inputs, modals, and buttons.
- 4px/8px spatial grid (
3. User Story → Flow → Wireframe Traceability (US-ID -> FLOW-ID -> SCR-ID -> STATE-ID -> AC-ID)
For every feature module, maintain stable IDs across revisions (CONFIRMED | PROPOSED | UNKNOWN | DEFERRED):
- Entry Point, Deep Links & Wayfinding: How the user reaches the screen (including cold deep-link with expired auth or missing permissions), breadcrumbs, unsaved-change guard on back navigation, and return-to-origin behavior.
- Information Hierarchy & Microcopy: Primary action (max 1 primary CTA per screen view using outcome verbs like
"Save invoice", never"OK"), secondary actions, and progressive disclosure. Error copy must state what happened, why (if helpful), and how to recover while preserving all user-typed input. - Responsive Reflow & I18n Contract (
320px/375pxMobile ->768pxTablet ->1440pxDesktop +200%Zoom):- How data tables transform or scroll horizontally with sticky key columns on mobile.
- Touch target minimums (
44x44pxrecommended, WCAG 2.2 minimum24x24 CSS px) and bottom sheet / drawer patterns on mobile vs modals/popovers on desktop. - Layout resilience for
+30–40%translated text expansion (e.g., Bahasa Indonesia / German), locale-aware date/currency formatting, and logical CSS properties (margin-inline,padding-inline).
4. Mandatory 9-State Component & Transition Contract
Model interactive screens and components as explicit state transitions (State + Event + Guard -> Next State / Side Effect / Visible Feedback). Every data-driven or transactional view MUST account for all 9 states:
- Initial / Pre-Action State: Clear entry affordance, preconditions, and default focus/selection.
- Loading / Pending State: Skeleton placeholders matching final geometry (zero CLS spikes); step/queue progress for operations
>3s. - Empty State (3 Distinct Sub-States):
- First-use / No data yet: Welcoming explanation + primary CTA to create the first record.
- No filter/search results: Show active query/filters + 1-click "Reset filters" button.
- Empty due to error or permission: Never disguise a failed API fetch or
403 Forbiddenas "0 items".
- Partial / Degraded State: When one sub-widget or non-critical service fails, render available data and isolate the retry banner to the failed section.
- Populated / Success State: Handle long strings (
text-overflow: ellipsisor clean wrapping),tabular-nums, and unambiguous completion feedback. - Validation / Recoverable Error State: Inline field-level errors linked via
aria-describedby+ error summary for long forms; never wipe user-typed form input on failed submit. - Permission-Denied (
401/403) State: Explain which role/permission is required and provide a safe action (request access, switch account, or return home) without leaking sensitive record metadata. - Offline / Disconnected State: Detect network loss, disable or queue unsafe mutations, preserve local draft state, and auto-reconcile on reconnect.
- Stale / Concurrent-Edit Conflict (
409/ETagMismatch) State: When another user or tab updates the same record, block silent overwrites; present a diff or choice to reload/merge changes safely.
5. Async (HTTP 202 Accepted != Completed) & Human-AI UX Contract
- Asynchronous Lifecycle Honesty:
- Distinguish Submitted -> Queued (
HTTP 202) -> Processing -> Indexing/Finalizing -> Completed -> Failed -> Cancelled. - Never display a green
"Completed"or"Ready"toast onHTTP 202 Acceptedwhen background worker indexing or settlement is still running. - Prevent duplicate submissions via disabled/loading submit state + server idempotency keys.
- Distinguish Submitted -> Queued (
- Human-AI Interaction Resilience:
- Explicitly design for: hallucination/uncertainty warnings, source citation links, empty retrieval (0 RAG hits), partial stream disconnect, tool/permission refusal, latency spikes, and prompt-injection quarantine in untrusted retrieved documents.
- Provide Stop generating, Retry, Edit prompt, and Human confirmation gates before any destructive, financial, legal, or external-sending action.
6. 12-Domain Adversarial UX Walkthrough & Severity-First Release Gate
Before signing off on any feature design (templates/FEATURE-DESIGN.md) or UX review (templates/UX-REVIEW.md):
- Run the 12-Domain Adversarial Walkthrough:
Test the flow against: (1) Input extremes/paste/Unicode, (2) Validation recovery, (3) Double-click/back-button/refresh mid-submit, (4) Deep-link/logged-out entry, (5) Multi-tab/concurrent edit (
ETag), (6) Slow/offline/partial API, (7) Empty vs no-results vs error, (8) Role/permission revocation mid-session, (9) Destructive action undo/confirmation, (10) Long lists/pagination/bulk selection, (11) Keyboard-only/screen-reader/zoom, and (12) Locale/timezone/DST boundaries. - Severity-First UX Quality Gate:
Heuristic scores (0–100) are internal expert estimates (
NOT TESTEDwith real users unless empirical testing was executed). Any unmitigated CRITICAL blocker (irreversible data loss, deceptiveHTTP 202success, broken keyboard/screen-reader core path, or permission leak) forces aREJECT / REVISEdecision regardless of numeric score. - Ethical & Anti-Dark-Pattern Gate (72+ Catalog):
Cross-check flows against
ghaida-intent/skills/intent/references/ethical-design.mdand07-privacy-security-and-ethics.md. Strictly prohibit:- Roach Motels / Asymmetric Friction: Unsubscribing, cancelling a trial, revoking consent, or deleting an account must be as direct as signing up.
- Confirmshaming, Fake Urgency & Pre-checked Opt-ins: Never pre-check marketing/telemetry consent or fabricate countdown timers.
- AI-Specific Dark Patterns: Never disguise AI-generated estimates as verified human/legal truth, hide model errors, or silently train on private tenant inputs without explicit opt-in (UU PDP / GDPR / EU DSA compliance).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

