oh-my-design-cli 1.6.0 → 1.6.2

package/web/references/voicetube/DESIGN.md

@@ -0,0 +1,227 @@
+---
+id: voicetube
+name: "VoiceTube"
+country: TW
+category: education
+homepage: "https://tw.voicetube.com"
+primary_color: "#7E3AAF"
+logo:
+  type: favicon
+  slug: "https://www.google.com/s2/favicons?domain=tw.voicetube.com&sz=256"
+verified: "2026-06-03"
+omd: "0.1"
+---
+
+# VoiceTube
+
+Asia's largest video-based English learning platform, blending immersive YouTube content with AI-powered study tools under a dramatic dark-purple brand identity.
+
+## 1. Visual Theme & Atmosphere
+
+VoiceTube presents a consistently dark, cinematic atmosphere built around a deep purple-to-near-black canvas. The body background is `#18131D` — a dark aubergine that evokes a premium streaming experience rather than a conventional classroom — while the navigation bar graduates from `#210040` to `#1D102B` as a horizontal gradient, anchoring every page in the brand's deepest signature hues. Primary call-to-action elements arrive as pill-shaped buttons bearing a vivid diagonal gradient from `#653AAF` to `#A73AAF`, injecting a pop of electric violet that reads immediately as the interactive signal layer. Secondary surfaces such as the sidebar and product grid use `#251633`, creating a subtle two-stop dark elevation system. The overall mood is energetic and night-mode-native: think streaming platform meets study app, where video thumbnail cards float on near-black panels, typography in soft white-gray (`#E3E3E3`) maintains clarity without harshness, and playful gradient accents ensure the interface never feels heavy or academic.
+
+## 2. Color Palette & Roles
+
+- **Brand Purple 400 (Primary):** `#7E3AAF` — interactive accents, badge fills, focused input borders
+- **Brand Purple 300 (Vibrant):** `#A73AAF` — gradient endpoint, hover highlights, accent text on dark
+- **Button Gradient Start:** `#653AAF` — primary CTA gradient origin (135.73°)
+- **Deep Purple 500:** `#210040` — navigation gradient start, deepest surface overlays
+- **Dark Aubergine 800 (Background):** `#18131D` — body canvas, default page background
+- **Surface 600:** `#251633` — sidebar background, secondary card surfaces
+- **Nav Gradient End:** `#1D102B` — navigation bar right edge
+- **Purple Tint 100:** `#E0D0EC` — light tag fill, subtle selected state
+- **White:** `#FFFFFF` — primary text on gradient buttons
+- **Gray 300 (Body Text):** `#E3E3E3` — body text on dark, outline button text and border
+- **Gray 400 (Secondary):** `#B4B4B4` — secondary labels, disabled state text
+- **Gray 500 (Muted):** `#9CA3AF` — placeholder text
+- **Error:** `#ED4F55` — danger borders, validation messages
+- **Success:** `#33991D` — correct answers, achievement indicators
+- **Link/Info:** `#4283E4` — hyperlink color, informational icons
+
+## 3. Typography Rules
+
+VoiceTube's global body font is a CJK-first stack: `-apple-system, BlinkMacSystemFont, PingFang TC, PingFang SC, Hiragino Sans, Hiragino Kaku Gothic ProN, Microsoft JhengHei, Microsoft YaHei, Meiryo, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif`. This stack ensures Mandarin and Japanese characters render optimally before falling back to Latin fonts. The base font weight is `400`, body text is set in `#E3E3E3` for comfortable contrast on dark backgrounds, and line-height defaults to `1.425` (the `vc-leading-base` token). The proprietary logomark typeface features 60° slanted stroke extensions that echo the play-button triangle — this angular DNA is brand-exclusive and not replicated in UI text. The type scale in use: `xs = 12px`, `sm = 14px`, `base/md = 16px`, `lg = 18px`, `xl = 20px`, `2xl = 24px`. Weight tokens span from `vc-font-light (300)` through `vc-font-normal (400)`, `vc-font-medium (500)`, `vc-font-semibold (600)`, `vc-font-bold (700)`, to `vc-font-black (900)`. Navigation labels and primary UI text use `500 (medium)`.
+
+## 4. Component Stylings
+
+### Primary CTA Button
+
+**Gradient Filled**
+- Background: `linear-gradient(135.73deg, #653AAF, #A73AAF 98.77%)`
+- Text: `#FFFFFF`
+- Radius: 9999px
+- Height: 40px
+- Padding: 0 20px
+- Font: 16px / 500
+
+### Outline Button
+
+**Ghost / Secondary**
+- Background: `transparent`
+- Text: `#E3E3E3`
+- Border: 1px solid `#E3E3E3`
+- Radius: 9999px
+- Height: 40px
+- Padding: 0 20px
+- Font: 16px / 500
+
+### Navigation Bar
+
+**Top Nav**
+- Background: `linear-gradient(to right, #210040, #1D102B)`
+- Text: `#E3E3E3`
+- Height: 64px
+
+### Sidebar Nav Item
+
+**Active / Hover**
+- Background: `rgba(126, 58, 175, 0.2)`
+- Text: `#E3E3E3`
+- Padding: 12px 8px
+- Font: 14px / 400
+- Radius: 0px
+
+### Tag / Badge Chip
+
+**Brand Tag**
+- Background: `#7E3AAF`
+- Text: `#E3E3E3`
+- Radius: 4px
+- Padding: 2.5px 12px
+- Font: 14px / 400
+
+### Text Input
+
+**Default State**
+- Background: `transparent`
+- Text: `#E3E3E3`
+- Border: 1px solid `#E3E3E3`
+- Radius: 4px
+
+**Focus / Hover**
+- Border: 1px solid `#7E3AAF`
+
+**Disabled**
+- Text: `#B4B4B4`
+
+**Error**
+- Border: 1px solid `#ED4F55`
+- Text: `#ED4F55`
+
+---
+**Verified:** 2026-06-03
+**Tier 1 sources:** https://tw.voicetube.com (homepage HTML + CSS `/_next/static/css/8c750a42d09ad582.css`); https://tw.voicetube.com/branding (brand page — structure + JS chunk `page-7cb732e6cbfefad2.js`); https://tw.voicetube.com/about (brand narrative)
+**Tier 2 sources:** getdesign.md/voicetube — NOT LISTED ("No designs found for 'voicetube'"). refero — no result found for VoiceTube.
+**Conflicts unresolved:** none
+
+## 5. Layout Principles
+
+VoiceTube uses a responsive two-column shell on desktop: a fixed 110px-wide sidebar navigation column paired with a fluid content area (`vc-grid-cols-[110px_1fr]`), which collapses to single-column on mobile (`lg:vc-grid-cols-1`). Content grids for video cards typically use 3–4 columns on large screens, scaling down through 2-column tablet to single-column mobile layouts. Horizontal container padding follows the Tailwind spacing scale (`p-4` = 16px, `p-5` = 20px, `p-6` = 24px). The overall max content width is not capped artificially narrow — VoiceTube leans into wide viewports for its video-first grid. Sticky positioning is used for the top navigation bar at `z-[800]`, ensuring it floats above all content as users scroll through dense video libraries.
+
+## 6. Depth & Elevation
+
+VoiceTube's elevation model is purely dark-stack-based — layers are distinguished by background darkness rather than box-shadows. The four tiers in practice: **L0** `#18131D` (body canvas), **L1** `#1D102B–#210040` (navigation, modal backdrops), **L2** `#251633` (sidebar panels, card surfaces), **L3** `#2B2B2B` (dark-500 floating elements, tooltips). Genuine `box-shadow` usage is sparse; focus states use a thin `0 0.1px 0 0 #7E3AAF` outline-shadow rather than a spread shadow, keeping the UI graphically flat. Modal/overlay z-indices follow a defined stack: content at 100, sticky nav at 800, modals at 1200–1299, toasts/notifications at 1500–1600.
+
+## 7. Do's and Don'ts
+
+### Do
+- Use the `linear-gradient(135.73deg, #653AAF, #A73AAF)` gradient as the primary CTA fill to maintain brand energy
+- Apply `#7E3AAF` for interactive focus rings, active link states, and selected filters
+- Use pill-shaped buttons (`border-radius: 9999px`) for all standalone CTA actions
+- Keep body backgrounds in the `#18131D` to `#251633` range for dark-mode consistency
+- Use `#E3E3E3` (gray-300) as the default text color on dark surfaces
+- Prefer the CJK-inclusive font stack for any Mandarin or Japanese content
+- Apply `ease-out` timing for all UI transitions at 150ms or 300ms
+
+### Don't
+- Don't use high-saturation colors from outside the purple / teal / orange product palette without clear context
+- Don't apply gradient buttons to destructive actions (delete, remove) — use plain `#ED4F55` borders instead
+- Don't use light backgrounds (`#FFFFFF`, `#F3F3F3`) as page canvas — VoiceTube is dark-mode-native
+- Don't mix border-radius: square corners would clash with the brand's pill-and-round language
+- Don't stack multiple box-shadows — elevation is communicated through dark tone layering, not shadow spreads
+- Don't reduce font weight below 400 for UI text at `14px` or smaller on dark surfaces
+
+## 8. Responsive Behavior
+
+VoiceTube's breakpoint system uses Tailwind's `md` (768px) and `lg` (1024px) prefixes extensively. The pattern `md:vc-h-9 md:vc-text-sm` on buttons demonstrates size reduction at tablet widths: button height drops from 40px to 36px and font from 16px to 14px. The sidebar collapses at `lg:vc-hidden`. Video grids shift from a multi-column layout to a vertically stacked, horizontally scrollable carousel on mobile. Hero section typography is set in viewport-relative units (`4.167vw` headline on desktop, `6.4vw` on mobile), ensuring the brand message fills the screen at every size. Padding contracts gracefully: `p-6` on desktop drops to `p-4` on mobile throughout content areas.
+
+## 9. Agent Prompt Guide
+
+When building VoiceTube-style UI:
+- Dark canvas: body background `#18131D`, sidebar `#251633`, nav `linear-gradient(to right, #210040, #1D102B)`
+- Primary button: `border-radius: 9999px`, `height: 40px`, `padding: 0 20px`, `background: linear-gradient(135.73deg, #653AAF, #A73AAF)`, `color: #FFFFFF`, `font-weight: 500`, `font-size: 16px`
+- Outline button: same shape, `background: transparent`, `border: 1px solid #E3E3E3`, `color: #E3E3E3`
+- Focus ring: `box-shadow: 0 0 0 1px #7E3AAF`
+- Error state: `border-color: #ED4F55`, `color: #ED4F55`
+- Disabled: `color: #B4B4B4`, `cursor: not-allowed`
+- Transitions: `transition-duration: 150ms`, `transition-timing-function: ease-out`
+- Font stack: `-apple-system, BlinkMacSystemFont, "PingFang TC", "PingFang SC", "Microsoft JhengHei", sans-serif`
+
+## 10. Voice & Tone
+
+VoiceTube's copy voice is **energetic, inclusive, encouraging** — a friendly study partner who celebrates small wins without condescension.
+
+| Dimension | Do | Don't |
+|---|---|---|
+| Register | Warm, conversational, direct | Academic, formal, passive |
+| Pacing | Short punchy sentences | Long subordinate clause chains |
+| CTA framing | "開始學習" / "免費加入" | "Please register to access content" |
+| Achievement framing | "你做到了！" / "再接再厲" | "Your score was insufficient" |
+| Error framing | "再試一次" (try again) | "An error has occurred" |
+
+Voice samples (illustrative):
+- *Illustrative — homepage headline register:* "連結世界、享受學習樂趣！" — Connect to the world, enjoy learning. No jargon, no friction, pure invitation.
+- *Illustrative — product description:* "每天20分鐘跟著練習，即可獲得30天免費訂閱制" — Specific promise, specific time, specific reward. Numbers over adjectives.
+- *Illustrative — branding tagline:* "Connect. Have fun!" — Two words each. The brand thinks in micro-copy that works across any language boundary.
+
+## 11. Brand Narrative
+
+VoiceTube launched in 2013 when three co-founders — Zenn, Lai, and Tsai — were teaching themselves English after work using YouTube videos. What started as a personal workaround became a community: a place where millions of Mandarin speakers could learn the world's lingua franca through the authentic, conversational content they actually wanted to watch. The insight was simple but powerful — context-rich video beats rote drilling, and the best classroom is one you choose to enter.
+
+From that origin story, VoiceTube built "Asia's largest online education platform," expanding from a curated video library into a full learning ecosystem: the core VoiceTube app for daily video-driven practice, Hero for AI-adaptive test preparation, Vclass for live celebrity-instructor courses, and Dictionary for deep vocabulary acquisition with dual-accent audio. The brand's name fuses "voice" (spoken language output, the hardest skill to acquire) with "tube" (YouTube's video-native learning environment), and the logo literalises this: a play triangle, the letter V, and a checkmark merged into a single mark whose 60°-angle typography echoes the geometry of the play button across every letterform.
+
+Today, with over 5 million users and recognition including Facebook App of the Year 2016, VoiceTube positions itself not as a language-learning tool but as a social platform for human connection through English — summarised in its rallying cry: **"Connect. Have fun!"**
+
+## 12. Principles
+
+1. **Video-first learning.** Real language lives in authentic video, not curated sentences. Every feature exists to make video consumption study-worthy. *UI implication:* Video thumbnails are the primary content atom; card grids prioritize visual poster art with minimal text overlay.
+
+2. **Connection over completion.** Learning English is a means to connect with people and ideas worldwide, not a checkmark. *UI implication:* Social indicators (learner counts, challenge rankings) are surfaced prominently to reinforce the community dimension.
+
+3. **Guided, not gatekept.** The platform meets learners where they are and provides direction without testing walls. *UI implication:* Free content is broadly accessible; premium features are surfaced contextually via gentle gradient CTAs rather than locked-content banners.
+
+4. **Innovation in every layer.** From AI vocabulary recommendations to gamified pronunciation challenges, technology should make learning feel effortless. *UI implication:* AI-powered elements are woven into the core flow — word lookup inline, difficulty auto-adjustment, personalised ranking — rather than siloed as premium add-ons.
+
+5. **Diverse and compound identity.** The brand serves Mandarin, Japanese, and Vietnamese speakers, and the design must flex accordingly. *UI implication:* CJK-optimized font stacks, locale-aware copy, and multi-lingual navigation are non-negotiable baseline requirements.
+
+## 13. Personas
+
+*Illustrative archetype — The Ambitious Professional:* A 28-year-old Taipei product manager who needs business English to advance her career. She has 20–30 minutes on her commute. She uses VoiceTube for daily video practice and Hero for TOEIC prep. She values progress indicators and streak mechanics that prove the time investment is working.
+
+*Illustrative archetype — The Pop-Culture Learner:* A 19-year-old university student in Taichung who watches English-language YouTube unsubbed but misses nuance. He found VoiceTube through a gaming channel and now uses the dictionary for slang. He values content discovery and social sharing over structured curricula.
+
+*Illustrative archetype — The Late-Stage Returner:* A 45-year-old parent in Kaohsiung who studied English in school, let it lapse, and now wants to rebuild for their child's international schooling applications. She learns through Vclass with established instructors. She values warmth, patience, and celebrity-instructor credibility over gamification.
+
+*Illustrative archetype — The Japanese Exchange Student:* A 22-year-old from Osaka studying at NTU who uses VoiceTube's Japanese-locale version to practice English while picking up Mandarin via Taiwanese content. He values the multi-locale product suite and dual-accent dictionary features.
+
+## 14. States
+
+- **Empty — no search results:** Dark panel with centered illustration and copy "找不到相關影片，試試其他關鍵字" — purple-tinted icon at low opacity against `#18131D`, no hard borders.
+- **Loading — video grid:** Skeleton cards in `#251633` with subtle shimmer animation sweeping left-to-right in `#1D102B`, matching the existing dark elevation tier so the layout shift is imperceptible.
+- **Error — form validation:** Input border shifts to `1px solid #ED4F55`, placeholder text and error label render in `#ED4F55`, the field label color also shifts to match.
+- **Error — page/server:** Full-page dark overlay at `#18131D` with a centered 404/500 message in `#E3E3E3`, no gradient backgrounds — keeps the dark canvas consistent.
+- **Success — quiz answer correct:** `#33991D` confirmation background at 10% opacity (`rgba(51, 153, 29, 0.1)`) with a full-opacity `#33991D` border and checkmark icon.
+- **Skeleton — video card:** `#251633` block sized to thumbnail aspect-ratio with a `#1D102B` shimmer pulse at 0.8s ease-in-out; title line represented by two `#251633` rounded bars.
+- **Disabled — button:** `opacity: 0.6`, `cursor: not-allowed`, text shifts to `#B4B4B4`, gradient or border color desaturates; no hover effect fires.
+
+## 15. Motion & Easing
+
+VoiceTube uses a compact three-step duration scale anchored in Tailwind custom tokens:
+
+| Token | Value | Use |
+|---|---|---|
+| `vc-duration-sm` | 86ms | Micro-interactions: hover color shifts, focus ring appearance |
+| `vc-duration-md` | 150ms | Standard transitions: button state changes, border-color, background-color |
+| `vc-duration-xl` | 300ms | Page-level: slide-in panels, carousel advances, modal entrance |
+
+The default easing is `ease-out` (`vc-ease-base`) — elements decelerate into their resting position, conveying arrival and completion. `cubic-bezier(0.4, 0, 0.2, 1)` (`vc-ease-in-out`) appears on keyboard-focus indicators and bi-directional carousels where enter and exit need to be symmetrical. Carousel progress dots use a width-transition at `vc-duration-md / ease-out` (active dot expands from 10px to 30px). No spring/bounce physics — the brand is energetic through color and gradient, not through over-engineered motion.

