익스클루시브

Variant Tree `<mv-variant-tree>`

CSS 사용자 정의 속성으로 제어되는 모든 요소(또는 콜백을 통한 모든 상태)를 위한 분기형 변형 탐색기입니다. “Generate 4 variants”를 누르면 적용된 변형에서 돌연변이 자식들이 돋아나고(Spread 슬라이더로 변이의 대담함을 설정), 라이브 썸네일의 깔끔한 트리로 표시됩니다. 썸네일은 대상의 축소된 비활성 복제본이므로 스크린숏 없이 어떤 컴포넌트와도 동작합니다.

작동 방식

CSS 사용자 정의 속성(또는 콜백을 통한 모든 상태)으로 제어되는 모든 요소를 위한 분기형 변형 탐색기입니다. “Generate 4 variants”는 적용된 변형에서 변이된 자식 변형을 만들어 내며(Spread 슬라이더로 변이의 대담함을 설정), 이는 실시간 썸네일로 이루어진 깔끔한 트리로 표시됩니다. 썸네일은 대상의 축소된 비활성 복제본이므로 스크린샷 없이 어떤 컴포넌트에서도 작동합니다. 마음에 드는 것은 보관하고, 막다른 길은 “3 variants discarded” 스텁으로 버리며, 최대 네 개의 변형을 실제 크기의 Compare 띠에 고정해 레이블이 붙은 차이(“hue 212 → 18”)를 보고, 두 변형을 매개변수 단위로 교배하며, 어떤 노드든 체크아웃하면 대상이 트윈 애니메이션으로 전환됩니다. 넓은 컨테이너에서는 가로 트리, 좁은 컨테이너에서는 들여쓰기 아웃라인으로 표시되며, 시드 지정, 직렬화, 원클릭 CSS 내보내기를 지원합니다.

카테고리	데이터 표시
유형	Web Component (`<mv-variant-tree>`)
상태	안정
Keywords	exclusive, variants, exploration, branching, tree, generative, design-tool, playground, compare, crossover, mutation, css-variables, theming, history, curation

When to use

Designers explore variations of a component by mutating CSS custom properties and branching from favorites
Several variants must be compared side by side at real size with labeled parameter diffs
An exploration must be reproducible from a seed and exported as CSS

Avoid when

Users only need to pick one color value → use Color Picker instead
End users of a consumer product configure a setting; this is a design and exploration tool
The need is to record and undo a user's form edits, not to generate and explore variants → use Rewind instead

설치

node scripts/add.mjs variant-tree --out ./src/marvelous

