@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.
Files changed (529) hide show
  1. package/.claude-plugin/plugin.json +164 -0
  2. package/AGENTS.ko.md +126 -0
  3. package/AGENTS.md +182 -0
  4. package/CHANGELOG.md +6883 -0
  5. package/CLAUDE.md +39 -0
  6. package/LICENSE +21 -0
  7. package/README.ko.md +245 -0
  8. package/README.md +277 -0
  9. package/agents/README.md +14 -0
  10. package/agents/a11y-reviewer.md +121 -0
  11. package/agents/component-architect.md +57 -0
  12. package/agents/design-critic.md +46 -0
  13. package/agents/token-extractor.md +63 -0
  14. package/cli/bin/design-ai-mcp.mjs +6 -0
  15. package/cli/bin/design-ai.mjs +40 -0
  16. package/cli/commands/audit.mjs +111 -0
  17. package/cli/commands/check.mjs +226 -0
  18. package/cli/commands/doctor.mjs +141 -0
  19. package/cli/commands/examples.mjs +58 -0
  20. package/cli/commands/help.mjs +271 -0
  21. package/cli/commands/install.mjs +161 -0
  22. package/cli/commands/learn.mjs +1871 -0
  23. package/cli/commands/list.mjs +143 -0
  24. package/cli/commands/mcp.mjs +27 -0
  25. package/cli/commands/pack.mjs +211 -0
  26. package/cli/commands/prompt.mjs +199 -0
  27. package/cli/commands/route.mjs +247 -0
  28. package/cli/commands/search.mjs +60 -0
  29. package/cli/commands/show.mjs +52 -0
  30. package/cli/commands/site.mjs +558 -0
  31. package/cli/commands/status.mjs +161 -0
  32. package/cli/commands/uninstall.mjs +119 -0
  33. package/cli/commands/update.mjs +184 -0
  34. package/cli/commands/version.mjs +94 -0
  35. package/cli/commands/workspace.mjs +176 -0
  36. package/cli/lib/brief.mjs +52 -0
  37. package/cli/lib/check.mjs +642 -0
  38. package/cli/lib/dispatch.mjs +109 -0
  39. package/cli/lib/doctor.mjs +505 -0
  40. package/cli/lib/examples.mjs +258 -0
  41. package/cli/lib/exec.mjs +63 -0
  42. package/cli/lib/help-flags.mjs +5 -0
  43. package/cli/lib/learn.mjs +3694 -0
  44. package/cli/lib/log.mjs +47 -0
  45. package/cli/lib/mcp-server.mjs +426 -0
  46. package/cli/lib/output.mjs +101 -0
  47. package/cli/lib/pack.mjs +599 -0
  48. package/cli/lib/paths.mjs +63 -0
  49. package/cli/lib/prompt.mjs +603 -0
  50. package/cli/lib/route.mjs +740 -0
  51. package/cli/lib/search.mjs +158 -0
  52. package/cli/lib/show.mjs +161 -0
  53. package/cli/lib/signals.mjs +2337 -0
  54. package/cli/lib/site.mjs +6617 -0
  55. package/cli/lib/skill-proposals.mjs +2046 -0
  56. package/cli/lib/suggest.mjs +66 -0
  57. package/cli/lib/workspace.mjs +1056 -0
  58. package/commands/README.md +25 -0
  59. package/commands/component-spec.md +34 -0
  60. package/commands/conversational.md +44 -0
  61. package/commands/design-from-brief.md +141 -0
  62. package/commands/design-review.md +62 -0
  63. package/commands/document-from-brief.md +47 -0
  64. package/commands/extract-tokens.md +38 -0
  65. package/commands/game-ui.md +40 -0
  66. package/commands/illustration.md +37 -0
  67. package/commands/iterate.md +167 -0
  68. package/commands/motion-design.md +54 -0
  69. package/commands/palette-from-brand.md +50 -0
  70. package/commands/print.md +49 -0
  71. package/commands/slide-deck.md +46 -0
  72. package/commands/spatial.md +47 -0
  73. package/commands/stability-review.md +74 -0
  74. package/commands/video.md +42 -0
  75. package/commands/website-improvement.md +77 -0
  76. package/docs/AGENT-DEVELOPMENT.md +658 -0
  77. package/docs/AI-LEARNING.md +429 -0
  78. package/docs/AIDER-INTEGRATION.md +224 -0
  79. package/docs/ARCHITECTURE.ko.md +183 -0
  80. package/docs/ARCHITECTURE.md +105 -0
  81. package/docs/CODEX-INTEGRATION.md +311 -0
  82. package/docs/COMPANY-WEBSITE-DOGFOOD.ko.md +144 -0
  83. package/docs/COMPANY-WEBSITE-DOGFOOD.md +150 -0
  84. package/docs/COMPANY-WEBSITE-INTAKE-TEMPLATE.ko.md +153 -0
  85. package/docs/COMPANY-WEBSITE-INTAKE-TEMPLATE.md +154 -0
  86. package/docs/CONTRIBUTING.ko.md +203 -0
  87. package/docs/CONTRIBUTING.md +242 -0
  88. package/docs/CURSOR-INTEGRATION.md +220 -0
  89. package/docs/DISTRIBUTION.ko.md +248 -0
  90. package/docs/DISTRIBUTION.md +253 -0
  91. package/docs/DOGFOOD-FINDINGS.md +180 -0
  92. package/docs/DOGFOOD-V4-FINDINGS.md +139 -0
  93. package/docs/DOGFOOD-V4-MKDOCS-FINDINGS.md +233 -0
  94. package/docs/DOGFOOD-V4-NPM-FINDINGS.md +157 -0
  95. package/docs/DOGFOOD-V4-VSCODE-FINDINGS.md +135 -0
  96. package/docs/FIGMA-INTEGRATION.md +222 -0
  97. package/docs/MCP-INTEGRATION.md +243 -0
  98. package/docs/MIGRATION-v4.md +121 -0
  99. package/docs/PLUGIN-PACKAGING.md +240 -0
  100. package/docs/PRODUCT-READINESS.md +66 -0
  101. package/docs/QUICKSTART.ko.md +178 -0
  102. package/docs/QUICKSTART.md +179 -0
  103. package/docs/RELEASE-CHECKLIST.md +292 -0
  104. package/docs/ROADMAP.md +19495 -0
  105. package/docs/SESSION-LOG.md +940 -0
  106. package/docs/TOKEN-SYNC.md +237 -0
  107. package/docs/USING.ko.md +206 -0
  108. package/docs/USING.md +218 -0
  109. package/docs/WEBSITE-IMPROVEMENT.ko.md +75 -0
  110. package/docs/WEBSITE-IMPROVEMENT.md +89 -0
  111. package/docs/announcements/README.md +56 -0
  112. package/docs/announcements/dev-to-korea.md +206 -0
  113. package/docs/announcements/hashnode-post.ko.md +232 -0
  114. package/docs/announcements/okky-post.ko.md +158 -0
  115. package/docs/announcements/press-kit.md +101 -0
  116. package/docs/announcements/reddit-r-korea.md +196 -0
  117. package/docs/announcements/show-hn.md +114 -0
  118. package/docs/announcements/twitter-thread.md +255 -0
  119. package/docs/external-status.md +34 -0
  120. package/docs/integrations/aider-walkthrough.ko.md +275 -0
  121. package/docs/integrations/aider-walkthrough.md +274 -0
  122. package/docs/integrations/codex-walkthrough.ko.md +297 -0
  123. package/docs/integrations/codex-walkthrough.md +297 -0
  124. package/docs/integrations/cursor-walkthrough.ko.md +281 -0
  125. package/docs/integrations/cursor-walkthrough.md +284 -0
  126. package/docs/integrations/design-ai-mcp-server.md +169 -0
  127. package/docs/integrations/figma-mcp.md +149 -0
  128. package/docs/integrations/github-mcp.md +178 -0
  129. package/docs/integrations/linear-mcp.md +215 -0
  130. package/docs/integrations/notion-mcp.md +174 -0
  131. package/docs/integrations/sdk-walkthrough.ko.md +375 -0
  132. package/docs/integrations/sdk-walkthrough.md +375 -0
  133. package/docs/integrations/slack-mcp.md +208 -0
  134. package/docs/integrations/vscode-walkthrough.ko.md +202 -0
  135. package/docs/integrations/vscode-walkthrough.md +205 -0
  136. package/docs/requirements.txt +16 -0
  137. package/docs/site-overrides/extra.css +83 -0
  138. package/docs/site-overrides/favicon.svg +4 -0
  139. package/docs/site-overrides/logo.svg +10 -0
  140. package/docs/site-overrides/main.html +18 -0
  141. package/docs/website-console/app.js +2540 -0
  142. package/docs/website-console/index.html +24 -0
  143. package/docs/website-console/styles.css +975 -0
  144. package/examples/README.md +252 -0
  145. package/examples/cases/dogfood-v4-korean-hr-onboarding.md +356 -0
  146. package/examples/component-accordion-actions.md +153 -0
  147. package/examples/component-accordion-details.md +147 -0
  148. package/examples/component-accordion-summary.md +180 -0
  149. package/examples/component-accordion.md +229 -0
  150. package/examples/component-account-card.md +284 -0
  151. package/examples/component-address-input.md +260 -0
  152. package/examples/component-affix.md +190 -0
  153. package/examples/component-alert-dialog.md +210 -0
  154. package/examples/component-alert-title.md +77 -0
  155. package/examples/component-alert.md +192 -0
  156. package/examples/component-amount-input.md +278 -0
  157. package/examples/component-anchor.md +198 -0
  158. package/examples/component-app-bar.md +249 -0
  159. package/examples/component-aspect-ratio.md +156 -0
  160. package/examples/component-auto-complete.md +199 -0
  161. package/examples/component-avatar-group.md +170 -0
  162. package/examples/component-avatar.md +191 -0
  163. package/examples/component-back-top.md +123 -0
  164. package/examples/component-backdrop.md +148 -0
  165. package/examples/component-badge.md +181 -0
  166. package/examples/component-banner.md +237 -0
  167. package/examples/component-biometric-gate.md +281 -0
  168. package/examples/component-blockquote.md +153 -0
  169. package/examples/component-border-beam.md +207 -0
  170. package/examples/component-bottom-navigation.md +226 -0
  171. package/examples/component-box.md +112 -0
  172. package/examples/component-breadcrumb.md +222 -0
  173. package/examples/component-button-base.md +190 -0
  174. package/examples/component-button-group.md +117 -0
  175. package/examples/component-button.md +213 -0
  176. package/examples/component-calendar.md +280 -0
  177. package/examples/component-callout.md +131 -0
  178. package/examples/component-card-actions.md +101 -0
  179. package/examples/component-card-content.md +90 -0
  180. package/examples/component-card-header.md +122 -0
  181. package/examples/component-card-media.md +79 -0
  182. package/examples/component-card.md +233 -0
  183. package/examples/component-carousel.md +266 -0
  184. package/examples/component-cascader.md +135 -0
  185. package/examples/component-category-picker.md +271 -0
  186. package/examples/component-chart.md +237 -0
  187. package/examples/component-chat-interface.md +399 -0
  188. package/examples/component-checkbox.md +149 -0
  189. package/examples/component-click-away-listener.md +87 -0
  190. package/examples/component-code.md +213 -0
  191. package/examples/component-collapsible.md +219 -0
  192. package/examples/component-color-picker.md +110 -0
  193. package/examples/component-combobox.md +267 -0
  194. package/examples/component-command.md +299 -0
  195. package/examples/component-config-provider.md +190 -0
  196. package/examples/component-context-menu.md +179 -0
  197. package/examples/component-css-baseline.md +148 -0
  198. package/examples/component-date-picker.md +249 -0
  199. package/examples/component-descriptions.md +242 -0
  200. package/examples/component-dialog-actions.md +111 -0
  201. package/examples/component-dialog-content-text.md +76 -0
  202. package/examples/component-dialog-content.md +105 -0
  203. package/examples/component-dialog-title.md +104 -0
  204. package/examples/component-dialog.md +176 -0
  205. package/examples/component-divider.md +182 -0
  206. package/examples/component-doc-page.md +217 -0
  207. package/examples/component-drawer.md +257 -0
  208. package/examples/component-dropdown.md +220 -0
  209. package/examples/component-email-layout.md +253 -0
  210. package/examples/component-empty-state.md +269 -0
  211. package/examples/component-empty.md +172 -0
  212. package/examples/component-fade.md +87 -0
  213. package/examples/component-feature-grid.md +201 -0
  214. package/examples/component-field.md +266 -0
  215. package/examples/component-filled-input.md +114 -0
  216. package/examples/component-flex.md +117 -0
  217. package/examples/component-float-button.md +214 -0
  218. package/examples/component-form-control-label.md +134 -0
  219. package/examples/component-form-control.md +113 -0
  220. package/examples/component-form-controls.md +251 -0
  221. package/examples/component-form-group.md +86 -0
  222. package/examples/component-form-helper-text.md +95 -0
  223. package/examples/component-form-label.md +98 -0
  224. package/examples/component-form.md +291 -0
  225. package/examples/component-game-hud.md +362 -0
  226. package/examples/component-game-menu.md +327 -0
  227. package/examples/component-grid.md +140 -0
  228. package/examples/component-grow.md +79 -0
  229. package/examples/component-hero-block.md +252 -0
  230. package/examples/component-hover-card.md +211 -0
  231. package/examples/component-icon-button.md +142 -0
  232. package/examples/component-icon.md +102 -0
  233. package/examples/component-illustration.md +280 -0
  234. package/examples/component-image-list.md +107 -0
  235. package/examples/component-image.md +282 -0
  236. package/examples/component-input-adornment.md +101 -0
  237. package/examples/component-input-base.md +134 -0
  238. package/examples/component-input-number.md +141 -0
  239. package/examples/component-input-otp.md +271 -0
  240. package/examples/component-input.md +213 -0
  241. package/examples/component-item.md +243 -0
  242. package/examples/component-kbd.md +197 -0
  243. package/examples/component-krw-amount.md +219 -0
  244. package/examples/component-label.md +118 -0
  245. package/examples/component-layout.md +217 -0
  246. package/examples/component-link.md +223 -0
  247. package/examples/component-list-item-avatar.md +72 -0
  248. package/examples/component-list-item-button.md +139 -0
  249. package/examples/component-list-item-icon.md +82 -0
  250. package/examples/component-list-item-text.md +98 -0
  251. package/examples/component-list-item.md +116 -0
  252. package/examples/component-list-subheader.md +70 -0
  253. package/examples/component-list.md +198 -0
  254. package/examples/component-loading-button.md +125 -0
  255. package/examples/component-loading-sequence.md +254 -0
  256. package/examples/component-lottie-player.md +279 -0
  257. package/examples/component-masonry.md +191 -0
  258. package/examples/component-mentions.md +189 -0
  259. package/examples/component-menu-item.md +102 -0
  260. package/examples/component-menu-list.md +98 -0
  261. package/examples/component-menu.md +139 -0
  262. package/examples/component-menubar.md +259 -0
  263. package/examples/component-message.md +162 -0
  264. package/examples/component-mobile-stepper.md +155 -0
  265. package/examples/component-modal.md +220 -0
  266. package/examples/component-navigation-menu.md +295 -0
  267. package/examples/component-notification.md +166 -0
  268. package/examples/component-otp-countdown.md +245 -0
  269. package/examples/component-outlined-input.md +145 -0
  270. package/examples/component-page-transition.md +281 -0
  271. package/examples/component-pagination.md +226 -0
  272. package/examples/component-paper.md +199 -0
  273. package/examples/component-pass-auth.md +265 -0
  274. package/examples/component-payment-brand-button.md +253 -0
  275. package/examples/component-payment-method-selector.md +272 -0
  276. package/examples/component-payment-receipt.md +277 -0
  277. package/examples/component-popconfirm.md +144 -0
  278. package/examples/component-popover.md +239 -0
  279. package/examples/component-popper.md +129 -0
  280. package/examples/component-pricing-cards.md +247 -0
  281. package/examples/component-progress.md +195 -0
  282. package/examples/component-qr-code.md +201 -0
  283. package/examples/component-radio.md +167 -0
  284. package/examples/component-rate.md +202 -0
  285. package/examples/component-resizable.md +163 -0
  286. package/examples/component-result.md +270 -0
  287. package/examples/component-scroll-area.md +199 -0
  288. package/examples/component-scroll-reveal.md +320 -0
  289. package/examples/component-segmented.md +178 -0
  290. package/examples/component-select.md +258 -0
  291. package/examples/component-separator.md +177 -0
  292. package/examples/component-sheet.md +277 -0
  293. package/examples/component-sidebar.md +257 -0
  294. package/examples/component-skeleton.md +178 -0
  295. package/examples/component-slide.md +89 -0
  296. package/examples/component-slider.md +208 -0
  297. package/examples/component-snackbar-content.md +92 -0
  298. package/examples/component-snackbar.md +121 -0
  299. package/examples/component-sonner.md +165 -0
  300. package/examples/component-space.md +125 -0
  301. package/examples/component-spatial-locomotion.md +373 -0
  302. package/examples/component-spatial-panel.md +330 -0
  303. package/examples/component-speed-dial-action.md +78 -0
  304. package/examples/component-speed-dial.md +177 -0
  305. package/examples/component-spin.md +173 -0
  306. package/examples/component-spinner.md +204 -0
  307. package/examples/component-splitter.md +210 -0
  308. package/examples/component-stack.md +130 -0
  309. package/examples/component-statistic.md +282 -0
  310. package/examples/component-step-button.md +157 -0
  311. package/examples/component-step-connector.md +157 -0
  312. package/examples/component-step-content.md +121 -0
  313. package/examples/component-step-icon.md +115 -0
  314. package/examples/component-step-label.md +101 -0
  315. package/examples/component-step.md +84 -0
  316. package/examples/component-steps.md +264 -0
  317. package/examples/component-stock-chart.md +251 -0
  318. package/examples/component-swipeable-drawer.md +149 -0
  319. package/examples/component-switch.md +99 -0
  320. package/examples/component-tab-scroll-button.md +180 -0
  321. package/examples/component-tab.md +120 -0
  322. package/examples/component-table-body.md +82 -0
  323. package/examples/component-table-cell.md +118 -0
  324. package/examples/component-table-container.md +75 -0
  325. package/examples/component-table-footer.md +72 -0
  326. package/examples/component-table-head.md +78 -0
  327. package/examples/component-table-pagination.md +137 -0
  328. package/examples/component-table-row.md +113 -0
  329. package/examples/component-table-sort-label.md +109 -0
  330. package/examples/component-table.md +202 -0
  331. package/examples/component-tabs.md +184 -0
  332. package/examples/component-tag-badge.md +309 -0
  333. package/examples/component-tag.md +102 -0
  334. package/examples/component-testimonial-carousel.md +218 -0
  335. package/examples/component-textarea-autosize.md +114 -0
  336. package/examples/component-textarea.md +173 -0
  337. package/examples/component-time-picker.md +205 -0
  338. package/examples/component-timeline.md +170 -0
  339. package/examples/component-toast.md +224 -0
  340. package/examples/component-toggle-button.md +129 -0
  341. package/examples/component-toggle.md +220 -0
  342. package/examples/component-toolbar.md +104 -0
  343. package/examples/component-tooltip.md +178 -0
  344. package/examples/component-tour.md +176 -0
  345. package/examples/component-transaction-list-item.md +243 -0
  346. package/examples/component-transfer.md +156 -0
  347. package/examples/component-tree-select.md +202 -0
  348. package/examples/component-tree.md +297 -0
  349. package/examples/component-typography.md +215 -0
  350. package/examples/component-upload.md +295 -0
  351. package/examples/component-video-hero.md +409 -0
  352. package/examples/component-video-player.md +340 -0
  353. package/examples/component-voice-input.md +408 -0
  354. package/examples/component-watermark.md +217 -0
  355. package/examples/component-zoom.md +92 -0
  356. package/examples/doc-explanation-example.md +196 -0
  357. package/examples/doc-how-to-example.md +205 -0
  358. package/examples/doc-tutorial-example.md +162 -0
  359. package/examples/dogfood-korean-fintech-system.md +433 -0
  360. package/examples/email-transactional-example.md +259 -0
  361. package/examples/palette-saas-violet.md +235 -0
  362. package/examples/print-business-card-spec.md +205 -0
  363. package/examples/print-packaging-spec.md +285 -0
  364. package/examples/report-example.md +228 -0
  365. package/examples/slide-deck-example.md +237 -0
  366. package/examples/website-improvement-report.md +128 -0
  367. package/examples/website-improvement-workspace.json +126 -0
  368. package/install.sh +189 -0
  369. package/knowledge/COVERAGE.md +740 -0
  370. package/knowledge/PRINCIPLES.md +108 -0
  371. package/knowledge/a11y/contrast.md +70 -0
  372. package/knowledge/a11y/keyboard-and-focus.md +108 -0
  373. package/knowledge/colors/color-theory.md +90 -0
  374. package/knowledge/colors/mui-palette-structure.md +105 -0
  375. package/knowledge/colors/palettes-by-product-type.md +876 -0
  376. package/knowledge/components/INDEX.md +231 -0
  377. package/knowledge/components/index.json +1470 -0
  378. package/knowledge/components/shadcn-registry.md +159 -0
  379. package/knowledge/conversational/ai-chat-interfaces.md +323 -0
  380. package/knowledge/conversational/chatbot-design.md +312 -0
  381. package/knowledge/conversational/conversational-ui-fundamentals.md +299 -0
  382. package/knowledge/conversational/korean-voice-conventions.md +281 -0
  383. package/knowledge/conversational/voice-ui-patterns.md +297 -0
  384. package/knowledge/design-tokens/ant-design.md +124 -0
  385. package/knowledge/design-tokens/material-3.md +235 -0
  386. package/knowledge/design-tokens/polaris-and-carbon.md +231 -0
  387. package/knowledge/design-tokens/tailwind-v4.md +284 -0
  388. package/knowledge/game-ui/game-accessibility.md +317 -0
  389. package/knowledge/game-ui/game-ui-fundamentals.md +281 -0
  390. package/knowledge/game-ui/hud-design.md +324 -0
  391. package/knowledge/game-ui/korean-gaming-conventions.md +312 -0
  392. package/knowledge/game-ui/menu-systems.md +388 -0
  393. package/knowledge/i18n/korean-app-store-visual.md +223 -0
  394. package/knowledge/i18n/korean-document-style.md +301 -0
  395. package/knowledge/i18n/korean-payments.md +211 -0
  396. package/knowledge/i18n/korean-product-conventions.md +96 -0
  397. package/knowledge/i18n/korean-publishing.md +139 -0
  398. package/knowledge/i18n/korean-typography.md +123 -0
  399. package/knowledge/icons/curated-sets.md +225 -0
  400. package/knowledge/illustration/hero-illustrations.md +234 -0
  401. package/knowledge/illustration/illustration-systems.md +221 -0
  402. package/knowledge/illustration/mascot-design.md +208 -0
  403. package/knowledge/illustration/spot-illustrations.md +246 -0
  404. package/knowledge/illustration/svg-optimization.md +308 -0
  405. package/knowledge/layout/spacing-and-grid.md +119 -0
  406. package/knowledge/motion/app-loading-sequences.md +277 -0
  407. package/knowledge/motion/choreography-depth.md +297 -0
  408. package/knowledge/motion/marketing-motion.md +223 -0
  409. package/knowledge/motion/micro-interactions.md +266 -0
  410. package/knowledge/motion/motion-tools.md +281 -0
  411. package/knowledge/motion/principles.md +126 -0
  412. package/knowledge/patterns/auth-flow-design.md +316 -0
  413. package/knowledge/patterns/b2b-onboarding-flows.md +182 -0
  414. package/knowledge/patterns/brand-identity.md +238 -0
  415. package/knowledge/patterns/brand-references.md +97 -0
  416. package/knowledge/patterns/chart-color-encoding.md +269 -0
  417. package/knowledge/patterns/chart-types.md +344 -0
  418. package/knowledge/patterns/dashboard-composition.md +299 -0
  419. package/knowledge/patterns/design-system-qa.md +356 -0
  420. package/knowledge/patterns/document-typography.md +248 -0
  421. package/knowledge/patterns/email-design.md +338 -0
  422. package/knowledge/patterns/empty-states.md +263 -0
  423. package/knowledge/patterns/error-states.md +318 -0
  424. package/knowledge/patterns/form-design.md +237 -0
  425. package/knowledge/patterns/information-architecture.md +341 -0
  426. package/knowledge/patterns/landing-hero-design.md +283 -0
  427. package/knowledge/patterns/landing-page-patterns.md +681 -0
  428. package/knowledge/patterns/list-and-feed.md +371 -0
  429. package/knowledge/patterns/mobile-navigation.md +278 -0
  430. package/knowledge/patterns/money-and-amount.md +301 -0
  431. package/knowledge/patterns/onboarding.md +300 -0
  432. package/knowledge/patterns/pricing-page-design.md +261 -0
  433. package/knowledge/patterns/realtime-data.md +280 -0
  434. package/knowledge/patterns/report-design.md +330 -0
  435. package/knowledge/patterns/search-ux.md +373 -0
  436. package/knowledge/patterns/settings-page.md +325 -0
  437. package/knowledge/patterns/slide-deck-design.md +316 -0
  438. package/knowledge/patterns/styles-catalog.md +2599 -0
  439. package/knowledge/patterns/technical-writing.md +306 -0
  440. package/knowledge/patterns/ui-reasoning.md +1853 -0
  441. package/knowledge/patterns/ux-guidelines.md +1454 -0
  442. package/knowledge/platforms/react-native.md +395 -0
  443. package/knowledge/print/brochures-and-flyers.md +276 -0
  444. package/knowledge/print/korean-print-conventions.md +284 -0
  445. package/knowledge/print/packaging.md +321 -0
  446. package/knowledge/print/print-fundamentals.md +238 -0
  447. package/knowledge/print/signage-and-posters.md +235 -0
  448. package/knowledge/print/stationery.md +262 -0
  449. package/knowledge/spatial/ar-patterns.md +253 -0
  450. package/knowledge/spatial/comfort-and-accessibility.md +245 -0
  451. package/knowledge/spatial/spatial-design-fundamentals.md +346 -0
  452. package/knowledge/spatial/spatial-ui-elements.md +343 -0
  453. package/knowledge/spatial/vr-patterns.md +302 -0
  454. package/knowledge/typography/font-pairings.md +332 -0
  455. package/knowledge/typography/mui-type-scale.md +57 -0
  456. package/knowledge/typography/type-scale-fundamentals.md +105 -0
  457. package/knowledge/video/in-product-video.md +277 -0
  458. package/knowledge/video/korean-video-conventions.md +247 -0
  459. package/knowledge/video/marketing-video.md +258 -0
  460. package/knowledge/video/social-and-short-form.md +257 -0
  461. package/knowledge/video/video-fundamentals.md +296 -0
  462. package/package.json +106 -0
  463. package/skills/README.md +39 -0
  464. package/skills/color-palette/PLAYBOOK.md +175 -0
  465. package/skills/color-palette/SKILL.md +6 -0
  466. package/skills/color-palette/TEMPLATE.md +103 -0
  467. package/skills/component-spec-writer/PLAYBOOK.md +169 -0
  468. package/skills/component-spec-writer/SKILL.md +6 -0
  469. package/skills/component-spec-writer/TEMPLATE.md +115 -0
  470. package/skills/conversational-ui-designer/PLAYBOOK.md +231 -0
  471. package/skills/conversational-ui-designer/SKILL.md +6 -0
  472. package/skills/design-broadcast/PLAYBOOK.md +146 -0
  473. package/skills/design-broadcast/SKILL.md +6 -0
  474. package/skills/design-critique/PLAYBOOK.md +137 -0
  475. package/skills/design-critique/SKILL.md +6 -0
  476. package/skills/design-pr-review/PLAYBOOK.md +171 -0
  477. package/skills/design-pr-review/SKILL.md +6 -0
  478. package/skills/design-system-builder/PLAYBOOK.md +218 -0
  479. package/skills/design-system-builder/SKILL.md +6 -0
  480. package/skills/design-system-qa/PLAYBOOK.md +163 -0
  481. package/skills/design-system-qa/SKILL.md +6 -0
  482. package/skills/document-author/PLAYBOOK.md +167 -0
  483. package/skills/document-author/SKILL.md +6 -0
  484. package/skills/figma-token-sync/PLAYBOOK.md +149 -0
  485. package/skills/figma-token-sync/SKILL.md +6 -0
  486. package/skills/game-ui-designer/PLAYBOOK.md +209 -0
  487. package/skills/game-ui-designer/SKILL.md +6 -0
  488. package/skills/handoff-spec/PLAYBOOK.md +170 -0
  489. package/skills/handoff-spec/SKILL.md +6 -0
  490. package/skills/illustration-designer/PLAYBOOK.md +166 -0
  491. package/skills/illustration-designer/SKILL.md +6 -0
  492. package/skills/motion-designer/PLAYBOOK.md +223 -0
  493. package/skills/motion-designer/SKILL.md +6 -0
  494. package/skills/print-designer/PLAYBOOK.md +209 -0
  495. package/skills/print-designer/SKILL.md +6 -0
  496. package/skills/slide-deck-author/PLAYBOOK.md +198 -0
  497. package/skills/slide-deck-author/SKILL.md +6 -0
  498. package/skills/spatial-designer/PLAYBOOK.md +238 -0
  499. package/skills/spatial-designer/SKILL.md +6 -0
  500. package/skills/ux-audit/PLAYBOOK.md +142 -0
  501. package/skills/ux-audit/SKILL.md +6 -0
  502. package/skills/video-designer/PLAYBOOK.md +240 -0
  503. package/skills/video-designer/SKILL.md +6 -0
  504. package/skills/website-improvement/PLAYBOOK.md +118 -0
  505. package/skills/website-improvement/SKILL.md +6 -0
  506. package/skills/website-improvement/TEMPLATE.md +103 -0
  507. package/tools/audit/changelog-generate.py +176 -0
  508. package/tools/audit/check-coverage.py +483 -0
  509. package/tools/audit/doctor_assertions.py +256 -0
  510. package/tools/audit/example-qa.py +108 -0
  511. package/tools/audit/frontmatter-check.py +199 -0
  512. package/tools/audit/integration-check.py +95 -0
  513. package/tools/audit/korean-copy-check.py +161 -0
  514. package/tools/audit/link-check.py +146 -0
  515. package/tools/audit/local-ci.py +558 -0
  516. package/tools/audit/package-contents.py +723 -0
  517. package/tools/audit/package-smoke.py +22443 -0
  518. package/tools/audit/raw-hex-check.py +252 -0
  519. package/tools/audit/registry-smoke.py +8188 -0
  520. package/tools/audit/release-metadata.py +9832 -0
  521. package/tools/audit/run-all.py +351 -0
  522. package/tools/audit/smoke_assertions.py +12742 -0
  523. package/tools/audit/stability-review.py +332 -0
  524. package/tools/audit/stale-check.py +156 -0
  525. package/tools/migrations/add-version-frontmatter.py +132 -0
  526. package/tools/migrations/bump-last-updated.py +131 -0
  527. package/tools/migrations/promote-stability.py +172 -0
  528. package/tools/preview/README.md +58 -0
  529. package/tools/preview/render-tokens.py +454 -0
