@design-ai/cli 4.55.0

package/examples/README.md

@@ -0,0 +1,252 @@
+# Examples
+
+Worked outputs from each skill — what "good" looks like. Use as reference when invoking the skill on your own task.
+
+### Website improvement
+
+| File | Skill | Input | What it demonstrates |
+| --- | --- | --- | --- |
+| [website-improvement-report.md](website-improvement-report.md) | `website-improvement` | Korean SaaS marketing site improvement control tower | Site Profile, audit summary, MCP readiness, refactor plan, prompt/report handoff, and MVP boundary that keeps target repo changes outside design-ai |
+
+### Color & tokens
+
+| File | Skill | Input | What it demonstrates |
+| --- | --- | --- | --- |
+| [palette-saas-violet.md](palette-saas-violet.md) | `color-palette` | B2B SaaS, violet seed `#7C3AED` | Full palette with OKLCH ramps, semantic aliases, light + dark, contrast matrix, Tailwind v4 + shadcn-ui + Style Dictionary outputs, use guidance |
+
+### Component specs (synthesized from Ant Design + MUI + shadcn-ui)
+
+| File | Component | What it covers |
+| --- | --- | --- |
+| [component-button.md](component-button.md) | Button | The most-used control. Variants, intent, sizes, loading state, asChild pattern. |
+| [component-button-base.md](component-button-base.md) | ButtonBase | Low-level interactive primitive for building design-system controls. Semantics, focus-visible, ripple, disabled, and polymorphic root rules. |
+| [component-border-beam.md](component-border-beam.md) | BorderBeam | Decorative moving border emphasis layer. Host DOM constraints, reduced motion, aria-hidden, and semantic-state boundaries. |
+| [component-input.md](component-input.md) | Input (text field) | Label/help/error, validation timing, autocomplete, IME (Korean) handling, password/clearable affordances. |
+| [component-modal.md](component-modal.md) | Modal / Dialog / Sheet | Focus trap, scroll lock, keyboard contract, three variants in one spec (dialog/alert-dialog/sheet). |
+| [component-toast.md](component-toast.md) | Toast / Snackbar | Imperative API (`toast.success(...)`), promise wrapper, intent + duration matrix, persistent errors. |
+| [component-card.md](component-card.md) | Card | Composition slots, variants, interactive cards, block-link pattern, when NOT to use a card. |
+| [component-form.md](component-form.md) | Form (composition pattern) | Field/Label/Control/HelpText/ErrorText composition, Zod schema validation, multi-step, server-error mapping, accessibility wiring. |
+| [component-table.md](component-table.md) | Table / DataTable | Headless engine (TanStack), sort/select/paginate, density, mobile→card-list, sticky columns. |
+| [component-tabs.md](component-tabs.md) | Tabs | Underline / segmented / card / bottom-bar variants, WAI-ARIA tabs pattern, manual vs automatic activation. |
+| [component-date-picker.md](component-date-picker.md) | DatePicker | Single/range/dateTime/quickRange modes, Korean date formats, calendar grid keyboard contract, mobile bottom sheet. |
+| [component-select.md](component-select.md) | Select / Combobox | Single/multi/searchable/creatable/async, WAI-ARIA combobox pattern, Korean IME composition handling. |
+| [component-pagination.md](component-pagination.md) | Pagination | Numbered + Load More + simple variants, sibling/boundary algorithm, URL sync, accessibility. |
+| [component-alert.md](component-alert.md) | Alert (Banner) | Persistent in-page feedback. Subtle/outlined/solid variants, intent + icon redundancy, action buttons, role=alert vs status. |
+| [component-tooltip.md](component-tooltip.md) | Tooltip | Hover/focus hint, why native `title` is wrong, touch handling, WAI-ARIA tooltip pattern, when NOT to use. |
+| [component-form-controls.md](component-form-controls.md) | Switch / Checkbox / Radio | Three sibling controls in one spec — semantic differences, when each, shared accessibility patterns, Korean marketing-consent rule. |
+| [component-skeleton.md](component-skeleton.md) | Skeleton | Loading shape (not progress %), shimmer animation, primitive composition, transition rules, reduced motion. |
+| [component-progress.md](component-progress.md) | Progress | Linear + circular, determinate vs indeterminate, intent variants, aria-valuenow rules, when Progress vs Spinner vs Skeleton. |
+| [component-avatar.md](component-avatar.md) | Avatar | Image → initials → icon fallback chain, Korean initials convention, AvatarGroup overlap, status indicators, hash-to-color. |
+| [component-breadcrumb.md](component-breadcrumb.md) | Breadcrumb | Hierarchy navigation, truncation algorithm, when not to use (mobile), aria-current="page", ordered list semantics. |
+| [component-accordion.md](component-accordion.md) | Accordion (Collapse) | Single vs multiple, four visual variants, height animation via grid-template-rows, WAI-ARIA disclosure pattern. |
+| [component-drawer.md](component-drawer.md) | Drawer | Side-anchored panel for navigation. Modal vs persistent mode, mobile detents, swipe-to-dismiss. |
+| [component-slider.md](component-slider.md) | Slider | Single + range, step semantics, when slider vs number input, WAI-ARIA slider pattern. |
+| [component-popover.md](component-popover.md) | Popover | Click-triggered overlay with interactive content. Distinct from Tooltip / Modal / Dropdown. |
+| [component-divider.md](component-divider.md) | Divider (Separator) | Horizontal + vertical, solid/dashed/dotted, inset, decorative vs semantic, when whitespace is better. |
+| [component-steps.md](component-steps.md) | Steps (Stepper) | Multi-step progress visualization. Status states, mobile compact variant, when Steps vs Tabs vs Progress. |
+| [component-rate.md](component-rate.md) | Rate (Rating) | Stars / emoji / custom icons. Input + display modes, half-star precision, slider-pattern a11y. |
+| [component-tag-badge.md](component-tag-badge.md) | Tag + Badge | Two sibling status indicators in one spec. Inline label vs dot/count overlay. |
+| [component-tree.md](component-tree.md) | Tree (TreeView) | Hierarchical data, async lazy-load, check + select modes, WAI-ARIA tree pattern, mobile drill-in alternative. |
+| [component-statistic.md](component-statistic.md) | Statistic | Hero KPI display. Delta semantics (goalDirection-aware coloring), Korean stock convention, sparkline. |
+| [component-upload.md](component-upload.md) | Upload | Drop zone + button + avatar patterns. Per-file progress, async validation, retry, Korean copy. |
+| [component-result.md](component-result.md) | Result + Empty | Two sibling full-page components in one spec. Status icons, primary/secondary actions, inline mode. |
+| [component-carousel.md](component-carousel.md) | Carousel | When NOT to use. Multi-slide view, auto-play warnings, WAI-ARIA carousel pattern. |
+| [component-image.md](component-image.md) | Image | Wrapper with lazy load, aspect-ratio, fallback, lightbox, srcset, alt rules. |
+| [component-calendar.md](component-calendar.md) | Calendar (full month view) | Distinct from DatePicker. Event rendering, holiday/weekend Korean colors, view modes. |
+| [component-cascader.md](component-cascader.md) | Cascader (multi-level select) | 2–4 level hierarchy picker. When NOT to use (mobile drill-in instead). |
+| [component-color-picker.md](component-color-picker.md) | ColorPicker | HSV square + hue slider, hex/rgb/hsl/oklch inputs, presets, alpha. |
+| [component-transfer.md](component-transfer.md) | Transfer (dual list) | Permission/tag editor pattern. When NOT to use (Multi-Select instead). |
+| [component-spin.md](component-spin.md) | Spin (Spinner) | Indeterminate loading. Distinct from Skeleton/Progress. Delay to avoid flash, reduced motion. |
+| [component-segmented.md](component-segmented.md) | Segmented (toggle button group) | iOS-native pill, time/view filters, WAI-ARIA radiogroup pattern. |
+| [component-auto-complete.md](component-auto-complete.md) | AutoComplete | Free-text + suggestions. Distinct from Select. Korean IME composition handling. |
+| [component-mentions.md](component-mentions.md) | Mention (@-trigger) | Trigger char (@/#/:) opens picker, chip insertion. Storage formats, IME. |
+| [component-timeline.md](component-timeline.md) | Timeline | Sequential events: order tracking, activity feed, audit log. Status indicators. |
+| [component-tour.md](component-tour.md) | Tour (in-product overlay) | Step-by-step UI walkthrough. When NOT to use (most cases). |
+| [component-affix.md](component-affix.md) | Affix (sticky positioning) | When CSS `position: sticky` isn't enough. Container-scoped sticky. |
+| [component-float-button.md](component-float-button.md) | FloatButton (FAB) | Floating action button. Speed-dial menu, safe-area handling. |
+| [component-qr-code.md](component-qr-code.md) | QRCode | Encoding strings as QR. Error correction levels, center logo, color contrast. |
+| [component-splitter.md](component-splitter.md) | Splitter (resizable panel) | When CSS sticky isn't enough. IDE / 3-pane layouts. |
+| [component-anchor.md](component-anchor.md) | Anchor (scrollspy / TOC) | Side-rail nav for long-form content. Active section detection. |
+| [component-app-bar.md](component-app-bar.md) | AppBar (top app bar) | Persistent top header. iOS large-title variant, search overlay, sub-tabs. |
+| [component-layout.md](component-layout.md) | Layout (page chrome) | Header / Sidebar / Content / Footer slots. Responsive sider collapse. |
+| [component-input-otp.md](component-input-otp.md) | InputOTP (verification code) | Multi-cell digit input. Korean SMS verification flow, autocomplete=one-time-code. |
+| [component-watermark.md](component-watermark.md) | Watermark | Repeating overlay for sensitive content. Per-user trace, screenshot deterrent. |
+| [component-code.md](component-code.md) | Code (inline + block) | Monospace text + syntax highlighting + copy button. |
+| [component-css-baseline.md](component-css-baseline.md) | CssBaseline | Root global baseline for app shells. Box sizing, body typography, color-scheme, print, SSR, and reset ownership. |
+| [component-typography.md](component-typography.md) | Typography (text primitive) | Variant-driven text. When NOT to use (Tailwind utility classes are usually clearer). |
+| [component-badge.md](component-badge.md) | Badge | Standalone label + indicator dual modes. Variants (default/secondary/destructive/outline), count + dot indicator on parent. |
+| [component-dropdown.md](component-dropdown.md) | Dropdown / DropdownMenu | Triggered overlay menu of actions. WAI-ARIA Menu pattern, sub-menus, checkbox / radio items, shortcuts. |
+| [component-context-menu.md](component-context-menu.md) | ContextMenu | Right-click / long-press triggered menu. Same WAI-ARIA Menu pattern as Dropdown. |
+| [component-config-provider.md](component-config-provider.md) | ConfigProvider | App-level design-system configuration boundary. Theme, locale, direction, portals, CSP, static APIs, and component defaults. |
+| [component-hover-card.md](component-hover-card.md) | HoverCard | Hover-triggered floating preview. Distinct from Tooltip + Popover; profile previews, link previews. |
+| [component-sheet.md](component-sheet.md) | Sheet | Side-anchored modal panel. Mobile-first detents, side variants (top/right/bottom/left). |
+| [component-command.md](component-command.md) | Command / CommandPalette | cmdk-based searchable command palette. Cmd+K pattern, fuzzy match, async results. |
+| [component-sidebar.md](component-sidebar.md) | Sidebar | Persistent collapsible navigation panel. Icon-only mode, mobile offcanvas, multi-level menu. |
+| [component-navigation-menu.md](component-navigation-menu.md) | NavigationMenu | Top horizontal nav with mega-menu panels. Marketing site / SaaS header pattern. |
+| [component-menubar.md](component-menubar.md) | Menubar | Persistent menu bar (File / Edit / View). Desktop-style web apps; hover-roving between menus. |
+| [component-aspect-ratio.md](component-aspect-ratio.md) | AspectRatio | Lock child to specific aspect ratio. Image, video, card thumbnail wrapper. |
+| [component-collapsible.md](component-collapsible.md) | Collapsible | Single expandable section primitive. Base for Accordion; FAQ, "Show more" patterns. |
+| [component-toggle.md](component-toggle.md) | Toggle / ToggleGroup | Two-state pressable button. Toolbar formatting, mutually-exclusive (single) or independent (multiple) groups. |
+| [component-scroll-area.md](component-scroll-area.md) | ScrollArea | Custom-styled scrollbar. Cross-platform consistency; visibility modes (auto/always/scroll/hover). |
+| [component-banner.md](component-banner.md) | Banner | Persistent in-page strip (system status, trial, cookie consent). Distinct from Alert + Toast. |
+| [component-kbd.md](component-kbd.md) | Kbd | Keyboard shortcut display. Platform-aware Mac/Win symbols, used in tooltips + menus. |
+| [component-separator.md](component-separator.md) | Separator | Horizontal / vertical divider. Decorative vs semantic; aliased as Divider in some libs. |
+| [component-alert-dialog.md](component-alert-dialog.md) | AlertDialog | Modal confirmation for destructive actions. Distinct from Modal; default focus on Cancel; `role="alertdialog"`. |
+| [component-bottom-navigation.md](component-bottom-navigation.md) | BottomNavigation | Mobile primary nav (3-5 tabs). iOS / Android / Material 3 conventions; safe-area handling. |
+| [component-chart.md](component-chart.md) | Chart | Recharts wrapper with theming + a11y. Korean stock convention (red=up); engine-agnostic chart-type table. |
+| [component-combobox.md](component-combobox.md) | Combobox | Searchable select. WAI-ARIA combobox pattern; Korean IME composition handling; multi-select + creatable variants. |
+| [component-field.md](component-field.md) | Field family | Form-field wrapper (Field / FieldLabel / FieldDescription / FieldError / FieldGroup / FieldSet / FieldLegend). |
+| [component-item.md](component-item.md) | Item family | List-item primitive (Item / ItemMedia / ItemContent / ItemTitle / ItemDescription / ItemActions). |
+| [component-link.md](component-link.md) | Link | Text link primitive. Link vs Button decision; external indicator; underline policies; Korean conventions. |
+| [component-paper.md](component-paper.md) | Paper | MUI surface primitive — elevation + outlined variants. Building block for Card, Modal, Drawer. |
+| [component-spinner.md](component-spinner.md) | Spinner | Indeterminate loading indicator. Spinner vs Progress vs Skeleton; size scale; reduced-motion. |
+| [component-empty.md](component-empty.md) | Empty | Inline "no data" primitive. Distinct from EmptyState (full-page custom KR-aware). |
+| [component-masonry.md](component-masonry.md) | Masonry | Pinterest-style staggered grid. CSS multicolumn vs JS measurement trade-offs; a11y reading order. |
+| [component-icon.md](component-icon.md) | Icon | Base primitive for rendering icons; size scale, currentColor theming, decorative vs meaningful. |
+| [component-icon-button.md](component-icon-button.md) | IconButton | Icon-only button. Variants (ghost/outline/filled/tonal), sizes, mandatory aria-label. |
+| [component-checkbox.md](component-checkbox.md) | Checkbox | Form selection control. Indeterminate state, "select all" pattern, Korean marketing-consent rule. |
+| [component-radio.md](component-radio.md) | Radio + RadioGroup | Mutually exclusive choice control. Radio vs Select decision; KR payment-method picker example. |
+| [component-label.md](component-label.md) | Label | Form-control label primitive. htmlFor linking, required/optional indicators, KR conventions. |
+| [component-box.md](component-box.md) | Box | Most generic styled `<div>` primitive. System-prop access; when to use vs Stack/Grid/Flex. |
+| [component-flex.md](component-flex.md) | Flex | flex layout primitive. Direction, gap, align, justify, wrap; common patterns. |
+| [component-grid.md](component-grid.md) | Grid | 2D grid layout. Ant Row+Col / MUI v2 / modern CSS Grid wrapper. |
+| [component-list.md](component-list.md) | List | Semantic + styled wrapper around Item rows. Pagination, infinite scroll, virtualization, empty state. |
+| [component-menu.md](component-menu.md) | Menu | Structured navigation menu (Ant style). Distinct from DropdownMenu / NavigationMenu / Sidebar. |
+| [component-message.md](component-message.md) | Message | Top thin pill notification (Ant). Imperative API; distinct from Toast / Notification. |
+| [component-notification.md](component-notification.md) | Notification | Richer corner card notification. Title + description + actions; placement variants. |
+| [component-space.md](component-space.md) | Space | Tiny utility for inline gap. Direction, size, wrap, split element-between-children. |
+| [component-button-group.md](component-button-group.md) | ButtonGroup | Visually-unified action button cluster. Distinct from ToggleGroup / Segmented. |
+| [component-speed-dial.md](component-speed-dial.md) | SpeedDial | FAB that expands into 2-5 secondary action FABs. Mobile compose pattern. |
+| [component-time-picker.md](component-time-picker.md) | TimePicker | Hour/minute/second picker. 24- vs 12-hour, step granularity, KR conventions, range variant. |
+| [component-tree-select.md](component-tree-select.md) | TreeSelect | Dropdown with hierarchical tree picker. Distinct from Cascader (columns) / Tree (full-page). |
+| [component-backdrop.md](component-backdrop.md) | Backdrop | Semi-opaque scrim overlay. Used internally by Modal/Drawer/Sheet; standalone for full-page loading. |
+| [component-switch.md](component-switch.md) | Switch | iOS-style toggle for binary on/off settings. Distinct from Checkbox (form). |
+| [component-tag.md](component-tag.md) | Tag | Closeable label / chip; filter chips, multi-select selected items. |
+| [component-snackbar.md](component-snackbar.md) | Snackbar | Material's bottom-anchored Toast variant; brief result + optional Undo. |
+| [component-sonner.md](component-sonner.md) | Sonner | Modern shadcn toast library; stacking depth, promise wrapper, rich actions. |
+| [component-textarea.md](component-textarea.md) | Textarea | Multi-line text input. Korean IME composition handling, character counter. |
+| [component-textarea-autosize.md](component-textarea-autosize.md) | TextareaAutosize | Textarea that grows with content; CSS field-sizing + JS measurement fallback. |
+| [component-popconfirm.md](component-popconfirm.md) | Popconfirm | Inline confirmation popover; lightweight alternative to AlertDialog. |
+| [component-popper.md](component-popper.md) | Popper | Low-level positioning primitive. Used internally by Tooltip / Popover / Menu. |
+| [component-swipeable-drawer.md](component-swipeable-drawer.md) | SwipeableDrawer | Drawer with swipe-to-open / swipe-to-close gestures; mobile-first. |
+| [component-resizable.md](component-resizable.md) | Resizable | IDE-style resizable panel groups (horizontal + vertical); layout persistence. |
+| [component-image-list.md](component-image-list.md) | ImageList | Uniform-grid photo display. Distinct from Masonry (varied) and Grid (general). |
+| [component-back-top.md](component-back-top.md) | BackTop | Floating "scroll to top" button after threshold; reduced-motion aware. |
+| [component-click-away-listener.md](component-click-away-listener.md) | ClickAwayListener | Outside-click callback utility. Used internally by overlays. |
+| [component-toolbar.md](component-toolbar.md) | Toolbar | Horizontal action container; app bar / editor / dialog footer. `role="toolbar"`. |
+| [component-step.md](component-step.md) | Step | Single step sub-component within a Steps / Stepper flow. |
+| [component-zoom.md](component-zoom.md) | Zoom | Transition primitive (scale + fade). Sibling to Fade / Slide / Grow. |
+| [component-speed-dial-action.md](component-speed-dial-action.md) | SpeedDialAction | Single action item inside a SpeedDial; child component spec. |
+| [component-slide.md](component-slide.md) | Slide | Direction-based slide-in/out transition. Used internally by Drawer / Sheet / Snackbar. |
+| [component-auto-complete.md](component-auto-complete.md) | AutoComplete | Free-text + suggestions input. (Canonical name; sibling of Combobox.) |
+| [component-mentions.md](component-mentions.md) | Mentions / Mention | @-trigger picker for inline chips / tagging. |
+
+### Documentation components
+
+| File | Component | Demonstrates |
+| --- | --- | --- |
+| [component-callout.md](component-callout.md) | Callout (doc info/warning/note) | Distinct from Alert. note/tip/info/warning/danger/success types, Korean header conventions. |
+| [component-blockquote.md](component-blockquote.md) | Blockquote | Attributed quotations. Italic Latin / weight-shift Korean. |
+| [component-doc-page.md](component-doc-page.md) | DocPage (doc-site layout) | Header + sidebar + body + right TOC + footer. Distinct from product app Layout. |
+| [component-email-layout.md](component-email-layout.md) | EmailLayout | Table-based responsive email scaffolding. Bulletproof button, preheader, Korean spam law. |
+| [component-descriptions.md](component-descriptions.md) | Descriptions (key-value list) | Static read-only multi-row labels + values. dl semantics, Korean labels. |
+| [component-hero-block.md](component-hero-block.md) | HeroBlock (landing hero) | Headline + sub-headline + CTA + visual. 4 layouts, video/image variants, Korean conventions. |
+| [component-feature-grid.md](component-feature-grid.md) | FeatureGrid | 3-up/4-up feature cells. Icon + title + description per cell. Mobile stacks. |
+| [component-testimonial-carousel.md](component-testimonial-carousel.md) | TestimonialCarousel | Customer quotes. single-large / 3-up-grid / auto-scroll variants. Don't fabricate. |
+| [component-pricing-cards.md](component-pricing-cards.md) | PricingCards | 2–4 pricing tiers with anchoring, monthly/annual toggle, Korean subscription disclosure. |
+
+### Custom components (Korean fintech / commerce)
+
+| File | Component | Demonstrates |
+| --- | --- | --- |
+| [component-amount-input.md](component-amount-input.md) | AmountInput | KRW-aware currency input. Auto-format, paste handling, IME composition, quick chips, max-balance affordance. |
+| [component-address-input.md](component-address-input.md) | AddressInput | Korean address with Daum Postcode lookup. Two-line structure (zip + main + detail), 도로명/지번 toggle. |
+| [component-biometric-gate.md](component-biometric-gate.md) | BiometricGate | Face ID / Touch ID / fingerprint gate for fintech app launch + sensitive flows. OS API integration, fallback to PIN. |
+| [component-payment-method-selector.md](component-payment-method-selector.md) | PaymentMethodSelector | Korean payment method selector. Audience-driven ordering (consumer vs B2B), saved cards, amount-based filtering. |
+| [component-payment-brand-button.md](component-payment-brand-button.md) | PaymentBrandButton | Brand-styled CTA for KakaoPay / NaverPay / Toss / Apple Pay / Samsung Pay. Official asset compliance. |
+| [component-category-picker.md](component-category-picker.md) | CategoryPicker | 가계부 emoji-first category selector. Horizontal pills / grid / list, custom category creation. |
+| [component-transaction-list-item.md](component-transaction-list-item.md) | TransactionListItem | Most-rendered row in 가계부 / banking. Tabular numerals, amount color semantics, status badges. |
+| [component-account-card.md](component-account-card.md) | AccountCard | Bank account card. Branded logo + masked number + balance. compact/default/hero variants. |
+| [component-stock-chart.md](component-stock-chart.md) | StockChart | Korean inverted color convention (red=up, blue=down). Candle/line/area, crosshair, performance with canvas. |
+| [component-krw-amount.md](component-krw-amount.md) | KRWAmount (display-only) | Display counterpart to AmountInput. Comma vs Korean number format, sign, hero variant. |
+| [component-payment-receipt.md](component-payment-receipt.md) | PaymentReceipt | Korean receipt convention with dotted dividers, structured price breakdown, share/reorder actions. |
+| [component-pass-auth.md](component-pass-auth.md) | PASSAuth (Korean 본인인증) | Wraps PASS app / NICE / KCB identity verification. Required for high-value Korean fintech transactions. |
+| [component-otp-countdown.md](component-otp-countdown.md) | OTPCountdown | SMS code expiration timer + resend cooldown. Pairs with InputOTP. |
+
+### Motion components
+
+| File | Component | Demonstrates |
+| --- | --- | --- |
+| [component-loading-sequence.md](component-loading-sequence.md) | LoadingSequence | Splash + biometric gate + first-screen reveal coordination for cold launch. Korean fintech default. |
+| [component-page-transition.md](component-page-transition.md) | PageTransition | Route-level wrapper (fade / slide / hero variants). Framer Motion + View Transitions API implementations. |
+| [component-lottie-player.md](component-lottie-player.md) | LottiePlayer | After Effects animation embed with lazy-load, offscreen pause, poster fallback, reduced-motion handling. |
+| [component-scroll-reveal.md](component-scroll-reveal.md) | ScrollReveal | Viewport-triggered animation primitive (fade-up / fade-in-blur / scale-in) with stagger and `once` semantics. |
+
+### Illustration components
+
+| File | Component | Demonstrates |
+| --- | --- | --- |
+| [component-empty-state.md](component-empty-state.md) | EmptyState | Layout for "no data yet" surfaces. Illustration registry, voice rules, KR 해요체 default. |
+| [component-illustration.md](component-illustration.md) | Illustration | Themeable SVG / Lottie display backed by a typesafe illustration registry. |
+
+### Print specs
+
+| File | Piece | Demonstrates |
+| --- | --- | --- |
+| [print-business-card-spec.md](print-business-card-spec.md) | Korean 명함 (premium tier) | Korean fintech business card spec: 90×50mm, 350gsm uncoated, soft-touch + spot UV, Pretendard, Pantone + CMYK, file delivery checklist. |
+| [print-packaging-spec.md](print-packaging-spec.md) | Folding carton (cosmetics) | Korean cosmetics carton spec: dieline, KFDA regulatory content (전성분 / 사용기한 / 분리배출 표시), FSC + soy ink, press proof. |
+
+### Video components
+
+| File | Component | Demonstrates |
+| --- | --- | --- |
+| [component-video-player.md](component-video-player.md) | VideoPlayer | Accessible HTML5 video with multi-language captions, speed control, transcript link, reduced-motion handling. |
+| [component-video-hero.md](component-video-hero.md) | VideoHero | Above-the-fold autoplay loop with poster fallback, art-direction (mobile vs desktop video), reduced-motion + slow-connection skip. |
+
+### Game UI components
+
+| File | Component | Demonstrates |
+| --- | --- | --- |
+| [component-game-hud.md](component-game-hud.md) | GameHUD | Composable HUD shell with anchored slots, customization, color-blind / contrast modes, UI scale, cross-platform input. |
+| [component-game-menu.md](component-game-menu.md) | GameMenu | Composable menu shell — main / pause / settings / inventory / store. Focus management, controller / d-pad nav, button-prompt swapping per platform, modal stacking. |
+
+### Conversational UI components
+
+| File | Component | Demonstrates |
+| --- | --- | --- |
+| [component-chat-interface.md](component-chat-interface.md) | ChatInterface | Reusable chat shell for chatbot / AI / live agent. Markdown + code block rendering, streaming, suggested chips, typing indicator, attachments, Korean IME + 해요체 defaults. |
+| [component-voice-input.md](component-voice-input.md) | VoiceInput | Push-to-talk + transcript voice input. Web Speech / Clova / Whisper backends, listening visualization, permission handling, Korean STT defaults. |
+
+### Spatial / AR / VR components
+
+| File | Component | Demonstrates |
+| --- | --- | --- |
+| [component-spatial-panel.md](component-spatial-panel.md) | SpatialPanel | Floating 2D-in-3D panel for VR / AR / spatial computing. Anchoring (world / wrist / hand / head), distance / scale / billboarding, comfort positioning, hand + gaze input, depth occlusion. |
+| [component-spatial-locomotion.md](component-spatial-locomotion.md) | SpatialLocomotion | VR locomotion controller with teleport, smooth, snap-turn, room-scale modes; comfort vignette, fade transitions, comfort-default presets. |
+
+### Documentation worked examples
+
+| File | Skill | Demonstrates |
+| --- | --- | --- |
+| [doc-tutorial-example.md](doc-tutorial-example.md) | `document-author` (tutorial) | Canonical tutorial format — time + audience, "what you'll build", numbered steps with confirmation, "what's next". |
+| [doc-how-to-example.md](doc-how-to-example.md) | `document-author` (how-to) | Problem-driven format — TL;DR + steps + variations + pitfalls. Korean localization context. |
+| [doc-explanation-example.md](doc-explanation-example.md) | `document-author` (explanation) | Discursive format — problem / alternatives / decision / tradeoffs. W3C DTCG choice rationale. |
+| [slide-deck-example.md](slide-deck-example.md) | `slide-deck-author` (talk) | 17-slide talk deck outline. Message-led titles, one visual per slide, speaker notes, Korean conference voice. |
+| [report-example.md](report-example.md) | `ux-audit` | UX audit report — TL;DR pyramid, severity-aggregated findings, citations, code diffs, "things that work well". |
+| [email-transactional-example.md](email-transactional-example.md) | `document-author` (email) | Korean fintech transactional email — preheader, receipt structure, bulletproof button, sender info per 정보통신망법. |
+
+### End-to-end deliverables
+
+| File | Skill | Demonstrates |
+| --- | --- | --- |
+| [dogfood-korean-fintech-system.md](dogfood-korean-fintech-system.md) | `design-system-builder` | Full design system bootstrap for a Korean fintech mobile app. Token cascade + foundations + component baseline + starter set + handoff. |
+
+## How to use these
+
+These are **reference shapes**, not templates to copy verbatim. When invoking a skill:
+
+1. Note the structure (which sections appear, in what order).
+2. Note the specificity (every claim has a number or a citation).
+3. Note the tradeoffs section (every choice has a "why this and not the obvious alternative").
+
+Adapt to your input.

package/examples/cases/dogfood-v4-korean-hr-onboarding.md

@@ -0,0 +1,356 @@
+# Dogfood v4 — Korean B2B SaaS HR onboarding
+
+End-to-end test of the design-ai v4.6 corpus on a realistic Korean B2B scenario. This is a *practical* run — every section invokes the skill / knowledge file it would in production, and the output is what an adopter would receive.
+
+## Brief
+
+> "팀온보딩" — Korean B2B SaaS HR app for small/mid companies (10–500 employees). The product handles new-employee onboarding: document collection (계약서, 신분증, 통장 사본), e-signature, IT account provisioning, first-week checklist. Audience: HR managers (primary), new hires (secondary). Brand voice: calm, professional, trust-driven (handling sensitive personal data). Primary brand color: muted teal `#0D9488`. Stack: shadcn-ui + Tailwind v4 + React 18. Locale: Korean primary; English UI for international hires (toggle). Density: comfortable. Light + dark.
+
+Skills to invoke: `design-system-builder` → `color-palette` → `component-spec-writer` → `ux-audit`.
+
+## Step 1 — Bootstrap tokens (via `design-system-builder`)
+
+### Color tokens (cite [`knowledge/colors/color-theory.md`](../../knowledge/colors/color-theory.md))
+
+Brand seed: `#0D9488` (teal-600). Generated full ramp:
+
+```yaml
+# brand
+brand-50:  #F0FDFA
+brand-100: #CCFBF1
+brand-200: #99F6E4
+brand-300: #5EEAD4
+brand-400: #2DD4BF
+brand-500: #14B8A6
+brand-600: #0D9488     # primary
+brand-700: #0F766E
+brand-800: #115E59
+brand-900: #134E4A
+brand-950: #042F2E
+
+# neutral (cool-gray to pair with teal)
+neutral-50:  #F9FAFB
+neutral-100: #F3F4F6
+neutral-200: #E5E7EB
+neutral-300: #D1D5DB
+neutral-400: #9CA3AF
+neutral-500: #6B7280
+neutral-600: #4B5563
+neutral-700: #374151
+neutral-800: #1F2937
+neutral-900: #111827
+neutral-950: #030712
+
+# semantic — sensitive data context
+success:  #10B981
+warning:  #F59E0B
+error:    #EF4444
+info:     #3B82F6
+```
+
+### Semantic aliases (cite [`knowledge/colors/color-theory.md`](../../knowledge/colors/color-theory.md))
+
+```yaml
+# light
+--color-bg-default:        white
+--color-bg-subtle:         neutral-50
+--color-bg-muted:          neutral-100
+--color-fg-default:        neutral-900
+--color-fg-muted:          neutral-600
+--color-fg-subtle:         neutral-400
+--color-fg-on-brand:       white
+--color-border-default:    neutral-200
+--color-border-strong:     neutral-300
+--color-brand-bg:          brand-600
+--color-brand-bg-hover:    brand-700
+--color-brand-fg:          white
+--color-error-bg:          error
+--color-error-fg:          white
+
+# dark — invert with care; brand stays at -500 for legibility on dark
+--color-bg-default:        neutral-900
+--color-bg-subtle:         neutral-800
+--color-fg-default:        neutral-50
+--color-fg-muted:          neutral-400
+--color-brand-bg:          brand-500   # NOT brand-600 in dark
+```
+
+Contrast verified per [`knowledge/a11y/contrast.md`](../../knowledge/a11y/contrast.md):
+- `fg-default` on `bg-default`: 17.79:1 (AAA ✓)
+- `brand-fg` on `brand-bg`: 4.94:1 (AA large ✓; AA normal at -700: 6.96:1 ✓)
+- `error-fg` on `error-bg`: 4.83:1 (AA large ✓)
+
+### Typography (cite [`knowledge/i18n/korean-typography.md`](../../knowledge/i18n/korean-typography.md))
+
+```css
+font-family-sans: "Pretendard Variable", Pretendard, -apple-system, BlinkMacSystemFont,
+                  system-ui, Roboto, "Helvetica Neue", "Segoe UI", "Apple SD Gothic Neo",
+                  "Noto Sans KR", "Malgun Gothic", sans-serif;
+font-family-mono: "JetBrains Mono", "D2Coding", monospace;
+```
+
+Type scale (base 14 product UI; +10% line-height for Korean per knowledge file):
+
+| Variant | Size | Weight | Line-height (KR-bumped) |
+| --- | --- | --- | --- |
+| display | 32 | 700 | 1.32 |
+| heading-lg | 24 | 600 | 1.42 |
+| heading-md | 20 | 600 | 1.5 |
+| heading-sm | 16 | 600 | 1.6 |
+| body-lg | 16 | 400 | 1.65 |
+| body | 14 | 400 | 1.65 |
+| caption | 12 | 400 | 1.55 |
+
+### Spacing / radius / elevation
+
+```yaml
+space: 4 8 12 16 20 24 32 40 48 64    # 9 stops, 4-base
+radius: 0 4 6 8 12 16 999             # last is "pill"
+elevation: 0 sm md lg xl              # 5 stops; subtle for B2B (less playful)
+```
+
+## Step 2 — Spec a component (via `component-spec-writer`)
+
+The HR onboarding flow's first screen is "신규 입사자 정보 입력". Five fields: 이름 / 사번 / 입사일 / 부서 / 이메일. Three of these are FormControls. Let me spec the **EmployeeInfoForm** composition.
+
+This exercises the v4.5 polished `form-control.md` spec end-to-end.
+
+### EmployeeInfoForm — composition spec
+
+```tsx
+const actionRowSx = { mt: 3 };
+
+<form onSubmit={handleSubmit}>
+  <FormControl error={!!errors.name} required disabled={isSubmitting} fullWidth>
+    <FormLabel htmlFor="name">이름</FormLabel>
+    <OutlinedInput
+      id="name"
+      value={values.name}
+      onChange={handleChange}
+      aria-invalid={!!errors.name}
+      aria-describedby={errors.name ? "name-error" : "name-help"}
+    />
+    <FormHelperText id={errors.name ? "name-error" : "name-help"}>
+      {errors.name ?? "주민등록상 이름과 동일하게 입력해 주세요"}
+    </FormHelperText>
+  </FormControl>
+
+  <FormControl error={!!errors.employeeId} required fullWidth>
+    <FormLabel htmlFor="employeeId">사번</FormLabel>
+    <OutlinedInput
+      id="employeeId"
+      value={values.employeeId}
+      onChange={handleChange}
+      placeholder="2026-001"
+      aria-invalid={!!errors.employeeId}
+    />
+    <FormHelperText>인사 담당자에게 받은 사번을 입력해 주세요</FormHelperText>
+  </FormControl>
+
+  <FormControl required fullWidth>
+    <FormLabel htmlFor="hireDate">입사일</FormLabel>
+    <DatePicker id="hireDate" value={values.hireDate} onChange={handleChange} />
+  </FormControl>
+
+  <FormControl required fullWidth>
+    <FormLabel htmlFor="department">부서</FormLabel>
+    <Select id="department" value={values.department} onChange={handleChange}>
+      <MenuItem value="engineering">개발</MenuItem>
+      <MenuItem value="design">디자인</MenuItem>
+      <MenuItem value="product">기획</MenuItem>
+      <MenuItem value="hr">인사</MenuItem>
+    </Select>
+  </FormControl>
+
+  <FormControl error={!!errors.email} required fullWidth>
+    <FormLabel htmlFor="email">회사 이메일</FormLabel>
+    <OutlinedInput
+      id="email"
+      type="email"
+      value={values.email}
+      onChange={handleChange}
+      placeholder="hong@team-onboarding.kr"
+    />
+    <FormHelperText>{errors.email ?? "회사 도메인 이메일을 입력해 주세요"}</FormHelperText>
+  </FormControl>
+
+  <Stack direction="row" justifyContent="flex-end" gap={1} sx={actionRowSx}>
+    <Button variant="outlined" onClick={handleCancel}>취소</Button>
+    <LoadingButton type="submit" variant="contained" loading={isSubmitting}>
+      다음 단계
+    </LoadingButton>
+  </Stack>
+</form>
+```
+
+### Korean text density adjustments (cite [`knowledge/typography/korean-typography.md`](../../knowledge/i18n/korean-typography.md))
+
+- Field labels keep short (1-3 words). "이메일" not "이메일 주소를 입력해 주세요" — that goes in helper text.
+- Helper text uses 해요체 ("입력해 주세요"). For legal forms (e.g., contract page), switch to 합쇼체 ("입력하시기 바랍니다") per [`knowledge/conversational/korean-voice-conventions.md`](../../knowledge/conversational/korean-voice-conventions.md).
+- Min-height on FormControl rows: 56px (vs 48px Latin default) — Hangul reads taller per the knowledge file.
+
+### Tokens consumed (per [`examples/component-form-control.md`](../component-form-control.md))
+
+```
+--color-fg-default
+--color-fg-error
+--color-fg-primary
+--color-bg-default
+--color-border-default
+--color-border-strong
+--space-md          /* horizontal padding */
+--space-sm          /* helper-text margin-top */
+--space-lg          /* between FormControls */
+--font-size-body    /* 14px */
+--line-height-body  /* 1.65 KR-bumped */
+--radius-md
+```
+
+## Step 3 — Spec the document upload (uses Card + Dialog families)
+
+Document collection screen needs a confirmation dialog before upload. Exercises v4.5's polished `dialog-title.md` / `dialog-content.md` / `dialog-actions.md`:
+
+```tsx
+const documentCardSx = { maxWidth: 480 };
+const secondaryCopySx = { mt: 1 };
+const documentListSx = { mt: 2 };
+
+<Card sx={documentCardSx}>
+  <CardContent>
+    <Typography variant="h6">필수 서류 업로드</Typography>
+    <Typography variant="body2" color="text.secondary" sx={secondaryCopySx}>
+      계약서 · 신분증 · 통장 사본
+    </Typography>
+
+    <List sx={documentListSx}>
+      {documents.map((doc) => (
+        <ListItem
+          key={doc.id}
+          secondaryAction={
+            doc.uploaded ? (
+              <CheckIcon color="success" aria-label="업로드 완료" />
+            ) : (
+              <Button size="small" onClick={() => handleUpload(doc.id)}>
+                업로드
+              </Button>
+            )
+          }
+        >
+          <ListItemText primary={doc.name} secondary={doc.description} />
+        </ListItem>
+      ))}
+    </List>
+  </CardContent>
+  <CardActions>
+    <Button size="small" onClick={handleSkipForNow}>나중에 하기</Button>
+    <Button size="small" variant="contained" onClick={handleSubmitAll}>
+      제출하기
+    </Button>
+  </CardActions>
+</Card>
+
+{/* Confirmation dialog — uses v4.5 family-completed primitives */}
+<Dialog
+  open={confirmOpen}
+  onClose={() => setConfirmOpen(false)}
+  aria-labelledby="confirm-title"
+  aria-describedby="confirm-desc"
+  fullWidth
+  maxWidth="sm"
+>
+  <DialogTitle id="confirm-title">서류를 제출할까요?</DialogTitle>
+  <DialogContent>
+    <DialogContentText id="confirm-desc">
+      제출 후에는 인사팀 검토를 거쳐 변경이 어려워요. 모든 정보가 정확한지 확인해 주세요.
+    </DialogContentText>
+  </DialogContent>
+  <DialogActions>
+    <Button onClick={() => setConfirmOpen(false)}>다시 확인</Button>
+    <LoadingButton
+      onClick={handleConfirmSubmit}
+      loading={isSubmitting}
+      variant="contained"
+      autoFocus
+    >
+      네, 제출할게요
+    </LoadingButton>
+  </DialogActions>
+</Dialog>
+```
+
+Citations:
+- [`examples/component-card-content.md`](../component-card-content.md) — Card body region
+- [`examples/component-card-actions.md`](../component-card-actions.md) — Card action row (left-aligned)
+- [`examples/component-list-item.md`](../component-list-item.md) — ListItem with secondaryAction
+- [`examples/component-dialog-title.md`](../component-dialog-title.md) — required `id` for `aria-labelledby`
+- [`examples/component-dialog-content.md`](../component-dialog-content.md) — `DialogContentText` with `id` for `aria-describedby`
+- [`examples/component-dialog-actions.md`](../component-dialog-actions.md) — Cancel · Primary order (Korean / Western convention)
+
+## Step 4 — UX audit (via `ux-audit` skill)
+
+Quick audit of the bootstrap output:
+
+| Issue | Severity | Resolution |
+| --- | --- | --- |
+| Field labels in 합쇼체 vs helper-text in 해요체 — register mismatch | MEDIUM | Standardized on 해요체 throughout (matches B2B onboarding tone, less stiff than 합쇼체) |
+| `email` field has placeholder + helper text + error message → 3 strings competing | MEDIUM | Removed placeholder; rely on helper text. Placeholder disappears on focus, accessibility issue |
+| No password field in initial draft | INFO | Out of scope for this screen; password set on email-verify step |
+| `LoadingButton` not in our spec'd components | HIGH | Need spec for it OR reference MUI directly. Action: add to roadmap |
+| Department `Select` with 4 options — should be radio? | LOW | 4 is borderline. Select OK on mobile (saves vertical space). Radio better on desktop. Acceptable |
+| No "save draft" before "다음 단계" — risky if user navigates away | HIGH | Add auto-save on blur per [`knowledge/patterns/form-design.md`](../../knowledge/patterns/form-design.md) |
+
+### Don't / avoid
+
+- Don't use placeholder text as the only field instruction; it disappears on focus and weakens screen-reader support.
+- Avoid hiding document-upload errors behind a generic toast. Inline status plus `aria-describedby` keeps the HR manager's recovery path visible.
+
+### Conversational support notes
+
+This screen can hand off to an HR assistant chat without changing the form contract. Primary intent examples: `upload_document`, `change_hire_date`, and `ask_required_documents`. Example utterance: "신분증은 어떤 파일 형식으로 올려야 하나요?" Turn-taking rule: answer the current question first, then offer one next action such as "파일 선택" or "인사팀에 문의". Fallback repair: when the assistant cannot identify the document type, ask one clarifying question and keep the user in the current step.
+
+### QA and PR review notes
+
+- Design-system QA: token checks cover color/spacing/type names, accessibility checks cover `aria-invalid` and focus order, and visual regression should snapshot light/dark EmployeeInfoForm plus mobile document upload in Storybook.
+- Figma token sync: Figma variables should map to the semantic token aliases above, with `--color-brand-bg` and typography tokens treated as the source of truth for export/import reviews.
+- Design PR review: changed files would include the form composition, document upload card, and dialog wiring. Impact is highest on HR manager onboarding completion and secondary on new-hire document submission. Validation should include keyboard-only flow, screen-reader labels, and responsive viewport checks.
+
+## Step 5 — Stability review dogfood
+
+Ran `/stability-review` mid-session to test:
+
+```bash
+$ python3 tools/audit/stability-review.py --today 2026-12
+```
+
+Output:
+- 90 stable, 0 beta/experimental/deprecated.
+- 1 file without metadata: `knowledge/COVERAGE.md` (generated artifact — false positive).
+- No promotion candidates yet (all v4.x knowledge is stable from day one).
+- 0 stale stable files at 7-month projection.
+
+**Finding**: `knowledge/COVERAGE.md` showing as "missing stability" is noise. It's a generated index, not a knowledge document. Either:
+1. Add `stability: stable` to the generator (signals "as fresh as the last regen").
+2. Skip generated files in `stability-review.py`.
+
+## Step 6 — What v4 enabled vs v3
+
+| Capability | v3 dogfood (fintech) | v4 dogfood (HR) |
+| --- | --- | --- |
+| Form-Control composition spec | I had to invent | `component-form-control.md` exists; cited directly |
+| Dialog-Title with `aria-labelledby` | I had to research | `component-dialog-title.md` makes the contract explicit |
+| ListItem with secondaryAction | I conflated with ListItemButton | `component-list-item.md` clarifies the boundary |
+| Card-Actions left-align convention | Unclear | `component-card-actions.md` documents it + cites Korean B2C precedent |
+| Korean B2B tone (해요체 vs 합쇼체) | General KR knowledge | Specific to onboarding context — could use a knowledge file |
+| Stability review | Manual | `/stability-review` automates |
+
+## Output — what I'd hand to a developer
+
+The above sections constitute the initial spec hand-off. Adopter receives:
+
+1. Token JSON (color / typography / spacing / radius / elevation / motion).
+2. EmployeeInfoForm composition spec (TypeScript).
+3. Document upload card + confirmation dialog spec.
+4. UX audit findings (6 issues categorized by severity).
+5. Stability review report (no actions needed this quarter).
+
+Total elapsed: ~30 min reading + composing for a senior-designer-equivalent hand-off. v3 dogfood took ~50 min for similar scope.