oh-my-design-cli 1.6.0 → 1.6.1

package/web/references/velog/DESIGN.md

@@ -0,0 +1,168 @@
+---
+id: "velog"
+name: "velog"
+country: KR
+category: developer-tools
+homepage: "https://velog.io"
+primary_color: "#12B886"
+logo:
+  type: favicon
+  slug: "https://www.google.com/s2/favicons?domain=velog.io&sz=128"
+verified: "2026-06-01"
+omd: "0.1"
+ds:
+  name: velog (open source)
+  url: "https://github.com/velog-io/velog"
+  type: system
+  description: velog's production frontend is fully open-source (MIT); its design tokens live in src/lib/styles (themes.ts + palette.ts), built on the Open Color palette.
+---
+# Design System Inspiration of velog
+
+## 1. Visual Theme & Atmosphere
+
+velog is a Korean developer-blogging platform built by velopert (Minjun Kim), and its surface is unmistakably reading-first: calm, minimal, and content-forward, with prose given room to breathe rather than competing with chrome. The palette is literally the Open Color system — a clean teal brand scale running from the near-white teal0 #F3FFFB up to the deep teal9 #087F5B, paired with a full neutral gray scale from gray0 #F8F9FA to gray9 #212529. The atmosphere is editorial and quiet: a soft gray page background (#F8F9FA) holds white content surfaces, dark near-black text (#212529) carries the writing, and the brand teal (#12B886) appears sparingly as the signal color for action. Nothing shouts; the teal is a confident accent reserved for the write button and primary moments rather than a wash across the page. The result feels engineered for long-form technical reading — high legibility, generous neutrality, and a single decisive brand hue that tells you exactly where to click.
+
+## 2. Color Palette & Roles
+velog's color system is the Open Color palette, surfaced through velog-client's `palette.ts` (raw scales) and `themes.ts` (semantic `themedPalette` tokens). The teal scale is the brand spine and the gray scale carries structure and text; red appears only for destructive intent.
+
+**Brand / Teal scale**
+- teal0: `#F3FFFB`
+- teal1: `#C3FAE8`
+- teal2: `#96F2D7`
+- teal3: `#63E6BE`
+- teal4: `#38D9A9`
+- teal5: `#20C997` (themedPalette primary2)
+- teal6: `#12B886` (BRAND / primary — themedPalette primary1)
+- teal7: `#0CA678`
+- teal8: `#099268`
+- teal9: `#087F5B`
+
+**Neutral / Gray scale**
+- gray0: `#F8F9FA` (page background — bg_page1)
+- gray1: `#F1F3F5`
+- gray2: `#E9ECEF`
+- gray3: `#DEE2E6`
+- gray4: `#CED4DA`
+- gray5: `#ADB5BD`
+- gray6: `#868E96`
+- gray7: `#495057`
+- gray8: `#343A40`
+- gray9: `#212529` (primary text — text1)
+
+**Semantic roles (themedPalette)**
+- Primary: `#12B886` (primary1)
+- Primary alt: `#20C997` (primary2)
+- Destructive: `#FF6B6B` (destructive1 / red5)
+- Text: `#212529` (text1)
+- Page background: `#F8F9FA` (bg_page1)
+
+Role guidance: teal6 #12B886 is the single primary-action color (the write button); the gray scale does all structural and typographic work (page #F8F9FA, text #212529); red5 #FF6B6B is reserved strictly for destructive actions. The teal is an accent, not a fill — use it where action lives, not as background.
+
+## 3. Typography Rules
+velog uses a native system font stack rather than a custom typeface, which keeps the reading surface fast and OS-consistent. Body copy renders through the system UI stack (-apple-system / system-ui) at a 16px base. The primary text color is gray9 #212529 — a near-black that delivers strong contrast against the gray0 #F8F9FA page and white content surfaces without the harshness of pure #000.
+
+- Font family: system stack (-apple-system / system-ui)
+- Body size: 16px
+- Primary text color: #212529 (gray9 / text1)
+
+The intent is editorial neutrality: let the writer's content set the tone while the system font and a single dark text color hold legibility steady across platforms.
+
+## 4. Component Stylings
+
+### Login button (header)
+
+**Default**
+- Background: #212529
+- Text: #FFFFFF
+- Border: none
+- Radius: 16px
+- Height: 32px
+- Font: 16px / 700
+- Use: dark pill in the top-right of the header for sign-in / sign-up entry
+
+### Write button (primary action)
+
+**Default**
+- Background: #12B886
+- Text: #FFFFFF
+- Border: none
+- Use: the brand teal primary-action button (buttonColorMap) — the single decisive call-to-action for composing a post
+
+### Header bar
+
+**Default**
+- Background: #FFFFFF
+- Text: #212529
+- Font: 16px (system stack)
+- Use: top navigation surface sitting on the gray0 page, holding brand and the dark login pill
+
+### Page surface
+
+**Default**
+- Background: #F8F9FA
+- Text: #212529
+- Font: 16px (system stack)
+- Use: the soft-gray reading canvas (bg_page1) that frames white content blocks
+
+## 5. Layout Principles
+velog is structured as a reading surface first. A soft gray page background (gray0 #F8F9FA) acts as the canvas, white surfaces (the header #FFFFFF and content blocks) sit on top, and near-black text (#212529) carries the writing. The layout logic is qualitative and editorial: maximize legibility and whitespace, keep chrome minimal, and let long-form technical content lead. Action is concentrated rather than scattered — the dark login pill anchors the header's top-right, and the teal write button is the single bright signal in an otherwise neutral field.
+
+## 6. Depth & Elevation
+velog's depth language is restrained and flat — elevation comes from value contrast, not heavy shadow. The gray0 #F8F9FA page sits one step back from the white (#FFFFFF) header and content surfaces, so the layering reads through tone alone. The dark login pill (#212529, radius 16px) is the heaviest visual object in the header, gaining presence from its near-black fill and rounded form rather than from a drop shadow. The overall effect is calm and tactile-but-quiet: surfaces are distinguished by the gray-to-white step, and the teal accent provides the only chromatic lift.
+
+## 7. Do's and Don'ts
+
+### Do
+- Reserve teal #12B886 for the primary action (the write button) — it is a signal, not a background wash.
+- Use the gray scale for all structure and text: page #F8F9FA, surfaces #FFFFFF, text #212529.
+- Keep the dark login pill at radius 16px and height 32px as documented.
+- Default to the system font stack (-apple-system / system-ui) at 16px for body.
+
+### Don't
+- Use red — #FF6B6B (destructive1) is reserved strictly for destructive actions.
+- Introduce pure black for text; the system's near-black is #212529.
+- Spread teal across large fills; it loses its role as the single action color.
+- Add heavy shadows — depth here is carried by the gray-to-white value step.
+
+## 8. Responsive Behavior
+The blob does not carry measured breakpoint, grid, or container values for velog, so responsive behavior is described qualitatively rather than with invented numbers. The surface is content-forward and reading-first, which favors a single legible column of prose that stays comfortable across viewport widths. The header holds the brand and the dark login pill (height 32px, radius 16px); the teal write button remains the primary action target at any size. Maintain the gray0 #F8F9FA page background and #FFFFFF surfaces across breakpoints so the editorial value contrast is preserved on both desktop and mobile.
+
+## 9. Agent Prompt Guide
+When generating UI in velog's style, instruct the agent: "Build a calm, reading-first developer-blog surface. Use a soft gray page background #F8F9FA (gray0) with white #FFFFFF surfaces and near-black text #212529 (gray9). Use the system font stack (-apple-system / system-ui) at 16px for body. Make teal #12B886 the single primary-action color — apply it only to the write/primary button, never as a large fill. Render the sign-in control as a dark pill: background #212529, white text, border-radius 16px, height 32px, font 16px/700. Reserve #FF6B6B strictly for destructive actions. Keep depth flat: layer surfaces by the gray-to-white value step rather than shadows. Lean on the Open Color teal scale (teal0 #F3FFFB through teal9 #087F5B) and gray scale (gray0 #F8F9FA through gray9 #212529) for any tints or states."
+
+## 10. Voice & Tone
+velog's voice is that of a quiet, capable tool that gets out of the writer's way. It is editorial and engineer-minded: plain, precise, and unhurried, trusting the developer's content to lead. There is no marketing flourish in the surface — the tone matches the visual restraint, favoring clarity over persuasion. The single teal accent is the closest thing to an exclamation point, and even that is reserved for the one moment that matters: writing.
+
+## 11. Brand Narrative
+velog was created by velopert (Minjun Kim) as a developer-blogging platform for the Korean developer community, and its character flows directly from that origin. The production frontend is fully open-source (MIT), and the design tokens live transparently in `src/lib/styles` — `themes.ts` and `palette.ts` — built on the Open Color palette. That openness is the narrative: velog is a tool by and for developers, where the teal brand and the gray reading surface aren't decoration but the legible, honest scaffolding around technical writing. The brand reads as calm, minimal, and content-forward — a place where the words come first and the interface is just the quiet teal-and-gray frame around them.
+
+## 12. Principles
+- Reading-first: legibility and whitespace before chrome; long-form content leads.
+- One signal color: teal #12B886 marks action and nothing else.
+- Neutral structure: the gray scale (#F8F9FA → #212529) carries page, surface, and text.
+- Restraint in red: #FF6B6B is destructive-only.
+- Open and honest: tokens are open-source, built on the Open Color palette.
+- Flat depth: layer by value contrast, not shadow.
+
+## 13. Personas
+- The developer-writer: drafting long-form technical posts and wanting an editorial, distraction-free canvas. The system answers with a #F8F9FA reading surface, #212529 text, and a single teal write button as the clear next step.
+- The developer-reader: scanning technical content for signal. The high-contrast near-black text on soft gray, the system font at 16px, and the minimal chrome keep attention on the writing.
+
+## 14. States
+- Default / primary action: teal #12B886 (primary1) — the write button.
+- Primary alt / hover-tier tint: #20C997 (primary2 / teal5) is the documented secondary teal step for primary action.
+- Destructive: #FF6B6B (destructive1 / red5), reserved for destructive actions only.
+- Text (resting): #212529 (text1).
+- Page (resting): #F8F9FA (bg_page1).
+
+The blob does not carry measured per-state hover/pressed/focus values for individual components, so those interaction states are described by the available token roles rather than invented numbers; lean on the teal and gray scales (e.g., adjacent teal steps such as teal5 #20C997 and teal7 #0CA678) for tint progressions when a state shift is needed.
+
+## 15. Motion & Easing
+The blob does not carry measured duration, easing-curve, or transition values for velog, so motion is described qualitatively rather than with invented numbers. In keeping with the calm, reading-first character and flat depth, motion should be minimal and unobtrusive — gentle, quick transitions that never pull focus from the content. The teal accent is the one element worth a subtle emphasis on interaction; everything else should settle quietly so the reading surface stays still.
+
+---
+**Verified:** 2026-06-01
+**Tier 1 sources:** https://velog.io (live DOM: page background #F8F9FA, header #FFFFFF, login pill #212529 / white / radius 16px / height 32px / 16px-700, system font 16px, brand teal #12B886 write button), https://github.com/velog-io/velog (open-source DS — tokens in src/lib/styles built on Open Color), https://github.com/velopert/velog-client (source files palette.ts + themes.ts giving the teal/gray/red scales and themedPalette semantic tokens)
+**Tier 2 sources:** getdesign.md/velog — NOT LISTED. refero — not listed (dev-blog SaaS absent).
+**Conflicts unresolved:** none
+**Proof:** see .verification.md (## Proof block)

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

package/data/reference-audits/2026-05-13-kr10.md

@@ -1,132 +0,0 @@
-# Batch Audit — 2026-05-13 / KR-10
-
-**Theme**: Korean IT companies with publicly observable design system signal
-**Brands added**: 10 (78 → 88)
-**Skill**: `omd:batch-launch` (Phase 2 build pipeline = `omd:add-reference` CREATE)
-**Verification date**: 2026-05-13
-
----
-
-## How the 10 were researched (pipeline applied to each)
-
-Every brand went through the standard `omd:add-reference` CREATE 3-tier pipeline. Each `omd-batch-launch` subagent was constrained to:
-
-1. **Tier 1 — Live inspect (required)**: playwright MCP `getComputedStyle` on hero CTA / nav / footer / input / cards across **≥1 surface** of the brand's production site. Where possible, also `curl` of the production CSS bundle (more authoritative than runtime sampling because it exposes the entire token system).
-2. **Tier 2 — Cross-check (both attempted)**: `getdesign.md/<id>` + `styles.refero.design/?q=<brand>` (also `?q=<한글명>`). Either source success = OK; both empty = explicitly logged in §4 footer.
-3. **Tier 3 — Reconcile + write**: 9 product sections (Stripe schema) + §10-15 philosophy (Toss §10-15 shape) + `_research.md` source map + `_promo.json` highlight + verified footer.
-
-Every brand also has:
-- `web/references/<id>/DESIGN.md` (the spec, frontmatter `omd: 0.1`)
-- `web/references/<id>/_research.md` (Tier-by-Tier source list + dates + confidence per section)
-- `web/references/<id>/_promo.json` (id, Korean name, logo URL, single "most striking" highlight for promo video)
-- §4 footer with `**Verified:** 2026-05-13` + Tier 1 sources + Tier 2 status + Conflicts unresolved
-
----
-
-## Systemic finding
-
-**Tier 2 directories (`getdesign.md`, `styles.refero.design`) have weak Korean coverage**. All 10 brands returned **empty** on both 3rd-party indexes. This is not a brand-quality issue — it's a directory-bias issue (both are English-tooling-oriented). Documented per-brand in §4 footers.
-
-**But brand-published DS / design narrative resources DO exist for most of the 10** — they were just not in those 3rd-party indexes. 7/10 have public DS-related surfaces that were used in Tier 1 reconcile:
-
-| brand | brand-published DS surface | type | live (2026-05-13) |
-|---|---|---|---|
-| socar | `design.socar.kr` | docs hub | ✅ 200 |
-| wanted | `montage.wanted.co.kr` + `wanted.co.kr/brandcenter` | full DS | ✅ 200 |
-| remember | `dramancompany.github.io/remember-ui` | Storybook | ✅ 200 |
-| banksalad | `github.com/banksalad` (org + styleguide repos) | source | ✅ 200 |
-| zigzag | `brunch.co.kr/@zigzag/73` + `devblog.kakaostyle.com` | brand articles (ZDS) | ✅ 200 |
-| gangnamunni | `blog.gangnamunni.com/post/welchis/` | DS architecture post | ✅ 200 |
-| kakaopay | `story.kakaopay.com` | brand / design narrative | ✅ 200 |
-| 29cm | — | — | ❌ no public DS |
-| ably | — | — | ❌ no public DS |
-| zigbang | — | — | ❌ no public DS |
-
-→ For future Korean batches, weight Tier 1 (live inspect + **brand-owned tech blogs / brunch / medium / GitHub orgs**) more heavily. Tier 2 (3rd-party directories) is documentation discovery, not validation.
-
-→ The 7 brand-published DS URLs are also registered in `web/src/lib/design-systems.ts` so they surface as DS buttons in Browse modal and Builder Step 3 preview header. The 3 brands without a public DS correctly return null and the DS button stays hidden.
-
----
-
-## Per-brand audit
-
-Confidence rubric:
-- **High** — ≥2 Tier 1 surfaces OR production CSS bundle captured; no unresolved hex; ≥3 supporting brand-owned sources (blog/medium/brunch); §10-15 sourced
-- **Medium** — 1 Tier 1 surface; some inferred values; brand-owned philosophy sources present
-- **Low** — Tier 1 partially blocked; key tokens marked `(unverified live)` or `(illustrative)`; needs UPDATE pass
-
-| # | id | confidence | Tier 1 depth | Tier 2 | Known gaps | Follow-up |
-|---|----|------------|--------------|--------|------------|-----------|
-| 1 | socar | **Medium** | 1 surface (home full); design.socar.kr partial (browser session contended) | empty (getdesign no record · refero no isolated set) | SOCAR Blue **exact hex unpublished** — brand-name-only reference. Brand fonts Sandoll Gothic Neo2 / Avenir (print) vs live Pretendard (web) — documented as intentional print-vs-web split. | UPDATE pass on `design.socar.kr` for canonical SOCAR Blue hex + Space Frame system tokens |
-| 2 | gangnamunni | **High** | 3 (home live + production CSS bundle `d246c5b2edcb00b6.css` with full Cell token map + blog.gangnamunni.com Cell+Welchis architecture post) | empty | none material | — |
-| 3 | kakaopay | **Medium** | 1 surface (home full live inspect); /payment/online second surface blocked by browser tab contention | empty (both verified empty) | none unresolved. KPDS = narrative-only on `story.kakaopay.com`, no public docs site. | UPDATE pass on /payment/online or /transfer for second surface verification |
-| 4 | zigzag | **High** | 4 (home live + production CSS bundle 184KB with full ZDS canonical tokens via `--zds-color-*` vars + devblog.kakaostyle.com ZDS rearchitecture + brunch.co.kr/@zigzag/73 brand-owned) | empty | Two-pink architecture (`#fa6ee3` brand-anchor vs `#f55dd6` interactive primary) — documented as intentional role split | — |
-| 5 | 29cm | **Medium** | 1 surface (home via isolated Playwright `browser_run_code_unsafe` workaround for session contention) | empty | PDP / checkout flows not inspected this pass | UPDATE pass on PDP + checkout (editorial product story modules) |
-| 6 | ably | **Low** | 1 navigation only — live `evaluate` calls blocked by Playwright session contention; §4 token hexes flagged `(unverified live)` in footer | empty / inconclusive (refero JS-rendered, capture blocked) | §4 token values need live re-capture. Brand disambiguation note added (Ably Corp KR commerce ≠ ably.com realtime API). | **Priority**: full Phase U2 live inspect re-run on a clean Playwright session |
-| 7 | banksalad | **High** | 5 (home live + 865KB production CSS bundle with `border-radius:2px` ×81 confirming system default + BPL tech blog + 2× GitHub orgs) | empty (both verified empty) | One nav exception documented (sign-in pill at 16px radius vs system 2px default) — already noted as exception, not conflict | — |
-| 8 | zigbang | **Medium** | 2 (home full + /home/apt/map partial — map-overlay listing card tokens inferred due to second-pass contention) | empty | (a) **brand-orange exact hex unpublished** — `~#FF6600` flagged illustrative in §2 + footer; (b) map-overlay listing-card / price-chip tokens inferred | UPDATE pass on /home/apt/map for canonical orange hex + listing-card token verification |
-| 9 | wanted | **High** | 8 sources (live DOM on `wdlist/518` 22 samples + brandcenter + Montage docs + wanted-sans GitHub + wanteddev org + wantedlab.com + WDS creation blog) | empty (refero blocked by session contention, getdesign verified empty) | none unresolved. `#14191E` (marketing) vs `#171719` (product) is documented two-surface split, not a conflict. | (optional) refero re-attempt on clean session |
-| 10 | remember | **High** | 5 (career page primary live inspect + `dramancompany.github.io/remember-ui/` Storybook root + corp x2 + redirect) | empty (3rd-party empty + GitHub UI repo 404 — source private/deleted, Storybook deploy still live) | (a) filter-chip **selected/active** state not observed (only default captured); (b) error/warning semantic tokens inferred from KR fintech convention | UPDATE pass capturing filter chip selected/active + error/warning states |
-
----
-
-## Confidence distribution
-
-- **High** (5): gangnamunni, banksalad, wanted, zigzag, remember
-- **Medium** (3): socar, 29cm, kakaopay
-- **Low** (1): ably
-- *(zigbang was kept at Medium even though 2 surfaces inspected, because of 2 unresolved illustrative tokens — orange hex + map overlay)*
-
-**Aggregate**: 5/10 are publishable as-is. 3/10 are publishable with marked uncertainty. **2/10 (ably + zigbang) warrant a follow-up UPDATE pass before being cited in external blog posts or comparisons.**
-
----
-
-## Known shared limitation — Playwright session contention
-
-The Phase 2 build ran 10 subagents in parallel, all sharing the host Playwright MCP browser. Several agents reported that `browser_evaluate` calls landed on *other agents' tabs* (kakaopay/zigzag/banksalad/29cm appear in multiple reports as "the tab that hijacked my session"). Mitigations applied per agent:
-
-- Fall back to direct `curl` of the production CSS bundle (banksalad, gangnamunni, zigzag) — actually higher signal than runtime sampling for these
-- Use `browser_run_code_unsafe` in isolated newPage context (29cm)
-- Document and explicitly flag affected surfaces in `_research.md` (ably, kakaopay, zigbang)
-
-**Process fix for next batch**: serialize Playwright sessions per brand (run 1-2 in parallel, not 10), OR isolate to `--user-data-dir` per agent if available. Cost: longer wall-clock. Benefit: no contention, clean §4 token values for every brand.
-
----
-
-## Promo highlight selection (auditable)
-
-Each brand's `_promo.json` records a single "most striking" element — chosen by the build subagent and used in the promo MP4. Type distribution:
-
-- **palette** (7): socar, gangnamunni, zigzag, ably, banksalad, zigbang, wanted
-- **voice** (2): kakaopay, 29cm
-- **cta** (1): remember
-
-Justifications are written into each `_promo.json` (`label` field) and re-verified during Phase 4 composition build.
-
----
-
-## Follow-up TODO (prioritized)
-
-1. **ably** — full Phase U2 live inspect re-run (clean session). §4 tokens currently `(unverified live)`.
-2. **zigbang** — UPDATE pass on `/home/apt/map` for canonical orange hex + map-overlay tokens.
-3. **socar** — UPDATE pass on `design.socar.kr` for canonical SOCAR Blue hex + Space Frame token system.
-4. **remember** — UPDATE pass capturing filter-chip selected/active + error/warning semantic tokens.
-5. **29cm** — UPDATE pass on PDP + checkout flows.
-6. **kakaopay** — UPDATE pass on a transactional second surface (e.g., /transfer).
-7. **reader UI**: long variant headings overlap preview area (observed on 29cm §5). Fix in `web/src/components/reference-preview.tsx` (or equivalent).
-8. **Process**: serialize Playwright sessions per build agent for future batches.
-
----
-
-## Schema for this file (future batches use the same shape)
-
-Required top-level sections (so they're greppable across batches in `data/reference-audits/`):
-- `## How the 10 were researched`
-- `## Systemic finding`
-- `## Per-brand audit` (table with id, confidence, Tier 1 depth, Tier 2, Known gaps, Follow-up)
-- `## Confidence distribution`
-- `## Known shared limitation`
-- `## Promo highlight selection`
-- `## Follow-up TODO`
-
-Filename: `data/reference-audits/<YYYY-MM-DD>-<batch-slug>.md`