MAX-DESIGN
One integrated, production-minded UI/UX workflow for AI coding agents. This root skill contains the shared workflow, every specialist playbook, decision documents, examples, validation scripts, and the local searchable design-knowledge catalog.
When to use
Use MAX-DESIGN for interface creation, product redesign, frontend implementation, UX improvements, design-system work, forms, dashboards, accessibility fixes, responsive behavior, localization, motion, design critique, or quality verification. Use the full workflow for substantial or cross-cutting tasks and only the relevant stages for narrow tasks.
Core principles
- Understand before styling. Inspect the existing product, routes, components, tokens, assets, tests, dependencies, and project instructions before changing code.
- Make intentional design decisions. Choose layout, hierarchy, density, typography, color roles, and signature details for the user's task instead of defaulting to generic templates.
- Preserve what works. Extend the existing stack and design system unless evidence supports a migration.
- Design the whole state model. Include relevant loading, pending, empty, no-results, validation, error, retry, disabled, focus, success, and stale-data states.
- Build real behavior. Do not fake backend success, customer metrics, testimonials, saved states, or other unsupported product claims.
- Make accessibility and resilience part of implementation. Consider semantic HTML, keyboard behavior, visible focus, contrast, reduced motion, zoom, touch input, long content, localization, RTL where relevant, and recovery from failed requests.
- Verify and report honestly. Separate code inspection, automated checks, browser testing, accessibility testing, performance measurement, and user research. Never claim a check that was not performed.
Workflow
1. Discover the user job
Identify the audience, primary task, primary action, important content, constraints, supported devices and input methods, risks, and observable acceptance criteria. Ask a question only when the answer could materially change the design; otherwise state a reasonable assumption and proceed.
2. Inspect the existing project
Read repository instructions, routes, representative screens, shared components, styles and tokens, assets, package scripts, tests, and existing documentation. Determine whether to preserve, extend, propose, or migrate the design system. Avoid unnecessary dependencies and broad rewrites.
3. Search the bundled design knowledge
Use the local catalog when a product, visual direction, page pattern, color, typography, motion, UX/accessibility, chart, implementation-stack, or density decision would benefit from a structured starting point. It is guidance, not a preset or an instruction to copy a pattern blindly. The knowledge is organized around original MAX-DESIGN records rather than imported third-party catalog files.
Run from the installed MAX-DESIGN directory:
bashnode scripts/search-design-knowledge.mjs "dashboard charts" node scripts/search-design-knowledge.mjs "AI assistant output states" --domain product node scripts/search-design-knowledge.mjs "dark dashboard palette" --domain color node scripts/search-design-knowledge.mjs "form errors" --domain ux node scripts/search-design-knowledge.mjs "reduced motion" --domain motion node scripts/search-design-knowledge.mjs "chart accessibility" --domain chart node scripts/search-design-knowledge.mjs "responsive charts" --domain stack node scripts/search-design-knowledge.mjs "responsive charts" --require-all --limit 5 node scripts/search-design-knowledge.mjs "modal focus lifecycle" --domain ux node scripts/search-design-knowledge.mjs "offline retry" --domain ux node scripts/search-design-knowledge.mjs "subscription invoice" --domain page node scripts/search-design-knowledge.mjs "Core Web Vitals" --domain stack
Available domains: all, direction, page, interaction, density, product, style, color, typography, motion, ux, chart, and stack. Use --json for machine-readable results. The search loader merges knowledge/design-patterns.json and knowledge/advanced-patterns.json; the search implementation is at scripts/search-design-knowledge.mjs. The supplementary records include advanced product workflows, AI streaming, account and billing, privacy and permissions, resilient network states, ARIA widget behavior, WCAG 2.2 checks, chart data integrity, and evidence-based performance review. Research provenance and source limitations are documented in docs/knowledge-sources.md. Search remains local and requires no network connection or third-party runtime dependency.
4. Select a specific direction
Read docs/decision-framework.md before substantial design work. Define the product personality, content hierarchy, focal point, type roles, semantic color, density, responsive behavior, one or two product-relevant signature details, motion rationale, and trade-offs. Do not default to gradients, glass, giant radii, repeated card grids, oversized headlines, or animated backgrounds without product-specific reasons.
5. Load the relevant specialist playbooks
MAX-DESIGN is the single installable skill. Its specialist workflows are bundled as reference playbooks in skills/; read the relevant files when needed. They are not intended to be installed as separate peer skills by the standard repository installation.
| Task | Bundled playbook |
|---|---|
| Distinctive frontend and responsive implementation | skills/frontend-design/SKILL.md |
| Navigation, information hierarchy, search, and task flows | skills/information-architecture/SKILL.md |
| Labels, onboarding, helper text, errors, and UX copy | skills/ux-writing-content/SKILL.md |
| Forms, validation, submission, and recovery | skills/forms-ux/SKILL.md |
| Tokens, components, themes, and safe migrations | skills/design-system/SKILL.md |
| Charts, metrics, tabular data, and analytical displays | skills/data-visualization/SKILL.md |
| Evidence-based interface critique | skills/design-review/SKILL.md |
| Transitions, micro-interactions, and motion | skills/interaction-motion/SKILL.md |
| Semantics, keyboard, focus, contrast, and accessibility | skills/accessibility-audit/SKILL.md |
| Localization, long text, RTL, and resilient error paths | skills/resilient-localization/SKILL.md |
| Interaction, responsive, accessibility, and visual verification | skills/ui-testing/SKILL.md |
Read only the playbooks relevant to the task, then combine their guidance into one coherent implementation. Shared principles and decision rules live in docs/design-principles.md, docs/quality-matrix.md, and docs/preflight-checklist.md.
6. Plan and implement
Structure content around the user task. Use semantic, maintainable components and the project's established conventions. Every visible control must perform a meaningful action, communicate its true state, or be explicitly disabled. Use realistic content and data. Preserve entered information after recoverable failures; provide clear feedback, retry paths, and confirmations proportionate to risk.
7. Review in impact order
Fix task-blocking behavior, incorrect information, confusing hierarchy, inaccessible interactions, broken responsive layouts, missing recovery states, and inconsistent tokens before decorative polish. Prioritize findings using docs/quality-matrix.md; separate observed issues from subjective preferences or untested assumptions.
8. Verify proportionately
Run the project's existing build, tests, lint, type checks, and other relevant scripts. Inspect narrow, medium, and wide layouts and exercise the key paths when browser tools are available. Use automated accessibility checks alongside manual keyboard review where practical. Check realistic long labels, empty states, errors, missing data, slow requests, and reduced-motion preferences when relevant.
The bundled repository has a dependency-free validator (Node.js 20+):
bashnpm test
The design-knowledge search is also available through:
bashnpm run search:design -- "responsive charts"
The validator checks the specialist playbooks, shared references, example tokens, catalog structure, and search smoke tests. Run it from the MAX-DESIGN directory. Do not run repository maintenance scripts from a target project unless you intend to validate the installed toolkit itself.
9. Hand off with evidence
For substantial work, summarize what changed, why major design decisions were made, what commands and viewports were checked, what remains unverified, and any meaningful trade-offs or risks. Never overstate accessibility, browser compatibility, performance, or conformance results.
Quality gates
- User goals, information hierarchy, and primary actions are clear.
- The design direction is distinctive for the product, not decorative by default.
- Existing project conventions and working behavior are preserved.
- UX copy, forms, charts, navigation, and data states are accurate and recoverable where relevant.
- Responsive behavior, keyboard operation, focus, semantics, contrast, zoom, and reduced motion are considered.
- Long text, localization, missing data, failed requests, and retry behavior are handled when applicable.
- Performance and dependency costs are proportionate to the value delivered.
- Verification claims match actual evidence and limitations are explicit.
Bundled content map
docs/— decision framework, design principles, quality matrix, and preflight checks.examples/— design brief template and semantic design-token example.knowledge/design-patterns.json— local searchable catalog of design directions, page patterns, interaction patterns, and density profiles.scripts/search-design-knowledge.mjs— offline catalog-search CLI.scripts/validate-skills.mjs— toolkit structure, metadata, token, catalog, and search validation.skills/— specialist playbooks included for on-demand use within this one MAX-DESIGN skill.