@@ -0,0 +1,87 @@
1
+ # `Fade` — spec
2
+
3
+ > Synthesized from MUI `Fade`. Opacity-only enter/exit transition. The lightest motion primitive — for elements that should appear/disappear without movement (Dialogs' default scrim, Tooltip enter, conditional content).
4
+
5
+ ## When to use
6
+
7
+ - Mounting/unmounting content where motion would distract.
8
+ - Default transition for Modal / Dialog backdrops.
9
+ - Conditional hide/show of inline content (e.g., loading spinner appearing while data fetches).
10
+
11
+ ## When NOT to use
12
+
13
+ - Page transitions → use `Slide` (directional context).
14
+ - Stack-of-cards scenarios → use `Grow` (origin-aware scale).
15
+ - Anything where reduced-motion users would still feel jolted (very-small fades are fine; full-screen white-flash fades are not).
16
+
17
+ ## API
18
+
19
+ ```tsx
20
+ <Fade in={open} timeout={200}>
21
+ <Box>Mounted only when in=true (or with mountOnEnter/unmountOnExit)</Box>
22
+ </Fade>
23
+ ```
24
+
25
+ | Prop | Type | Default | Description |
26
+ | --- | --- | --- | --- |
27
+ | `in` | `boolean` | required | Trigger enter/exit |
28
+ | `timeout` | `number \| { enter, exit }` | `{ enter: 225, exit: 195 }` | Duration in ms |
29
+ | `easing` | `string \| { enter, exit }` | theme default | CSS easing |
30
+ | `addEndListener` | `(node, done) => void` | — | Custom transition-end logic |
31
+ | `appear` | `boolean` | `true` | Animate on initial mount |
32
+ | `mountOnEnter` | `boolean` | `false` | Don't render until first `in=true` |
33
+ | `unmountOnExit` | `boolean` | `false` | Remove from DOM after exit |
34
+
35
+ ## Tokens consumed
36
+
37
+ ```
38
+ --motion-duration-200 /* default ~225ms ≈ 200 token */
39
+ --motion-easing-out
40
+ --motion-easing-in
41
+ ```
42
+
43
+ ## Accessibility
44
+
45
+ - Respect `prefers-reduced-motion`. MUI's transitions auto-disable when the user has the system preference set (returns immediately to final state).
46
+ - For decorative fades, no aria; for content that becomes meaningful (e.g., error message), pair with `aria-live="polite"` on the destination so the screen reader reads it.
47
+ - Keep timeout under 250ms to avoid feeling sluggish.
48
+
49
+ ## Edge cases
50
+
51
+ - **Long timeouts** — > 400ms feels slow. For elaborate enters, prefer `Grow` or stage with a stagger.
52
+ - **Reduced-motion users** — verified-correct: MUI snaps to final state. Don't override unless intentional.
53
+ - **Mount + immediate `in=true`** — without `appear=true` (the default), the first render skips animation. Set `appear={false}` to disable.
54
+
55
+ ## Code example
56
+
57
+ ```tsx
58
+ <Fade in={!isLoading} unmountOnExit>
59
+ <List>...</List>
60
+ </Fade>
61
+
62
+ // Loading + content swap
63
+ <Box position="relative">
64
+ <Fade in={isLoading} unmountOnExit>
65
+ <CircularProgress sx={{ position: 'absolute', inset: 0, m: 'auto' }} />
66
+ </Fade>
67
+ <Fade in={!isLoading}>
68
+ <DataTable rows={rows} />
69
+ </Fade>
70
+ </Box>
71
+ ```
72
+
73
+ ## Don't
74
+
75
+ - Don't use for fully reusable elements that frequently mount/unmount — adds runtime cost.
76
+ - Don't fade-in critical alerts — they should appear immediately.
77
+
78
+ ## References
79
+
80
+ - MUI: [`Fade`](../refs/mui/packages/mui-material/src/Fade/)
81
+
82
+ ## Cross-reference
83
+
84
+ - [`component-grow.md`](component-grow.md)
85
+ - [`component-slide.md`](component-slide.md)
86
+ - [`component-zoom.md`](component-zoom.md)
87
+ - [`knowledge/motion/principles.md`](../knowledge/motion/principles.md)
@@ -0,0 +1,201 @@
1
+ # `FeatureGrid` (3-up / 4-up feature display) — spec
2
+
3
+ > Marketing-page primitive. Renders 3–6 feature cells in a grid below the hero. Each cell: icon + headline + 1-line description.
4
+
5
+ ## Purpose
6
+
7
+ Communicate **3–6 things the product does** in a scannable layout. Used after the hero on most landing pages.
8
+
9
+ ## Anatomy
10
+
11
+ ```
12
+ ┌──────────────────────────────────────────────────────┐
13
+ │ Section title (optional) │
14
+ │ Section sub-headline (optional) │
15
+ ├──────────────────────────────────────────────────────┤
16
+ │ ┌────────┐ ┌────────┐ ┌────────┐ │
17
+ │ │ [icon] │ │ [icon] │ │ [icon] │ │
18
+ │ │ │ │ │ │ │ │
19
+ │ │ Title │ │ Title │ │ Title │ │
20
+ │ │ │ │ │ │ │ │
21
+ │ │ Desc │ │ Desc │ │ Desc │ │
22
+ │ │ │ │ │ │ │ │
23
+ │ └────────┘ └────────┘ └────────┘ │
24
+ └──────────────────────────────────────────────────────┘
25
+ ```
26
+
27
+ ## API
28
+
29
+ ```tsx
30
+ <FeatureGrid
31
+ title="왜 우리 가계부인가요?"
32
+ features={[
33
+ {
34
+ icon: <BankIcon />,
35
+ title: "30개 은행 자동 연동",
36
+ description: "한 번 연결하면 자동으로 거래내역이 들어옵니다.",
37
+ },
38
+ {
39
+ icon: <CategoryIcon />,
40
+ title: "AI 자동 분류",
41
+ description: "거래마다 카테고리가 자동으로 정리됩니다.",
42
+ },
43
+ {
44
+ icon: <ShieldIcon />,
45
+ title: "은행급 보안",
46
+ description: "AES-256 암호화 + 본인인증으로 안전합니다.",
47
+ },
48
+ ]}
49
+ columns={{ default: 1, md: 3 }}
50
+ />
51
+ ```
52
+
53
+ | Prop | Type | Default | Description |
54
+ | --- | --- | --- | --- |
55
+ | `title` | `string \| ReactNode` | — | Section heading |
56
+ | `subtitle` | `string \| ReactNode` | — | Section sub-headline |
57
+ | `features` | `Feature[]` | — | 3–6 features |
58
+ | `columns` | `number \| { default, md, lg, ... }` | `{ default: 1, md: 3 }` | Column count per breakpoint |
59
+ | `cardStyle` | `"plain" \| "outlined" \| "elevated"` | `"plain"` | Visual treatment |
60
+ | `iconStyle` | `"colored-bg" \| "plain" \| "outline"` | `"colored-bg"` | Icon container |
61
+ | `align` | `"left" \| "center"` | `"left"` | Per-cell content alignment |
62
+
63
+ ```ts
64
+ type Feature = {
65
+ icon?: ReactNode;
66
+ title: string;
67
+ description: string;
68
+ ctaLabel?: string;
69
+ ctaHref?: string;
70
+ };
71
+ ```
72
+
73
+ ## Layout variants
74
+
75
+ ### 3-up grid (default)
76
+
77
+ Most landing pages. Each cell has equal weight. Mobile: stacks vertically.
78
+
79
+ ### 2-up grid
80
+
81
+ When you have 4 features. Visually distinct from 3-up (less "feature catalog" feel).
82
+
83
+ ### 4-up grid
84
+
85
+ Tighter cells. Use when you have exactly 4 strong features. More than 4 → split into multiple sections.
86
+
87
+ ### Alternating "zig-zag"
88
+
89
+ Each feature alternates: left-image right-text, then right-image left-text. Used for richer feature explanations (1 cell ≈ 1 row, image takes ~50%).
90
+
91
+ ```
92
+ ┌──────────────────────────────────────┐
93
+ │ [image] Title │
94
+ │ Description │
95
+ ├──────────────────────────────────────┤
96
+ │ Title [image] │
97
+ │ Description │
98
+ ├──────────────────────────────────────┤
99
+ │ [image] Title │
100
+ │ Description │
101
+ └──────────────────────────────────────┘
102
+ ```
103
+
104
+ For richer features: zig-zag works. For a tight 3-up: standard grid.
105
+
106
+ ## Cell anatomy
107
+
108
+ | Slot | Required | Notes |
109
+ | --- | --- | --- |
110
+ | Icon | usually | 32–48px, brand-colored bg or plain |
111
+ | Title | yes | 1 line ideal, weight 600 |
112
+ | Description | yes | 1–2 lines, body color |
113
+ | Optional CTA | optional | "Learn more" link |
114
+
115
+ For Korean: title 6-12자 typical. Description 한 문장 (~25 자).
116
+
117
+ ## Tokens consumed
118
+
119
+ ```
120
+ --color-bg-default
121
+ --color-bg-elevated (cardStyle elevated)
122
+ --color-bg-subtle (icon bg when colored-bg)
123
+ --color-primary-default (icon color when plain/outline)
124
+ --color-primary-subtle-bg (icon container bg)
125
+ --color-text-primary (title)
126
+ --color-text-secondary (description)
127
+ --space-md, --space-lg, --space-xl
128
+ --radius-md, --radius-lg
129
+ --shadow-card (elevated)
130
+ --font-size-base, --font-size-lg, --font-size-xl
131
+ --font-weight-semibold
132
+ ```
133
+
134
+ ## Sizes
135
+
136
+ | Element | Mobile | Desktop |
137
+ | --- | --- | --- |
138
+ | Cell padding | 24px | 32px |
139
+ | Icon size | 32px | 40–48px |
140
+ | Title font | 16px | 18–20px |
141
+ | Description font | 14px | 14–16px |
142
+ | Cell min-height | auto | ~280px (so cells equalize) |
143
+
144
+ ## Accessibility
145
+
146
+ - Wrap in `<section>` with `<h2>` for section title.
147
+ - Each feature cell: `<article>` with `<h3>` for title.
148
+ - Icons: `aria-hidden="true"` (title carries meaning).
149
+ - For interactive cells (with CTAs): the CTA button gets focus, not the whole cell.
150
+
151
+ ## Korean conventions
152
+
153
+ - Section title: question or declarative. "왜 우리 가계부인가요?" / "이런 기능들이 있어요"
154
+ - Feature title: 짧은 명사구 ("자동 연동", "AI 분류").
155
+ - Description: 한 문장. 문장형 끝맺음 ("정리됩니다", "안전합니다") matches ~합니다 voice.
156
+
157
+ ## Code example
158
+
159
+ ```tsx
160
+ <FeatureGrid
161
+ title="왜 우리 가계부인가요?"
162
+ subtitle="번거로운 가계부 입력은 이제 그만"
163
+ features={[
164
+ {
165
+ icon: <BankIcon />,
166
+ title: "30개 은행 자동 연동",
167
+ description: "한 번 연결하면 자동으로 거래내역이 들어옵니다.",
168
+ },
169
+ {
170
+ icon: <CategoryIcon />,
171
+ title: "AI 자동 분류",
172
+ description: "거래마다 카테고리가 자동으로 정리됩니다.",
173
+ },
174
+ {
175
+ icon: <ShieldIcon />,
176
+ title: "은행급 보안",
177
+ description: "AES-256 암호화 + 본인인증으로 안전합니다.",
178
+ },
179
+ ]}
180
+ columns={{ default: 1, md: 3 }}
181
+ iconStyle="colored-bg"
182
+ />
183
+ ```
184
+
185
+ ## Don't
186
+
187
+ - Don't show 7+ features in one grid — overwhelming.
188
+ - Don't use generic stock icons that don't match the feature.
189
+ - Don't make each cell a different visual weight — equal-by-design.
190
+ - Don't put long descriptions (3+ lines). Trim or move to a dedicated explainer page.
191
+ - Don't omit icons for visual rhythm — but don't force icons that aren't meaningful.
192
+
193
+ ## References
194
+
195
+ No upstream component matches exactly. Each marketing-page builder (Webflow, Framer) has variants. The 3-up grid is the universal pattern.
196
+
197
+ ## Cross-reference
198
+
199
+ - [`examples/component-hero-block.md`](component-hero-block.md) — hero comes before
200
+ - [`examples/component-testimonial-carousel.md`](component-testimonial-carousel.md) — social proof comes after
201
+ - [`knowledge/patterns/landing-page-patterns.md`](../knowledge/patterns/landing-page-patterns.md) — full landing structure
@@ -0,0 +1,266 @@
1
+ # `Field` — spec
2
+
3
+ > Synthesized from shadcn-ui `field` (an opinionated form-field wrapper). The "Field family" — `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldSet`, `FieldLegend` — ship as a set, providing a consistent layout for labeled form inputs. Pairs with [`examples/component-form.md`](component-form.md) for the broader form composition.
4
+
5
+ ## When to use
6
+
7
+ - **Wrapping any form input** (Input, Textarea, Select, Checkbox, Switch) with consistent label / description / error layout.
8
+ - **Replacing ad-hoc div+label markup** with a semantic, a11y-correct primitive.
9
+ - **As the building block** for higher-level form patterns (Form skill in design-ai).
10
+
11
+ When NOT to use:
12
+ - Pure presentation labels (use a `<label>` directly).
13
+ - Complex multi-input compositions — use `FieldGroup`.
14
+
15
+ ## Field family
16
+
17
+ ```
18
+ FieldSet (multi-field section, optional)
19
+ └─ FieldLegend (section heading)
20
+ └─ FieldGroup (related fields, e.g., First + Last name)
21
+ └─ Field (single labeled control)
22
+ ├─ FieldLabel
23
+ ├─ <Input> | <Select> | <Checkbox> | etc.
24
+ ├─ FieldDescription (helper text, optional)
25
+ └─ FieldError (validation message, conditional)
26
+ ```
27
+
28
+ ## Anatomy
29
+
30
+ ```
31
+ Email ← FieldLabel
32
+ [ user@example.com ] ← <Input>
33
+ We'll never share your... ← FieldDescription
34
+ Email is required ← FieldError (when invalid)
35
+ ```
36
+
37
+ ## API
38
+
39
+ ```tsx
40
+ <Field>
41
+ <FieldLabel htmlFor="email">Email</FieldLabel>
42
+ <Input id="email" type="email" {...register("email")} />
43
+ <FieldDescription>We'll never share your email.</FieldDescription>
44
+ <FieldError>{errors.email?.message}</FieldError>
45
+ </Field>
46
+
47
+ <FieldGroup>
48
+ <Field>
49
+ <FieldLabel htmlFor="first">First name</FieldLabel>
50
+ <Input id="first" {...register("first")} />
51
+ </Field>
52
+ <Field>
53
+ <FieldLabel htmlFor="last">Last name</FieldLabel>
54
+ <Input id="last" {...register("last")} />
55
+ </Field>
56
+ </FieldGroup>
57
+
58
+ <FieldSet>
59
+ <FieldLegend>Notification preferences</FieldLegend>
60
+ <Field>
61
+ <FieldLabel htmlFor="email-notif">
62
+ <Checkbox id="email-notif" />
63
+ Email notifications
64
+ </FieldLabel>
65
+ </Field>
66
+ <Field>
67
+ <FieldLabel htmlFor="sms-notif">
68
+ <Checkbox id="sms-notif" />
69
+ SMS notifications
70
+ </FieldLabel>
71
+ </Field>
72
+ </FieldSet>
73
+ ```
74
+
75
+ ## Composition
76
+
77
+ | Part | Purpose | Semantic element |
78
+ | --- | --- | --- |
79
+ | `Field` | Wrapper for one labeled input | `<div>` |
80
+ | `FieldLabel` | Label for the input | `<label>` |
81
+ | `FieldDescription` | Helper text below | `<p>` (linked via `aria-describedby`) |
82
+ | `FieldError` | Validation error | `<p role="alert">` (linked via `aria-describedby`) |
83
+ | `FieldGroup` | Visual grouping of related fields (no semantic) | `<div role="group">` |
84
+ | `FieldSet` | Semantic group with shared legend | `<fieldset>` |
85
+ | `FieldLegend` | Heading for `FieldSet` | `<legend>` |
86
+
87
+ ## Variants
88
+
89
+ ### Layout direction
90
+
91
+ | Layout | Use |
92
+ | --- | --- |
93
+ | Vertical (default) | Label above input; mobile-friendly |
94
+ | Horizontal | Label left of input (rare; tight tabular forms) |
95
+ | Inline | Single-line for short inputs (search, toggle) |
96
+
97
+ ```tsx
98
+ <Field orientation="horizontal">
99
+ <FieldLabel>Country</FieldLabel>
100
+ <Select>...</Select>
101
+ </Field>
102
+ ```
103
+
104
+ ### Required indicator
105
+
106
+ ```tsx
107
+ <Field required>
108
+ <FieldLabel>Email *</FieldLabel>
109
+ <Input ... />
110
+ </Field>
111
+ ```
112
+
113
+ The `required` prop on Field auto-adds:
114
+ - `aria-required="true"` on the wrapped input
115
+ - Visual asterisk on FieldLabel
116
+ - Optional: required marker on the right OR text "(required)"
117
+
118
+ ### Optional indicator (Korean / Japanese style)
119
+
120
+ For markets that mark optional vs required: `<Field optional>` adds "(선택)" / "(任意)".
121
+
122
+ ## States
123
+
124
+ | State | Visual |
125
+ | --- | --- |
126
+ | Default | Resting |
127
+ | Focused | Input shows focus ring |
128
+ | Filled | Input has value |
129
+ | Disabled | Reduced opacity; input non-interactive |
130
+ | Read-only | No focus ring; muted bg |
131
+ | Error | Input border red; FieldError visible; FieldDescription dims |
132
+ | Success | Optional checkmark icon (post-validation) |
133
+
134
+ ## Tokens consumed
135
+
136
+ ```
137
+ --field-gap (vertical space between Label / Input / Description)
138
+ --field-label-fg
139
+ --field-description-fg (typically muted)
140
+ --field-error-fg (red)
141
+ --field-asterisk-fg (required marker color)
142
+ --space-xs, --space-sm, --space-md
143
+ --font-size-sm (Label, Description, Error)
144
+ --font-weight-medium (Label)
145
+ --motion-fast (state transitions)
146
+ ```
147
+
148
+ ## Accessibility
149
+
150
+ - `FieldLabel` uses real `<label htmlFor="...">`. Click on label focuses input.
151
+ - `FieldDescription` linked via `aria-describedby="<id>-desc"`.
152
+ - `FieldError` linked via `aria-describedby="<id>-err"`. When error visible, both descriptions can be linked: `aria-describedby="<id>-desc <id>-err"`.
153
+ - `aria-invalid="true"` on input when in error state.
154
+ - `FieldSet` is a real `<fieldset>` — screen readers announce the legend before each input within it. Critical for grouped checkboxes / radios.
155
+ - Required: prefer `aria-required` over relying on visual asterisk alone.
156
+ - Touch targets: input ≥ 44pt for primary mobile.
157
+
158
+ ## Korean conventions
159
+
160
+ ```
161
+ 이메일 ← FieldLabel
162
+ [ user@example.com ]
163
+ 이메일은 공유되지 않아요. ← FieldDescription (해요체)
164
+ 이메일을 입력해 주세요. ← FieldError
165
+ ```
166
+
167
+ - 해요체 ("...해요") for casual brand voice
168
+ - 합쇼체 ("...해 주세요") for formal / banking
169
+ - "(선택)" for optional, "(필수)" or "*" for required
170
+ - Avoid mixing levels within one form
171
+
172
+ ## Code example — sign-up form
173
+
174
+ ```tsx
175
+ function SignupForm() {
176
+ const { register, handleSubmit, formState: { errors } } = useForm<SignupSchema>({
177
+ resolver: zodResolver(signupSchema),
178
+ });
179
+
180
+ return (
181
+ <form onSubmit={handleSubmit(onSubmit)}>
182
+ <Field required>
183
+ <FieldLabel htmlFor="email">이메일</FieldLabel>
184
+ <Input
185
+ id="email"
186
+ type="email"
187
+ autoComplete="email"
188
+ {...register("email")}
189
+ aria-invalid={!!errors.email}
190
+ />
191
+ <FieldDescription>로그인 시 사용해요.</FieldDescription>
192
+ {errors.email && <FieldError>{errors.email.message}</FieldError>}
193
+ </Field>
194
+
195
+ <Field required>
196
+ <FieldLabel htmlFor="password">비밀번호</FieldLabel>
197
+ <Input
198
+ id="password"
199
+ type="password"
200
+ autoComplete="new-password"
201
+ {...register("password")}
202
+ aria-invalid={!!errors.password}
203
+ />
204
+ <FieldDescription>8자 이상, 영문 + 숫자 + 특수문자 포함.</FieldDescription>
205
+ {errors.password && <FieldError>{errors.password.message}</FieldError>}
206
+ </Field>
207
+
208
+ <FieldGroup>
209
+ <Field>
210
+ <FieldLabel htmlFor="first">이름</FieldLabel>
211
+ <Input id="first" {...register("first")} />
212
+ </Field>
213
+ <Field>
214
+ <FieldLabel htmlFor="last">성</FieldLabel>
215
+ <Input id="last" {...register("last")} />
216
+ </Field>
217
+ </FieldGroup>
218
+
219
+ <FieldSet>
220
+ <FieldLegend>알림 설정</FieldLegend>
221
+ <Field>
222
+ <FieldLabel htmlFor="marketing">
223
+ <Checkbox id="marketing" {...register("marketing")} />
224
+ 마케팅 정보 수신 동의 (선택)
225
+ </FieldLabel>
226
+ </Field>
227
+ </FieldSet>
228
+
229
+ <Button type="submit">가입하기</Button>
230
+ </form>
231
+ );
232
+ }
233
+ ```
234
+
235
+ ## Edge cases
236
+
237
+ - **Multiple errors on same field**: show only the most-relevant; or stack with separator.
238
+ - **Async validation**: show "Checking..." state while validating; transition to FieldError or success.
239
+ - **Input is wrapped in another component** (e.g., Combobox, DatePicker): Field still works; pass id via Combobox's render prop.
240
+ - **Field with multiple inputs** (e.g., date split into 3 inputs): use FieldGroup; each input has its own aria-labelled-by referencing FieldLabel.
241
+ - **Help icon next to label**: render Tooltip trigger in FieldLabel; tooltip content = additional context.
242
+ - **Reduced motion**: skip transition on error appearance.
243
+
244
+ ## Don't
245
+
246
+ - Don't use plain `<div>` + `<label>` for form fields. Use Field — a11y baked in.
247
+ - Don't omit FieldDescription for non-obvious inputs. Help users.
248
+ - Don't rely on placeholder as label. Placeholder ≠ label.
249
+ - Don't show error before user has interacted with the field. On-blur or on-submit, not on-change.
250
+ - Don't use FieldSet for visual grouping only. Use FieldGroup. FieldSet has semantic meaning.
251
+ - Don't use red text alone for error — pair with icon for color-blind users.
252
+ - Don't auto-focus on error after submit if there are multiple errors — focus on first invalid field, but only one.
253
+
254
+ ## References
255
+
256
+ - shadcn-ui: [`field`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/field.tsx)
257
+ - WAI-ARIA Authoring Practices: form labeling
258
+ - Native HTML: `<fieldset>`, `<legend>`, `<label>`
259
+
260
+ ## Cross-reference
261
+
262
+ - [`examples/component-form.md`](component-form.md) — Form composition (uses Field internally)
263
+ - [`examples/component-form-controls.md`](component-form-controls.md) — Switch / Checkbox / Radio (Field-compatible)
264
+ - [`examples/component-input.md`](component-input.md) — most common Field child
265
+ - [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md)
266
+ - [`knowledge/i18n/korean-document-style.md`](../knowledge/i18n/korean-document-style.md) — 해요체 / 합쇼체
@@ -0,0 +1,114 @@
1
+ # `FilledInput` — spec
2
+
3
+ > Synthesized from MUI `FilledInput`. Filled-background input variant — denser, less prominent than `OutlinedInput`. Useful inside cards or dense forms where 30+ borders would create visual noise.
4
+
5
+ ## When to use
6
+
7
+ - Dense data-entry forms (10+ fields per screen).
8
+ - Inputs inside cards with already-active borders (avoids "border on border").
9
+ - Mobile-first layouts where the filled look reads as a touch target.
10
+
11
+ ## When NOT to use
12
+
13
+ - General-purpose product UI — `OutlinedInput` has the cleanest "this is editable" affordance.
14
+ - Forms with many error states — error styling is more legible against an outlined background.
15
+
16
+ ## Anatomy
17
+
18
+ ```
19
+ ┌─ Label (floats up on focus) ─────────────┐
20
+ │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ ← filled bg
21
+ │ ░Input value ░│
22
+ │ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔│ ← bottom rule (focus → brand)
23
+ └─────────────────────────────────────────────┘
24
+ ```
25
+
26
+ ## API
27
+
28
+ ```tsx
29
+ <FormControl variant="filled" fullWidth>
30
+ <InputLabel htmlFor="name">이름</InputLabel>
31
+ <FilledInput
32
+ id="name"
33
+ value={name}
34
+ onChange={(e) => setName(e.target.value)}
35
+ />
36
+ </FormControl>
37
+ ```
38
+
39
+ | Prop | Type | Default | Description |
40
+ | --- | --- | --- | --- |
41
+ | `value` / `defaultValue` | `string` | — | Controlled / uncontrolled |
42
+ | `disableUnderline` | `boolean` | `false` | Hide the bottom rule |
43
+ | `hiddenLabel` | `boolean` | `false` | Drop the label region (use placeholder only) |
44
+
45
+ Inherits everything from `InputBase` — see [`component-input-base.md`](component-input-base.md).
46
+
47
+ ## States
48
+
49
+ | State | Visual |
50
+ | --- | --- |
51
+ | Default | bg-subtle fill, neutral underline |
52
+ | Hover | bg-subtle (slightly darker) |
53
+ | Focus | brand underline (animates from neutral) |
54
+ | Error | error underline + label color |
55
+ | Disabled | muted bg + fg |
56
+
57
+ ## Tokens consumed
58
+
59
+ ```
60
+ --input-bg-filled /* surface-subtle */
61
+ --input-bg-filled-hover
62
+ --input-underline
63
+ --input-underline-focus /* brand */
64
+ --input-underline-error
65
+ --input-min-height-48 /* taller than outlined to compensate for filled aesthetic */
66
+ ```
67
+
68
+ ## Accessibility
69
+
70
+ Same a11y contract as `OutlinedInput`:
71
+ - `htmlFor` ↔ `id` association via `InputLabel`.
72
+ - `aria-required`, `aria-invalid`, `aria-describedby` per state.
73
+ - Touch target: ≥ 48px (default — `FilledInput` is taller than `OutlinedInput` by design).
74
+
75
+ ## Edge cases
76
+
77
+ - **Mixing variants on one screen** — pick one. Mixed outlined + filled looks haphazard.
78
+ - **`hiddenLabel`** — only acceptable when context is unmistakable (e.g., a search field labeled by a magnifying-glass icon nearby with `aria-label`).
79
+ - **Korean labels** — same density consideration as outlined; expect labels to need 10-15% more horizontal room than Latin.
80
+
81
+ ## Code example
82
+
83
+ ```tsx
84
+ <Stack direction="column" gap={1.5}>
85
+ <FormControl variant="filled" fullWidth>
86
+ <InputLabel htmlFor="name">이름</InputLabel>
87
+ <FilledInput id="name" />
88
+ </FormControl>
89
+ <FormControl variant="filled" fullWidth>
90
+ <InputLabel htmlFor="email">이메일</InputLabel>
91
+ <FilledInput id="email" type="email" />
92
+ </FormControl>
93
+ <FormControl variant="filled" fullWidth>
94
+ <InputLabel htmlFor="phone">전화번호</InputLabel>
95
+ <FilledInput id="phone" type="tel" />
96
+ </FormControl>
97
+ </Stack>
98
+ ```
99
+
100
+ ## Don't
101
+
102
+ - Don't mix with `OutlinedInput` on the same form.
103
+ - Don't use `disableUnderline=true` without an alternative focus indicator — accessibility break.
104
+ - Don't use without `InputLabel` (or `inputProps.aria-label`) — silent accessibility miss.
105
+
106
+ ## References
107
+
108
+ - MUI: [`FilledInput`](../refs/mui/packages/mui-material/src/FilledInput/)
109
+
110
+ ## Cross-reference
111
+
112
+ - [`component-input-base.md`](component-input-base.md)
113
+ - [`component-outlined-input.md`](component-outlined-input.md)
114
+ - [`component-form-control.md`](component-form-control.md)