@design-ai/cli 4.55.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/.claude-plugin/plugin.json +164 -0
- package/AGENTS.ko.md +126 -0
- package/AGENTS.md +182 -0
- package/CHANGELOG.md +6883 -0
- package/CLAUDE.md +39 -0
- package/LICENSE +21 -0
- package/README.ko.md +245 -0
- package/README.md +277 -0
- package/agents/README.md +14 -0
- package/agents/a11y-reviewer.md +121 -0
- package/agents/component-architect.md +57 -0
- package/agents/design-critic.md +46 -0
- package/agents/token-extractor.md +63 -0
- package/cli/bin/design-ai-mcp.mjs +6 -0
- package/cli/bin/design-ai.mjs +40 -0
- package/cli/commands/audit.mjs +111 -0
- package/cli/commands/check.mjs +226 -0
- package/cli/commands/doctor.mjs +141 -0
- package/cli/commands/examples.mjs +58 -0
- package/cli/commands/help.mjs +271 -0
- package/cli/commands/install.mjs +161 -0
- package/cli/commands/learn.mjs +1871 -0
- package/cli/commands/list.mjs +143 -0
- package/cli/commands/mcp.mjs +27 -0
- package/cli/commands/pack.mjs +211 -0
- package/cli/commands/prompt.mjs +199 -0
- package/cli/commands/route.mjs +247 -0
- package/cli/commands/search.mjs +60 -0
- package/cli/commands/show.mjs +52 -0
- package/cli/commands/site.mjs +558 -0
- package/cli/commands/status.mjs +161 -0
- package/cli/commands/uninstall.mjs +119 -0
- package/cli/commands/update.mjs +184 -0
- package/cli/commands/version.mjs +94 -0
- package/cli/commands/workspace.mjs +176 -0
- package/cli/lib/brief.mjs +52 -0
- package/cli/lib/check.mjs +642 -0
- package/cli/lib/dispatch.mjs +109 -0
- package/cli/lib/doctor.mjs +505 -0
- package/cli/lib/examples.mjs +258 -0
- package/cli/lib/exec.mjs +63 -0
- package/cli/lib/help-flags.mjs +5 -0
- package/cli/lib/learn.mjs +3694 -0
- package/cli/lib/log.mjs +47 -0
- package/cli/lib/mcp-server.mjs +426 -0
- package/cli/lib/output.mjs +101 -0
- package/cli/lib/pack.mjs +599 -0
- package/cli/lib/paths.mjs +63 -0
- package/cli/lib/prompt.mjs +603 -0
- package/cli/lib/route.mjs +740 -0
- package/cli/lib/search.mjs +158 -0
- package/cli/lib/show.mjs +161 -0
- package/cli/lib/signals.mjs +2337 -0
- package/cli/lib/site.mjs +6617 -0
- package/cli/lib/skill-proposals.mjs +2046 -0
- package/cli/lib/suggest.mjs +66 -0
- package/cli/lib/workspace.mjs +1056 -0
- package/commands/README.md +25 -0
- package/commands/component-spec.md +34 -0
- package/commands/conversational.md +44 -0
- package/commands/design-from-brief.md +141 -0
- package/commands/design-review.md +62 -0
- package/commands/document-from-brief.md +47 -0
- package/commands/extract-tokens.md +38 -0
- package/commands/game-ui.md +40 -0
- package/commands/illustration.md +37 -0
- package/commands/iterate.md +167 -0
- package/commands/motion-design.md +54 -0
- package/commands/palette-from-brand.md +50 -0
- package/commands/print.md +49 -0
- package/commands/slide-deck.md +46 -0
- package/commands/spatial.md +47 -0
- package/commands/stability-review.md +74 -0
- package/commands/video.md +42 -0
- package/commands/website-improvement.md +77 -0
- package/docs/AGENT-DEVELOPMENT.md +658 -0
- package/docs/AI-LEARNING.md +429 -0
- package/docs/AIDER-INTEGRATION.md +224 -0
- package/docs/ARCHITECTURE.ko.md +183 -0
- package/docs/ARCHITECTURE.md +105 -0
- package/docs/CODEX-INTEGRATION.md +311 -0
- package/docs/COMPANY-WEBSITE-DOGFOOD.ko.md +144 -0
- package/docs/COMPANY-WEBSITE-DOGFOOD.md +150 -0
- package/docs/COMPANY-WEBSITE-INTAKE-TEMPLATE.ko.md +153 -0
- package/docs/COMPANY-WEBSITE-INTAKE-TEMPLATE.md +154 -0
- package/docs/CONTRIBUTING.ko.md +203 -0
- package/docs/CONTRIBUTING.md +242 -0
- package/docs/CURSOR-INTEGRATION.md +220 -0
- package/docs/DISTRIBUTION.ko.md +248 -0
- package/docs/DISTRIBUTION.md +253 -0
- package/docs/DOGFOOD-FINDINGS.md +180 -0
- package/docs/DOGFOOD-V4-FINDINGS.md +139 -0
- package/docs/DOGFOOD-V4-MKDOCS-FINDINGS.md +233 -0
- package/docs/DOGFOOD-V4-NPM-FINDINGS.md +157 -0
- package/docs/DOGFOOD-V4-VSCODE-FINDINGS.md +135 -0
- package/docs/FIGMA-INTEGRATION.md +222 -0
- package/docs/MCP-INTEGRATION.md +243 -0
- package/docs/MIGRATION-v4.md +121 -0
- package/docs/PLUGIN-PACKAGING.md +240 -0
- package/docs/PRODUCT-READINESS.md +66 -0
- package/docs/QUICKSTART.ko.md +178 -0
- package/docs/QUICKSTART.md +179 -0
- package/docs/RELEASE-CHECKLIST.md +292 -0
- package/docs/ROADMAP.md +19495 -0
- package/docs/SESSION-LOG.md +940 -0
- package/docs/TOKEN-SYNC.md +237 -0
- package/docs/USING.ko.md +206 -0
- package/docs/USING.md +218 -0
- package/docs/WEBSITE-IMPROVEMENT.ko.md +75 -0
- package/docs/WEBSITE-IMPROVEMENT.md +89 -0
- package/docs/announcements/README.md +56 -0
- package/docs/announcements/dev-to-korea.md +206 -0
- package/docs/announcements/hashnode-post.ko.md +232 -0
- package/docs/announcements/okky-post.ko.md +158 -0
- package/docs/announcements/press-kit.md +101 -0
- package/docs/announcements/reddit-r-korea.md +196 -0
- package/docs/announcements/show-hn.md +114 -0
- package/docs/announcements/twitter-thread.md +255 -0
- package/docs/external-status.md +34 -0
- package/docs/integrations/aider-walkthrough.ko.md +275 -0
- package/docs/integrations/aider-walkthrough.md +274 -0
- package/docs/integrations/codex-walkthrough.ko.md +297 -0
- package/docs/integrations/codex-walkthrough.md +297 -0
- package/docs/integrations/cursor-walkthrough.ko.md +281 -0
- package/docs/integrations/cursor-walkthrough.md +284 -0
- package/docs/integrations/design-ai-mcp-server.md +169 -0
- package/docs/integrations/figma-mcp.md +149 -0
- package/docs/integrations/github-mcp.md +178 -0
- package/docs/integrations/linear-mcp.md +215 -0
- package/docs/integrations/notion-mcp.md +174 -0
- package/docs/integrations/sdk-walkthrough.ko.md +375 -0
- package/docs/integrations/sdk-walkthrough.md +375 -0
- package/docs/integrations/slack-mcp.md +208 -0
- package/docs/integrations/vscode-walkthrough.ko.md +202 -0
- package/docs/integrations/vscode-walkthrough.md +205 -0
- package/docs/requirements.txt +16 -0
- package/docs/site-overrides/extra.css +83 -0
- package/docs/site-overrides/favicon.svg +4 -0
- package/docs/site-overrides/logo.svg +10 -0
- package/docs/site-overrides/main.html +18 -0
- package/docs/website-console/app.js +2540 -0
- package/docs/website-console/index.html +24 -0
- package/docs/website-console/styles.css +975 -0
- package/examples/README.md +252 -0
- package/examples/cases/dogfood-v4-korean-hr-onboarding.md +356 -0
- package/examples/component-accordion-actions.md +153 -0
- package/examples/component-accordion-details.md +147 -0
- package/examples/component-accordion-summary.md +180 -0
- package/examples/component-accordion.md +229 -0
- package/examples/component-account-card.md +284 -0
- package/examples/component-address-input.md +260 -0
- package/examples/component-affix.md +190 -0
- package/examples/component-alert-dialog.md +210 -0
- package/examples/component-alert-title.md +77 -0
- package/examples/component-alert.md +192 -0
- package/examples/component-amount-input.md +278 -0
- package/examples/component-anchor.md +198 -0
- package/examples/component-app-bar.md +249 -0
- package/examples/component-aspect-ratio.md +156 -0
- package/examples/component-auto-complete.md +199 -0
- package/examples/component-avatar-group.md +170 -0
- package/examples/component-avatar.md +191 -0
- package/examples/component-back-top.md +123 -0
- package/examples/component-backdrop.md +148 -0
- package/examples/component-badge.md +181 -0
- package/examples/component-banner.md +237 -0
- package/examples/component-biometric-gate.md +281 -0
- package/examples/component-blockquote.md +153 -0
- package/examples/component-border-beam.md +207 -0
- package/examples/component-bottom-navigation.md +226 -0
- package/examples/component-box.md +112 -0
- package/examples/component-breadcrumb.md +222 -0
- package/examples/component-button-base.md +190 -0
- package/examples/component-button-group.md +117 -0
- package/examples/component-button.md +213 -0
- package/examples/component-calendar.md +280 -0
- package/examples/component-callout.md +131 -0
- package/examples/component-card-actions.md +101 -0
- package/examples/component-card-content.md +90 -0
- package/examples/component-card-header.md +122 -0
- package/examples/component-card-media.md +79 -0
- package/examples/component-card.md +233 -0
- package/examples/component-carousel.md +266 -0
- package/examples/component-cascader.md +135 -0
- package/examples/component-category-picker.md +271 -0
- package/examples/component-chart.md +237 -0
- package/examples/component-chat-interface.md +399 -0
- package/examples/component-checkbox.md +149 -0
- package/examples/component-click-away-listener.md +87 -0
- package/examples/component-code.md +213 -0
- package/examples/component-collapsible.md +219 -0
- package/examples/component-color-picker.md +110 -0
- package/examples/component-combobox.md +267 -0
- package/examples/component-command.md +299 -0
- package/examples/component-config-provider.md +190 -0
- package/examples/component-context-menu.md +179 -0
- package/examples/component-css-baseline.md +148 -0
- package/examples/component-date-picker.md +249 -0
- package/examples/component-descriptions.md +242 -0
- package/examples/component-dialog-actions.md +111 -0
- package/examples/component-dialog-content-text.md +76 -0
- package/examples/component-dialog-content.md +105 -0
- package/examples/component-dialog-title.md +104 -0
- package/examples/component-dialog.md +176 -0
- package/examples/component-divider.md +182 -0
- package/examples/component-doc-page.md +217 -0
- package/examples/component-drawer.md +257 -0
- package/examples/component-dropdown.md +220 -0
- package/examples/component-email-layout.md +253 -0
- package/examples/component-empty-state.md +269 -0
- package/examples/component-empty.md +172 -0
- package/examples/component-fade.md +87 -0
- package/examples/component-feature-grid.md +201 -0
- package/examples/component-field.md +266 -0
- package/examples/component-filled-input.md +114 -0
- package/examples/component-flex.md +117 -0
- package/examples/component-float-button.md +214 -0
- package/examples/component-form-control-label.md +134 -0
- package/examples/component-form-control.md +113 -0
- package/examples/component-form-controls.md +251 -0
- package/examples/component-form-group.md +86 -0
- package/examples/component-form-helper-text.md +95 -0
- package/examples/component-form-label.md +98 -0
- package/examples/component-form.md +291 -0
- package/examples/component-game-hud.md +362 -0
- package/examples/component-game-menu.md +327 -0
- package/examples/component-grid.md +140 -0
- package/examples/component-grow.md +79 -0
- package/examples/component-hero-block.md +252 -0
- package/examples/component-hover-card.md +211 -0
- package/examples/component-icon-button.md +142 -0
- package/examples/component-icon.md +102 -0
- package/examples/component-illustration.md +280 -0
- package/examples/component-image-list.md +107 -0
- package/examples/component-image.md +282 -0
- package/examples/component-input-adornment.md +101 -0
- package/examples/component-input-base.md +134 -0
- package/examples/component-input-number.md +141 -0
- package/examples/component-input-otp.md +271 -0
- package/examples/component-input.md +213 -0
- package/examples/component-item.md +243 -0
- package/examples/component-kbd.md +197 -0
- package/examples/component-krw-amount.md +219 -0
- package/examples/component-label.md +118 -0
- package/examples/component-layout.md +217 -0
- package/examples/component-link.md +223 -0
- package/examples/component-list-item-avatar.md +72 -0
- package/examples/component-list-item-button.md +139 -0
- package/examples/component-list-item-icon.md +82 -0
- package/examples/component-list-item-text.md +98 -0
- package/examples/component-list-item.md +116 -0
- package/examples/component-list-subheader.md +70 -0
- package/examples/component-list.md +198 -0
- package/examples/component-loading-button.md +125 -0
- package/examples/component-loading-sequence.md +254 -0
- package/examples/component-lottie-player.md +279 -0
- package/examples/component-masonry.md +191 -0
- package/examples/component-mentions.md +189 -0
- package/examples/component-menu-item.md +102 -0
- package/examples/component-menu-list.md +98 -0
- package/examples/component-menu.md +139 -0
- package/examples/component-menubar.md +259 -0
- package/examples/component-message.md +162 -0
- package/examples/component-mobile-stepper.md +155 -0
- package/examples/component-modal.md +220 -0
- package/examples/component-navigation-menu.md +295 -0
- package/examples/component-notification.md +166 -0
- package/examples/component-otp-countdown.md +245 -0
- package/examples/component-outlined-input.md +145 -0
- package/examples/component-page-transition.md +281 -0
- package/examples/component-pagination.md +226 -0
- package/examples/component-paper.md +199 -0
- package/examples/component-pass-auth.md +265 -0
- package/examples/component-payment-brand-button.md +253 -0
- package/examples/component-payment-method-selector.md +272 -0
- package/examples/component-payment-receipt.md +277 -0
- package/examples/component-popconfirm.md +144 -0
- package/examples/component-popover.md +239 -0
- package/examples/component-popper.md +129 -0
- package/examples/component-pricing-cards.md +247 -0
- package/examples/component-progress.md +195 -0
- package/examples/component-qr-code.md +201 -0
- package/examples/component-radio.md +167 -0
- package/examples/component-rate.md +202 -0
- package/examples/component-resizable.md +163 -0
- package/examples/component-result.md +270 -0
- package/examples/component-scroll-area.md +199 -0
- package/examples/component-scroll-reveal.md +320 -0
- package/examples/component-segmented.md +178 -0
- package/examples/component-select.md +258 -0
- package/examples/component-separator.md +177 -0
- package/examples/component-sheet.md +277 -0
- package/examples/component-sidebar.md +257 -0
- package/examples/component-skeleton.md +178 -0
- package/examples/component-slide.md +89 -0
- package/examples/component-slider.md +208 -0
- package/examples/component-snackbar-content.md +92 -0
- package/examples/component-snackbar.md +121 -0
- package/examples/component-sonner.md +165 -0
- package/examples/component-space.md +125 -0
- package/examples/component-spatial-locomotion.md +373 -0
- package/examples/component-spatial-panel.md +330 -0
- package/examples/component-speed-dial-action.md +78 -0
- package/examples/component-speed-dial.md +177 -0
- package/examples/component-spin.md +173 -0
- package/examples/component-spinner.md +204 -0
- package/examples/component-splitter.md +210 -0
- package/examples/component-stack.md +130 -0
- package/examples/component-statistic.md +282 -0
- package/examples/component-step-button.md +157 -0
- package/examples/component-step-connector.md +157 -0
- package/examples/component-step-content.md +121 -0
- package/examples/component-step-icon.md +115 -0
- package/examples/component-step-label.md +101 -0
- package/examples/component-step.md +84 -0
- package/examples/component-steps.md +264 -0
- package/examples/component-stock-chart.md +251 -0
- package/examples/component-swipeable-drawer.md +149 -0
- package/examples/component-switch.md +99 -0
- package/examples/component-tab-scroll-button.md +180 -0
- package/examples/component-tab.md +120 -0
- package/examples/component-table-body.md +82 -0
- package/examples/component-table-cell.md +118 -0
- package/examples/component-table-container.md +75 -0
- package/examples/component-table-footer.md +72 -0
- package/examples/component-table-head.md +78 -0
- package/examples/component-table-pagination.md +137 -0
- package/examples/component-table-row.md +113 -0
- package/examples/component-table-sort-label.md +109 -0
- package/examples/component-table.md +202 -0
- package/examples/component-tabs.md +184 -0
- package/examples/component-tag-badge.md +309 -0
- package/examples/component-tag.md +102 -0
- package/examples/component-testimonial-carousel.md +218 -0
- package/examples/component-textarea-autosize.md +114 -0
- package/examples/component-textarea.md +173 -0
- package/examples/component-time-picker.md +205 -0
- package/examples/component-timeline.md +170 -0
- package/examples/component-toast.md +224 -0
- package/examples/component-toggle-button.md +129 -0
- package/examples/component-toggle.md +220 -0
- package/examples/component-toolbar.md +104 -0
- package/examples/component-tooltip.md +178 -0
- package/examples/component-tour.md +176 -0
- package/examples/component-transaction-list-item.md +243 -0
- package/examples/component-transfer.md +156 -0
- package/examples/component-tree-select.md +202 -0
- package/examples/component-tree.md +297 -0
- package/examples/component-typography.md +215 -0
- package/examples/component-upload.md +295 -0
- package/examples/component-video-hero.md +409 -0
- package/examples/component-video-player.md +340 -0
- package/examples/component-voice-input.md +408 -0
- package/examples/component-watermark.md +217 -0
- package/examples/component-zoom.md +92 -0
- package/examples/doc-explanation-example.md +196 -0
- package/examples/doc-how-to-example.md +205 -0
- package/examples/doc-tutorial-example.md +162 -0
- package/examples/dogfood-korean-fintech-system.md +433 -0
- package/examples/email-transactional-example.md +259 -0
- package/examples/palette-saas-violet.md +235 -0
- package/examples/print-business-card-spec.md +205 -0
- package/examples/print-packaging-spec.md +285 -0
- package/examples/report-example.md +228 -0
- package/examples/slide-deck-example.md +237 -0
- package/examples/website-improvement-report.md +128 -0
- package/examples/website-improvement-workspace.json +126 -0
- package/install.sh +189 -0
- package/knowledge/COVERAGE.md +740 -0
- package/knowledge/PRINCIPLES.md +108 -0
- package/knowledge/a11y/contrast.md +70 -0
- package/knowledge/a11y/keyboard-and-focus.md +108 -0
- package/knowledge/colors/color-theory.md +90 -0
- package/knowledge/colors/mui-palette-structure.md +105 -0
- package/knowledge/colors/palettes-by-product-type.md +876 -0
- package/knowledge/components/INDEX.md +231 -0
- package/knowledge/components/index.json +1470 -0
- package/knowledge/components/shadcn-registry.md +159 -0
- package/knowledge/conversational/ai-chat-interfaces.md +323 -0
- package/knowledge/conversational/chatbot-design.md +312 -0
- package/knowledge/conversational/conversational-ui-fundamentals.md +299 -0
- package/knowledge/conversational/korean-voice-conventions.md +281 -0
- package/knowledge/conversational/voice-ui-patterns.md +297 -0
- package/knowledge/design-tokens/ant-design.md +124 -0
- package/knowledge/design-tokens/material-3.md +235 -0
- package/knowledge/design-tokens/polaris-and-carbon.md +231 -0
- package/knowledge/design-tokens/tailwind-v4.md +284 -0
- package/knowledge/game-ui/game-accessibility.md +317 -0
- package/knowledge/game-ui/game-ui-fundamentals.md +281 -0
- package/knowledge/game-ui/hud-design.md +324 -0
- package/knowledge/game-ui/korean-gaming-conventions.md +312 -0
- package/knowledge/game-ui/menu-systems.md +388 -0
- package/knowledge/i18n/korean-app-store-visual.md +223 -0
- package/knowledge/i18n/korean-document-style.md +301 -0
- package/knowledge/i18n/korean-payments.md +211 -0
- package/knowledge/i18n/korean-product-conventions.md +96 -0
- package/knowledge/i18n/korean-publishing.md +139 -0
- package/knowledge/i18n/korean-typography.md +123 -0
- package/knowledge/icons/curated-sets.md +225 -0
- package/knowledge/illustration/hero-illustrations.md +234 -0
- package/knowledge/illustration/illustration-systems.md +221 -0
- package/knowledge/illustration/mascot-design.md +208 -0
- package/knowledge/illustration/spot-illustrations.md +246 -0
- package/knowledge/illustration/svg-optimization.md +308 -0
- package/knowledge/layout/spacing-and-grid.md +119 -0
- package/knowledge/motion/app-loading-sequences.md +277 -0
- package/knowledge/motion/choreography-depth.md +297 -0
- package/knowledge/motion/marketing-motion.md +223 -0
- package/knowledge/motion/micro-interactions.md +266 -0
- package/knowledge/motion/motion-tools.md +281 -0
- package/knowledge/motion/principles.md +126 -0
- package/knowledge/patterns/auth-flow-design.md +316 -0
- package/knowledge/patterns/b2b-onboarding-flows.md +182 -0
- package/knowledge/patterns/brand-identity.md +238 -0
- package/knowledge/patterns/brand-references.md +97 -0
- package/knowledge/patterns/chart-color-encoding.md +269 -0
- package/knowledge/patterns/chart-types.md +344 -0
- package/knowledge/patterns/dashboard-composition.md +299 -0
- package/knowledge/patterns/design-system-qa.md +356 -0
- package/knowledge/patterns/document-typography.md +248 -0
- package/knowledge/patterns/email-design.md +338 -0
- package/knowledge/patterns/empty-states.md +263 -0
- package/knowledge/patterns/error-states.md +318 -0
- package/knowledge/patterns/form-design.md +237 -0
- package/knowledge/patterns/information-architecture.md +341 -0
- package/knowledge/patterns/landing-hero-design.md +283 -0
- package/knowledge/patterns/landing-page-patterns.md +681 -0
- package/knowledge/patterns/list-and-feed.md +371 -0
- package/knowledge/patterns/mobile-navigation.md +278 -0
- package/knowledge/patterns/money-and-amount.md +301 -0
- package/knowledge/patterns/onboarding.md +300 -0
- package/knowledge/patterns/pricing-page-design.md +261 -0
- package/knowledge/patterns/realtime-data.md +280 -0
- package/knowledge/patterns/report-design.md +330 -0
- package/knowledge/patterns/search-ux.md +373 -0
- package/knowledge/patterns/settings-page.md +325 -0
- package/knowledge/patterns/slide-deck-design.md +316 -0
- package/knowledge/patterns/styles-catalog.md +2599 -0
- package/knowledge/patterns/technical-writing.md +306 -0
- package/knowledge/patterns/ui-reasoning.md +1853 -0
- package/knowledge/patterns/ux-guidelines.md +1454 -0
- package/knowledge/platforms/react-native.md +395 -0
- package/knowledge/print/brochures-and-flyers.md +276 -0
- package/knowledge/print/korean-print-conventions.md +284 -0
- package/knowledge/print/packaging.md +321 -0
- package/knowledge/print/print-fundamentals.md +238 -0
- package/knowledge/print/signage-and-posters.md +235 -0
- package/knowledge/print/stationery.md +262 -0
- package/knowledge/spatial/ar-patterns.md +253 -0
- package/knowledge/spatial/comfort-and-accessibility.md +245 -0
- package/knowledge/spatial/spatial-design-fundamentals.md +346 -0
- package/knowledge/spatial/spatial-ui-elements.md +343 -0
- package/knowledge/spatial/vr-patterns.md +302 -0
- package/knowledge/typography/font-pairings.md +332 -0
- package/knowledge/typography/mui-type-scale.md +57 -0
- package/knowledge/typography/type-scale-fundamentals.md +105 -0
- package/knowledge/video/in-product-video.md +277 -0
- package/knowledge/video/korean-video-conventions.md +247 -0
- package/knowledge/video/marketing-video.md +258 -0
- package/knowledge/video/social-and-short-form.md +257 -0
- package/knowledge/video/video-fundamentals.md +296 -0
- package/package.json +106 -0
- package/skills/README.md +39 -0
- package/skills/color-palette/PLAYBOOK.md +175 -0
- package/skills/color-palette/SKILL.md +6 -0
- package/skills/color-palette/TEMPLATE.md +103 -0
- package/skills/component-spec-writer/PLAYBOOK.md +169 -0
- package/skills/component-spec-writer/SKILL.md +6 -0
- package/skills/component-spec-writer/TEMPLATE.md +115 -0
- package/skills/conversational-ui-designer/PLAYBOOK.md +231 -0
- package/skills/conversational-ui-designer/SKILL.md +6 -0
- package/skills/design-broadcast/PLAYBOOK.md +146 -0
- package/skills/design-broadcast/SKILL.md +6 -0
- package/skills/design-critique/PLAYBOOK.md +137 -0
- package/skills/design-critique/SKILL.md +6 -0
- package/skills/design-pr-review/PLAYBOOK.md +171 -0
- package/skills/design-pr-review/SKILL.md +6 -0
- package/skills/design-system-builder/PLAYBOOK.md +218 -0
- package/skills/design-system-builder/SKILL.md +6 -0
- package/skills/design-system-qa/PLAYBOOK.md +163 -0
- package/skills/design-system-qa/SKILL.md +6 -0
- package/skills/document-author/PLAYBOOK.md +167 -0
- package/skills/document-author/SKILL.md +6 -0
- package/skills/figma-token-sync/PLAYBOOK.md +149 -0
- package/skills/figma-token-sync/SKILL.md +6 -0
- package/skills/game-ui-designer/PLAYBOOK.md +209 -0
- package/skills/game-ui-designer/SKILL.md +6 -0
- package/skills/handoff-spec/PLAYBOOK.md +170 -0
- package/skills/handoff-spec/SKILL.md +6 -0
- package/skills/illustration-designer/PLAYBOOK.md +166 -0
- package/skills/illustration-designer/SKILL.md +6 -0
- package/skills/motion-designer/PLAYBOOK.md +223 -0
- package/skills/motion-designer/SKILL.md +6 -0
- package/skills/print-designer/PLAYBOOK.md +209 -0
- package/skills/print-designer/SKILL.md +6 -0
- package/skills/slide-deck-author/PLAYBOOK.md +198 -0
- package/skills/slide-deck-author/SKILL.md +6 -0
- package/skills/spatial-designer/PLAYBOOK.md +238 -0
- package/skills/spatial-designer/SKILL.md +6 -0
- package/skills/ux-audit/PLAYBOOK.md +142 -0
- package/skills/ux-audit/SKILL.md +6 -0
- package/skills/video-designer/PLAYBOOK.md +240 -0
- package/skills/video-designer/SKILL.md +6 -0
- package/skills/website-improvement/PLAYBOOK.md +118 -0
- package/skills/website-improvement/SKILL.md +6 -0
- package/skills/website-improvement/TEMPLATE.md +103 -0
- package/tools/audit/changelog-generate.py +176 -0
- package/tools/audit/check-coverage.py +483 -0
- package/tools/audit/doctor_assertions.py +256 -0
- package/tools/audit/example-qa.py +108 -0
- package/tools/audit/frontmatter-check.py +199 -0
- package/tools/audit/integration-check.py +95 -0
- package/tools/audit/korean-copy-check.py +161 -0
- package/tools/audit/link-check.py +146 -0
- package/tools/audit/local-ci.py +558 -0
- package/tools/audit/package-contents.py +723 -0
- package/tools/audit/package-smoke.py +22443 -0
- package/tools/audit/raw-hex-check.py +252 -0
- package/tools/audit/registry-smoke.py +8188 -0
- package/tools/audit/release-metadata.py +9832 -0
- package/tools/audit/run-all.py +351 -0
- package/tools/audit/smoke_assertions.py +12742 -0
- package/tools/audit/stability-review.py +332 -0
- package/tools/audit/stale-check.py +156 -0
- package/tools/migrations/add-version-frontmatter.py +132 -0
- package/tools/migrations/bump-last-updated.py +131 -0
- package/tools/migrations/promote-stability.py +172 -0
- package/tools/preview/README.md +58 -0
- package/tools/preview/render-tokens.py +454 -0
|
@@ -0,0 +1,371 @@
|
|
|
1
|
+
<!-- hand-written -->
|
|
2
|
+
---
|
|
3
|
+
title: List and feed patterns
|
|
4
|
+
applies_to: [web, mobile, all-ui]
|
|
5
|
+
version: 1.0.0
|
|
6
|
+
last_updated: 2026-05
|
|
7
|
+
stability: stable
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# List and feed patterns
|
|
11
|
+
|
|
12
|
+
Lists are everywhere — transaction history, search results, settings, chat threads, product feeds. The pattern looks simple; getting it right is harder than it appears.
|
|
13
|
+
|
|
14
|
+
## When list vs grid vs table
|
|
15
|
+
|
|
16
|
+
| Pattern | Use when |
|
|
17
|
+
| --- | --- |
|
|
18
|
+
| **List** (vertical, single column) | Items have variable text length; primary scan is "what's at the top"; mobile-first |
|
|
19
|
+
| **Grid** (2+ columns) | Items have visual primary (photos); items are equal; product browsing |
|
|
20
|
+
| **Table** (multi-column with headers) | Multi-attribute comparison; data analysis; desktop-first; `<table>` semantics |
|
|
21
|
+
| **Card list** (vertical with cards) | Each item is a self-contained unit (article, project, listing); medium info density |
|
|
22
|
+
|
|
23
|
+
This file covers **lists** and **feeds** (a list with infinite scroll or refresh).
|
|
24
|
+
|
|
25
|
+
## List item anatomy
|
|
26
|
+
|
|
27
|
+
A list item is a small composition:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
┌──────────────────────────────────────────────────────────┐
|
|
31
|
+
│ [icon/avatar] Primary text [meta] [→] │
|
|
32
|
+
│ Secondary text │
|
|
33
|
+
└──────────────────────────────────────────────────────────┘
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
| Slot | Required | Notes |
|
|
37
|
+
| --- | --- | --- |
|
|
38
|
+
| Leading visual | optional | Icon, avatar, color swatch, status dot |
|
|
39
|
+
| Primary text | yes | The thing |
|
|
40
|
+
| Secondary text | optional | Metadata, subtitle |
|
|
41
|
+
| Trailing meta | optional | Timestamp, count, amount, status badge |
|
|
42
|
+
| Trailing affordance | optional | Chevron `>` (drill in), checkbox, switch |
|
|
43
|
+
|
|
44
|
+
### Heights
|
|
45
|
+
|
|
46
|
+
| Density | Single-line | Two-line | Three-line |
|
|
47
|
+
| --- | --- | --- | --- |
|
|
48
|
+
| Compact | 40px | 56px | 72px |
|
|
49
|
+
| Comfortable (default) | 48px | 64px | 80px |
|
|
50
|
+
| Spacious | 56px | 72px | 88px |
|
|
51
|
+
|
|
52
|
+
For Korean consumer apps: lean toward **compact-to-comfortable**. Western apps default spacious.
|
|
53
|
+
|
|
54
|
+
## Common list patterns
|
|
55
|
+
|
|
56
|
+
### Settings list
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
┌──────────────────────────────────────────────────┐
|
|
60
|
+
│ 알림 > │
|
|
61
|
+
│ ─────────────────────────────────────────────── │
|
|
62
|
+
│ 결제 수단 > │
|
|
63
|
+
│ ─────────────────────────────────────────────── │
|
|
64
|
+
│ 보안 ● > │ ← red dot = needs attention
|
|
65
|
+
│ ─────────────────────────────────────────────── │
|
|
66
|
+
│ 버전 v1.4.2 │
|
|
67
|
+
│ ─────────────────────────────────────────────── │
|
|
68
|
+
│ 로그아웃 │ ← destructive, red
|
|
69
|
+
└──────────────────────────────────────────────────┘
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Conventions:
|
|
73
|
+
- Section headers (group settings into 2–4 sections).
|
|
74
|
+
- Chevron `>` for items that drill in.
|
|
75
|
+
- Trailing value for items that show the current setting (`v1.4.2`, `한국어`).
|
|
76
|
+
- Switch on the right for booleans (Wi-Fi, notifications).
|
|
77
|
+
- Destructive actions (logout, delete) at the bottom, in `--color-error`, no chevron.
|
|
78
|
+
|
|
79
|
+
### Conversation / chat list
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
┌──────────────────────────────────────────────────┐
|
|
83
|
+
│ ● 김민지 (3) 어제 오후 11:23 [3] │
|
|
84
|
+
│ "내일 점심 같이 먹을래?" │
|
|
85
|
+
├──────────────────────────────────────────────────┤
|
|
86
|
+
│ 이서준 오전 10:42 │
|
|
87
|
+
│ 이미지를 보냈습니다 │
|
|
88
|
+
├──────────────────────────────────────────────────┤
|
|
89
|
+
│ 가족 단톡방 화 │
|
|
90
|
+
│ 엄마: "오늘 저녁 6시" │
|
|
91
|
+
└──────────────────────────────────────────────────┘
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- Avatar/group icon on left.
|
|
95
|
+
- Primary line: name (+ unread count).
|
|
96
|
+
- Secondary line: latest message preview, single-line truncated.
|
|
97
|
+
- Timestamp far right (relative — "어제 오후 11:23", "방금 전", "화", "10/05").
|
|
98
|
+
- Unread indicator: dot on left or count badge on right.
|
|
99
|
+
- Bold weight for unread items (entire row).
|
|
100
|
+
|
|
101
|
+
### Transaction list (fintech)
|
|
102
|
+
|
|
103
|
+
See [knowledge/patterns/money-and-amount.md](money-and-amount.md). Tabular numerals, right-aligned amounts.
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
┌────────────────────────────────────────────────────┐
|
|
107
|
+
│ 5월 7일 │ ← date header (sticky)
|
|
108
|
+
├────────────────────────────────────────────────────┤
|
|
109
|
+
│ 🍽 스타벅스 강남점 -₩5,500 │
|
|
110
|
+
│ 카페 · 12:34 │
|
|
111
|
+
├────────────────────────────────────────────────────┤
|
|
112
|
+
│ 💼 급여 +₩2,500,000 │
|
|
113
|
+
│ 회사 · 09:00 │
|
|
114
|
+
└────────────────────────────────────────────────────┘
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
- Sticky date headers between sections.
|
|
118
|
+
- Income / expense color via `--color-money-positive` / `--color-money-negative`.
|
|
119
|
+
|
|
120
|
+
### Search results
|
|
121
|
+
|
|
122
|
+
```
|
|
123
|
+
┌──────────────────────────────────────────────────┐
|
|
124
|
+
│ "결과 142건" [필터] │
|
|
125
|
+
├──────────────────────────────────────────────────┤
|
|
126
|
+
│ Result item 1 │
|
|
127
|
+
├──────────────────────────────────────────────────┤
|
|
128
|
+
│ Result item 2 (highlighted match) │
|
|
129
|
+
├──────────────────────────────────────────────────┤
|
|
130
|
+
│ ... │
|
|
131
|
+
└──────────────────────────────────────────────────┘
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
- Result count.
|
|
135
|
+
- Filter / sort affordance.
|
|
136
|
+
- Highlighted matches (bold or `<mark>` background).
|
|
137
|
+
- "더 보기" or pagination at bottom (or infinite scroll).
|
|
138
|
+
|
|
139
|
+
## Pull-to-refresh
|
|
140
|
+
|
|
141
|
+
Mobile-native gesture. Required for any feed that updates from a server.
|
|
142
|
+
|
|
143
|
+
### Behavior
|
|
144
|
+
|
|
145
|
+
1. User pulls down at top of list. List moves with finger.
|
|
146
|
+
2. Past threshold (~64–80px), refresh indicator appears (spinner).
|
|
147
|
+
3. Release: list bounces back, indicator stays for ~1s while fetch happens.
|
|
148
|
+
4. Indicator disappears, new content (if any) is at top.
|
|
149
|
+
|
|
150
|
+
### Implementation cues
|
|
151
|
+
|
|
152
|
+
- iOS: native via `UIRefreshControl`. RN: `RefreshControl` component on FlatList/ScrollView.
|
|
153
|
+
- Android: native via `SwipeRefreshLayout`. Material default.
|
|
154
|
+
- Web: not native; use a library (no clean cross-browser implementation).
|
|
155
|
+
|
|
156
|
+
### Don't
|
|
157
|
+
|
|
158
|
+
- Don't pull-to-refresh on lists where the user controls when data appears (e.g., a static settings list).
|
|
159
|
+
- Don't pull-to-refresh AND have a refresh button in the header — pick one.
|
|
160
|
+
- Don't show "no new items" toast after every refresh — silent if nothing new.
|
|
161
|
+
|
|
162
|
+
## Infinite scroll
|
|
163
|
+
|
|
164
|
+
Auto-loads next page when user scrolls near the bottom.
|
|
165
|
+
|
|
166
|
+
### Implementation
|
|
167
|
+
|
|
168
|
+
1. Reserve a "load more" trigger at the bottom (last 3 items in viewport).
|
|
169
|
+
2. When trigger enters viewport, fetch next page.
|
|
170
|
+
3. Append to list.
|
|
171
|
+
4. If error, show inline error with "다시 시도" button.
|
|
172
|
+
|
|
173
|
+
### Versus explicit "Load more" button
|
|
174
|
+
|
|
175
|
+
| Use infinite scroll | Use Load More button |
|
|
176
|
+
| --- | --- |
|
|
177
|
+
| Feed-style content (social, news, transactions) | Search results, e-commerce results |
|
|
178
|
+
| Mobile primarily | Desktop primarily |
|
|
179
|
+
| Engagement is a goal | User needs to know "where am I?" |
|
|
180
|
+
|
|
181
|
+
Infinite scroll has tradeoffs:
|
|
182
|
+
- Footer becomes unreachable (avoid on sites with critical footer).
|
|
183
|
+
- Browser back doesn't restore scroll position by default.
|
|
184
|
+
- Accessibility: screen reader users get lost. Add `aria-live` updates: "20 more results loaded".
|
|
185
|
+
|
|
186
|
+
### Hybrid: chunked infinite scroll
|
|
187
|
+
|
|
188
|
+
After every 3 pages, pause and show an explicit "Load more" or "View all 142 results". Lets the user catch breath, restores reachability of footer.
|
|
189
|
+
|
|
190
|
+
## Empty state
|
|
191
|
+
|
|
192
|
+
Required for any list that can be empty.
|
|
193
|
+
|
|
194
|
+
```
|
|
195
|
+
┌──────────────────────────────────────────────────┐
|
|
196
|
+
│ │
|
|
197
|
+
│ │
|
|
198
|
+
│ ┌────────┐ │
|
|
199
|
+
│ │ 📭 │ │
|
|
200
|
+
│ └────────┘ │
|
|
201
|
+
│ │
|
|
202
|
+
│ 아직 거래 내역이 없어요 │
|
|
203
|
+
│ 첫 거래를 추가해보세요 │
|
|
204
|
+
│ │
|
|
205
|
+
│ [거래 추가하기] │
|
|
206
|
+
│ │
|
|
207
|
+
└──────────────────────────────────────────────────┘
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
| Element | Notes |
|
|
211
|
+
| --- | --- |
|
|
212
|
+
| Illustration / icon | Friendly, related to content type. Don't use generic "empty box". |
|
|
213
|
+
| Title | What's empty, in user terms ("아직 거래 내역이 없어요"). |
|
|
214
|
+
| Description | Why and what to do next (1 sentence). |
|
|
215
|
+
| Primary CTA | The action that fills the list (if applicable). |
|
|
216
|
+
|
|
217
|
+
### Don't
|
|
218
|
+
|
|
219
|
+
- Don't show "No data" alone. That's hostile.
|
|
220
|
+
- Don't auto-redirect to onboarding.
|
|
221
|
+
- Don't show empty state with a "Refresh" button as the only action — refresh won't change the state; an "add" action will.
|
|
222
|
+
|
|
223
|
+
## Loading states
|
|
224
|
+
|
|
225
|
+
### First load (initial render)
|
|
226
|
+
|
|
227
|
+
Show **skeleton placeholders** matching the shape of the eventual list. Cite [knowledge/patterns/ux-guidelines.md](ux-guidelines.md).
|
|
228
|
+
|
|
229
|
+
```
|
|
230
|
+
┌──────────────────────────────────────────────────┐
|
|
231
|
+
│ ▢▢▢ ▔▔▔▔▔▔▔▔▔ │ ← shimmer animation
|
|
232
|
+
│ ▔▔▔▔▔▔ │
|
|
233
|
+
├──────────────────────────────────────────────────┤
|
|
234
|
+
│ ▢▢▢ ▔▔▔▔▔▔▔▔▔▔ │
|
|
235
|
+
│ ▔▔▔▔▔ │
|
|
236
|
+
└──────────────────────────────────────────────────┘
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
- 3–5 skeleton items.
|
|
240
|
+
- Shimmer animation: 1500ms loop, linear easing.
|
|
241
|
+
- Match the actual layout's heights — no jumping when real data arrives.
|
|
242
|
+
- Stop shimmer immediately when data arrives.
|
|
243
|
+
|
|
244
|
+
### Pagination load (load-more)
|
|
245
|
+
|
|
246
|
+
Inline spinner at the bottom:
|
|
247
|
+
|
|
248
|
+
```
|
|
249
|
+
┌──────────────────────────────────────────────────┐
|
|
250
|
+
│ ... existing items ... │
|
|
251
|
+
├──────────────────────────────────────────────────┤
|
|
252
|
+
│ ⏳ 더 불러오는 중... │
|
|
253
|
+
└──────────────────────────────────────────────────┘
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
### Refresh (already-loaded list)
|
|
257
|
+
|
|
258
|
+
Use the platform's native refresh indicator (RefreshControl). Don't replace existing items with skeletons during refresh.
|
|
259
|
+
|
|
260
|
+
## Error states
|
|
261
|
+
|
|
262
|
+
```
|
|
263
|
+
┌──────────────────────────────────────────────────┐
|
|
264
|
+
│ │
|
|
265
|
+
│ ⚠ 불러오기에 실패했어요 │
|
|
266
|
+
│ 네트워크 연결을 확인하고 │
|
|
267
|
+
│ 다시 시도해주세요. │
|
|
268
|
+
│ │
|
|
269
|
+
│ [다시 시도] │
|
|
270
|
+
│ │
|
|
271
|
+
└──────────────────────────────────────────────────┘
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
- Specific message ("네트워크 연결을 확인" not "오류 발생").
|
|
275
|
+
- Retry action.
|
|
276
|
+
- For pagination errors: inline at the bottom, not full-screen.
|
|
277
|
+
|
|
278
|
+
## Swipe actions (mobile)
|
|
279
|
+
|
|
280
|
+
iOS-native pattern. Swipe left on a list item reveals trailing actions:
|
|
281
|
+
|
|
282
|
+
```
|
|
283
|
+
[item content ] ← drag right-to-left
|
|
284
|
+
→ [Archive] [Delete]
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
| Action position | Use |
|
|
288
|
+
| --- | --- |
|
|
289
|
+
| Trailing (right) — destructive | Delete, Remove, Archive |
|
|
290
|
+
| Trailing (right) — non-destructive | Mark read, Pin, Mute |
|
|
291
|
+
| Leading (left) | Quick positive action (Mark unread, Star) |
|
|
292
|
+
|
|
293
|
+
### Rules
|
|
294
|
+
|
|
295
|
+
- Swipe-to-delete must show a confirmation. Don't delete on first swipe — that's destructive without explicit confirm.
|
|
296
|
+
- Provide visible action button as a fallback (long-press menu, kebab `⋮`). Never gate destructive actions behind ONLY swipe — discoverability fails for new users and accessibility.
|
|
297
|
+
- Swipe affordance hint: on first list view, briefly reveal the action color on the rightmost ~10% of an item, then settle. Once per session.
|
|
298
|
+
|
|
299
|
+
### Implementation
|
|
300
|
+
|
|
301
|
+
- iOS: `UITableView` swipe actions are native.
|
|
302
|
+
- Android: not a native pattern — Material 3 deprecated swipe-to-dismiss. Use long-press → contextual action bar.
|
|
303
|
+
- RN: libraries like `react-native-gesture-handler` Swipeable.
|
|
304
|
+
|
|
305
|
+
## Section headers
|
|
306
|
+
|
|
307
|
+
For grouped lists (chat by date, transactions by date, contacts by initial):
|
|
308
|
+
|
|
309
|
+
```
|
|
310
|
+
─── 어제 ─────────────────────────────────────────
|
|
311
|
+
[item]
|
|
312
|
+
[item]
|
|
313
|
+
|
|
314
|
+
─── 5월 5일 ──────────────────────────────────────
|
|
315
|
+
[item]
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
| Spec | Notes |
|
|
319
|
+
| --- | --- |
|
|
320
|
+
| Sticky | Header stays at top of viewport while scrolling within its section |
|
|
321
|
+
| Style | Smaller text (12–13px), uppercase or bold, color `--color-text-tertiary` |
|
|
322
|
+
| Background | Often subtle bg `--color-bg-subtle` to differentiate from items |
|
|
323
|
+
| Spacing | More space above (16–24px) than between items |
|
|
324
|
+
|
|
325
|
+
## Dividers
|
|
326
|
+
|
|
327
|
+
| Style | Use |
|
|
328
|
+
| --- | --- |
|
|
329
|
+
| Hairline (1px `--color-divider`) | Default between similar items |
|
|
330
|
+
| Inset (skip leading visual) | When items have leading icons/avatars — divider starts after icon column |
|
|
331
|
+
| Heavy (4–8px gap, no line) | Between major sections |
|
|
332
|
+
| None | When items already have card backgrounds (cards in a list) |
|
|
333
|
+
|
|
334
|
+
## Long press
|
|
335
|
+
|
|
336
|
+
Long-press (500ms+) opens a contextual action menu. Common in:
|
|
337
|
+
- Chat (message → react, copy, reply, forward, delete)
|
|
338
|
+
- Photo grid (tap to select, long-press to enter selection mode)
|
|
339
|
+
- Item in a list with multiple actions
|
|
340
|
+
|
|
341
|
+
### Don't
|
|
342
|
+
|
|
343
|
+
- Don't make long-press the only path to a destructive action — too easy to trigger accidentally.
|
|
344
|
+
- Don't use long-press for primary action (it has a 500ms delay; users feel the lag).
|
|
345
|
+
|
|
346
|
+
## Accessibility
|
|
347
|
+
|
|
348
|
+
- Lists are `<ul>`/`<ol>` (web). RN lists are read by screen readers as collections.
|
|
349
|
+
- Items are `<li>` (web). RN: each item should have `accessibilityRole="button"` if interactive.
|
|
350
|
+
- Long lists: announce count and position. "Item 5 of 142."
|
|
351
|
+
- Empty state: announce on render (`aria-live="polite"`).
|
|
352
|
+
- Loading: announce ("Loading"). On data arrive: announce result count.
|
|
353
|
+
- Pull-to-refresh: announce when refresh starts and when complete.
|
|
354
|
+
- Skeleton loaders: don't announce as "loading loading loading" — set `aria-hidden="true"` on skeletons; announce loading state once at container level.
|
|
355
|
+
|
|
356
|
+
## Performance
|
|
357
|
+
|
|
358
|
+
For lists > 50 items on mobile, virtualization is mandatory:
|
|
359
|
+
- RN: `FlatList` (not `ScrollView`).
|
|
360
|
+
- Web: `react-window` or `@tanstack/react-virtual`.
|
|
361
|
+
- Native iOS/Android: `UITableView` / `RecyclerView` are virtualized natively.
|
|
362
|
+
|
|
363
|
+
Don't render 1,000 items in a `ScrollView`. Frame drops, memory issues, scroll lag.
|
|
364
|
+
|
|
365
|
+
## Cross-reference
|
|
366
|
+
|
|
367
|
+
- [knowledge/patterns/money-and-amount.md](money-and-amount.md) — transaction list specifics
|
|
368
|
+
- [knowledge/patterns/mobile-navigation.md](mobile-navigation.md) — search lists
|
|
369
|
+
- [knowledge/patterns/ux-guidelines.md](ux-guidelines.md) — skeleton loading conventions
|
|
370
|
+
- [knowledge/platforms/react-native.md](../platforms/react-native.md) — FlatList performance, RefreshControl
|
|
371
|
+
- [knowledge/a11y/keyboard-and-focus.md](../a11y/keyboard-and-focus.md) — list keyboard navigation
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
<!-- hand-written -->
|
|
2
|
+
---
|
|
3
|
+
title: Mobile navigation patterns
|
|
4
|
+
applies_to: [mobile, ios, android, react-native, responsive-web]
|
|
5
|
+
version: 1.0.0
|
|
6
|
+
last_updated: 2026-05
|
|
7
|
+
stability: stable
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Mobile navigation patterns
|
|
11
|
+
|
|
12
|
+
The four primary mobile navigation patterns, when to use each, and the rules they obey. Skipping these conventions makes the app read as foreign.
|
|
13
|
+
|
|
14
|
+
## The four patterns
|
|
15
|
+
|
|
16
|
+
| Pattern | Use when | Examples |
|
|
17
|
+
| --- | --- | --- |
|
|
18
|
+
| **Bottom tab bar** | 3–5 top-level destinations equally important | Toss, Instagram, KakaoTalk, banking apps |
|
|
19
|
+
| **Top app bar** | Single primary destination per screen with secondary actions | Settings, detail screens, compose |
|
|
20
|
+
| **Drawer (hamburger)** | 5+ destinations, secondary frequency | Gmail, Slack channels |
|
|
21
|
+
| **Stack-only** | Linear flows (onboarding, multi-step forms, checkout) | Wizards |
|
|
22
|
+
|
|
23
|
+
## Bottom tab bar
|
|
24
|
+
|
|
25
|
+
The dominant pattern for Korean consumer apps. **Default for any consumer mobile product with multiple top-level sections.**
|
|
26
|
+
|
|
27
|
+
### Rules
|
|
28
|
+
|
|
29
|
+
| Rule | Detail |
|
|
30
|
+
| --- | --- |
|
|
31
|
+
| Tab count | **3–5**. 6+ becomes a scroll target on iOS or hamburger on Android. |
|
|
32
|
+
| Always present | At every top-level screen. Hidden on detail / modal / form screens. |
|
|
33
|
+
| Persistent across navigation within a tab | Stack pushes inside a tab keep the bar visible. |
|
|
34
|
+
| Active state | Highlighted color + filled icon (vs outlined inactive) + bold label. |
|
|
35
|
+
| Labels | **Always show** — Korean apps include Korean labels. Icon-only is acceptable for Western iOS-native style but reads as foreign in KR. |
|
|
36
|
+
| Height | iOS: 49pt + safe-area-inset-bottom. Android: 56–64dp. RN: ~56–60 + insets. |
|
|
37
|
+
|
|
38
|
+
### Tab anatomy
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
|
42
|
+
│ 🏠 │ │ 📊 │ │ ➕ │ │ 🔔 │ │ 👤 │
|
|
43
|
+
│ 홈 │ │ 통계 │ │ 추가 │ │ 알림 │ │ MY │
|
|
44
|
+
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
|
|
45
|
+
active inactive center inactive inactive
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
| Part | Spec |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| Icon | 24×24 typical. Filled when active, outlined when inactive. |
|
|
51
|
+
| Label | 11–12px font, weight 500 active / 400 inactive. |
|
|
52
|
+
| Spacing | Equal-width tabs, label centered under icon. |
|
|
53
|
+
| Active color | `--color-primary-default` |
|
|
54
|
+
| Inactive color | `--color-text-tertiary` |
|
|
55
|
+
|
|
56
|
+
### Center-tab variants
|
|
57
|
+
|
|
58
|
+
Korean apps frequently elevate the center tab as a primary action:
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
┌─────────┐ ┌─────────┐ ┌─────╮ ╭─────┐ ┌─────────┐ ┌─────────┐
|
|
62
|
+
│ 홈 │ │ 검색 │ │ ╲ ╱ │ │ 알림 │ │ MY │
|
|
63
|
+
│ │ │ │ │ ┌─┐ │ │ │ │ │
|
|
64
|
+
│ │ │ │ │ │+│ │ │ │ │ │
|
|
65
|
+
│ │ │ │ │ └─┘ │ │ │ │ │
|
|
66
|
+
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The center is a **floating action**, raised by 8–12px, with a colored background (often primary). It's a separate button, not a tab — it triggers a modal or compose screen rather than navigating to a destination.
|
|
70
|
+
|
|
71
|
+
Use when there's a clear "create / send / 추가" primary action that would otherwise be buried.
|
|
72
|
+
|
|
73
|
+
### Hiding the tab bar
|
|
74
|
+
|
|
75
|
+
Hide on:
|
|
76
|
+
- Modal screens
|
|
77
|
+
- Forms (so keyboard + footer button can claim space)
|
|
78
|
+
- Full-bleed media viewers
|
|
79
|
+
- Onboarding
|
|
80
|
+
|
|
81
|
+
Don't hide on:
|
|
82
|
+
- Top-level destinations (always show)
|
|
83
|
+
- Stack pushes within a tab (keep visible)
|
|
84
|
+
- Settings (it's still browsing)
|
|
85
|
+
|
|
86
|
+
### Don't
|
|
87
|
+
|
|
88
|
+
- Don't put 6+ tabs. If you have 6, your app has 5 destinations + something that should be in a menu.
|
|
89
|
+
- Don't change tab order across screens.
|
|
90
|
+
- Don't have a "More" tab as the 5th — find the meaningful 4 or 5 and commit.
|
|
91
|
+
- Don't use the tab bar as a loading indicator (animating active state).
|
|
92
|
+
- Don't gate tabs behind login state. Show all tabs; auth-walled tabs go to login screen on tap.
|
|
93
|
+
|
|
94
|
+
## Top app bar
|
|
95
|
+
|
|
96
|
+
The header strip with title and actions on most non-tab screens.
|
|
97
|
+
|
|
98
|
+
### Anatomy
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
┌──────────────────────────────────────────────────┐
|
|
102
|
+
│ ← Screen title ⋮ ✕ Close │
|
|
103
|
+
└──────────────────────────────────────────────────┘
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
| Slot | Use |
|
|
107
|
+
| --- | --- |
|
|
108
|
+
| Left | Back button (chevron + optional label) OR Close (✕) on modal screens OR menu button (≡) on top-level |
|
|
109
|
+
| Center | Screen title (truncate if long, no wrap) |
|
|
110
|
+
| Right | Up to 2 action buttons (search, share, more menu) |
|
|
111
|
+
|
|
112
|
+
### Rules
|
|
113
|
+
|
|
114
|
+
- Height: 44pt (iOS) / 56dp (Android). RN: ~56 + status bar inset.
|
|
115
|
+
- One title per bar. No subtitle unless absolutely needed; if it's needed, the design likely needs a hero block, not a stuffed bar.
|
|
116
|
+
- Right-side actions: max 2 visible. 3+ goes into a `⋮` (kebab) menu.
|
|
117
|
+
- Title alignment: centered (iOS / KR consumer convention) or left (Android Material 3).
|
|
118
|
+
|
|
119
|
+
### Variants
|
|
120
|
+
|
|
121
|
+
| Variant | Use |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| Standard | Most screens |
|
|
124
|
+
| Large title (iOS native) | Top of stack, sets tone for content. Collapses to standard on scroll. |
|
|
125
|
+
| Search-as-bar | Replace the title with a search input (e.g., "🔍 search...") |
|
|
126
|
+
| Tabs-in-bar | Bottom of bar has segmented control or scrollable tabs |
|
|
127
|
+
|
|
128
|
+
### Don't
|
|
129
|
+
|
|
130
|
+
- Don't put the back button on the right.
|
|
131
|
+
- Don't omit the back button on inner screens. Even if the system back gesture works, users want a tappable affordance.
|
|
132
|
+
- Don't use the title as a navigation menu (Android pre-Material 3 convention is dead — don't revive).
|
|
133
|
+
- Don't put primary CTAs in the header. Headers are for navigation and meta-actions; primary CTAs go in the body or footer.
|
|
134
|
+
|
|
135
|
+
## Drawer (hamburger menu)
|
|
136
|
+
|
|
137
|
+
Side-panel that slides in. Use sparingly.
|
|
138
|
+
|
|
139
|
+
### When to use
|
|
140
|
+
|
|
141
|
+
- 5+ top-level destinations and they're not all equally accessed.
|
|
142
|
+
- Account / settings / less-frequent destinations live here.
|
|
143
|
+
- Apps with many "spaces" or "channels" (e.g., team chat with many rooms).
|
|
144
|
+
|
|
145
|
+
### When NOT to use
|
|
146
|
+
|
|
147
|
+
- Default consumer mobile app with 3–5 destinations: use bottom tab bar instead.
|
|
148
|
+
- Korean consumer apps: drawer is uncommon. Korean users prefer visible tabs.
|
|
149
|
+
- E-commerce: drawer reduces discoverability of categories.
|
|
150
|
+
|
|
151
|
+
### Anatomy
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
←───────────── drawer (75–85% screen width)
|
|
155
|
+
│ ┌─────────┐
|
|
156
|
+
│ │ Avatar │
|
|
157
|
+
│ │ Name │
|
|
158
|
+
│ │ Email │
|
|
159
|
+
│ └─────────┘
|
|
160
|
+
│
|
|
161
|
+
│ 🏠 Home
|
|
162
|
+
│ 📊 Statistics
|
|
163
|
+
│ ⚙ Settings
|
|
164
|
+
│ 🚪 Logout
|
|
165
|
+
│
|
|
166
|
+
└──────────────
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
- Width: 75–85% of screen. Don't go full-width (must show backdrop).
|
|
170
|
+
- Backdrop: 50% black. Tappable to close.
|
|
171
|
+
- Slide-in: 250ms ease-out from left (LTR) or right (RTL).
|
|
172
|
+
- Header section: user identity (avatar, name, email) — most common pattern.
|
|
173
|
+
|
|
174
|
+
### Don't
|
|
175
|
+
|
|
176
|
+
- Don't combine drawer + bottom tabs. Pick one as primary.
|
|
177
|
+
- Don't put main app navigation in a drawer if the user uses it more than 3x per session — they'll resent the extra tap. Move to a tab.
|
|
178
|
+
|
|
179
|
+
## Stack-only navigation
|
|
180
|
+
|
|
181
|
+
For linear flows: onboarding (4–5 screens), multi-step forms, checkout, signup.
|
|
182
|
+
|
|
183
|
+
- No tab bar visible.
|
|
184
|
+
- Top app bar shows progress (1/4, 2/4, ...) or step name.
|
|
185
|
+
- Back button always available (don't trap user without an exit).
|
|
186
|
+
- Final screen has a clear "complete" affordance — not just disappearing.
|
|
187
|
+
- Skipping: provide an "Skip" affordance for non-critical onboarding screens, but never for required setup.
|
|
188
|
+
|
|
189
|
+
## Back navigation
|
|
190
|
+
|
|
191
|
+
Mobile back has multiple sources:
|
|
192
|
+
|
|
193
|
+
| Source | Behavior |
|
|
194
|
+
| --- | --- |
|
|
195
|
+
| Header back button (`←`) | Standard pop-stack |
|
|
196
|
+
| iOS swipe-from-edge gesture | System-native; respect it |
|
|
197
|
+
| Android system back button | OS-level; must respect |
|
|
198
|
+
| Android system back gesture | Newer Android; respect |
|
|
199
|
+
| In-page link / button | Application-defined |
|
|
200
|
+
|
|
201
|
+
**Always** make these all work consistently. The system back must:
|
|
202
|
+
- Pop one stack level at a time.
|
|
203
|
+
- Close modals if open.
|
|
204
|
+
- Close the keyboard before popping if the keyboard is visible (some prefer popping immediately).
|
|
205
|
+
- Show a confirmation if there's unsaved work (`이 화면을 나가시겠습니까? 작성 중인 내용이 사라집니다.`).
|
|
206
|
+
|
|
207
|
+
Don't:
|
|
208
|
+
- Don't intercept Android back to do nothing.
|
|
209
|
+
- Don't remap back to "go to home" — it's pop-stack semantically everywhere else.
|
|
210
|
+
- Don't show a custom back button without also handling system back.
|
|
211
|
+
|
|
212
|
+
## Search behavior
|
|
213
|
+
|
|
214
|
+
Korean consumer apps **search heavily**. Make search prominent.
|
|
215
|
+
|
|
216
|
+
### Patterns
|
|
217
|
+
|
|
218
|
+
| Pattern | Use |
|
|
219
|
+
| --- | --- |
|
|
220
|
+
| Persistent search at top of screen | Apps where search is the primary action (Naver, e-commerce) |
|
|
221
|
+
| Search icon in app bar → opens overlay | Apps where search is secondary (gmail, banking) |
|
|
222
|
+
| Tab dedicated to search | Multi-purpose apps (Instagram, KakaoTalk has chat search but not a tab) |
|
|
223
|
+
|
|
224
|
+
### Search overlay (icon-tap-to-open variant)
|
|
225
|
+
|
|
226
|
+
```
|
|
227
|
+
┌─────────────────────────────────────────────────┐
|
|
228
|
+
│ ← 🔍 [ type to search ] │
|
|
229
|
+
├─────────────────────────────────────────────────┤
|
|
230
|
+
│ 최근 검색어 │
|
|
231
|
+
│ • previous query 1 ✕ │
|
|
232
|
+
│ • previous query 2 ✕ │
|
|
233
|
+
│ ───── │
|
|
234
|
+
│ 추천 검색어 │
|
|
235
|
+
│ • trending 1 │
|
|
236
|
+
│ • trending 2 │
|
|
237
|
+
└─────────────────────────────────────────────────┘
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Must include:
|
|
241
|
+
- Recent searches (with clear-each + clear-all)
|
|
242
|
+
- Recommended / trending (if applicable)
|
|
243
|
+
- Clear input button (✕) when input has value
|
|
244
|
+
- Cancel / back to close
|
|
245
|
+
|
|
246
|
+
Search type-ahead: debounce 200–300ms, cancel previous request on new keystroke.
|
|
247
|
+
|
|
248
|
+
## Modal screens
|
|
249
|
+
|
|
250
|
+
Different from inline modal/dialog. A "modal screen" takes over the full screen, often presented from below (iOS sheet style):
|
|
251
|
+
|
|
252
|
+
- Used for: compose, settings detail, photo viewer, camera.
|
|
253
|
+
- Presentation: slide up from bottom (iOS) or fade (Android typically).
|
|
254
|
+
- Dismissal: explicit Close (✕) or Cancel button. iOS swipe-down gesture on sheet handle. Don't rely on backdrop tap (no backdrop visible above status bar).
|
|
255
|
+
- Header pattern: ✕ on left, "Save" / primary action on right.
|
|
256
|
+
|
|
257
|
+
### Sheet variants (iOS 15+ and pull-up sheets in apps)
|
|
258
|
+
|
|
259
|
+
```
|
|
260
|
+
╱─╲ (drag handle)
|
|
261
|
+
┌───────────────────────────────────────────┐
|
|
262
|
+
│ ✕ Title Save │
|
|
263
|
+
│ │
|
|
264
|
+
│ body content │
|
|
265
|
+
│ │
|
|
266
|
+
└───────────────────────────────────────────┘
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
- Pull-handle indicator at top.
|
|
270
|
+
- Detents: 25%, 50%, 90% sizes (user can drag to resize).
|
|
271
|
+
- Use for: filter panels, location pickers, brief forms.
|
|
272
|
+
|
|
273
|
+
## Cross-reference
|
|
274
|
+
|
|
275
|
+
- [knowledge/i18n/korean-product-conventions.md](../i18n/korean-product-conventions.md) — KR navigation conventions
|
|
276
|
+
- [knowledge/platforms/react-native.md](../platforms/react-native.md) — RN-specific implementation
|
|
277
|
+
- [knowledge/a11y/keyboard-and-focus.md](../a11y/keyboard-and-focus.md) — focus on route change
|
|
278
|
+
- [knowledge/motion/principles.md](../motion/principles.md) — drawer/sheet timing
|