# Apply guide — translating a DESIGN.md into the current project

The fetched DESIGN.md is a *brief*, not code. The job is to express its intent in the
target project's own styling system without flattening the brand's character or fighting
the codebase you're in.

## 1. Detect the target styling system first

Before editing, figure out how this project styles UI, and work with its grain:

- **Tailwind** — look for `tailwind.config.{js,ts}` or an `@theme` block in CSS, plus
  utility classes in JSX. Map tokens into the theme (colors, fontFamily, spacing,
  borderRadius), then use utilities. Don't scatter arbitrary `[#hex]` values.
- **CSS custom properties** — a `:root { --… }` block or a design-token file. Add/override
  variables there; don't sprinkle literals through components.
- **CSS-in-JS** (styled-components, emotion, vanilla-extract) — find the theme object and
  extend it.
- **Plain CSS / inline** — introduce a small variable block at the top scope and reference
  it.

A brand restyle that fights the project's system creates debt; one that flows through its
tokens stays maintainable.

## 2. Map the DESIGN.md sections

| DESIGN.md section   | Where it lands in the target |
|---------------------|------------------------------|
| Colors (OKLCH)      | color tokens / theme palette; keep semantic roles (primary, surface, ink) |
| Typography          | font-family + size/weight/line-height scale; load webfonts if the md gives a `font-*-src` URL |
| Spacing             | spacing scale — gap & padding steps |
| Rounded (radius)    | border-radius scale |
| Elevation & Depth   | shadow tokens |
| Components          | reference patterns for buttons, cards, inputs — match structure & states, don't clone pixel-for-pixel |
| Do's & Don'ts       | hard constraints to honor (e.g. "pure black 금지", "CTA fill은 1차 액션에만") |

## 3. OKLCH values

The catalog expresses color in OKLCH. Modern CSS supports `oklch()` directly — prefer
keeping it (wider gamut, perceptually uniform, and it's what the brand actually specified).
Only convert to hex/rgb when the target toolchain genuinely can't consume `oklch()`, and
when you do, note that the converted value is an approximation, not the brand's exact spec.

## 4. Fidelity & attribution

- Pull the real numbers from the md; don't approximate when the value is given.
- When you must go beyond what the brand documents, mark it as *your* inference, not the
  brand's spec — the user should know which parts are faithful and which are filled in.
- A DESIGN.md cites its sources with `[src:N]`; you don't need to carry those into the
  target project, but do preserve the brand's stated intent when it's explicit.

## 5. Scope & verification

- Large or structural work → design it first: widen the options, then narrow to one
  before writing any code.
- Restyle of an existing screen → proceed, but change tokens at the source so the whole
  surface moves together rather than patching one component at a time.
- Verify visually (preview/screenshot) or via the project's tests before saying it's done
  — evidence before assertions. A brand restyle is a visual claim — back it with a
  visual check.

## 6. Brand name vs. visual language — stay vendor-neutral

A DESIGN.md documents a brand's visual language using that system's own name throughout
(its title heading, `design_system_name`, package names like `@vapor-ui/*`, class prefixes
like `vp-*`). Those names are part of the *source's* identity, not visual tokens — do not
let them leak into the UI you generate.

This applies to *every* entry, not just named design systems: a plain service brand name
(토스, 배민, …) shouldn't land in your generated UI either. The examples below lean on
design-system names (`Vapor UI`, `SEED Design`) because those are the most common leak, but
the rule is the same for any source brand name.

- **Borrow**: the color palette, type scale, spacing, radius, shadow system, and component
  structure & states.
- **Don't surface the source's name**: never put the design system's own name (`Vapor UI`,
  `SEED Design`, `KRDS`, …), its package names, or its class prefixes into your generated
  UI's headers, page titles, button/label copy, or class names. Use the user's *own*
  product name and nomenclature.
- **Why**: the system name is product/brand identity, not a token. A header that reads
  "Vapor UI" when the user asked for "their dashboard styled like Vapor" is a leak, not a
  feature.
- **Attribution exception**: if the user genuinely wants to credit the source, a footer
  line ("Vapor UI 기반" / "Built with SEED Design") is fine — but the name still
  must not appear in primary UI copy.

Each catalog entry's `## Do's and Don'ts` restates this as a brand-specific Don't; honor it.

# Endpoints — ko-design-md catalog (getdesign.kr)