package/web/references/wadiz/DESIGN.md

@@ -10,6 +10,25 @@ logo:
   slug: "https://www.google.com/s2/favicons?domain=wadiz.kr&sz=256"
 verified: "2026-05-14"
 omd: "0.1"
+
+## 16. Do's and Don'ts
+
+### Do
+- Reserve the brand mint #00c4c4 for interactive moments only — CTA fills, links, checkbox marks, focus outlines, progress fills, and the waffle loader — so mint always reads as a verb
+- Default to 8px radius for buttons, cards, inputs, and modals (the 112-occurrence workhorse), reserving 16px for hero modals and the 16px 16px 0 0 bottom-sheet pattern and 50% for avatars and indicator dots
+- Set body text in Pretendard at 15px / 400 and reserve 700 for funding amounts, percentages, headings, and maker names so the eye bounces between the two near-parity weights
+- Use the Toss-family ink scale (#191f28 heading, #4e5968 muted, #6b7684 subtle, #8b95a1 placeholder) for all text instead of pure black
+- Build funding-state chips from the LabelBadge system using solid / outlined / tint shapes across the mint, yellow #fcc500, blue #4672f9, and red #ff5959 hues (오픈중 = mint solid, 마감임박 = red solid, 인기 = yellow solid)
+- Reach for the tint button (#e6fafa surface, #00c4c4 label, hover to #bef5f5 / #07abae) to carry marketing weight, letting it land before outlined buttons in the page rhythm
+
+### Don't
+- Use pure black #000 anywhere — #191f28 is the ink floor of the system
+- Apply mint #00c4c4 onto campaign photography or thumbnails — mint colorizes the chrome that frames the image, with the waffle loader as the single exception
+- Tint drop-shadows with the brand color — shadows stay blue-black (0 6px 6px -1px #0a16461a), never mint, never theatrical
+- Put 12px or larger radius on functional buttons — that consumer-app idiom breaks Wadiz's 8px retail-catalog read
+- Drop skeleton placeholders on the home grid — the thumbnail opacity 0 to 1 fade-in over 0.25s ease-in-out IS the loading state
+- Reach for marketing superlatives like 최고, 최강, or 혁신적, or introduce a serif or 300-weight thin face — the funding-state vocabulary does the selling and Pretendard does the entire type job
+
 ---
 
 # Design System Inspiration of Wadiz

package/web/references/webflow/DESIGN.md

@@ -165,8 +165,22 @@ Webflow's website is a visually rich, tool-forward platform that communicates "d
 ## 6. Depth: 5-layer cascading shadow system
 
 ## 7. Do's and Don'ts
-- Do: Use WF Visual Sans Variable at 500–600. Blue (#146ef5) for CTAs. 4px radius. translate(6px) hover.
-- Don't: Round beyond 8px for functional elements. Use secondary colors on primary CTAs.
+
+### Do
+- Set WF Visual Sans Variable as the type face, using weight 600 for headlines (e.g. the 80px / -0.8px Display Hero), 500 for buttons, and 400 for body
+- Reserve Webflow Blue (#146ef5) for the primary CTA, links, and focus borders on a white (#ffffff) canvas with near-black (#080808) text
+- Keep border-radius conservative and sharp on the 2px / 4px / 8px scale — 4px for buttons, inputs, and badges, 8px for standard cards
+- Apply the signature translate(6px) horizontal nudge on button hover, timed with motion-fast (150ms)
+- Deploy purple (#7a3dff), pink (#ed52cb), and green (#00d722) together as a SET for category coding and tier comparison — e.g. a 4px top-edge color bar on feature cards
+- Build depth with the 5-layer cascading shadow stack rather than a single flat drop shadow
+
+### Don't
+- Round functional elements beyond 8px, or make them pill-shaped or fully square — radius stays moderate between geometric and rounded
+- Use the secondary accents (purple #7a3dff, pink #ed52cb, green #00d722, etc.) on primary CTAs — those stay Webflow Blue #146ef5
+- Use a single secondary accent in isolation; the purple/pink/green trio only reads correctly when used together as category coding
+- Render the marketing surface in dark mode — keep it bright and airy on white (#ffffff)
+- Substitute another typeface for WF Visual Sans Variable or drift off its 400/500/600 weights
+- Write copy like "Revolutionary no-code" or aggressive Wix-comparison framing — both are forbidden under the agentic-web-platform voice
 
 ## 8. Responsive: 479px, 768px, 992px
 

package/web/references/yeogiotte/DESIGN.md

@@ -429,6 +429,25 @@ Interpretive claims (editorial, not documented Yeogiotte brand statements):
 - The KKR-vs-CVC clarification in §11 — KKR is widely confused in casual press; primary press citations confirm CVC.
 -->
 
+
+## 16. Do's and Don'ts
+
+### Do
+- Reserve Yeogiotte Blue `#1D8BFF` for primary CTAs (hero `검색`, login, `지도 보기`), filter-chip selected-state, and the `반짝특가` promo badge, targeting ≤2 blue elements per viewport in a primary flow
+- Hold to the three-tier radius scale of 8px buttons, 12px cards, and 100px filter pills, with inline badges at the tight 3-6px range
+- Set body and headings in Pretendard at `#222222` rather than pure black, and confine 700 weight to the listing name, final price, promo badges, and hero CTA while keeping location and distance meta at 400-500
+- Render the promo-badge grammar by role: yellow `#FFC83B` rating chip, blue-tint `#E3F0FF`/`#1D8BFF` `반짝특가`, slate `#49627A` `회원가`, and red `#FFEDEA`/`#F94239` coupon-applied price
+- Separate borderless `#ffffff` listing cards by whitespace gap and let the edge-to-edge room photo fill the 12px-radius card top, placing all badges and pricing in the metadata block below
+- Keep hashtag filter chips in user-language Korean (`#감성숙소`, `#연인추천`, `#반려견`) on a single 32px-tall horizontal-scroll row with 1.5px `#E6E6E6` borders as the primary filter surface
+
+### Don't
+- Use `#1D8BFF` as a hero background, card fill, divider, or decorative accent, or let three blue surfaces compete on one screen instead of demoting to the `#E3F0FF` tint
+- Style the `회원가` member-rate badge in brand blue, red, or yellow — keep it on slate `#49627A` so it reads as account utility, not a flash deal
+- Reach for an off-system radius like 10px, 14px, or 20px on a button or card when the answer is one of 8px, 12px, or pill
+- Place any promo or coupon badge on top of the room photo or tint the photo with a brand-color filter — badges live below the image and the destination must read true
+- Translate hashtag chips into category-style labels like `Romantic Stays` or `Pet-Friendly`, add extra adjectives to `#감성숙소`, or collapse the filter-chip row behind a primary `Filters` modal
+- Apply spring or overshoot easing to chrome and money surfaces, bold an entire listing card, or stack two same-color-family promo badges on one card
+
 ---
 
 **Verified:** 2026-05-09

package/data/architecture-proposals/2026-05-13-thin-install-fresh-fetch.md

@@ -1,189 +0,0 @@
-# Thin install + fresh fetch (WebFetch + MCP)
-
-**Status**: proposed — not implemented
-**Author context**: 2026-05-13 conversation, after KR-10 batch
-**Motivation**: npm publish on every brand addition is high-friction and produces stale installs
-
----
-
-## Problem statement
-
-Current `oh-my-design-cli` package bundles 88 brand DESIGN.md files (~12MB) and ships them via npm.
-
-**Pain points observed**:
-1. Every batch (10 brands) requires `npm publish` to reach end users
-2. Users installed at count N keep seeing N brands forever, even after we add more
-3. Skill descriptions historically baked the count (`"67개 ..."`) — required re-edit per batch, easy to forget (we forgot in the 78 release; observed again at 88)
-4. Bundle grows linearly; cold install time scales
-5. Single brand typo fix = minor version bump + publish
-
-**Decided 2026-05-13**: skill descriptions are now **count-agnostic** ("실제 기업 레퍼런스" without a number). Won't regress this kind of bug again. But the fundamental delivery model still needs reform.
-
----
-
-## Proposed architecture
-
-Hybrid: **thin npm baseline + fresh fetch at runtime**.
-
-```
-npm package (thin, ~500KB)
-├─ skills/                       (routing logic, count-agnostic)
-├─ data/reference-fingerprints.json   (metadata only — id, category, primary, tone keywords)
-├─ data/snapshot-date.txt        ("baseline 2026-05-13")
-├─ hooks/, agents/, bin/         (unchanged)
-└─ (no DESIGN.md bundled — fetched at runtime)
-
-Runtime (skill execution in user's agent)
-1. Match brand via local fingerprints.json (offline-capable)
-2. Fetch full DESIGN.md from:
-   - Primary:  WebFetch  https://oh-my-design.kr/api/references/<id>/design-md
-   - MCP path: omd_get_designmd(id)        (if MCP server connected)
-   - Fallback: bundled (if shipped — optional Phase 3 decision)
-3. Apply, write to project DESIGN.md
-```
-
-**Outcome**:
-- New brand batch → `git push` web + git commit fingerprints; **no npm publish**
-- Users see new brands on next skill call (no reinstall)
-- npm publish frequency drops to "skill behavior changes" (<1/month)
-- Marketing copy (READMEs) still updates count per batch — that's intentional
-
----
-
-## Implementation phases
-
-### Phase 1 — Backend HTTP endpoint (~1h)
-
-`web/src/app/api/references/[id]/design-md/route.ts`:
-```ts
-import { readFileSync } from 'fs';
-import { join } from 'path';
-import { NextRequest, NextResponse } from 'next/server';
-
-export async function GET(_req: NextRequest, { params }: { params: { id: string } }) {
-  try {
-    const md = readFileSync(join(process.cwd(), 'references', params.id, 'DESIGN.md'), 'utf-8');
-    return new NextResponse(md, {
-      headers: {
-        'Content-Type': 'text/markdown; charset=utf-8',
-        'Cache-Control': 'public, max-age=300, s-maxage=3600',
-        'Access-Control-Allow-Origin': '*',
-        'ETag': `"${md.length}-${md.slice(-32)}"`,
-      },
-    });
-  } catch {
-    return NextResponse.json({ error: 'not found' }, { status: 404 });
-  }
-}
-```
-
-Smoke test: `curl https://oh-my-design.kr/api/references/kakaopay/design-md | head -20`
-
-### Phase 2 — MCP server (~3h, parallel with Phase 1)
-
-New package `oh-my-design-mcp` (separate npm package).
-
-Tools exposed:
-| Tool | Args | Returns |
-|---|---|---|
-| `omd_search_references` | `{ query, top_k? }` | top-N brand fingerprints (id, score, why) |
-| `omd_get_designmd` | `{ id }` | full DESIGN.md markdown |
-| `omd_list_categories` | — | category → ids map |
-| `omd_get_snapshot_date` | — | "2026-05-13" (for staleness check) |
-
-Resources exposed (MCP resources, browsable):
-- `omd://references` — list all
-- `omd://references/<id>` — single DESIGN.md
-
-Server reads from same HTTP endpoint internally (single source of truth) OR direct disk if self-hosted.
-
-Distribution: `npx -y oh-my-design-mcp` in MCP config:
-```json
-{
-  "mcpServers": {
-    "oh-my-design": { "command": "npx", "args": ["-y", "oh-my-design-mcp"] }
-  }
-}
-```
-
-### Phase 3 — Skill updates (~1h)
-
-`skills/omd-init/SKILL.md`, `skills/omd-harness/SKILL.md`:
-
-```diff
-- Phase 4: fetch reference DESIGN.md from .claude/data/references/<id>/DESIGN.md
-+ Phase 4: fetch reference DESIGN.md (priority order):
-+   a) If MCP `oh-my-design` connected: call omd_get_designmd(id)
-+   b) Else WebFetch https://oh-my-design.kr/api/references/<id>/design-md
-+   c) Else (offline): bundled .claude/data/references/<id>/DESIGN.md if present
-+   d) Else: report "id not in catalog, network unavailable, no bundle"
-```
-
-Skill must also surface the snapshot date to the user when fetching offline:
-> "오프라인 모드 — 2026-05-13 기준 카탈로그 사용 중. 최신 brand 보려면 인터넷 연결 후 재시도."
-
-### Phase 4 — Bundle diet (~30m, optional)
-
-`package.json`:
-```diff
-"files": [
-  "dist",
-  "skills/*",
-  "agents",
-  "data",
-- "web/references/*/DESIGN.md",
-+ "data/snapshot-date.txt",
-  ".claude/hooks/*.cjs",
-  ".claude/settings.json"
-]
-```
-
-`scripts/postinstall.cjs`: stop copying DESIGN.md files into `.claude/data/references/`. Skills will fetch.
-
-**Trade-off**: completely offline-broken if API down. Mitigation: optional flag `--bundle-references` for users who want offline guarantee.
-
-### Phase 5 — `omd:batch-launch` SKILL update (~15m)
-
-Phase 3 SYNC:
-- Remove `npm publish` from suggested follow-ups
-- Add note: "After git push, brand reaches users automatically via API"
-- Marketing surfaces (README count, llms.txt count) still need batch sync since they're static
-
----
-
-## Migration plan
-
-1. **Phase 1 first** (backend endpoint) — non-breaking, just adds capability
-2. **Phase 2 in parallel** (MCP) — non-breaking, separate package
-3. **Phase 3** (skill update) — backward-compat: tries MCP → WebFetch → bundle, so old installs still work
-4. **Phase 4 last** (bundle diet) — only after Phase 3 has shipped for 1-2 weeks and we confirm fetch reliability
-5. **Phase 5** (omd:batch-launch update) — final cleanup after migration is stable
-
----
-
-## Open questions
-
-- **Authentication**: keep API public read? (Yes — DESIGN.md files are intended for public consumption, that's the product.)
-- **Rate limit**: needed? (Probably basic per-IP at edge — Vercel/Cloudflare. Not critical for v1.)
-- **Versioning of DESIGN.md content**: should the API return a `?version=YYYY-MM-DD` parameter so installs can pin? (Defer — KISS for v1.)
-- **Caching**: should the skill cache fetched DESIGN.md locally per session? (Yes — agent runtime should cache the parsed result for the session.)
-- **What about agent that has no WebFetch tool?** (Edge case. Codex CLI has it. Cursor has it via tool config. If a user's agent really has neither WebFetch nor MCP, they install the `--bundle-references` flag at install time.)
-
----
-
-## When to do this
-
-**Trigger**: next time the user mentions "10개 더" or any brand addition. Pause Phase 2 build, ship the architecture first, then resume.
-
-**Or**: after 2 more batches (100, 110 brands), npm package bundle pain becomes hard to ignore — natural breakpoint.
-
-**Not now**: this conversation closed with count-agnostic skill descriptions as the immediate fix. Architecture is tracked but not implemented yet.
-
----
-
-## Reading list / inspirations
-
-- Linear's hosted catalog approach (linear.app/docs API)
-- Tailwind v4 CDN-first delivery model
-- shadcn/ui's "components are not a package, they're snippets you copy" — opposite direction but instructive
-- MCP spec: `https://modelcontextprotocol.io/`

package/data/issues/2026-05-13-multi-surface-schema-rfc.md

@@ -1,67 +0,0 @@
-# RFC: Multi-surface brand spec (deferred)
-
-**Status**: deferred / not blocking
-**Filed**: 2026-05-13
-**Trigger**: Banksalad mismatch — canonical DESIGN.md captured "advisor app" idiom, but `banksalad.com` is a "marketing landing" idiom. Generated landing.html was schema-faithful but didn't resemble the actual brand homepage.
-**Decision**: do NOT do this schema change now. Solve at the skill level first (see `data/issues/2026-05-13-multi-surface-schema-rfc.md` companion fix in commit history). Revisit only if skill-level fix proves insufficient after ~10 more brand additions or repeated user complaints about surface mismatch.
-
----
-
-## Problem
-
-One brand can have visually distinct surfaces (marketing landing, in-app, docs, onboarding). The current `DESIGN.md`-per-brand schema implicitly picks ONE surface as canonical. Generators following the spec faithfully will mismatch when user requests a different surface.
-
-## Why we're deferring the schema change
-
-1. **Both prior-art systems we surveyed keep schema single**:
-   - Google Stitch treats variants/modes/devices as runtime workflows (sidebar items in their docs), not separate spec documents.
-   - getdesign.md allows N entries per brand with catalog-level tags, but actual catalog data shows 1 entry per brand in practice (e.g. Apple has 1 entry).
-   - W3C Design Tokens Community Group spec deliberately does NOT scope tokens by surface — leaves it to vendor `$extensions`.
-2. **Authoring cost scales poorly**: 88 brands × N surfaces is real maintenance overhead for marginal cases. Only ~10-15% of brands appear to have visually distinct landing/app idioms.
-3. **The Banksalad case is a generator priority bug, not a schema gap**. We already had `tokens.json#live_overrides` and screenshots — the generator just didn't weight them.
-4. **Backward compatibility**: 88 published references would all need migration. High blast radius for unclear payoff.
-
-## What might warrant revisiting
-
-- ≥3 distinct user reports of "this brand's generated output doesn't look like the real brand"
-- A new batch where ≥30% of brands exhibit landing-vs-app idiom split
-- AI coding agents adopting a multi-surface convention (W3C tokens spec, Stitch, etc. adding `surface` as a first-class field)
-
-## Sketch (if/when we do this)
-
-Probable shape based on the survey:
-
-- `web/references/<id>/DESIGN.md` stays — essence-leaning (voice, principles, motion philosophy, raw palette)
-- Optional `surfaces/<surface>.md` overlay files — delta only, frontmatter `surface: marketing|product|docs|onboarding`, `extends: ../DESIGN.md`
-- Generator reads essence + (one) overlay → composes
-- Closed enum chosen for AI determinism (Spectrum/Carbon precedent — productive vs expressive moment)
-- Only ~10-15% of brands need overlays — most stay single-doc
-
-## What we're doing instead (now)
-
-Skill-level fix shipping in v1.4.0 or similar:
-
-1. `omd:reference-capture` writes `structure.json` recording observable composition cues (hero type, CTA shape, nav structure, ornament style) — facts, not copyrighted content.
-2. `omd:apply` / `omd:harness` instructed to Read hero screenshots as images for visual grounding before composing.
-3. Token-resolution priority order documented: `tokens.json#live_overrides` > canonical DESIGN.md > `delta_set`. Brand essence (voice, principles, motion philosophy) stays canonical-only.
-4. `omd:harness` Step 4 master prompt includes a `surface_signal` field derived from task keywords (`랜딩`→marketing, `대시보드`→product, etc.). Master uses it to weight reference-capture artifacts vs canonical spec.
-
-The skill-level fix achieves the same Banksalad-landing outcome without any schema or migration work.
-
-## References (survey notes)
-
-- Stitch docs at `stitch.withgoogle.com/docs/design-md/overview` — sidebar nav includes `Device Types`, `Design Modes`, `Generate design variations` as separate workflows
-- getdesign.md catalog (`getdesign.md/apple`) — N-entries-per-brand with category tags at catalog level, but actual data has single entries
-- W3C Design Tokens spec `tr.designtokens.org` — `$extensions` escape hatch, no surface primitive
-- Material 3 (`m3.material.io`) — three-tier `ref/sys/comp` is vertical, not surface-horizontal
-- Carbon (`carbondesignsystem.com`) — theme axis (`white/g10/g90/g100`) is the closest to surface, but it's a single coarse dimension
-- Adobe Spectrum (`spectrum.adobe.com`) — `productive/expressive` moment is a 2-bucket idiom split; precedent for closed enum
-- shadcn/ui (`ui.shadcn.com`) — explicitly refuses the surface problem by shipping unstyled primitives
-
----
-
-## Linked actions
-
-- [ ] Implement skill-level fix (4 items above) — target v1.4.0
-- [ ] After 3 more batches, re-evaluate whether skill fix is sufficient
-- [ ] If not, draft formal `omd: 0.2` schema following the surfaces/<name>.md sketch