Marvelous UI MCP 서버를 사용하는 AI 에이전트: install_components({ slugs: ["variant-tree"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

복사되는 파일(의존성 포함): tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/motion.js, core/observe.js, components/variant-tree/variant-tree.js, components/variant-tree/variant-tree.css.

사용법

기본 마크업입니다. 여기서 시작해 속성, data-*, CSS 변수로 커스터마이즈하세요:

<div id="vt-demo" style="width:min(100%,72rem);margin-inline:auto">
  <style>
    #vt-demo .vt-layout { display:grid; gap:1.25rem; align-items:start }
    @media (min-width:60rem) { #vt-demo .vt-layout { grid-template-columns:minmax(19rem,22rem) minmax(0,1fr) } #vt-demo .vt-stage { position:sticky; top:1rem } }
    #vt-demo .vt-stage { display:grid; gap:.75rem; justify-items:center; padding:1.5rem 1rem 1rem; border:1px solid var(--mv-border); border-radius:var(--mv-radius-xl);
      background:radial-gradient(circle at 1px 1px, color-mix(in oklab, var(--mv-fg) 10%, transparent) 1px, transparent 1.5px) 0 0 / 18px 18px, var(--mv-bg-subtle) }
    #vt-demo .vt-stage-label { justify-self:stretch; display:flex; justify-content:space-between; gap:1rem; color:var(--mv-fg-muted); font-size:.75rem }
    #vt-demo .vt-stage-label strong { color:var(--mv-fg); font-weight:600 }
    #vt-demo .vt-hint { margin:.5rem 0 0; color:var(--mv-fg-muted); font-size:.75rem; text-align:center; line-height:1.9 }

    /* The explored target: a promo card driven entirely by four custom properties. */
    #vt-demo .vt-promo {
      --hue: 262; --radius: 18px; --scale: 1; --weight: 650;
      --mv-accent: light-dark(oklch(0.56 var(--mv-accent-c) var(--hue)), oklch(0.68 var(--mv-accent-c) var(--hue)));
      --mv-accent-hover: color-mix(in oklch, var(--mv-accent), var(--mv-fg) 12%);
      --mv-accent-active: color-mix(in oklch, var(--mv-accent), var(--mv-fg) 22%);
      --mv-accent-subtle: color-mix(in oklch, var(--mv-accent) 14%, transparent);
      --mv-accent-fg: light-dark(oklch(0.45 var(--mv-accent-c) var(--hue)), oklch(0.82 calc(var(--mv-accent-c) * .8) var(--hue)));
      --mv-button-radius: calc(var(--radius) * .6);
      --mv-badge-radius: calc(var(--radius) * .5);
      box-sizing:border-box; width:17rem; display:grid; gap:.625rem; padding:.875rem; border-radius:var(--radius);
      background:linear-gradient(170deg, color-mix(in oklch, var(--mv-accent) 9%, var(--mv-surface-raised)), var(--mv-surface-raised) 55%);
      border:1px solid color-mix(in oklch, var(--mv-accent) 24%, var(--mv-border)); box-shadow:var(--mv-shadow-lg);
      color:var(--mv-fg); font-family:var(--mv-font-sans); text-align:left;
    }
    #vt-demo .vt-visual { position:relative; display:grid; place-items:center; height:7.25rem; border-radius:calc(var(--radius) * .72); overflow:hidden; color:var(--mv-fg-on-accent);
      background:radial-gradient(circle at 28% 22%, color-mix(in oklch, var(--mv-accent) 40%, var(--mv-fg-on-accent)), transparent 58%), linear-gradient(150deg, var(--mv-accent), color-mix(in oklch, var(--mv-accent), var(--mv-gray-950) 42%)) }
    #vt-demo .vt-visual svg { width:4.25rem; height:4.25rem; filter:drop-shadow(0 6px 10px color-mix(in oklch, var(--mv-gray-950) 35%, transparent)) }
    #vt-demo .vt-visual .mv-badge { position:absolute; top:.625rem; left:.625rem; box-shadow:0 0 0 2px color-mix(in oklch, var(--mv-fg-on-accent) 35%, transparent) }
    #vt-demo .vt-kicker { margin:.125rem 0 0; color:var(--mv-accent-fg); font-size:.6875rem; font-weight:600; letter-spacing:.08em; text-transform:uppercase }
    #vt-demo .vt-title { margin:0; font-size:calc(1.25rem * var(--scale)); font-weight:var(--weight); line-height:1.15; letter-spacing:-.015em }
    #vt-demo .vt-text { margin:0; color:var(--mv-fg-muted); font-size:.8125rem; line-height:1.45 }
    #vt-demo .vt-price { display:flex; align-items:baseline; gap:.5rem; margin:.125rem 0 .125rem }
    #vt-demo .vt-price strong { font-size:calc(1.5rem * var(--scale)); font-weight:var(--weight); letter-spacing:-.02em; font-variant-numeric:tabular-nums }
    #vt-demo .vt-price s { color:var(--mv-fg-subtle); font-size:.875rem }
    #vt-demo .vt-price span { margin-inline-start:auto; color:var(--mv-success); font-size:.75rem; font-weight:500 }
    #vt-demo .vt-promo .mv-button { width:100% }
  </style>

  <div class="vt-layout">
    <div class="vt-stage">
      <div class="vt-stage-label"><strong>Live preview</strong><span>Follows the applied variant</span></div>
      <article class="vt-promo" id="vt-promo" data-vary="--hue: 0..360; --radius: 4..28px; --scale: .9..1.25 as type scale; --weight: 500|650|800">
        <div class="vt-visual">
          <span class="mv-badge" data-appearance="solid" data-variant="danger">−30%</span>
          <svg viewBox="0 0 64 64" fill="none" stroke="currentColor" stroke-width="4" stroke-linecap="round" aria-hidden="true"><path d="M12 40v-8a20 20 0 0 1 40 0v8"/><rect x="8" y="38" width="12" height="18" rx="5" fill="currentColor" stroke="none"/><rect x="44" y="38" width="12" height="18" rx="5" fill="currentColor" stroke="none"/></svg>
        </div>
        <p class="vt-kicker">Back-to-school deal</p>
        <h4 class="vt-title">Aurelo ANC Headphones</h4>
        <p class="vt-text">Active noise cancelling, 40-hour battery, folds flat for travel.</p>
        <p class="vt-price"><strong>$139</strong><s>$199</s><span>Free shipping</span></p>
        <button class="mv-button" type="button">Get the deal</button>
      </article>
    </div>

    <div>
      <mv-variant-tree id="vt-tree" for="vt-promo" count="4" seed="180" spread="0.45"></mv-variant-tree>
      <p class="vt-hint">Click a thumbnail to apply it · double-click to branch from it · in the tree:
        <kbd class="mv-kbd">↑</kbd> <kbd class="mv-kbd">↓</kbd> browse, <kbd class="mv-kbd">F</kbd> keep, <kbd class="mv-kbd">P</kbd> compare, <kbd class="mv-kbd">G</kbd> generate, <kbd class="mv-kbd">Del</kbd> discard</p>
    </div>
  </div>

  <script type="module">
    const vt = document.getElementById("vt-tree");
    await customElements.whenDefined("mv-variant-tree");
    // A past exploration session, so the tree tells a story on first sight:
    // four first tries, three dead ends discarded, one branch explored further.
    const quiet = { animate: false };
    const [a, b, c, d] = vt.generate(4, quiet);
    [a, c, d].forEach((id) => vt.prune(id));
    const kids = vt.generate(4, { ...quiet, from: b });
    vt.favorite(kids[1]);
    vt.pin(kids[1]);
    vt.pin(kids[3]);
    vt.checkout(kids[1], quiet);

    vt.addEventListener("mv-checkout", (e) => console.info("mv-checkout", e.detail.id, e.detail.params));
  </script>
</div>

API

Attributes

Name	유형	Default	Description
`for`	string		Id of the element to explore (looked up in the same root; waited for if rendered later). Without it, the first child element is the target.
`params`	string		Explorable parameters, same syntax as data-vary on the target (which is used when this attribute is absent).
`data-vary`	string		On the target: “--hue: 0..360; --radius: 0..28px step 2 as corners; --weight: 400\|600\|800”. Numeric ranges (unit taken from the bounds, optional step, wrap for circular values; a 0..360 hue wraps by default) or discrete sets separated by \|. “as `<label>`” names the parameter in the UI; otherwise the last segment of the property name is used. Plain CSS properties (opacity…) work too.
`count`	number	`4`	Children created per generation (1-12).
`spread`	number (0-1)	`0.4`	Mutation strength, mirrored by the Spread slider: subtle nudges and neighbor values when low, far jumps when high. At least one parameter always changes, siblings never duplicate each other.
`seed`	number		Seeds the random generator: the same seed and actions give the same tree (demos, tests, shareable explorations).
`label`	string	`Explore variants`	Panel title.
`max-previews`	number	`16`	Maximum live clones in the tree. Priority: applied path, pinned, kept, then newest; the others show a cheap bar glyph of their parameters.
`layout`	auto \| horizontal \| vertical	`auto`	Tidy horizontal tree, or indented outline. auto switches to the outline under 520px of component width (ResizeObserver).

Properties

Name	유형	Description
`params`	Param[] \| string	Parsed parameters ({ name, label, type: "range", min, max, unit, step, wrap } \| { name, label, type: "set", values }). Assign an array or a string to redefine them (restarts the tree).
`nodes`	{ id, parent, mate, label, params, favorite, pinned, pruned, current }[]	Serializable tree. Assign a saved array to restore an exploration (can be set before the element is defined).
`current`	{ id, params, css }	The applied variant, with its CSS declarations ready to paste (read-only).
`mutate`	(state, rng, spread) => state	Custom mutation for arbitrary state (return a new object or mutate the copy). rng() is the seeded generator.
`apply`	(state, el) => void	Custom rendering: called on the target and on every preview clone. Replaces the default custom-property writes (no tween).

Methods

Name	Description
`generate(n?, { from?, animate? })`	Creates n mutated children of the applied node (or from) and returns their ids. animate: false skips the sprout animation (seeding).
`checkout(id, { animate? })`	Applies a node to the target; numeric parameters tween (hue the short way around), discrete ones switch.
`favorite(id?, force?)`	Toggles the star (defaults to the applied node).
`pin(id?, force?)`	Toggles a node in the Compare strip (4 at most, the oldest makes room).
`combine(a, b, picks?)`	Creates and applies a hybrid child of a: for each differing parameter, the value of a or b (picks: { name: "a" \| "b" }, random but mixed when omitted). Returns its id, or null if it would equal a parent.
`prune(id?) / restore(id)`	Folds a node and its descendants into a stub / unfolds a node or every pruned child of id.
`reset(state?)`	Starts over from state (default: the target's current computed values).
`refresh()`	Re-clones the previews (content changes inside the target are also picked up automatically).

Events

Name	Description
`mv-generate`	New children. detail: { parent, ids, params[] }.
`mv-checkout`	A node was applied. detail: { id, params }.
`mv-combine`	A hybrid was created. detail: { id, a, b, params }.
`mv-favorite`	detail: { id, favorite }.
`mv-prune`	detail: { id, count }.

Content structure

Name	Description
`(content)`	Optional: the target itself, when for is not used.

CSS classes

Name	Description
`mv-variant-tree-panel / -head / -bar`	Generated panel, header (title, status, Copy variables) and toolbar acting on the applied variant.
`mv-variant-tree-view / -node / -thumb / -stub / -edge`	Scrollable tree canvas, tiles (role treeitem) with their live thumbnail, discarded-variants stub and SVG edges (data-path on the applied path, data-kind="mate" for a hybrid's second parent).
`mv-variant-tree-combine / -compare / -chip`	Crossover panel, Compare strip and diff chips.

CSS variables

Name	Default	Description
`--mv-variant-tree-accent`	`var(--mv-accent)`	Applied node, path and primary actions.
`--mv-variant-tree-favorite`	`var(--mv-warning)`	Star of kept variants.
`--mv-variant-tree-mate`	`var(--mv-info)`	Side B of a crossover and the hybrid's second edge.
`--mv-variant-tree-thumb-bg`	`var(--mv-bg-subtle)`	Background behind the clones.
`--mv-variant-tree-bg`	`var(--mv-surface)`	Panel background.
`--mv-variant-tree-max-height`	`42rem`	Height of the tree view before it scrolls.

Accessibility

The tree is a real role="tree": each tile is a treeitem with aria-level, aria-setsize, aria-posinset, aria-expanded and aria-selected (the applied variant), named by its parameter summary (“Variant 3 · hue 18, radius 12px · kept · in comparison, slot 1”). Roving tabindex (Tab enters the tree on the applied variant): Up/Down/Home/End browse in reading order, Right/Left expand, collapse or move to child/parent, Enter or Space applies, F keeps, P compares, G generates from the focused node, Delete discards (focus moves to the stub; Enter on it restores and focuses the first variant back). Thumbnails are aria-hidden and inert clones (ids, names and labels stripped, never focusable). Applying, generating, keeping, comparing, combining and copying are announced in a polite live region; the Spread slider has an aria-valuetext (“Moderate, 45%”); unavailable actions stay focusable with aria-disabled and explain why when used. Diff chips read “hue 212 becomes 18”. Focus rings everywhere. Reduced motion (OS or data-motion="reduce"): no sprout, bloom, edge growth or glide, and the target switches instantly instead of tweening. Forced colors: the applied node, its path, pressed Keep / Compare and the Spread slider switch to system colors and outlines. Known limits: preview clones lose their ids, names and ARIA references, so style the target by class rather than by id; custom elements inside the target run in every live thumbnail (capped by max-previews); a custom apply switches without tween; texts, announcements and numbers are English (en-US) with no strings or locale override yet.