Fetch order and fallbacks for the consumer skill. All getdesign.kr endpoints below are
`text/plain`, CORS-open (`access-control-allow-origin: *`), and CDN-cached ~1h.

## 1. Catalog index (discover)

```
GET https://getdesign.kr/llms.txt
```

llms.txt format — a header plus one markdown link per entry:

```
- [<name>](https://getdesign.kr/services/<slug>/llms.txt): <category> — <tagline>
```

Use it to resolve a brand name to a slug and to browse by category. It is generated
server-side from the live catalog, so it is always current — no stale hardcoded list.

## 2. Single entry (fetch)

```
GET https://getdesign.kr/services/<slug>/llms.txt
```

Returns the entry's DESIGN.md verbatim, in the catalog format: Stitch's section
structure, DESIGN.md-spec token maps in YAML frontmatter, and the catalog's own
`[src:N]` citation convention. Prefer `curl -s` over WebFetch to preserve exact
token values (see SKILL.md Step 2 for why).

**This is the endpoint to use for applying a design system.** It carries the
`[src:N]` citations, provenance notes and audit blockquotes — the evidence that lets
you tell a published value from a reconstructed one.

## 2b. Same entry, Google DESIGN.md format

```
GET https://getdesign.kr/services/<slug>/DESIGN.md
```

The same entry rendered in Google's published DESIGN.md format
(`github.com/google-labs-code/design.md`, spec `alpha`): design tokens as
`colors` / `typography` / `spacing` / `rounded` maps in YAML frontmatter, each
token's usage note kept as a trailing YAML comment, prose sections kept. Body
shadow fences already published as `elevation:` are dropped; the rest — component
specs, motion tokens — stay as `text` fences, readable but outside the token
model. Generated per request from the same source, so it can never be stale.

Use it when a consumer expects the standard shape — Stitch, the official
`design.md` CLI, or tooling built against that schema. Inline `[src:N]` citations
and the `## References` list survive, so claims still resolve to their sources.
What does not survive is the entry's own frontmatter — `slug`, dates,
`logo` — which the standard schema has no slot for. Fetch `llms.txt` when you
need the entry verbatim.

Two caveats worth knowing before you rely on a value:

- Values the `alpha` schema cannot express are reported as errors by its own
  linter and may resolve oddly — `border-radius: 50%` (spec Dimensions are
  px/em/rem only) and multi-stop gradients stored as colours (`seed-design`).
- Where an entry declares one token name per theme, only the first survives, since
  frontmatter keys must be unique. Catalog entries prefix the dark scale
  (`dark-bg-canvas`), so both are present — but a future entry that does not would
  silently lose its dark values here while `llms.txt` keeps them.

## 3. Token sidecar (optional, structured tokens)

```
GET https://raw.githubusercontent.com/CaesiumY/ko-design-md/main/services/<slug>.tokens.json
```

JSON shape: `{ colors[], typography[], spacing[], radius[], elevation?[] }`. Each color
has `name`/`value` (value usually OKLCH) plus optional `note`/`group`. `elevation` holds
ready-to-paste CSS `box-shadow` values (comma-joined when a token stacks layers) and is
**omitted** for entries whose Elevation section publishes usage labels or z-indices
rather than shadow values — read it with `?? []`, not as a guaranteed array. There is no
getdesign.kr endpoint for tokens yet — GitHub raw is the source of record. If a tokens
endpoint appears on getdesign.kr later, prefer it and update this file.

## Fallbacks

- If getdesign.kr is unreachable, the same markdown is on GitHub raw:
  `https://raw.githubusercontent.com/CaesiumY/ko-design-md/main/services/<slug>.md`
- The index has no GitHub-raw equivalent (it's generated server-side). To list entries
  without the index, read the repo's `services/` directory via the GitHub API, or fall
  back to `https://getdesign.kr/sitemap.xml` (URLs only — no names/categories/taglines).

## Example

```bash
slug=toss
curl -s https://getdesign.kr/llms.txt                                                   # find the slug
curl -s https://getdesign.kr/services/$slug/llms.txt                                     # the entry's DESIGN.md, verbatim
curl -s https://raw.githubusercontent.com/CaesiumY/ko-design-md/main/services/$slug.tokens.json  # tokens (optional)
curl -s https://getdesign.kr/services/$slug/DESIGN.md                                    # Google DESIGN.md format
```